Skip to content

Design: session-scoped /plan command with durable out-of-workspace plan storage #1081

Description

@cairn-intern

Background

PR #1074 ("feat(tui): add session-scoped plan mode and durable plan editing", recreated from closed #1008) implements a TUI /plan workflow. Per the contribution gate, that PR needs an approved design issue behind it before review: this issue is that design proposal.

Proposal: session-scoped /plan command

Add a /plan command to the TUI with four subcommands:

  • /plan on -- enter Plan mode for the current session.
  • /plan status -- show the current plan (from the durable store when available).
  • /plan open -- edit the session's plan in the user's configured editor ($VISUAL, then $EDITOR), saving through the durable store.
  • /plan off -- leave Plan mode and restore the previous permission mode.

Lifecycle

  • Entering Plan mode restricts the tool surface and permission requests and pauses automatic loops and goal continuations; they resume on exit.
  • Switching sessions exits Plan mode (loops paused by Plan mode are stopped with a user-visible notice, matching /new, /resume, and /btw).
  • Returning from a /btw conversation restores the parent session's mode.
  • Exiting Plan mode restores the permission mode the session had before.
  • A plan update is accepted only after its durable write succeeds (persist-then-propagate): a failed save is a failed tool operation that keeps the last accepted snapshot and surfaces the storage error, so the tool, panel, status, and durable file can never disagree.

Durable storage outside the workspace

  • Plans are stored per workspace/session outside the workspace, under protected directory handles: Unix no-follow checks and Windows reparse-point checks; all sandbox-writable temporary roots are excluded from trusted storage and editor staging.
  • Atomic replacement across processes with interprocess acceptance locking; baseline sidecars are required for editor edits, rejected saved edits are preserved for recovery, and cancellation is honored during writer-lock acquisition.
  • Newly written plan files carry a <!-- zero-plan-format: 2 --> marker so leading backslashes stay literal; the legacy decoder is retained and older plans convert with a baseline check before staging.

Why #664 does not cover this

#664 ("Expose spec-draft (Plan Mode) as a settable session mode over ACP", approved, assigned to @anandh8x) is scoped to the ACP wire surface: making spec-draft a settable/advertised session mode via session/set_mode so external ACP clients can offer the research-plan-approve workflow. This proposal is the interactive TUI surface instead: a /plan command with its own session-scoped lifecycle, tool/permission restrictions, loop pausing, /btw interplay, and a durable plan store with external editor support. The two share the "plan mode" concept but differ in client surface (ACP protocol vs terminal UI), scope of change (mode advertisement vs full plan editing workflow plus storage design), and assignee.

Open questions for maintainers

  1. Storage location conventions for plans outside the workspace (per-OS config roots vs a single Zero-managed root).
  2. Whether Plan mode should eventually also be advertised over ACP, and if so, how it relates to Expose spec-draft (Plan Mode) as a settable session mode over ACP #664's spec-draft mode.
  3. Naming: keep /plan as the command name, or align with spec-draft terminology?

Once the design here is agreed, PR #1074 can be rebased against this issue for review.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions