Fix native Claude plan approval replay

Author: ndom91

AGENTS.md

@@ -53,7 +53,7 @@ For environments that don't run `npm install` after fetching the plugin (Claude
 - `opencode/bridge.js` — Spawns the binary with a fake HookEvent, parses the HookOutput response.
 - `opencode/config.js` — Reads `open-plan-annotator.json` config for implementation handoff settings.
 - `ui/` — React + Vite frontend, built to a single `build/index.html` embedded at compile time.
-- `hooks/hooks.json` — Claude Code hook registration. `SessionStart` runs `scripts/install-runtime.mjs` (runtime fetch) and `scripts/session-context.mjs` (injects plan-routing instructions into Claude's session context). `PreToolUse:ExitPlanMode` launches the annotator binary.
+- `hooks/hooks.json` — Claude Code hook registration. `SessionStart` runs `scripts/install-runtime.mjs` (runtime fetch) and `scripts/session-context.mjs` (injects plan-routing instructions into Claude's session context). `PreToolUse:ExitPlanMode` launches the annotator binary for Conductor-compatible denies; `PermissionRequest:ExitPlanMode` preserves native Claude Code approval behavior.
 - `skills/plan-review-triggers/SKILL.md` — Auto-loaded Claude Code skill with the full trigger heuristics. This is the long-form reference; the SessionStart context injection is the always-on nudge that keeps Claude from rationalizing past it.
 
 ## Critical Rules
@@ -99,14 +99,21 @@ bun run format         # Format
 
 ## Hook Protocol
 
-Claude Code sends a `HookEvent` JSON on stdin with `tool_input.plan` containing the plan markdown. The binary responds on stdout with a `HookOutput` JSON:
+Claude Code sends a `HookEvent` JSON on stdin with `tool_input.plan` containing the plan markdown. The binary responds on stdout with a `HookOutput` JSON matching the incoming hook event.
+
+For `PreToolUse`:
 
 - Approve: `{ hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "allow" } }`
 - Deny: `{ hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: "..." } }`
 
-The deny `permissionDecisionReason` contains serialized annotations (deletions, replacements, insertions, comments) as markdown so Claude can revise the plan.
+For `PermissionRequest`:
+
+- Approve: `{ hookSpecificOutput: { hookEventName: "PermissionRequest", decision: { behavior: "allow" } } }`
+- Deny: `{ hookSpecificOutput: { hookEventName: "PermissionRequest", decision: { behavior: "deny", message: "..." } } }`
+
+The deny feedback field (`permissionDecisionReason` or `decision.message`) contains serialized annotations (deletions, replacements, insertions, comments) as markdown so Claude can revise the plan.
 
-The hook is registered on `PreToolUse` (not `PermissionRequest`) so it fires before the permission flow and regardless of `--permission-mode`. This makes Request Changes (`deny`) work across all hosts, including Conductor — which runs Claude Code with `--permission-prompt-tool stdio --permission-mode bypassPermissions` and never surfaces a `PermissionRequest` hook decision. (Note: in Conductor, exiting plan mode on approve is still owned by Conductor's own plan-approval UI, so an `allow` decision does not by itself leave plan mode there.)
+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.
 
 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.
 

hooks/hooks.json

@@ -28,6 +28,18 @@
           }
         ]
       }
+    ],
+    "PermissionRequest": [
+      {
+        "matcher": "ExitPlanMode",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/bin/open-plan-annotator.mjs\"",
+            "timeout": 345600
+          }
+        ]
+      }
     ]
   }
 }

server/historyLifecycle.test.ts

@@ -244,6 +244,82 @@ describe("stdout immediacy", () => {
       rmSync(tempRoot, { recursive: true, force: true });
     }
   }, 15000);
