[BUG] PreToolUse hook outputting permissionDecision "defer" + additionalContext errors the tool call ([Tool result missing due to internal error])

Environment

• Claude Code v2.1.217, VSCode native extension, macOS (Darwin 27.0.0)
• Model: claude-fable-5

Summary

A PreToolUse hook that outputs permissionDecision: "defer" together with additionalContext causes the gated tool call to fail. The additionalContext warning is delivered to the model, but the tool result comes back as [Tool result missing due to internal error] — for Write, the file never lands on disk.

The hooks docs (https://code.claude.com/docs/en/hooks) list defer as a valid permissionDecision value ("defers to the default permission flow"), so this looks like the harness mishandling a documented-valid output rather than a hook authoring error.

Minimal repro

/tmp/defer_hook.py:

#!/usr/bin/env python3
import json, sys
sys.stdin.read()
print(json.dumps({
    "hookSpecificOutput": {
        "hookEventName": "PreToolUse",
        "permissionDecision": "defer",
        "permissionDecisionReason": "advisory test",
        "additionalContext": "advisory warning text",
    }
}))

settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Bash",
        "hooks": [
          { "type": "command", "command": "/usr/bin/env python3 /tmp/defer_hook.py", "timeout": 5 }
        ]
      }
    ]
  }
}

Then ask Claude to Write any file (or run any Bash command).

Expected

The hook defers to the normal permission flow, the additionalContext is injected, and the tool call executes normally.

Actual

• The additionalContext IS injected (visible to the model as "PreToolUse:Write hook additional context: …").
• The tool call itself errors: [Tool result missing due to internal error]. A Write never reaches disk; the model sees no tool result.
• Reproduces deterministically, on both Write and Bash.

Notes

• Hook exits 0; stdout is a single valid JSON object (verified by piping the same stdin payload manually).
• Changing the output to additionalContext-only (no permissionDecision key) works perfectly — warning injected, tool call runs. That's our workaround.
• permissionDecision: "ask" and "deny" behave as documented; only "defer" triggers the failure (we did not isolate whether defer alone, without additionalContext, also fails).
• Real-world impact: we ran an advisory secret-scan hook emitting defer + warning; every flagged Write/Edit/Bash across all our repos failed with the internal error until we found the correlation — the failure gives no hint that a hook output caused it.

🤖 Filed with the help of Claude Code