Defer native plan-mode approve so PermissionRequest exits plan mode

On approve, PreToolUse:ExitPlanMode returned permissionDecision "allow". In
native Claude Code that resolves the tool's permission early and skips the
plan-approval dialog, so the PermissionRequest hook — the only documented path
that exits plan mode — never fires. Claude Code then falls back to the TUI
prompt, forcing the user to approve a second time after clicking Approve in the
browser UI.

Gate the PreToolUse approve output on permission_mode: in native plan mode
("plan") emit permissionDecision "ask" instead of "allow". The dialog then
fires, PermissionRequest replays the cached approval as
{decision:{behavior:"allow"}}, and plan mode exits with no terminal prompt.
Conductor (bypassPermissions) and OpenCode/pi (default) have no
PermissionRequest, so they keep the immediate "allow".

- server/types.ts: PreToolUse permissionDecision union += "ask"
- server/runtime/decision.ts: defer approve when permission_mode === "plan"
- server/historyLifecycle.test.ts: plan-mode defer + PermissionRequest replay test
- AGENTS.md: document the deferral (with a don't-revert-to-allow warning)

server/index.ts unchanged: the PreToolUse decision cache write is already
ungated, so PermissionRequest can replay the "ask"-deferred approval.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: ndom91

AGENTS.md

@@ -115,6 +115,8 @@ The deny feedback field (`permissionDecisionReason` or `decision.message`) conta
 
 The hook is registered on both `PreToolUse` and `PermissionRequest`. `PreToolUse` fires before the permission flow and regardless of `--permission-mode`, which makes Request Changes (`deny`) work in Conductor. Native Claude Code still needs `PermissionRequest` to apply final plan approval. When both fire for the same tool call, the `PreToolUse` decision is cached briefly and replayed to `PermissionRequest` so the browser UI opens only once.
 
+**Native plan-mode approve must be deferred, not allowed.** In native Claude Code the ExitPlanMode `PreToolUse` event arrives with `permission_mode: "plan"`. Returning `permissionDecision: "allow"` there resolves the tool's permission early and skips the plan-approval dialog — which means the `PermissionRequest` hook that actually exits plan mode never runs, and the user is forced to approve a second time in the TUI. So on approve in `permission_mode: "plan"` the binary emits `permissionDecision: "ask"` (defer) instead of `allow`; the dialog then fires, `PermissionRequest` replays the cached approval as `{decision:{behavior:"allow"}}`, and plan mode exits with no terminal prompt. Every other host (Conductor `bypassPermissions`, OpenCode/pi `default`) has no `PermissionRequest`, so those keep the immediate `PreToolUse` `allow`. Do not "simplify" plan-mode approve back to `allow` — that reintroduces the double-approve.
+
 The OpenCode bridge (`opencode/bridge.js`) constructs the same `HookEvent` format and parses the same `HookOutput` response, so the binary always goes through the same code path.
 
 ## Plan Review Trigger Rules

server/historyLifecycle.test.ts

@@ -45,7 +45,7 @@ type SessionDecision = "approve" | "deny";
 interface SessionResult {
   version: number;
   history: string[];
-  outputBehavior: "allow" | "deny";
+  outputBehavior: "allow" | "deny" | "ask";
 }
 
 function seedUpdateCheckCache(configHome: string) {
@@ -124,7 +124,7 @@ async function runSession(args: {
     }
 
     const output = JSON.parse(stdout.trim()) as {
-      hookSpecificOutput: { permissionDecision: "allow" | "deny" };
+      hookSpecificOutput: { permissionDecision: "allow" | "deny" | "ask" };
     };
 
     return {
@@ -321,6 +321,88 @@ describe("stdout immediacy", () => {
       rmSync(tempRoot, { recursive: true, force: true });
     }
   }, 15000);
+
+  test("plan-mode PreToolUse approve defers with ask, then PermissionRequest replays allow", async () => {
+    const tempRoot = mkdtempSync(join(tmpdir(), "open-plan-annotator-planmode-"));
+    const fakeBin = join(tempRoot, "bin");
+    const configHome = join(tempRoot, "config");
+
+    try {
+      mkdirSync(fakeBin, { recursive: true });
+      mkdirSync(configHome, { recursive: true });
+      seedUpdateCheckCache(configHome);
+
+      for (const name of ["open", "xdg-open", "cmd"]) {
+        const shimPath = join(fakeBin, name);
+        writeFileSync(shimPath, "#!/bin/sh\nexit 0\n", "utf8");
+        chmodSync(shimPath, 0o755);
+      }
+
+      const hookEvent = {
+        transcript_path: join(tempRoot, "transcript.jsonl"),
+        session_id: `session-${tempRoot}`,
+        cwd: "/repo",
+        permission_mode: "plan",
+        hook_event_name: "PreToolUse",
+        tool_name: "ExitPlanMode",
+        tool_use_id: "tool-planmode",
+      };
+      const env = {
+        NODE_ENV: "test",
+        XDG_CONFIG_HOME: configHome,
+        SHUTDOWN_DELAY_MS: "100",
+        PATH: `${fakeBin}${delimiter}${process.env.PATH ?? ""}`,
+      };
+
+      // Native CC plan mode: PreToolUse approve must defer with "ask" (not "allow"),
+      // so the plan-approval dialog fires and PermissionRequest gets to exit plan mode.
+      const preToolUse = await runSession({ decision: "approve", plan: "Plan-mode plan", env, hookEvent });
+      expect(preToolUse.outputBehavior).toBe("ask");
+
+      // PermissionRequest then replays the cached approval as behavior "allow" without
+      // reopening the browser — this is what actually exits plan mode with no TUI prompt.
+      const child = spawn(process.execPath, ["run", "server/index.ts"], {
+        cwd: join(import.meta.dir, ".."),
+        env: { ...process.env, ...env },
+        stdio: ["pipe", "pipe", "pipe"],
+      });
+
+      let stdout = "";
+      let stderr = "";
+      child.stdout.on("data", (chunk) => {
+        stdout += String(chunk);
+      });
+      child.stderr.on("data", (chunk) => {
+        stderr += String(chunk);
+      });
+
+      const childExit = new Promise<number>((resolve, reject) => {
+        child.once("error", reject);
+        child.once("close", (code) => resolve(code ?? -1));
+      });
+
+      const payload = {
+        ...hookEvent,
+        hook_event_name: "PermissionRequest",
+        tool_use_id: "tool-planmode-permission",
+        tool_input: { plan: "Plan-mode plan" },
+      };
+      child.stdin.write(`${JSON.stringify(payload)}\n`);
+      child.stdin.end();
+
+      const exitCode = await Promise.race([childExit, Bun.sleep(3000).then(() => -2)]);
+      expect(exitCode).toBe(0);
+      expect(stderr).not.toContain("UI available at");
+
+      const output = JSON.parse(stdout.trim()) as {
+        hookSpecificOutput: { hookEventName: "PermissionRequest"; decision: { behavior: "allow" | "deny" } };
+      };
+      expect(output.hookSpecificOutput.hookEventName).toBe("PermissionRequest");
+      expect(output.hookSpecificOutput.decision.behavior).toBe("allow");
+    } finally {
+      rmSync(tempRoot, { recursive: true, force: true });
+    }
+  }, 15000);
 });
 
 describe("generic review CLI mode", () => {

server/runtime/decision.ts

@@ -29,7 +29,15 @@ export async function writeHookDecisionToStdout(decision: ServerDecision, hookEv
           hookSpecificOutput: decision.approved
             ? {
                 hookEventName: "PreToolUse",
-                permissionDecision: "allow",
+                // In native Claude Code plan mode, returning "allow" here resolves the
+                // tool's permission early and skips the plan-approval dialog — which
+                // means the PermissionRequest hook that actually exits plan mode never
+                // runs, and the user is left to confirm again in the TUI. Defer with
+                // "ask" so the dialog fires and PermissionRequest replays the cached
+                // approval (see server/index.ts + decisionCache.ts). Other hosts
+                // (Conductor bypassPermissions, OpenCode/pi default) have no
+                // PermissionRequest, so they keep the immediate "allow".
+                permissionDecision: hookEvent.permission_mode === "plan" ? "ask" : "allow",
               }
             : {
                 hookEventName: "PreToolUse",

server/types.ts

@@ -29,7 +29,7 @@ export type HookOutput =
   | {
       hookSpecificOutput: {
         hookEventName: "PreToolUse";
-        permissionDecision: "allow" | "deny";
+        permissionDecision: "allow" | "deny" | "ask";
         permissionDecisionReason?: string;
       };
     }