SMCP Phase 2b: the sanctum__tools governor goes live

The May 26 post ("SMCP Tool Governance: Attach, Detach, and Help as a Protocol") defined attach, detach, and help as a protocol. This one is the shipped implementation: a real governor that filters the advertised tool list to the attached set, gates detached calls with an attach hint, exposes a single sanctum__tools control tool, and boots a profile from an env var. The agent now sees a curated tool surface instead of the whole catalog. The protocol becomes a thing the agent can actually use.

Where the protocol left us

In May we argued that the right way to keep a model's tool surface small was not just to filter tools/list server-side, but to expose a protocol for shaping it from inside the conversation. Attach a tool, detach a tool, ask for help on what is available. The shape was right, the wire was right, and the part that was still missing was the thing the agent could actually call. A protocol that is not implemented is a diagram, and diagrams do not run.

That is the gap Phase 2b closes. The governor is now real code (commit a6fa39d, June 6), and the agent that boots today sees a curated tool surface by default instead of every plugin we have ever installed.

The major call: a real governor

The new file is governor.py - about 208 lines - and it is the single source of truth for what the agent is allowed to see and call. Its surface is small on purpose:

• an in-process registry (_attached / _catalog sets)
• attach(), detach(), attach_profile() to mutate it
• filter_tools() to apply it to tools/list
• gate_tool_call() to apply it to every other call
• handle_governor() to route the single sanctum__tools tool through its actions

smcp.py is the only place that wires the governor into the MCP surface: it imports the governor, calls set_catalog(...) at boot, appends the governor's own tool to the advertised list, routes sanctum__tools to handle_governor, and runs every other call through gate_tool_call before dispatch. The total change to smcp.py is small - roughly +22/-7 lines - and the rest of the file does not need to know the rules exist. That is the seam we wanted: a real policy layer that does not bleed into the rest of the runtime.

Mechanism 1: tools/list filtering

The first place the governor shows up is tools/list. list_tools_handler no longer returns the whole catalog; it returns governor.filter_tools(all_tools). By default, the agent sees only the tools currently in the attached set, plus the governor tool itself, so the agent always has a way to widen its own surface.

The intent is the same intent we wrote down in May: shrink the model's tools/list so the model reasons about fewer things and pays fewer tokens to do it. The mechanism is the boring part - a set membership check - and that is exactly why it is reliable.

Mechanism 2: call gating with attach hints

The second place is every non-governor tool call. Before dispatch, the call runs through governor.gate_tool_call(...). If the called tool is attached, the call proceeds. If it is not, the call does not fail with a generic permission error; it fails with an attach hint - a structured response that tells the agent to run sanctum__tools action=attach … for the tool it wanted to call.

This is the part the May 26 post did not have. The protocol said "detach" is a thing the agent can do; the implementation makes "detach" a thing that has a consequence. A detached call is no longer a silent error; it is a structured nudge toward the right next action. The agent that wanted to call tasks__create-task but had it detached now knows, in its own protocol, that the right move is to ask for it back.

Mechanism 3: the single sanctum__tools control tool

Rather than expose six or seven narrow control tools, the governor advertises exactly one: sanctum__tools. Behind it, a dispatcher routes the action parameter to the right handler. The full action set:

• help - describe the protocol and the available actions
• list-available - show what the catalog has, regardless of attachment
• list-attached - show what is currently attached
• attach - add a tool to the attached set
• detach - remove a tool from the attached set
• attach-profile - load a named profile (see below)

One tool, one job. The agent that wants to widen or shrink its surface goes through one well-known entry point, and that entry point is itself attached at all times. There is no path through which the agent loses the ability to recover its own surface.

Profiles: chatter, admin, full

The governor boots with a profile. The profile is selected by the env var SMCP_ATTACH_PROFILE at server start, and the three built-ins are:

• chatter - a curated subset of the tasks__ commands. This is the default-friendly profile: just enough surface to chat through tasks, no admin machinery, no plumbing. The list lives in _TASKS_PROFILES["chatter"] in governor.py.
• admin - all discovered tasks__ commands. The governor fills this in at runtime, not at code-write time, so adding a new tasks__ plugin automatically widens the admin surface.
• full - the entire catalog. For when you want the agent to see everything and the only policy is "use what you need."

Booting with SMCP_ATTACH_PROFILE=chatter is the small-surface default. Booting with admin is the floor-of-the-room default. Booting with full is the audit mode, and the audit mode is now a one-env-var change instead of a code change.

Done vs pending

Done:

• tools/list is filtered to the attached set plus the governor tool.
• Detached calls return attach hints, not silent errors.
• A single sanctum__tools control tool exposes the full action set.
• SMCP_ATTACH_PROFILE boots the server with chatter, admin, or full.
• The attach registry is a real in-process state, not a config-file lookup.

Pending:

• Profile persistence: the attached set is per-process today; a server restart drops the runtime state. The right next step is to make the attached set survive a restart for the same profile.
• Cross-call audit logging: the gate currently returns hints; it does not yet log every gated call into a queryable surface.
• Profile composition: chatter and admin are flat lists today. The next iteration should let one profile extend another.
• Per-tool policies (rate limits, scoped access) layered on top of attach/detach.

What's next

The next batch of work is mostly "make the surface that exists today durable and inspectable." Persist the attached set. Log gated calls. Compose profiles. None of that is on the protocol layer - the protocol is settled - and none of it changes how a plugin is written. It changes how the governor is operated.

The May 26 post was the picture. Phase 2b is the plane. The next post in this series, when it ships, will be the operation manual for running the governor at scale.