[design] A "tmux Operator" can drive iTerm2 — a creator cannot declare which backend an agent may touch, or that it owns exactly one terminal

[serge-ivo]

Why the "tmux Operator" shows iTerm2 windows

Because it is not a tmux agent. It is a generic terminal agent with a tmux name.

Its declared tools (live, list_instance_tools on cda75e28) are the generic connector's:

terminal_list_targets · terminal_capture · terminal_run_command
terminal_send_keys · terminal_new_target · terminal_kill_target

terminal_list_targets takes backend: "all" | "tmux" | "kitty" | "iterm2", defaulting to
all (connectors/terminal.ts:50), and backend(input) (:22) simply reads back whatever the
model passed. Nothing in the agent's capabilities constrains it. So the name is a label and the
capability is "every local terminal on the machine" — the agent behaved correctly and reported two
iTerm2 windows, because that is genuinely what it can reach.

There is an immediate fix that needs no code. A tmux-only connector already exists in the
registry (registry.ts id: "tmux") with six backend-exclusive tools — tmux_list_sessions,
tmux_capture_pane, tmux_run_command, tmux_send_keys, tmux_new_session, tmux_kill_session.
Declaring THOSE in the agent's capabilities.tools instead of the generic six makes it a tmux agent
by construction: there is no iTerm2 code path behind them to reach. That is a config change on the
agent row.

That fixes one agent. The rest of this ticket is why the general case still needs building.

The gap: there is no ceiling a creator can declare

capabilities already lets a creator declare surfaces, runtime, workflow and a tool allowlist. What
it cannot express is a constraint on a tool's arguments — "this agent may use the terminal
connector, but only the tmux backend". Today the only ways to narrow an agent are to pick different
tools (works here only because a parallel tmux connector happens to exist) or to write it in the
prompt (which is a request, not a boundary — #386 and ADR 0001 are this month's reminder that a
constraint the model can talk around is not a constraint).

The design — two different things, and conflating them is the mistake

The platform already draws this line and it should be applied rather than re-invented:

	who decides	what it is
capabilities (surfaces/runtime/workflow/tools)	creator, immutable by the subscriber	what the agent IS
instance config / settings (runnerNode, settings, consent)	subscriber	how this instance is used

