🤖 fix: soften plan-mode no-mutation guidance

[ammar-agent]

Summary

Plan Mode's "no mutations" instruction was phrased as an absolute, non-overridable rule. This reframes it as guidance: Plan Mode should default to read-only work and avoid implementation, but mutations that don't touch the tracked source tree are fine when implicit to the user's request (e.g. rewriting the plan file, filing a GitHub issue when asked, or downloading a file to analyze for the plan).

Background

Only one restriction is actually enforced at runtime: file_edit_* is locked to the plan file via validatePlanModeAccess (src/node/services/tools/fileCommon.ts). The rest of the "read-only only / no rm/mv/cp / no installs" language was prompt text presented as a hard rule, which over-constrained the planner. It also self-contradicted — the runtime instruction told the agent to "delete the file and start fresh" while simultaneously banning rm.

src/common/utils/ui/modeUtils.ts documents the intended split: non-overridable workspace facts live in the runtime instruction, while opinionated/overridable guidance lives in the agent spec so users can override it. This change honors that split.

Implementation

• src/common/utils/ui/modeUtils.ts (getPlanModeInstruction, the non-overridable runtime instruction): removed the absolute READ-ONLY and read-only-bash rules; replaced with the accurate hard fact (file_edit_* locked to the plan file) plus explicit permission to create, rewrite, or delete the plan file itself — resolving the old contradiction.
• src/node/builtinAgents/plan.md (overridable agent spec): added a "Scope: planning, not implementation" section framing no-mutations as guidance, not a hard rule; clarified that mutating the tracked source tree (project edits, dependency installs, migrations, commits) is for Exec mode, while non-source-tree mutations implicit to the request are permitted. Removed the now-redundant "switch to Exec mode" bullet.
• Regenerated artifacts: docs/agents/index.mdx (via scripts/gen_docs.ts), builtInAgentContent.generated.ts, and builtInSkillContent.generated.ts (mux-docs skill snapshot).

Validation

• bun scripts/gen_docs.ts check confirms docs are in sync; agent/skill regeneration is idempotent.
• Existing modeUtils.test.ts and streamContextBuilder.test.ts still pass (they assert on Plan file path: / propose_plan, both retained).

Risks

Low — prompt/guidance-only change plus regenerated docs. No runtime enforcement logic was modified; the file_edit_* lock remains intact.

---

Generated with mux • Model: anthropic:claude-opus-4-8 • Thinking: xhigh • Cost: $2.73

[ammar-agent]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. What shall we delve into next?

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".