Plan-first workflows

Use when: you want the model to think through the change first, commit that thinking to an artifact a human can review, and only then start editing. Common in code-review flows, migrations, change-management environments, and unattended runs where a bad plan is cheaper to catch than a bad diff.

How it works

core-agent has a plan-first posture with two strengths, picked via permissions.plan_mode:

• required — the permission gate refuses every non-exempt tool (write_file, edit_file, delete_file, bash, fetch_url, spawn_agent/spawn_remote_agent, and the mcp namespace) until the model has called record_plan for the current turn. The plan is a precondition. Reads through the built-in file and search tools stay exempt so the model can gather what it needs to write a plan worth reviewing. MCP reads are exempt too if the server is marked read_only: true — the gate only ever sees the namespace, never the underlying tool, so without that declaration it has no way to tell a list from a delete and gates both.
• advisory — record_plan is registered and the artifact is persisted exactly the same way, but nothing is blocked. The plan is an audit trail: the agent records what it’s about to do and then does it in the same turn.

Delegation counts as an action (v2.9+): under required, a parent that has recorded no plan can’t spawn a subagent to do the acting for it. Both doors onto a declarative subagent are held — spawn_agent { agent: "cluster" } and the cluster(request: …) parent tool that the same roster entry registers. stop_agent is the deliberate exception and is never gated in any mode: denying a cancel leaves running exactly what the model was trying to halt.

Reach for required when a human is genuinely going to read the plan before the diff lands. Reach for advisory for unattended runs where you want the reasoning on file but there is nobody to approve it — an armed gate with no approver just stalls the run.

Tip

Turn it on with permissions.plan_mode: "required" (or "advisory") in config, Permissions.PlanMode in the library API, or --plan-mode=required|advisory on the CLI. The older permissions.require_plan_artifact: true bool still works and means required, but it is deprecated — it cannot express advisory.

Where the details live

• Configuration → Plan mode — the mode table, composition with permissions.mode, migration off the deprecated bool.
• Built-in tools → Planning — the record_plan tool the model calls, its schema, and its mode-aware description.
• Built-in tools → record_plan — what the result tells the model it unblocked, the artifact’s author frontmatter, and how /replan picks which plan to revoke.
• Permissions → Background subagents and the gate — how the spawn gate keys its rules on the subagent being launched, and why one rule closes both doors.
• Agent design → System instructions — how to phrase the AGENTS.md so the model reaches for a plan naturally.