[ashx-j]

Phase 5 of the plugin system roadmap (#3, phase issue #9). It builds on #20, so until #14 to #20 merge this diff also shows their commits.

Plugins could see a message before it was sent, but not what happened after, and agents could list plugins but not use them. This adds a run-completed hook that never misses a run, gives the send hook the whole message, and lets agents drive plugins.

• turns.afterRunCompleted(handler) runs once for every run that ends (completed, interrupted, failed, cancelled or rolled back), in order. It is built from the plugin's own events.stored stream and storage: after each ended run it saves the event's sequence, so runs that end while the plugin is off or the server is down arrive when the plugin starts again. The first registration starts from now.
• turns.beforeDispatch now also gets the message id, a summary of each attachment (type, name, MIME type, size) and the model the message asked for.
• Agent tools. t3_plugins_invoke calls a method a plugin registered and t3_plugins_set_enabled turns a plugin on or off. Both count as writes, so read-only and plan-mode sessions can't call them. Like t3_plugins_list, they only appear once a plugin is installed.
• The tool policy item was already done in Phase 3: plugin write tools need the same access as built-in writes.

Changes from the roadmap (issue #9 is updated):

• Not built yet:
  • turns.onRuntimeRequest, which would let a plugin answer approvals. It needs rules the user sets per plugin, which this doesn't have yet.
  • Context providers with composer chips. They need a send-path change for each chip, and the send hook already appends context.
  • Plugin skills. Each provider finds skills on its own (Claude reads skill folders, Codex its own list), so plugin skills need a decision per adapter.
  • Server-handled slash commands. A plugin's web slash command (feat(plugins): palette, keybinding and composer commands from plugins #19) can already call its server half over rpc.invoke.
• afterRunCompleted keeps one saved position per registration, in registration order, rather than a name the plugin picks.

Measurements:

• Send path, measured with a benchmark of PluginHooks.beforeDispatch over 5,000 messages: about 1 µs per message with no hooks and about 15 µs with one no-op hook. Sending a message also writes to the database, which takes milliseconds.
• afterRunCompleted writes to the plugin's storage once per ended run, not once per event.
• With no plugins installed nothing changes: no hooks, and none of the plugin MCP tools are advertised. AgentContextBudget.test.ts passes unchanged.

Test plugins: none new. The behaviour is covered by tests against fake event streams and the existing fixtures (workbench-plugin for the send hook, mcp-plugin for the MCP tools).

Verification:

• api/turns.test.ts delivers runs that ended to a handler, skips a run still going, saves the position, and checks that a second activation resumes after the last handled run.
• PluginMcpTools.test.ts checks the 2 new tools appear only with a plugin installed, a read-only session can't invoke, and a full-access one invokes and toggles a plugin through the host's actions.
• PluginHost.test.ts and ThreadManagementService.test.ts pass with the richer hook message.
• vp run check:changed passed.
• Not verified: the 2 new tool descriptions with the mcp-tool-use eval, and a hook seeing a real provider turn. Both need paid agent turns.

Review: an adversarial review of #18 to #22 found issues in this PR; the fixes are in #23.

---

PR filed by Claude Opus 5.5 in Claude Code through T3 Code.