[Feature]: Make proposed plans first-class artifacts for implementation and compaction

[baohappy02]

Before submitting

• I searched existing issues and did not find a duplicate.
• I am describing a concrete problem or use case, not just a vague idea.

Area

apps/server, apps/web, packages/contracts or packages/shared

Problem or use case

Plan mode and implementation handoff are currently very text-centric.

In Codex plan mode, the agent is intentionally blocked from mutating repo-tracked files, so a finalized plan cannot simply be written out by the agent while staying in plan mode. That makes sense for the mode contract, but it also means there is no durable plan artifact created as part of the normal plan workflow.

Today, the implementation handoff appears to work by resending the full plan markdown in the next prompt (for example, PLEASE IMPLEMENT THIS PLAN: ...) while sourceProposedPlan is mainly an internal reference. That is robust for the initial handoff, but it has a few drawbacks:

• it duplicates a potentially large block of text into implementation prompts
• it does not create a first-class plan artifact that can be reused later
• the inline resend mostly helps at kickoff, but it is not durable memory
• if a long-running implementation gets compacted shortly after start, a lot of the value of resending the full plan is lost
• relying on prior prompt text or on a remembered file path is fragile unless the host/server can persist and rehydrate that reference after compaction or resume
• if the plan file lives outside the active worktree or is only mentioned in prompt text, a later thread or resumed session may no longer be able to recover it cleanly

The key pain point here is compaction durability, not just token efficiency.

Proposed solution

Treat proposed plans as first-class artifacts managed by T3 Code itself rather than by the agent in plan mode.

Suggested behavior:

• when a <proposed_plan> is finalized, persist the canonical markdown in the DB as today, and optionally materialize a deterministic local artifact such as .t3/plans/<plan-id>.md
• make that file creation a host-side action, not an agent-side file write, so it does not violate plan mode's non-mutating contract
• persist artifact metadata alongside the plan, such as relative path, checksum, project/worktree ownership, and enough identity to find the same artifact later
• prefer storing the artifact in a location that can actually be reached by the eventual implementation session, rather than only in app-local state outside the working context
• when the user clicks Implement, prefer a short handoff prompt plus a server-side plan artifact/reference rehydration step instead of always copying the full markdown back into the user-visible prompt
• when a session is compacted, resumed, or a new implementation thread is created, automatically rehydrate the same canonical plan artifact/reference
• if the artifact is unavailable or the provider cannot consume the reference cleanly, fall back to the stored planMarkdown

I think this should be a hybrid system, not an all-or-nothing replacement for the current prompt-based fallback.

Why this matters

This would make plan -> implement handoff more durable in long-running sessions, especially when compaction or thread switching happens.

The biggest win is not just using fewer tokens. The bigger win is that the plan can survive compaction as a canonical source of truth that the host can rehydrate when the model no longer remembers the original prompt or file path.

It also avoids asking plan mode to break its own contract just to get a useful saved artifact, and it opens the door to a cleaner workflow where plans behave more like reusable documents than one-time prompt text.

Benefits:

• plan context can survive compaction, resume, and new-thread implementation more reliably
• inline full-plan resend becomes a fallback rather than the only source of truth
• less prompt duplication during implementation handoff
• clearer separation between plan content, plan metadata, and implementation prompts
• a workflow that aligns better with research file / plan file session handoff patterns used in other agent tools

Smallest useful scope

A first pass could keep the current inline prompt fallback, but add:

• host-side export/materialization of finalized proposed plans
• persisted artifact metadata for each proposed plan
• implement flow that rehydrates from planId first and falls back to inline markdown only when needed
• compaction/resume handling that reuses the same canonical plan artifact instead of assuming the model still remembers the earlier prompt

Even that narrower version would already solve the main durability problem.

Alternatives considered

Current behavior: resend the full plan markdown inline for implementation.

• simple and robust for the initial handoff
• but duplicates tokens and does not create a durable plan artifact
• once compaction happens, this behaves more like a one-time kickoff hint than a persistent source of truth

Path-only prompt handoff.

• lighter than inlining the full plan
• but still fragile if compaction or session loss makes the model forget the path, unless the host rehydrates it

Risks or tradeoffs

• this likely needs coordination across apps/web, apps/server, and shared contracts
• artifact paths must be deterministic and portable enough across worktrees and local environments
• providers may differ in how well they can consume artifact references, so an inline fallback is probably still necessary
• if artifacts are stored only in app-local paths that the active implementation context cannot access, the durability story breaks down
• there is a risk of adding complexity if this is implemented as provider-specific special cases instead of a single canonical handoff mechanism

Examples or references

Related issues and context:

• feat/bug: Plan mode prevents writing to file. #448 feat/bug: Plan mode prevents writing to file.
• [Feature]: When finishing Plan mode, provide an option for clearing context before starting implementation #1058 [Feature]: When finishing Plan mode, provide an option for clearing context before starting implementation
• CodeLayer navigation inspo #304 CodeLayer navigation inspo (mentions the workflow of starting a new session with a research/plan file)

[juliusmarminge]

Proposed plans are now first-class state, can be saved to the workspace, and are preserved through implementation handoff and compaction.

This was closed as part of a large repo-wide maintenance sweep. If you think it's still relevant, please reopen.