Proposed worksheet · Method notes updated 11 November 2026 · Not independently tested

The decision

Audit the exact pre-action guard and rehearse its failure behavior before relying on it.

Use this guide with your own evidence

The draft includes this method’s reference and proposed checks. Confirm they fit your task, then add your authorized scope and observations. No checks have been run.

Start a JSON recordStart a Markdown record

Use this when

A Python hook in Claude Agent SDK is part of the path that controls a consequential action.

Skip this when

You do not use the SDK, or the hook only adds optional telemetry. Preserve the ordinary authorization layer either way.

Work through the checks

  1. Inspect the deployed pair

    Record the SDK, bundled CLI, hook event and actual configuration. The recovered source review identifies on_failure="block" in Python SDK v0.2.177; its default remained continue. This is a dated feature reference, not a current-version recommendation.

  2. Check capability, not just configuration

    Confirm the runtime supports and applied the required behavior. The reviewed change describes refusing connection when blocking support is absent. Stop hooks have different behavior; do not generalize this setting to every hook.

  3. Use a harmless effect counter

    In an authorized isolated environment, use a local counter instead of a real message, payment or production change. Exercise allow, deny, exception, None, malformed response and timeout.

  4. Inspect effects and errors together

    Allow should increment the counter once. Deny and required failure cases should leave it unchanged and expose a detectable failure. Unsupported blocking capability should stop startup rather than continue silently.

What would count as success?

  1. The valid path works; a system that denies everything does not pass. Evidence for check 1
  2. Each failure case preserves the required authorization boundary. Evidence for check 2
  3. Capability absence is visible and prevents use of the affected path. Evidence for check 3

Evidence to bring back

Proposed evidence plan, not observed results or extra mandatory process. Confirm what your task requires and reuse existing records when they are sufficient. Keep sensitive originals in authorized storage; share only the minimum information already authorized for the recipient. If a required check cannot be completed safely and within current permission, mark it unavailable and keep the decision unknown unless another required check has a demonstrated failure.

  1. The valid path works; a system that denies everything does not pass.

    Proposed evidence for acceptance check 1. No result has been observed here.

    Bring back: Record the exact SDK/CLI configuration and a harmless allow-case trace with effect count before and after. The valid case should show one intended effect.

    Not enough: A suite in which all actions are denied, or an allow response without inspecting the effect.

  2. Each failure case preserves the required authorization boundary.

    Proposed evidence for acceptance check 2. No result has been observed here.

    Bring back: Keep one result per deny, exception, None, malformed-response and timeout case: input, expected boundary, observed error and effect-counter delta. Use only the authorized isolated fake sink.

    Not enough: A hook error or log message without checking whether the effect still happened.

  3. Capability absence is visible and prevents use of the affected path.

    Proposed evidence for acceptance check 3. No result has been observed here.

    Bring back: Record an unsupported-capability rehearsal and the resulting startup or connection refusal. Identify the SDK/runtime pair actually exercised.

    Not enough: A configuration flag or release note by itself; neither proves the deployed pair enforces it.

Stop or recover

Keep the action disabled or behind its existing human gate if a required case fails. Reverting to a fail-open configuration is not a safe rollback.

What this does not establish

The specific SDK change was rechecked against primary sources on 10 November 2026, but its behavior was not rerun for this reconstruction. Verify the current deployed SDK/CLI pair before use. Source review is not runtime validation.

Reference links

Links checked 10 November 2026. Each note below states what the reference supports. No source review validates this worksheet’s effectiveness or replaces testing in your environment.

  • Claude Agent SDK Python v0.2.177

    Primary release record for introduction of HookMatcher on_failure. Supports the dated feature claim, not a claim about your deployed configuration.

  • HookMatcher on_failure change

    Same-publisher implementation detail for blocking hook failure handling and capability checks. Not independent runtime validation.

Take this worksheet with you

Section links identify this page, not an immutable copy. Numbered checks may change in later revisions. For an exact reference, retain build revision release-2026-11-11-r12 and the method source hash in the JSON or Markdown version.

This guide’s draft recordHow to complete a recordRead MarkdownRead JSON