Skip to content

fix(hook): review Claude's plan file, not its stale inline snapshot - #1667

Merged
backnotprop merged 3 commits into
backnotprop:mainfrom
workflow:fix/claude-stale-batched-plan
Oct 2, 2026
Merged

backnotprop merged 3 commits into
backnotprop:mainfrom
workflow:fix/claude-stale-batched-plan

Conversation

@workflow

@workflow workflow commented Oct 2, 2026

Copy link
Copy Markdown
Contributor

In Claude Code, plan review sometimes opened the previous version of a plan, typically the one just denied. This happens when the model edits the plan file and calls ExitPlanMode in the same assistant message, which recent models do often after a deny.

Cause

Claude Code fills ExitPlanMode's tool_input.plan from the plan file when it records the assistant message, before any of that message's tools run. When the same message also contains the Write/Edit of the plan file, the captured plan predates the edit. The hook rendered tool_input.plan, so it showed the stale text, and history and the approval recorded it too.

From a real session (Claude Code 2.1.280):

  • 17:42:24.647: Write to ~/.claude/plans/<slug>.md with the revised plan.
  • 17:42:24.649: ExitPlanMode recorded, with plan byte-identical to the denied version (5508 bytes).
  • 17:43:02: the Write result arrives.
  • The review showed the denied plan. Every batched Write/Edit + ExitPlanMode I could find in my transcripts had a stale plan.

tool_input.planFilePath is sent alongside, and by the time the PermissionRequest hook fires the file holds the edited plan. This is the Claude Code counterpart of the Pi race fixed in #1622.

What changed

  • apps/hook/server/claude-plan.ts (new): resolveClaudePlan reads planFilePath when it is sent and readable and non-empty. Otherwise it falls back to the inline plan, which keeps other hosts on the PermissionRequest path unchanged.
  • apps/hook/server/index.ts:
    • The non-Gemini branch uses resolveClaudePlan.
    • On approval, updatedInput carries the reviewed plan ({ ...event.tool_input, plan }), so the plan Claude Code proceeds with is the version the user approved, not the stale snapshot.
  • Unchanged: Gemini (already reads its plan from disk), Codex, OpenCode, Pi and Vibe.

Testing

  • bun test apps/hook/server/claude-plan.test.ts: 5 pass. With the resolver returning the inline plan (the behaviour on main), the stale-snapshot test fails.
  • bun test apps/hook/server: 350 pass, 0 fail.
  • End to end: I replayed the real stale PermissionRequest event from a session through bun apps/hook/server/index.ts with the built UI. /api/plan served the edited plan file (2538 bytes), not the stale inline snapshot (2352 bytes).
  • Live: I ran the same fix as a local wrapper around the 0.27.24 hook that rewrites tool_input.plan from planFilePath. I forced the batched case in Claude Code: deny, then edit + ExitPlanMode in one message. The transcript still recorded the stale plan, while the review and history/…/002.md showed the edited file.

Notes

  • This relies on Claude Code running the batched Write/Edit before the ExitPlanMode permission hook, which matches the timings above. If Claude Code ever ran them concurrently, the read could still race, and the fix would belong in Claude Code (filling plan when the tool runs, not when the message is recorded).

workflow and others added 3 commits October 2, 2026 20:20
Claude Code fills ExitPlanMode's plan from the plan file when it records the
assistant message. When the model edits the plan file and calls ExitPlanMode
in the same message, that snapshot predates the edit, so the review showed
the plan the user had just rejected. Read planFilePath at hook time instead,
and carry the reviewed plan in updatedInput on approval.

Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: workflow <w0rkflow@pm.me>
A batched plan edit and ExitPlanMode must review the edited file, and every
missing or unreadable source must fall back to the inline plan.

Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: workflow <w0rkflow@pm.me>
Only read planFilePath when it is an absolute .md path naming a regular
file within MAX_ANNOTATABLE_FILE_BYTES; otherwise fall back to the inline
plan. Reading a FIFO there blocked the hook forever, and an unbounded
file was read whole into memory. Tests cover the gate and that a
file-sourced plan passes readPlanFile's trust check for /api/doc.
@backnotprop
backnotprop merged commit cd50349 into backnotprop:main Oct 2, 2026
24 checks passed
@backnotprop

Copy link
Copy Markdown
Owner

Thanks @workflow, this is a real catch with a great write-up. Merged. I added one commit on top that only reads the plan file when it is an absolute .md regular file under 2 MB (same rule as the existing plan-file read), so a FIFO or huge file can't hang the hook. Claude Code 2.1.285 also fixed the root cause upstream, so this covers everyone on older versions. It ships in the next release.

workflow added a commit to workflow/dotfiles that referenced this pull request Oct 24, 2026
numtide/llm-agents.nix builds plannotator from source and updates daily;
the plugin, skills, commands and opencode plugin pin follow its src and
version. 0.28 reviews the plan file itself (backnotprop/plannotator#1667),
so the fresh-plan hook wrapper goes. Trust cache.numtide.com for it.

Assisted-by: Claude Code:claude-opus-5-5
Signed-off-by: workflow <w0rkflow@pm.me>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants