RuAgentBroker is the single tool execution authority¶
Terminal fallback update (2026-10-12): ADR 0017 replaces command-form and network approval heuristics with canonical launch-directory policy. Terminal classifications and reason codes below are historical.
Superseded in part by ADR 0014 on 2026-10-10: the Broker child process, its authenticated WebSocket lease and
RuAgentBroker.exewere retired when tool execution moved into the Host process; the single-execution-authority invariant this ADR established — one code path behindIToolGateway— remains in force. This file remains as migration history.Current execution profile: ADR 0011 keeps Broker as the sole execution authority and binds its canonical profile fallback to the explicit workspace trust decision. This ADR's original rationale and migration history remain unchanged.
Ru had two parallel tool implementations: the in-process HarnessToolGateway
(~4,300 lines inside the ASP.NET Core web host) and the process-isolated
Broker adapters, forcing manual parity between them. We decided that every
model-visible tool call (read, write, edit, bash)
executes only in RuAgentBroker, reached through the existing IToolGateway
seam (Evaluate → Prepare → Execute → Cancel); the Host keeps auth, policy
projection, approvals, and recovery persistence only.
The Broker is also the only authority for session-scoped Agent
permissions. It owns the in-memory SessionDirectoryGrantRegistry and
the typed pending-approval reasons (external_directory_required,
terminal_delete_requires_approval,
terminal_external_mutation_requires_approval,
terminal_timeout_requires_approval, web_approval_required,
terminal_unknown_executable).
Host and UI never persist or duplicate those grants; the GUI and CLI
only render the server-selected reason and forward a parameterless
approve.
Considered options¶
- Full Broker (chosen): one seam, one enforcement place, real process isolation; every tool call pays one loopback round-trip.
- Hybrid (rejected): files/terminal via Broker, web kept in the Host — keeps two execution paths alive, the root cause of the duplication.
- Reverse (rejected): keep the gateway and drop the Broker path — contradicts ADR-0001's "Broker is the execution boundary" and loses process isolation.
Consequences¶
- Preimage hashes for file mutations are Broker-captured (existing
FileHashService) and Host-persisted (FileRecoveryStore); recovery artifacts move through a run-scoped handoff directory, never through model proposals. The invariant "Host-captured preimage" becomes "Broker-captured, Host-persisted". HarnessToolGatewayand the duplicateRuBackend/Agent/CapabilityProfile.csare deleted; Broker policy (ADR-0007 profiles, ADR-0008 workspace coordination) applies unchanged.-
Migration is strangler-ordered: conformance tests first, then read-only file tools, mutations, terminal, web.
-
Migration status (updated 2026-09-03, cutover complete):
BrokerSessionsupports multiple concurrent run leases (per-lease close), andToolExecutionServiceresolves every workspace-bound adapter against the lease's canonical root — the precondition for multiple concurrent runs on one Broker process.- A shared
ToolGatewayConformancesuite (inRuAgent.Harness.Core.Tests/Conformance/) locks one behavior contract across adapters; both the in-process gateway andBrokerToolGatewaysubclassed it. Twenty-three facts run against the Broker adapter, including the migrated regression facts (preimage never in model proposals, canonicalis_regex,readwithop=helpread-only lifecycle). - All V2-wire tool families are conformance-locked: read-only file ops,
writewithop=write/edit/op=delete/op=restore(Broker-captured preimage), andbashwithmode=run/mode=shell(analyzer-safe forms allow; unrecognized forms ask). - The Host projects its
PolicySnapshotonto the wire viaPolicySnapshotMapper(hash-identical to the Core canonicalizer) andAgentRuntimeCoordinatorFactoryopens a per-run Broker lease throughBrokerToolGatewayFactory; gateway disposal is tied to run teardown inAgentRuntimeLoopService. The in-processHarnessToolGatewayand its fallback branch are deleted — a missing or unconfigured Broker descriptor fails closed (broker_gateway_unavailable) instead of silently downgrading to the Host path. - Approval bridging: the Host approval endpoint forwards the resolution to
the Broker (
approval.respond) before resuming the run and the resumed proposal executes with the returned one-timeauthorization_token(60 s). Only the explicitallow_alwaysdecision persists a reusable project-scope allow rule for the exact intent;allow_onceand the session-directory grant stay single-use. (The Broker lease rebind this paragraph once called future work landed with the 2026-10-07 amendment below: the gateway factory opens a new lease generation for the re-materialized snapshot.) - Web wiring: web options are defined once on the Host, forwarded to the
Broker process through the environment, and the v2 lease enables the
standalone
web_search/web_fetchtools only when enabled. Web tools always ask; explicit rules still deny first. Live-network acceptance stays separate per docs/operations/verification.md. - The v2 lease advertises the full authoritative tool set (16 bindings: system, help, notes, files, terminal) plus web when enabled.
RuBackend/Agent/CapabilityProfile.csis intentionally kept: it is the v1 wire contract ofAgentBrokerClient(chat/agent profiles), not a duplicate of the Broker's three-profile enum.
Amendment (2026-10-01): the v1 AgentBrokerClient wire contract was removed;
the execution authority description above is unchanged.
Amendment (2026-10-07): approvals also remember the exact approved intent for
the session. Any allow (allow_once or allow_always) records the intent in
the Host's in-process session approval ledger (exact PolicyMatcher fields,
30-minute TTL, 64 entries per session, cleared when the session is deleted);
the next drive pass re-materializes the snapshot with run-scope allow rules
and the gateway factory rebinds the Broker lease, so the same intent no
longer asks again in that session — including later calls in the same run.
External-directory approvals are excluded (the session directory grant is the
whole authorization), and a host restart asks again. allow_always
additionally still persists the durable project-scope rule.