(a) The ceiling — creator-declared, subscriber CANNOT widen.
capabilities.surfaceOptions.terminal.backends: ["tmux"]. A tmux Operator can never see or touch
iTerm2, on any instance, ever. This belongs with capabilities because it is a claim the catalog
makes: the agent is named tmux Operator and lintAgentClaims (#362) already checks descriptions
against capabilities. If a subscriber could widen it, the description would become false by
configuration — which is exactly what that lint exists to prevent.

(b) The binding — subscriber-chosen, within the ceiling.
Which tmux session this instance drives. This is the same shape as config.runnerNode: that the
agent uses a machine is the creator's declaration; which machine is the subscriber's.

"Should an agent connect to only one terminal?" — right for some, wrong as a rule

Making one-target universal would be a mistake, and the platform already has the precedent for the
correct form: surfaceOptions.coding.repos: "single" — declared per agent, not imposed on all
of them, because a Repo Coder owns one repo while the Coder surveys many.

The same reasoning applies exactly:

• A named operator ("Heartfull tmux") should be targets: "single". One pane, one job. A
  mis-selected target here is a shell command on a real machine, so ambiguity is not a cosmetic
  problem.
• The generic Terminal Operator must stay many — surveying every backend is its entire
  purpose; it is the agent that exercises the connector.

So: terminal: { backends: [...], targets: "single" | "many" }, default many so nothing
changes for existing agents, and a single-target agent gets a subscriber-bound target the way it
gets a bound runner node.

The part to insist on: enforce it server-side

With targets: "single" and a bound target, a tool call naming a different target must be
refused in the handler, not merely hidden in the console and not merely discouraged in the
prompt. Same for a backend outside the declared set. Otherwise this is a labelling convention that
the first confidently-wrong model call walks straight through — and the value here is the guarantee,
not the tidiness.

Natural home: runRegistryTool, beside the write-consent gate (#90), which is already the place a
tool call is refused for reasons the model does not control.

Acceptance

• A creator can declare terminal.backends and terminal.targets; both are sanitised and
  persisted with the rest of capabilities.
• A subscriber can bind a target within the ceiling and cannot widen the backends.
• A call naming an out-of-scope backend or a non-bound target is refused server-side, with a
  message that says which constraint applied.
• The seeded tmux/kitty/iTerm2 Operator agents declare their own backend, so their names become
  true.
• Default (backends absent, targets: "many") is byte-identical to today.

Files: workers/api/src/lib/connectors/terminal.ts:22,50,
workers/api/src/lib/connectors/registry.ts (terminal + tmux),
workers/api/src/lib/agent-capabilities.ts (sanitizeDeclaredCapabilities, surfaceOptions),
workers/api/src/lib/tool-registry.ts (runRegistryTool). Related: #362 (claims lint), #90
(write consent), ADR 0001 (why a prompt is not a boundary).

[serge-ivo]

Rescoped by the direction doc — docs/capability-constraints.md — and split, because this ticket currently contains three things with different costs and different readiness.

• [chore] The tmux, kitty and iTerm2 Operators are one agent wearing three names — declare backend-exclusive tools (no code) #403 — the seed fix, available today with no code: the tmux Operator declares the six backend-exclusive tmux_* tools that already exist in the registry. kitty and iTerm2 cannot be fixed that way (there is no kitty_* connector), which is precisely the argument for the primitive rather than a fourth parallel connector.
• [design] Capability constraints — declare what an agent may PASS, and enforce it at the tool boundary #404 — the primitive: constraint declaration, sanitiser, and the enforcement point in runRegistryTool. That enforcement point is genuinely new — optionsFor is consulted in four places today and none of them is the dispatcher, because every existing constraint works by withholding a tool before dispatch is reached.
• This ticket — the terminal consumer on top of [design] Capability constraints — declare what an agent may PASS, and enforce it at the tool boundary #404: the backends ceiling and the targets: "single" binding, with the subscriber binding one target the way runnerNode binds one machine.

The design in the body stands unchanged; what moves is that the general mechanism is built once, with terminal as its first consumer, rather than as terminal-shaped code that #75 would later have to reinvent for domains and actions.

[serge-ivo]

Shipped in f3df811, deployed, and verified in production.

The consumer half on top of #404's primitive: the targets binding, and the seed change that finally
makes the kitty and iTerm2 names true. #403 (78d2cfe) had already fixed the tmux Operator by
construction; #404 (d8eb4f8) built the backends ceiling and the dispatcher gate. This is the rest.

Migration is 0104, not 0103. 0103 was claimed for this lane up front, and the #424 lane landed
0103_error_log_level_and_repeats.sql first. check-migrations --require-history after the rebase
caught it and it was renumbered before the push — which is the gate working, and is the 0092
collision from #369 not repeating.

Acceptance, measured against live production

#	Acceptance	Verdict
1	Creator declares terminal.backends + terminal.targets; sanitised and persisted with capabilities	✅
2	Subscriber can bind a target within the ceiling and cannot widen the backends	✅ code + tests; binding not exercised live (see below)
3	Out-of-scope backend / non-bound target refused server-side, message says which constraint	✅ verified live
4	Seeded operator agents declare their own backend, so their names become true	✅ verified live
5	Default (backends absent, targets: "many") byte-identical to today	✅ verified live

Criterion 4 — production D1 after the deploy applied 0104:

kitty-operator      backends=["kitty"]    tools intact (6 terminal_*)   description rewritten
iterm-operator      backends=["iterm2"]   tools intact (6 terminal_*)   description rewritten
terminal-operator   backends=null         untouched — generic by design
tmux-operator       backends=null         untouched — already true via 0099's tmux_* tools

The path-specific json_set did not drop the tools, which was the #415 whole-object trap this
migration deliberately avoided.

Criterion 3 — the refusal, called through runRegistryTool on live instances:

kitty-operator  · terminal_list_targets {backend:"iterm2"}
  → "Refused by this agent's declared capability constraint `terminal.backends` (kitty):
     \"iterm2\" is not a terminal backend this agent may use."   success:false

iterm-operator  · terminal_list_targets {backend:"kitty"}
  → "Refused by this agent's declared capability constraint `terminal.backends` (iterm2):
     \"kitty\" is not a terminal backend this agent may use."    success:false

Criterion 5 — the control, and it is the exact scenario this ticket opened with. The
unconstrained terminal-operator asked for backend: "iterm2" still returns the owner's two iTerm2
windows:

[{"backend":"iterm2","id":"1:1:1","name":"✳ Claude Code (node)"},
 {"backend":"iterm2","id":"1:2:1","name":"✳ Host knowledge base on Glassdocs (node)"}]

That is the disclosure the ticket was filed about — correct here, because this agent is named the
generic Terminal Operator and its description says so. The same call on the kitty Operator is now
refused. The behaviour did not change for anyone who did not declare a ceiling.

And kitty-operator asking for its own backend passes the gate and returns [] (no kitty panes
running) — a success, not a refusal, so the ceiling narrows rather than bricks.

Design decisions worth recording

• tmux-operator deliberately gets no terminal ceiling. Since 0099 it declares tmux_* tools,
  whose connector has no constraint vocabulary, so parseConstraintSpec would drop a terminal
  ceiling on the next agent write. Storing config the sanitiser deletes reads to the next person as a
  ceiling that exists. Its claim is already true by construction, which is the stronger guarantee.
• terminal-operator left unconstrained, per this ticket's body — surveying every backend is its
  purpose.
• Rejected: suffix-only matching of a bound target. kitty:main and tmux:main share one, and
  accepting it would silently redirect a command onto the bound pane instead of refusing it.
• Rejected: gating terminal_new_target under single. "May not create a second terminal" is
  expressible by not declaring the tool — the allowlist's job. This constraint is about arguments.

Not done, deliberately

• The targets: "single" binding is built but unexercised in production. The vocabulary, the
  GET/PUT /v1/instances/{id}/terminal-target route (modelled on /runner-node) and the dispatcher
  enforcement all exist and are tested at runRegistryTool — bind-within-ceiling, the widen attempt,
  a non-bound target refused with callRunner asserted never called. But no catalog agent declares
  targets: "single" yet, so I could not exercise it end to end the way I exercised backends.
  Saying that plainly rather than rounding criterion 2 up.
• No console control for the binding — it would render for nobody today. It belongs with the first
  agent that declares single; worth a ticket then.
• lintAgentClaims still does not read constraints. [design] Capability constraints — declare what an agent may PASS, and enforce it at the tool boundary #404's close-out said "[design] A "tmux Operator" can drive iTerm2 — a creator cannot declare which backend an agent may touch, or that it owns exactly one terminal #402 wants the first",
  but it is on neither ticket's acceptance list and criterion 4 is satisfied by the data change.
  operator-backend-ceiling.test.ts records that a green lint tick is not a verdict here.
• The tool schema shown to the model still advertises all three backends for a constrained agent
  (unchanged from [design] Capability constraints — declare what an agent may PASS, and enforce it at the tool boundary #404 — the in-band refusal names the constraint, so it self-corrects).
• enforceConstraints cannot post-filter a tool's results. Under a single-backend ceiling that
  is equivalent to filtering; under a two-backend one it would not be. Separate ticket if it matters.

Verified

pnpm typecheck · pnpm vitest run 6488 passed / 395 files · biome --error-on-warnings ·
design-tokens · agents-allowlist · qa-config · file-size · check-migrations --require-history
(105 migrations, 104 distinct) · test-isolation · docs:drift (297/297) — all re-run after the
rebase and the 0103→0104 renumber, not before. CI green, Deploy API Worker green.

pnpm test:e2e: 248 passed, 1 failed — console.spec.ts:1779 "browser runtime docs show the ProAgentStore runtime architecture". Pre-existing on main: it fails identically on a clean
tree, and this change touches no console code or docs page. Flagging it as a separate problem rather
than attributing it here.