Intercept and control agent behavior with hooks changedagent-sdk/hooks
Nearest release: v2.1.286, published 10 hours before upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 1 Oct 2026 03:48 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 1 Oct 2026 04:07 UTC.
Upstream edited
Recorded here
Lines+6added
Lines−2removed
From line
392
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits13to this page, all time
The whole hunk
from line 392, old and new numbered
/
from line 392
392392 ```
393393</CodeGroup>
394394
395To confirm the block, register the callback under `PreToolUse` with a `Write|Edit` matcher and ask the agent to create a file under `/etc`: the Write tool's result in the message stream contains `Writing to /etc is not allowed`, and no file is created.
396
395397### Auto-approve specific tools
396398
397399By default, the agent may prompt for permission before using certain tools. This example auto-approves read-only filesystem tools (Read, Glob, Grep) by returning `permissionDecision: 'allow'`, letting them run without user confirmation while leaving all other tools subject to normal permission checks:
from line 440
438440
439441When an event fires, all matching hooks run in parallel. For permission decisions, the most restrictive result applies: a single `deny` blocks the tool call regardless of what the other hooks return. Because completion order is non-deterministic, write each hook to act independently rather than relying on another hook having run first.
440442
441The example below registers three independent checks for every tool call:
443The example below registers three independent checks for every tool call. The hook names in it, such as `audit_logger` in Python or `auditLogger` in TypeScript, stand in for callbacks you define:
442444
443445<CodeGroup>
444446 ```python Python theme={null}
from line 470
468470
469471### Filter with multi-tool matchers
470472
471Use multi-tool matchers to share one callback across related tools. This example registers three matchers with different scopes:
473Use multi-tool matchers to share one callback across related tools. This example registers three matchers with different scopes, and each hook it names stands in for a callback you define:
472474
473475* A pipe-separated exact list (`Write|Edit|NotebookEdit`) triggers `file_security_hook` only for file modification tools.
474476* A regex (`^mcp__`) triggers `mcp_audit_hook` for any MCP tool whose name starts with `mcp__`.
from line 552
550552 };
551553 ```
552554</CodeGroup>
555
556To confirm the hook fires, register the callback and ask the agent to delegate a small task to a subagent, such as listing the files in the current directory: when the subagent finishes, the callback prints the `[SUBAGENT] Completed:` lines with the subagent's ID and transcript path.
553557
554558### Make HTTP requests from hooks
555559
No line in this hunk matches that.