1:1 mentoring with Big Tech AI engineers
LLM & Agentic

Permissions & Hooks: Gating the Agent

Gate a Claude agent: permission modes, disallowed_tools vs allowed_tools, deciding per call with can_use_tool, and using PreToolUse and PostToolUse hooks for audit logging and redaction.

Last updated

Production5 min readFirst readCustom Tools: @tool and SDK MCP Servers

After this section you can

  • Separate tool availability from per-call permission
  • Pick a permission mode, and know why unattended runs need can_use_tool
  • Deny, allow or rewrite a call from can_use_tool
  • Know the two configurations that stop can_use_tool from ever firing
  • Use hooks for audit logging and redaction, not only for blocking
  • Scope a subagent to its own prompt, tools and context window
36

Permissions & Hooks: Gating the Agent

An SDK agent starts with a filesystem and a shell. Everything about making that safe is two options and one callback — plus hooks, for the things a permission cannot express.

THE CENTRAL IDEA

Separate the two questions. disallowed_tools answers “may this tool exist at all”. can_use_tool answers “may this call, with these arguments, proceed” — and it can rewrite the arguments instead of just refusing.

Four controls, two questions: may this tool exist, and may this call proceed?
DOES THE TOOL EXIST? disallowed_tools removes it from the agent the only real filter MAY THIS CALL PROCEED? allowed_tools listed → auto-approved unlisted → falls through permission_mode + can_use_tool callback allow · deny · rewrite args PreToolUse hook deterministic code can deny, and can log the tool body runs and validates its own arguments anyway A tool in allowed_tools is approved before can_use_tool runs, so a gate that must see every call belongs in a PreToolUse hook. None of this replaces validation inside the tool: a permission layer approves the call, it does not check that the arguments make sense.

Related

More in LLM & Agentic

LLM Lifecycle

Preview

Complete lifecycle of large language models from pre-training through fine-tuning, RLHF, and deployment — with architecture diagrams and production considerations.

How LLMs Call Tools

Preview

How LLMs use function calling and tool use — the mechanics behind tool-calling agents, from prompt engineering to structured output.

Prompt Engineering Foundations

Preview

Where an instruction belongs — tool description, system prompt, or user turn — why emphasis that worked on older models now causes over-triggering, and the prompt patterns that have expired.

Tool Surface Design

Preview

When an action deserves its own tool instead of bash, how to write a description that raises selection accuracy, and how to scale past a few dozen tools without destroying the prompt cache.

Get full access to all 74+ sections with code examples, diagrams, and interactive animations.

Unlock Premium