Plan Mode — master tracker for the 9-PR upstream rollout

Replaces the original umbrella PR #68939 (closed) which consolidated 10 dependent sub-PRs but couldn't land because the cumulative diff (~38k lines, 734 commits behind main) was too large for productive review. After several restructurings, the work is now decomposed into 9 focused PRs: 6 numbered per-part PRs + 2 thematic carve-outs + 1 integration bundle.

Status: all 9 PRs open and ready for review. Maintainer takeover-ready (with a small bot-feedback triage queue noted below).

What plan mode is

An opt-in, per-session workflow where agents must propose a structured, approvable plan (title + steps + assumptions + risks + verification criteria) before executing any mutating tool (bash, edit, write, apply_patch, process management, messaging, etc.). The user reviews, edits, approves, or rejects with feedback; only on approve/edit do the mutation tools unlock for that session.

• Default state: OFF. No existing session or model behaves differently on merge until opt-in via /plan on or model-specific agents.defaults.planMode.autoEnableFor config.
• Spans the stack: 6 new agent tools, 2 runtime gates (mutation gate + subagent gate), 4-state approval state machine, disk-persisted markdown plan files (audit trail), live sidebar rendering in webchat, universal /plan slash commands across Telegram/Slack/Discord/iMessage/Signal/Matrix/CLI/WhatsApp.
• Tests: 200+ added (unit/integration/e2e).
• Risk profile: Additive + flag-gated. Rollback = flag flip (agents.defaults.planMode.enabled: false).

The 9 PRs

Numbered per-part stack (sequential merge in order)

Thematic carve-outs (sibling to numbered stack)

Integration bundle

Suggested merge order: 1/6 → 2/6 → 3/6 → 4/6 → 5/6 → 6/6 → INJECTIONS → AUTOMATION → (optional) FULL for integration verification.

Single-merge alternative: maintainer can merge [Plan Mode FULL] (#70071) as one bundle and close the per-part PRs.

What was deferred (schema-reserved or follow-up)

These are noted in code comments at src/config/types.agent-defaults.ts:316–355 (the authoritative source) and shipped as schema-only:

• agents.defaults.planMode.autoEnableFor — model-pattern auto-enable (schema reserved; runtime scanner deferred to follow-up cycle)
• agents.defaults.planMode.approvalTimeoutSeconds — cron watchdog (schema reserved; timeout firing deferred)
• /plan self-test slash-command harness — non-blocking hardening
• Bug B: stale approval-card auto-dismiss on expiry — webchat UX polish
• Non-web-channel inline-button cards (Telegram/Slack/Discord text-only via /plan commands today)
• GPT-5 prompt foundation (was [Plan Mode 9/9] OPTIONAL, closed as [Plan Mode 9/9] (OPTIONAL) GPT-5 prompt foundation #69449) — separate focused PR after this rollout settles + a GPT-5.4 deep-dive cycle

Bot review status (as of 2026-04-22 ~16:30 GMT+7)

Greptile + Copilot + Codex have fired on all 9 PRs. Triage so far:

• [Plan Mode 1/6] Plan-state foundation #70031 (1/6): ✅ P0 fixed (bf19766b5a removes forward-reference imports + duplicate sessions_spawn). Remaining: 3 P2 (plan-store startsWith, path resolution, etc.) — queued.
• All other 8 PRs: acknowledgment comments posted. ~12 P1s + ~30 P2/nits queued for a focused follow-up cycle (~3-4 hours of work).

Each per-part PR has an explicit "stack-coordination concerns are by design (red CI expected)" note in its body header. Real source-code bugs queued for the follow-up cycle will be fixed with Fixed in {SHA} replies on each inline thread per the standard pr-review-loop pattern.

Rollout journey (for context — closed predecessor PRs)

• #68939 — original consolidated umbrella PR, closed in favor of decomposition (38k lines too large for review)
• #69324 — first decomposition attempt, also too large
• #69449 — GPT-5 prompt foundation (was Plan Mode 9/9 OPTIONAL), deferred to separate cycle
• #70011, #70015–#70020 — initial 7-PR per-part attempt; closed because they had cumulative diffs (10k–30k each) instead of clean per-part diffs. Replaced by current 9-PR rollout with proper per-part isolation.

Historical issues (already closed — for reference)

These were the original tracking issues split out of #68939's stack. All closed when their content landed in the precursor PRs:

• #67538 — plan mode runtime + escalating retry + auto-continue
• #67541 — plan template support for skill-driven planning
• #67542 — cross-session plan store with file-level locking (TOCTOU fix)
• #67840 — plan-mode integration bridge wiring
• #67512 — GPT-5.4 prompt discipline + personality bridge

Maintainer-handoff checklist

• All 9 PRs open with focused per-part diffs + cross-references
• Foundation PR ([Plan Mode 1/6] Plan-state foundation #70031) compiles cleanly after P0 fix
• Original umbrella PR (feat(plan-mode): full rollout + iter-1/2/3 hardening (consolidates PRs A/B/C/D/E/F/7/8/10/11) #68939) closed with its narrative carried forward to this issue
• Stale local fork PRs closed with redirect comments to this issue
• Bot-feedback triage cycle completed (~12 P1s + ~30 P2/nits)
• FULL bundle manual smoke verified end-to-end
• Maintainer-handoff summary added when triage closes

Suggested next steps (any order)

1. Review the foundation — start with #70031 [Plan Mode 1/6]. It's the most-load-bearing piece (schema + persister + hydration). Architecture doc lives in #70070 [Plan Mode 6/6] (docs/plans/PLAN-MODE-ARCHITECTURE.md).
2. Decide landing strategy — sequential merge (1/6 → 6/6 + INJECTIONS + AUTOMATION) for line-level review, OR single-merge of [[Plan Mode FULL] Integrated bundle for testing (Parts 1\u20136 + automation + executing-state lifecycle) #70071 FULL] for integration testing.
3. Wait on bot triage — we'll close out the remaining P1/P2 bot threads in a focused cycle within ~24h. Each thread will get a Fixed in {SHA} or Won't fix: {rationale} reply.

This issue is the master tracker for the plan-mode rollout. Comments here drive priorities; per-PR comments drive line-level review.