fix(hooks): don't emit invalid permissionDecision 'defer' — it swallows the AskUserQuestion widget

docs/spikes/claude-code-hook-mutation.md

@@ -51,7 +51,12 @@ Optional in subagent context: `agent_id`, `agent_type`.
 - `"deny"` — block (feedback to Claude, NOT a synthetic answer per Codex
   correction in D-prefixed decisions)
 - `"ask"` — escalate to user
-- `"defer"` — let permission flow continue
+- `"defer"` — **NOT a valid value.** The schema accepts only `allow` / `deny` /
+  `ask`. As of Claude Code 2.1.14 an unrecognized `"defer"` is treated as
+  "defer the tool call": the call is swallowed and never executes. For
+  AskUserQuestion this means the question widget never renders and the user
+  sees nothing at all. To signal "no opinion, let permission flow continue",
+  OMIT `permissionDecision` entirely (`additionalContext` is still delivered).
 
 **`updatedInput` semantics:** shallow merge of fields present in the returned
 object onto the original `tool_input`. Only valid with
@@ -88,7 +93,9 @@ required for our hook to fire there.
   accepting.
 
 **`permissionDecision` precedence (when multiple hooks decide):**
-`deny > ask > allow > defer` — most restrictive wins.
+`deny > ask > allow` — most restrictive wins. A hook with no opinion omits
+`permissionDecision` entirely rather than emitting a sentinel value; see the
+note above on why `"defer"` is not valid here.
 
 ## Implementation hookSpecificOutput examples
 
@@ -110,8 +117,7 @@ required for our hook to fire there.
 ```json
 {
   "hookSpecificOutput": {
-    "hookEventName": "PreToolUse",
-    "permissionDecision": "defer"
+    "hookEventName": "PreToolUse"
   }
 }
 ```

hosts/claude/hooks/question-preference-hook.ts

@@ -93,9 +93,14 @@ function readStdin(): Promise<string> {
 }
 
 function defer(additionalContext?: string): void {
+  // NOTE: do NOT emit `permissionDecision: 'defer'`. Claude Code's PreToolUse
+  // schema only accepts 'allow' | 'deny' | 'ask'; as of 2.1.14 an unrecognized
+  // 'defer' is interpreted as "defer the tool call", which SWALLOWS the
+  // AskUserQuestion widget — it never renders and the user sees nothing.
+  // Omitting permissionDecision entirely is the correct "no opinion" signal:
+  // normal permission flow continues and additionalContext is still delivered.
   const out: Record<string, unknown> = {
     hookEventName: 'PreToolUse',
-    permissionDecision: 'defer',
   };
   if (additionalContext) out.additionalContext = additionalContext;
   process.stdout.write(JSON.stringify({ hookSpecificOutput: out }));

test/memory-cache-injection.test.ts

@@ -91,7 +91,7 @@ describe('memory injection', () => {
         ],
       },
     });
-    expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBe('defer');
+    expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBeUndefined();
     expect(r.parsed?.hookSpecificOutput?.additionalContext).toContain('verbose explanations');
   });
 
@@ -115,7 +115,7 @@ describe('memory injection', () => {
         ],
       },
     });
-    expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBe('defer');
+    expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBeUndefined();
     expect(r.parsed?.hookSpecificOutput?.additionalContext).toBeUndefined();
   });
 
@@ -219,7 +219,7 @@ describe('per-session memory cache', () => {
         ],
       },
     });
-    expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBe('defer');
+    expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBeUndefined();
     expect(r.parsed?.hookSpecificOutput?.additionalContext).toBeUndefined();
   });
 });

test/question-preference-hook.test.ts

@@ -126,7 +126,7 @@ describe('defers (no enforcement)', () => {
       },
     });
     expect(r.status).toBe(0);
-    expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBe('defer');
+    expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBeUndefined();
   });
 
   test('marker missing → defer (D18)', () => {
@@ -141,7 +141,7 @@ describe('defers (no enforcement)', () => {
         ],
       },
     });
-    expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBe('defer');
+    expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBeUndefined();
   });
 
   test('always-ask preference → defer', () => {
@@ -156,7 +156,7 @@ describe('defers (no enforcement)', () => {
         ],
       },
     });
-    expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBe('defer');
+    expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBeUndefined();
   });
 
   test('empty stdin → defer (crash safety)', () => {
@@ -168,13 +168,13 @@ describe('defers (no enforcement)', () => {
     const res = spawnSync(HOOK, [], { env, input: '', encoding: 'utf-8' });
     expect(res.status).toBe(0);
     const parsed = JSON.parse(res.stdout || '{}');
-    expect(parsed.hookSpecificOutput?.permissionDecision).toBe('defer');
+    expect(parsed.hookSpecificOutput?.permissionDecision).toBeUndefined();
   });
 
   test('non-AUQ tool_name → defer (defensive)', () => {
     writeProjectPref('test-q', 'never-ask');
     const r = runHook({ session_id: 's4', tool_name: 'Bash', tool_use_id: 'tu-4', tool_input: {} });
-    expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBe('defer');
+    expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBeUndefined();
   });
 });
 
@@ -219,7 +219,7 @@ describe('enforces never-ask preferences', () => {
         ],
       },
     });
-    expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBe('defer');
+    expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBeUndefined();
   });
 
   test('ambiguous recommendation (two labels) → defer (D2 refuse-on-ambiguous)', () => {
@@ -237,7 +237,7 @@ describe('enforces never-ask preferences', () => {
         ],
       },
     });
-    expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBe('defer');
+    expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBeUndefined();
   });
 
   test('no recommendation marker AND no prose match → defer', () => {
@@ -255,7 +255,7 @@ describe('enforces never-ask preferences', () => {
         ],
       },
     });
-    expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBe('defer');
+    expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBeUndefined();
   });
 });
 
@@ -317,7 +317,7 @@ describe('precedence: project wins over global (D8)', () => {
         ],
       },
     });
-    expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBe('defer');
+    expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBeUndefined();
   });
 });
 
@@ -443,7 +443,7 @@ describe('Conductor prose redirect', () => {
       undefined,
       CONDUCTOR,
     );
-    expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBe('defer');
+    expect(r.parsed?.hookSpecificOutput?.permissionDecision).toBeUndefined();
   });
 });
 

test/skill-e2e-plan-tune-cathedral.test.ts

@@ -296,7 +296,7 @@ describeIfSelected('PlanTune cathedral E2E: annotation', ['plan-tune-annotation'
     });
     expect(res.status).toBe(0);
     const parsed = JSON.parse(res.stdout || '{}');
-    expect(parsed.hookSpecificOutput?.permissionDecision).toBe('defer');
+    expect(parsed.hookSpecificOutput?.permissionDecision).toBeUndefined();
     expect(parsed.hookSpecificOutput?.additionalContext).toContain('verbose explanations');
   });
 });