+
+  test("PermissionRequest replays a cached PreToolUse decision without reopening the UI", async () => {
+    const tempRoot = mkdtempSync(join(tmpdir(), "open-plan-annotator-replay-"));
+    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: "acceptEdits",
+        hook_event_name: "PreToolUse",
+        tool_name: "ExitPlanMode",
+        tool_use_id: "tool-replay",
+      };
+      const env = {
+        NODE_ENV: "test",
+        XDG_CONFIG_HOME: configHome,
+        SHUTDOWN_DELAY_MS: "100",
+        PATH: `${fakeBin}${delimiter}${process.env.PATH ?? ""}`,
+      };
+
+      await runSession({ decision: "approve", plan: "Replay plan", env, hookEvent });
+
+      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_input: { plan: "Replay 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/index.ts

@@ -12,6 +12,7 @@ import {
   writeHookDecisionToStdout,
   writeReviewDecisionToStdout,
 } from "./runtime/decision.ts";
+import { consumeDecisionForPermissionRequest, storeDecisionForPermissionRequest } from "./runtime/decisionCache.ts";
 import { cleanupHistory, loadPlanHistory } from "./runtime/history.ts";
 import { loadHtmlContent } from "./runtime/html.ts";
 import { parseReviewRuntimeInput, parseRuntimeInput } from "./runtime/input.ts";
@@ -79,6 +80,15 @@ const runtimeInput = await (cliMode === "review"
 });
 
 const { hookEvent, planContent } = runtimeInput;
+
+if (runtimeInput.mode === "hook" && hookEvent.hook_event_name === "PermissionRequest") {
+  const cachedDecision = await consumeDecisionForPermissionRequest(hookEvent);
+  if (cachedDecision) {
+    await writeHookDecisionToStdout(cachedDecision, hookEvent);
+    process.exit(0);
+  }
+}
+
 const { configDir, historyRootDir, preferencesPath } = resolveRuntimePaths();
 const preferences = await loadPreferences(preferencesPath);
 const persistPreferences = createPreferencesPersister(preferencesPath, configDir);
@@ -135,7 +145,13 @@ await cleanupHistory(isDev, decision.approved, historyDir);
 if (runtimeInput.mode === "review") {
   await writeReviewDecisionToStdout(decision, runtimeInput.planPath ?? "");
 } else {
-  await writeHookDecisionToStdout(decision);
+  if (hookEvent.hook_event_name === "PreToolUse") {
+    await storeDecisionForPermissionRequest(hookEvent, decision).catch((err: unknown) => {
+      const message = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`open-plan-annotator: failed to cache hook decision: ${message}\n`);
+    });
+  }
+  await writeHookDecisionToStdout(decision, hookEvent);
 }
 
 const keepAliveMs = Number(process.env.SHUTDOWN_DELAY_MS) || 5000;

server/runtime/decision.ts

