Claude Agent SDK hooks let an application inspect an agent event and decide what happens next. For a sensitive tool call, a PreToolUse hook can allow the call, deny it, ask for approval, or provide changed input before the tool runs. That makes hooks useful when an agent can prepare an action but must not create an unreviewed side effect.
- 01PreToolUse
Inspect the proposed tool and its input.
- 02Tool executes
The service enforces its own checks and performs the action.
- 03PostToolUse
Inspect or adapt the returned result.
What Agent SDK hooks control
An Agent SDK hook is a callback registered in the SDK options. The SDK invokes it for events such as a tool call, failure, subagent start or session end. A matcher can restrict it to a tool or event target, and the callback receives details such as tool name, input and session ID.
For PreToolUse, the callback can return permissionDecision: "deny" with a reason, use "ask" for human approval, or return updatedInput. PostToolUse can add context or replace the result after execution, but cannot prevent an earlier side effect. See Anthropic's current Agent SDK hooks documentation.
Agent SDK hooks are different from Claude Code hooks. Claude Code hooks are configured in the Claude Code environment, while Agent SDK hooks are registered by the application running the agent, using ClaudeAgentOptions in Python or SDK options in TypeScript. The event names may overlap, but the configuration owner differs.
Timo's production Claude tool-loop guide covers validation, retries and approval across a workflow. A hook is one enforcement point; it does not replace tool schemas, authorization, business validation or audit records.
Illustrative scenario: invoice approval
Consider an agent that reads an invoice, compares it with a purchase order and calls request_invoice_approval. The call creates a downstream approval record, so the application requires three checks:
- The invoice identifier and amount must be present and have the expected types.
- The supplier and purchase order must match an allowed record.
- The call must carry an approval reason and remain below the operator's approval limit.
request_invoice_approval receives an invoice, amount, supplier, purchase order and approval reason.
Await the hook’s decision. Check required fields, supplier and purchase-order match, and the operator’s approval limit.
Required data or a business condition fails. Return a reason; the tool does not run.
The application’s canUseTool or can_use_tool handler obtains a human decision. Continue only after approval.
The request satisfies the hook policy. Continue to the tool service.
Repeat authorization and business validation. Use an idempotency key to prevent duplicate approval records.
Record the outcome or add context. Reversing a completed action requires a separate, explicitly designed process.
The scenario is illustrative. It does not describe a Timo customer system, and no implementation or result is claimed.
The hook inspects the input before execution. Missing data, a supplier mismatch or an exceeded limit returns a useful denial. Valid data that still needs approval returns ask. The application must provide an approval handler, such as canUseTool in TypeScript or can_use_tool in Python, and use a permission configuration that permits asking. Returning ask alone does not create an approval interface. The downstream tool must repeat authorization and business checks because the hook does not own the invoice record.
A hook that gates an action must return its decision before execution. A callback returning async: true (or async_: True in Python) cannot block the tool or modify its input.
The failure paths matter. A malformed call needs a repairable denial, a lookup timeout needs a fail-closed or explicit retry policy, and the approval service should detect duplicates with an idempotency key. Passing the hook does not prove that the invoice is correct or paid.
A useful test plan
Test the control boundary before connecting a real side effect:
- Send a valid, below-limit request and confirm that the tool receives unchanged input.
- Remove a required field, change the supplier or exceed the approval limit. Confirm the expected denial or human decision.
- Simulate a lookup timeout, tool error and duplicate request. Confirm that each path produces an observable event and no unintended approval.
- Check that the hook logs the session ID, tool-use ID, decision and reason without unnecessary invoice or personal data.
The output should show which control fired, its decision and whether the tool ran. Review blocked and failed paths as carefully as the successful request.
How this supports CCDV-F and CCAR-F preparation
CCDV-F candidates need to reason about tool inputs, failures, retries and structured outputs. CCAR-F candidates also need to identify which check belongs in the hook, tool service or human approval. In a practice scenario, explain which component should enforce the rule and why a check in a different place would leave a gap.
Timo Labs is run by Amotion AI, a member of the Claude Partner Network. Timo reviews applications from individuals who need partner access. Accepted applicants complete a freelance consulting agreement and receive account setup instructions. Partner access is available through Timo. Anthropic awards the credential. You can try the public CCDV-F mock-exam preview and read the registration guide when you need the official access route. The preview contains independent Timo practice material. Official exam access and certification follow Anthropic’s requirements.
FAQs
Can an Agent SDK hook stop a tool call?
Yes. A PreToolUse hook can return a deny decision before the tool executes. The reason should tell the agent and operator what condition failed. The tool service must still enforce its own authorization and business rules.
How is an Agent SDK hook different from a Claude Code hook?
An Agent SDK hook is registered by the application running the SDK agent. A Claude Code hook is configured in the Claude Code environment. They can use similar event names, but they do not share the same configuration owner or deployment boundary.
Can a PostToolUse hook undo an invoice approval?
No. A post-tool hook can add context, replace the result shown to the agent or record an event. It cannot reliably reverse a side effect that the tool already performed. Use pre-execution checks and an explicitly designed reversal process where reversals are allowed.
How can Timo help me practise tool-control decisions for CCDV-F?
Start with Timo’s original CCDV-F questions and worked explanations. For each scenario, identify the requirement, choose an action and explain why the alternatives do not satisfy that requirement. Use the example above to practise locating an approval check before a business action. Anthropic awards the official credential.