Block Claude agent actions when custom checks fail

Anthropic’s November 3, 2026 release of its TypeScript Claude Agent SDK adds an option to block an agent action when a custom check crashes or returns invalid output. It matters to developers and automation owners whose agents must obtain approval before changing files or calling business tools.

Version 0.3.317 introduces onFailure: "block" for callback matchers—the configuration that selects which checks run. Upgrading alone does not enable it: the published interface defaults to continue. That default means a callback failure does not itself stop the action; other permission controls still apply.

Decide which checks must stop the action

A hook is application code that runs at a defined point in the agent’s work. For checks that must precede a tool action, use PreToolUse. Anthropic’s permission guidance places hooks before other permission steps. Do not rely solely on canUseTool to inspect every call: earlier approvals can mean that callback is never reached.

Consider a hypothetical agent with a tool that updates customer records. If a required approval service is unavailable, should the update wait? That is a separate decision from whether the service normally approves a particular change.

Our recommendation: use blocking for required checks, and keep optional usage logging in a separate matcher if its failure should not interrupt work. This trades uninterrupted automation for withholding an action when its prerequisite cannot be established. Decide who restores the check and how the task resumes.

Configure the matcher and its runtime

Use @anthropic-ai/claude-agent-sdk@0.3.317 with its aligned Claude Code runtime. The package metadata identifies runtime 2.1.317 and requires Node.js 18.14.0 or newer. Review custom executable paths and connections to existing sessions; updating the application dependency is not proof that a separate runtime supports the option.

Put onFailure on the matcher alongside hooks, as defined in the version-pinned package. This illustrative fragment belongs inside query() options. It is not a tested authorization implementation: policyCheck stands for your application’s own callback.

hooks: {
  PreToolUse: [{
    matcher: "Write|Edit",
    hooks: [policyCheck],
    onFailure: "block",
    timeout: 15
  }]
}

Here, 15 seconds is an example timeout, not a universal recommendation. The callback must await its required evaluation and return a normal verdict. Use hookSpecificOutput.permissionDecision: "deny" for an explicit rejection, following the callback-output contract. A thrown error means the evaluation failed, not that it successfully rejected the request.

An implementation implication: catching a policy-service error and returning {} hides the failure from onFailure. Do not convert an unavailable mandatory check into a normal return merely to silence an error.

With blocking configured, the SDK’s initialization code withholds the first prompt until compatibility checks pass. It rejects a runtime that does not confirm support, or an initial response explicitly reporting that the hooks were not applied to an already-running session. For a mandatory check, resolve the mismatch or start a correctly configured session; do not remove blocking just to make startup succeed.

Keep errors, timeouts and coverage separate

• Tool coverage: Write|Edit covers those named tools, not file changes made through Bash. Review every tool path to the protected action. The hooks guide documents this limit; keep appropriate sandbox and server-side permissions too.

• Background work: an async JavaScript function can await a check, but returning { async: true } tells the agent to proceed without waiting. That asynchronous output cannot block the operation. Do not use it for required approval.

• Event limits: Stop, SubagentStop, TaskCompleted and TeammateIdle ignore this failure setting, according to the released interface. A post-action check also cannot prevent an action that already happened.

• Timeouts: existing timeout rules already block a PreToolUse tool call when its callback takes too long. PostToolUse and PostToolUseFailure timeouts retain the result and continue. Do not treat this release’s exception/output policy as the introduction of timeout blocking.

Validate the failure paths before rollout

In an isolated deployment, replace consequential writes and external actions with harmless stand-ins that record whether they ran. Exercise the actual SDK-to-runtime path, not only the callback function. The following are proposed acceptance checks, not reported test results:

• A permitted call should reach the intended stand-in; an explicit policy denial should not.

• A thrown callback and invalid callback output should each prevent a matched action with blocking enabled. Check a timeout separately.

• Try an unmatched tool that can perform the same kind of action. Use this case to identify missing coverage, not to assume one matcher protects the whole workflow.

• Check an unsupported runtime and an existing session that explicitly did not apply the hooks. Confirm the configured gate prevents the first prompt from proceeding.

Record the SDK and runtime versions, inputs, timestamps, returned messages and whether each stand-in ran. The release also adds callback-failure warnings to the message stream; route those to the person responsible for restoring the check. A warning is not a substitute for verifying that the action stayed blocked.

For teams maintaining several agent frameworks, the separate Pi custom-tool validation guide covers preserving checks before an action during a different migration. Pi’s input validation and Claude’s callback-failure policy need separate configurations and acceptance cases.