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 mutating tool (write_file, edit_file, delete_file, bash with non-read-only commands, spawn_agent, MCP writes) until the model has called record_plan for the current turn. The plan is a precondition.
• 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.

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.
• Agent design → System instructions — how to phrase the AGENTS.md so the model reaches for a plan naturally.