Skip to content

fix(plan): open docs linked beside the plan file - #1620

Merged
backnotprop merged 5 commits into
backnotprop:mainfrom
bendrucker:plan-open-linked-docs
Sep 27, 2026
Merged

backnotprop merged 5 commits into
backnotprop:mainfrom
bendrucker:plan-open-linked-docs

Conversation

@bendrucker

Copy link
Copy Markdown
Contributor

A plan that links a document beside it, like [evidence](foo-evidence.md), returned 404 when clicked in plan review. The link resolved against the working directory, but Claude Code writes the plan under ~/.claude/plans/. Closes #1443

Implementation

The hook now forwards planFilePath from Claude Code's ExitPlanMode input. The plan server trusts it only when the file's contents match the plan under review, because the path is model-generated tool input. /api/plan then advertises the plan's directory, and the client uses it as the base for linked-doc opens.

/api/doc serves a document from that directory only when the plan's text names the requested relative path, and only when the file stays inside the directory after symlink resolution. The directory never becomes an allowed root, so other plans in ~/.claude/plans/ stay unreachable. A name that doesn't resolve there falls through to the existing root resolution, so plans that link project docs relative to the working directory behave as before. Wikilinks count as naming name.md.

The name check is a substring match on the plan text, so a plain mention of a sibling filename counts the same as a link. That doesn't grant anything extra. A plan that can mention a file can also link it, and the human sees either one in the plan under review.

Only the Claude Code hook passes a plan path. Pi's plan file sits under the project root, where links already resolve. OpenCode's backing file is an internal copy in the data directory, so it has no siblings to link.

Testing

Added tests covering:

  • The content check on the plan file
  • Named and wikilinked siblings
  • Unnamed siblings, ../ escapes, and symlink escapes
  • A base other than the plan directory
  • Project docs resolved from the roots while the base is the plan directory

Verified end to end by piping a PermissionRequest event with planFilePath into the hook and clicking each link in a browser:

  • The linked sibling opened
  • The wikilinked sibling opened
  • A project doc linked relative to the working directory opened
  • An unnamed sibling returned 404 when requested directly

The recording shows the three clicks:

plan-linked-docs.mp4

Follow Up

Linked documents could be shown in the sidebar as well. I was going to try to tackle that as a follow-up pull request, but I'm happy to work on incorporating it here too.

Claude Code's ExitPlanMode input carries planFilePath under
~/.claude/plans/, outside the review root, so a relative link to a
sibling document returned 404. The plan server now trusts that path
when the file holds the plan under review, and /api/doc serves the
documents the plan names from its directory. The rest of the
directory stays unreachable.

Closes backnotprop#1443
@bendrucker bendrucker changed the title fix(plan): open documents linked beside the plan file fix(plan): open docs linked beside the plan file Sep 27, 2026
planNamesPath matched the requested path as a substring of the plan
text, so a link to evidence.md unlocked e.md and [[notes-extended]]
unlocked notes.md, reaching other files in ~/.claude/plans/. The plan
directory now serves only paths equal to one of the plan's link
targets (markdown links, wiki links, HTML href), normalized the same
way on both sides (no fragment or query, percent-decoded, ./ collapsed).
…irectory

The client sends the plan directory as base on every open. When that
directory sits inside the project it was trusted for root resolution,
so HTML links resolved only against it and lost the project-root
fallback. The plan-directory base now feeds only the plan-linked lookup;
root resolution runs without a base, as before. Documents that a linked
file beside the plan shadows a project doc of the same name.
resolvePlanLinkedDoc matched the normalized key but joined the raw
request onto the plan directory, so a ?/.. or #/.. suffix after a linked
name (linked.md?/../other-plan.md) collapsed to a sibling the plan never
linked. Every check and the path join now read the normalized key, which
also makes a percent-encoded link (my%20doc.md) open the decoded file.
Links written inside fenced code or code spans no longer count as
targets.
The fence-stripping regex backtracked quadratically on a long run of
backticks or tildes (50k chars took ~0.9s), as did the wiki-link
pattern on a run of [[ openers, and targets were recomputed on every
plan-directory /api/doc request, blocking the event loop. Code is now
stripped by a line scan, the wiki and href patterns stop at a newline
or the next opener, and readPlanFile stores the targets on PlanFile.
@backnotprop
backnotprop merged commit 3723ce2 into backnotprop:main Sep 27, 2026
24 checks passed
@backnotprop

Copy link
Copy Markdown
Owner

Thanks @bendrucker, this was a good fix and a real gap for Claude Code users, whose plans live in ~/.claude/plans. We pushed a few commits on top before merging:

  • Only files the plan actually links to (exact names, not substrings) can be opened beside the plan, so other saved plans in that folder stay unreachable.
  • The served file is always the normalized link target, so query/fragment tricks like linked.md?/../other.md can't reach unlinked files.
  • Links inside code blocks don't count, and link scanning runs in linear time and once per plan.
  • Plans saved inside the project keep the project-root fallback for HTML links.

It'll go out in the next release.

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.

Open docs linked from a plan

2 participants