Let plugins give standing instructions to every agent turn - #3285

🤖

Summary

• Plugins could already add tools for agents, but they had no way to tell agents how or when to use them, or to set other standing rules. Tool descriptions are the only place that guidance can go, and a one-time note for the next turn is treated as data, not instructions.
• Plugins can now give standing instructions: ctx.agents.addInstructions({ id, text, when? }). While the plugin is on, every turn of the agents this copy of the app runs includes the text in a section named after the plugin. The agent follows it like its own instructions, but it cannot override Buzz's base prompt or the owner's requests.
• Every instruction is auditable. Each plugin's text gets its own section, labeled with that plugin's id (<plugin-instructions plugin="…">), so an agent's transcript shows exactly which plugin told it what, on which turn. A plugin's text cannot open or close a section, so it cannot add unlabeled instructions or pose as another plugin.
• Turning the plugin off, or a when that no longer matches, removes the instructions from the next turn. The base prompt tells agents that each turn carries the complete current set of plugin instructions, so a long-running session stops following instructions it saw in earlier turns.

Details

• Where it shows. The section sits at the end of each turn, before the end-of-turn attention note, in Claude, Codex, goose and Pi turns. It also appears in turns that installed harness plugins build with ctx.agents.harness.turnPrompt, in watch and timer turns, and in messages steered into a running turn. Every harness already ends its turns through one shared helper, so the change lives in that one place. Mesh agents build their own prompt and do not get the section.
• Why per turn, not the system prompt. Instructions in the system prompt would apply only to new sessions. Changing them would mean restarting sessions (Claude keeps one process per conversation). Per-turn text applies on the next turn with no restart. It costs tokens on every turn, so the docs ask authors to keep it short. Harness-native prompt hooks (registerHook with UserPromptSubmit) work for only one harness each, and only the first plugin that answers is used.
• Scoping. when(agent) is asked every time a turn's prompt is built. Only a literal true admits the instructions. A when that throws, or that returns a Promise, leaves out only that plugin's instructions. Sections are sorted by plugin and id, so the order plugins start in does not change the prompt.
• Framing. The plugin's text cannot open a section, or close its own section, the turn's event section, or the steering section. This keeps the prompt well formed. It is not a trust boundary: plugins are trusted code, and the docs say the text should be the plugin's own, not content from others.
• Types. AgentInstructions is exported from @buzz/author. AgentHandle.instructions() returns the set that is current for a turn.

🤖 Generated with Claude Code