@@ -1,4 +1,4 @@
-import type { HookOutput, ReviewOutput, ServerDecision } from "../types.ts";
+import type { HookEvent, HookOutput, ReviewOutput, ServerDecision } from "../types.ts";
 
 export interface DecisionController {
   decisionPromise: Promise<ServerDecision>;
@@ -14,19 +14,29 @@ export function createDecisionController(): DecisionController {
   return { decisionPromise, resolveDecision };
 }
 
-export async function writeHookDecisionToStdout(decision: ServerDecision): Promise<void> {
-  const output: HookOutput = {
-    hookSpecificOutput: decision.approved
+export async function writeHookDecisionToStdout(decision: ServerDecision, hookEvent: HookEvent): Promise<void> {
+  const output: HookOutput =
+    hookEvent.hook_event_name === "PermissionRequest"
       ? {
-          hookEventName: "PreToolUse",
-          permissionDecision: "allow",
+          hookSpecificOutput: {
+            hookEventName: "PermissionRequest",
+            decision: decision.approved
+              ? { behavior: "allow" }
+              : { behavior: "deny", message: decision.feedback ?? "Plan changes requested." },
+          },
         }
       : {
-          hookEventName: "PreToolUse",
-          permissionDecision: "deny",
-          permissionDecisionReason: decision.feedback ?? "Plan changes requested.",
-        },
-  };
+          hookSpecificOutput: decision.approved
+            ? {
+                hookEventName: "PreToolUse",
+                permissionDecision: "allow",
+              }
+            : {
+                hookEventName: "PreToolUse",
+                permissionDecision: "deny",
+                permissionDecisionReason: decision.feedback ?? "Plan changes requested.",
+              },
+        };
 
   const jsonLine = `${JSON.stringify(output)}\n`;
   const { closeSync, writeSync } = await import("node:fs");

server/runtime/decisionCache.ts

@@ -0,0 +1,103 @@
+import { createHash } from "node:crypto";
+import { mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { HookEvent, ServerDecision } from "../types.ts";
+
+const CACHE_TTL_MS = 10 * 60 * 1000;
+const CACHE_DIR = join(tmpdir(), "open-plan-annotator-decisions");
+
+interface CachedDecision {
+  approved: boolean;
+  feedback?: string;
+  createdAt: number;
+}
+
+function cachePathForHookEvent(hookEvent: HookEvent): string {
+  const key = JSON.stringify({
+    sessionId: hookEvent.session_id,
+    transcriptPath: hookEvent.transcript_path,
+    cwd: hookEvent.cwd,
+    toolName: hookEvent.tool_name,
+    toolUseId: hookEvent.tool_use_id,
+  });
+  const digest = createHash("sha256").update(key).digest("hex");
+  return join(CACHE_DIR, `${digest}.json`);
+}
+
+function parseCachedDecision(value: unknown): CachedDecision | null {
+  if (!value || typeof value !== "object") {
+    return null;
+  }
+
+  const cached = value as { approved?: unknown; feedback?: unknown; createdAt?: unknown };
+  if (typeof cached.approved !== "boolean" || typeof cached.createdAt !== "number") {
+    return null;
+  }
+
+  if (cached.feedback !== undefined && typeof cached.feedback !== "string") {
+    return null;
+  }
+
+  return {
+    approved: cached.approved,
+    feedback: cached.feedback,
+    createdAt: cached.createdAt,
+  };
+}
+
+async function cleanupExpiredCacheEntries(now = Date.now()): Promise<void> {
+  let entries: string[];
+  try {
+    entries = await readdir(CACHE_DIR);
+  } catch {
+    return;
+  }
+
+  await Promise.all(
+    entries.map(async (entry) => {
+      if (!entry.endsWith(".json")) {
+        return;
+      }
+
+      const path = join(CACHE_DIR, entry);
+      try {
+        const cached = parseCachedDecision(JSON.parse(await readFile(path, "utf8")));
+        if (!cached || now - cached.createdAt > CACHE_TTL_MS) {
+          await rm(path, { force: true });
+        }
+      } catch {
+        await rm(path, { force: true });
+      }
+    }),
+  );
+}
+
+export async function storeDecisionForPermissionRequest(hookEvent: HookEvent, decision: ServerDecision): Promise<void> {
+  await cleanupExpiredCacheEntries();
+  await mkdir(CACHE_DIR, { recursive: true });
+  const cached: CachedDecision = {
+    approved: decision.approved,
+    feedback: decision.feedback,
+    createdAt: Date.now(),
+  };
+  await writeFile(cachePathForHookEvent(hookEvent), `${JSON.stringify(cached)}\n`, "utf8");
+}
+
+export async function consumeDecisionForPermissionRequest(hookEvent: HookEvent): Promise<ServerDecision | null> {
+  await cleanupExpiredCacheEntries();
+  const path = cachePathForHookEvent(hookEvent);
+
+  try {
+    const cached = parseCachedDecision(JSON.parse(await readFile(path, "utf8")));
+    await rm(path, { force: true });
+
+    if (!cached || Date.now() - cached.createdAt > CACHE_TTL_MS) {
+      return null;
+    }
+
+    return { approved: cached.approved, feedback: cached.feedback };
+  } catch {
+    return null;
+  }
+}

server/types.ts

@@ -25,13 +25,20 @@ export interface UserPreferences {
   autoCloseOnSubmit: boolean;
 }
 
-export interface HookOutput {
-  hookSpecificOutput: {
-    hookEventName: "PreToolUse";
-    permissionDecision: "allow" | "deny";
-    permissionDecisionReason?: string;
-  };
-}
+export type HookOutput =
+  | {
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse";
+        permissionDecision: "allow" | "deny";
+        permissionDecisionReason?: string;
+      };
+    }
+  | {
+      hookSpecificOutput: {
+        hookEventName: "PermissionRequest";
+        decision: { behavior: "allow" } | { behavior: "deny"; message: string };
+      };
+    };
 
 export interface HistoryKeySource {
   transcript_path?: unknown;