docs(plugins): add example plugins and record plugin trust constraints

[saphid]

Model: Claude Opus 5.5. Rebased onto current main with Claude Opus 5.5 on 2026-10-12.

Stacked on #16064 (and #15010). Review only the top commit: af081bc.

Rebased 2026-10-10 onto #15010's current head (1fe8efd69a, on main 57b3780). The example plugin test imports the status store from @t3tools/provider-core, its new home. Main moved the host process references into a HostProcess module (#17641), so the example plugin test provides the process arguments through HostProcess.Arguments. GPT-6.1 Sol (high) reviewed this port: SHIP. Captures below were taken at the revisions they name. At this head (af081bceca) these pass: focused tests (1 files, 4 tests), typecheck (t3), lint and fmt on the changed files, knip.

Problem

The plugin guide documents each capability on its own, but there is no complete plugin to start from. An author has to assemble a manifest, an entry module and the proposed API from separate sections, and nothing in the repository proves that a plugin written that way actually loads and runs.

Why this qualifies

This is the "who uses this?" answer for the plugin system proposed in #6837 / #6714, and no maintainer has agreed to that system yet. It is a small, optional PR on top of the plugin approvals PR and the plugin PRs below it, so it rides on the same plugin-system approval; if the plugin system is declined, this closes with it. Nothing depends on it. Previous PR in this stack: feat(server,web,mobile): let plugins answer approval requests (#16064).

Fix

• examples/plugins/turn-notifier: events + notifications. Notifies when a turn ends ("Fix login finished", "Upgrade deps failed"), or when finishing it fails (names the failed step), and offers to open the thread.
• examples/plugins/todo-count: tools. Gives agents a count_todos tool with a declared input schema; read-only, skips hidden entries and node_modules, caps files and size, honours cancellation.
• examples/plugins/machine-label: events + settings + status. Shows a configurable label and color on threads that finish a turn, defaulting to the host name.
• Each is a plain directory (manifest, one .mjs, a README with install steps) using only the documented proposed API. They are not workspace packages and nothing imports them.
• apps/server/src/plugins/examplePlugins.test.ts installs each copy through the real manifest loader, catalogue (add → approve → enable) and supervisor, running real plugin child processes, and asserts the notifications, tool results and statuses a user would see.
• docs/user/plugins.md "Writing a plugin" points to the examples.
• docs/internals/plugins.md records the cross-PR decisions a maintainer could otherwise get wrong, now that every capability in this stack exists: plugins are trusted code and the child process is an availability boundary, not a sandbox; consent binds an inspected tree, not executed-artifact identity; contributions are static manifest declarations and new requirements are new capability names; per-session capability gating at send time; reserved t3. names and host-method prefixes; the generation as revocation epoch and disable ordering.

Size: 12 files, +615; 320 lines are the test.

Evidence

Environment: macOS arm64; this PR on top of the plugin approvals PR.

Checks at this head (f2955898a3), re-run 2026-10-05 (CI=true, all exit 0):

• vp test run src/plugins/examplePlugins.test.ts (apps/server): 1 file, 4 tests pass. Recorded during development: with the examples removed, all 4 fail (FileSystem.copy … examples/plugins/<name> not found).
• vp run --filter t3 typecheck; vp lint --report-unused-disable-directives and vp fmt --check on the touched files (no warnings); vp run knip:check; vp run --filter @t3tools/web build; vp run build:desktop; node scripts/release-smoke.ts.
• As the top of the stack, this head also ran every focused test of the PRs from the Preview panel PR up to this one, per package: server 47 files / 866 tests, web 86 / 1245, client-runtime 17 / 286, contracts 10 / 76, mobile 9 / 151, desktop 2 / 39; typecheck of every package; lint (no warning on a line the stack changes), format and knip over the files the stack changes; vp run lint:mobile. All pass.

Dev-server run of each example (on an earlier revision of this PR that differs from this head only in an example README; isolated vp run dev, fresh state, environment labelled "Proof server", Codex GPT-6.1-Sol turns, WebSocket frames recorded from the browser). Before this PR there is no examples directory, so there is nothing to add. With this PR each example was copied unchanged, then added in Settings > Plugins, reviewed, trusted and enabled (plugins.add → plugins.consent with the digest → plugins.enable, generation 1):

Example	Effect observed
Machine label (Label set to "Proof server", Color Green)	after a finished turn, a status frame and a green "Proof server" chip on the thread; disabling clears it and the next turn does not restore it
Turn notifier	after a finished turn, a notification frame (example.turn-notifier, " finished", tone success) and a toast with Open thread; disabled → no notification on the next turn
TODO count	in a new session the agent called plugin_tools_list then plugin_tool_call and reported 3 markers (index.js 2, README.md 1); disabled → the next turn does not call it

Surfaces

• Entry points: none new; examples are added through the existing Settings > Plugins flow.
• Clients: no client code changes. Web, desktop and mobile show the examples' notifications and statuses through the existing renderers.
• Providers: the TODO tool is offered to every provider through T3's plugin tools MCP tools, as for any plugin tool; no adapter changes.
• Contracts: none.
• Reverse states: disable or remove the example plugin as for any plugin.
• Connection modes: unchanged; examples run on the server.
• Docs: one pointer in docs/user/plugins.md; each example has a README; docs/internals/plugins.md (decisions and constraints only).

Not verified

• The dev-server run used web only and Codex only; desktop and mobile show the same notifications and statuses through renderers this PR does not change.
• Rate-limit drops in the notifier and label, status eviction past 16 threads, scan truncation and cancellation are not exercised by the test.

Claude Opus 5.5 (build), GPT-6.1 Sol (review) and GPT-6 Astra (captures) via T3 Code
🤖 Generated with Claude Code

[macroscopeapp]

Macroscope has since reviewed this pull request. An earlier review was skipped by a cost limit; a review has now completed, so that notice no longer applies.

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — The requested range introduces a broad plugin execution platform spanning server processes, persistence, RPC authorization, MCP tools, npm distribution, client views, and orchestration behavior—not merely documentation or examples. It also changes product capability defaults and adds static-analysis suppression directives, making the security and integration surface unsuitable for automatic approval.

^{You can add or adjust custom eligibility rules. Learn more.}

[saphid]

Review requested

Date (UTC)	Reviewer	Where
2026-10-06	Julius	Discord DM

_{Logged so this PR shows when a maintainer was asked to review it.}