feat(core): add agent instructions and use them for Plan mode - #63669

Issue for this PR

Closes #62628. That loop came from Plan re-adding its reminder as a synthetic after each compaction, which woke the session again. This PR removes that code path, and after compaction the rules sit in the system prompt with no new message. The review bot ran the issue's mock-model repro with a 3,000-token context limit: on dev it never exits (1,873 requests in 40s), and with this PR it exits after 3 requests (title, one compaction, the answer).

Related: #62554 (this removes the one-off Plan reminder it lists; the other one-off prompts are unchanged).

The revert case below relies on #63667, which is merged.

Type of change

• Bug fix
• New feature
• Refactor / code improvement
• Documentation

What does this PR do?

Agents get an instructions field: text that's added to the default prompt while the agent is selected, without replacing the prompt like system does. It's either a string or { active, inactive? }:

item.instructions = "You are in Plan mode..."  // generic note on leaving
item.instructions = { active: "You are in Plan mode...", inactive: "You are NO LONGER in Plan mode..." }

active is a state: it's shown whenever the agent is selected, including in the system prompt after compaction. inactive is a transition: it's sent once when the session switches away and never again, so after compaction on another agent neither text appears. Plan mode now uses it in place of its own reminder machinery.

Today a plugin can't add rules for one agent without trouble. Plan injects "you are in Plan mode" reminders as synthetic messages and repairs them on every request after compaction or a revert (#42652). The internal orchestrator agent adds its rules to the system prompt in a context hook, so every agent switch rewrites the start of the prompt and loses the cache, and the rules aren't stored with the session.

Core already has the right mechanism: instruction sources, which are stored per session, shown once in the system prompt, and sent as an update at the next step when they change. This adds one source, core/agent, built from the selected agent:

agent has instructions → value { id, name, text }
agent has none         → removed

first step             → text in the system prompt
switch in              → text as an update before the next prompt
switch away            → the agent's inactive text, or "The Plan agent
                          is no longer selected. Its instructions from
                          earlier in this conversation no longer apply."
switch between two     → one update: inactive text + new agent's text
plugin edits the text  → "...instructions changed. These replace..."

Compaction, reverts, forks and storage all come from the existing instruction state. The source is last in the list because it changes most often.

plan.ts now sets instructions and drops the event subscription, the per-request repair hook and the reminder bookkeeping (about 60 lines). Its permissions and the error rewrite for blocked edits stay.

What changes for Plan, beyond the plumbing:

• Both texts are the same as before, without the <system-reminder> wrapper, since they're now system content.
• The rules arrive as a system message (or in the system prompt), not as a user-role synthetic. In the timeline that shows as the standard "Instructions updated: core/agent" row.
• Switching away and back before the next step now sends nothing. Plan used to send both reminders.
• Sessions that are already in Plan when this ships still have the old reminder in history and get the rules once more as an update. That happens once per session.

The field is plugin-only for now. Agent config files have their own schema, and config already uses instructions for a list of file paths, so exposing this there needs a naming decision first.

How did you verify your code works?

New runner scenarios under agent instructions in session-runner.test.ts use real agents and switchAgent: starting in an agent, switching in, switching to an agent without instructions, switching away and back, switching between two agents, a plugin editing the text, a custom inactive text (including that it isn't shown after compaction), editing only the inactive text (sends nothing), compaction, reverting past the switch in, and reverting between switching in and out. All pass, and the system prompt stays byte-identical across switches.

• bun run check from the root.
• Ran every core test file that touches history, compaction, forks, reverts, instructions, agents or Plan (179 files): 3,141 pass. The 33 failures are in shell, integration, provider and image test files and fail the same way on unchanged dev on my machine.
• Regenerated the client (AgentInfo.instructions).

Screenshots / recordings

Not a UI change; the timeline row is the existing instruction notice.

Checklist

• I have tested my changes locally
• I have not included unrelated changes in this PR

Added by the opencode bot (AI-generated).

Fixes #62628

Related: #62554

Public API: adds optional instructions (string or { active, inactive? }) to Agent.Info (schema, plugin agent editor, client AgentInfo, OpenAPI); backwards compatible