Three defects the first sweep left behind, each caught by a rule the guard did not yet have. Statuses. RULES.md gives three; the tree had 25 values, and the free-text ones were carrying progress. "Implemented (wiring landed)" and "Ratified (rev. 2e). Rev. 2e adds the OpenTaskByPR lookup. Rev. 2d revised section 10..." were both changelogs living in the one field the other rules exempt. Every PRD now declares Draft, Approved or Finalised and nothing else; five that declared nothing now declare one. A revision number moves to **Revision:**, a pointer to the authoritative document to **Authority:**, and what a past revision changed to git. CLAUDE.md's citation of state-store-contract rev. 2e still resolves. Stale cross-references. "Supersedes the 2026-09-03 open question", "this bullet previously said", "an earlier draft of this document claimed" all point at text the reader cannot see, because it was replaced. A supersede marker survives only when it names a file, a section or a symbol that can be found. Temporal hedges. 100 uses of today, currently and right now across 31 files. Each dates its sentence to the day it was written: "[notify] today is one webhook URL, read in one place" stops being true the moment this design lands, while still reading as the premise it rests on. The header-field exemption was also too wide. "**Date:** 2026-09-03, Channel resolved 2026-09-22" smuggled a dated status into the one line the rules did not read; the exemption is now a Date holding only a date and a Status holding only one of the three.
11 KiB
MCP client and tool-guardrail completion
Status: Approved
Epic: archie-core-1786637493439-140-2cee2e9b / GitHub #161 ("[EPIC] Tools:
central registry, MCP client, guardrails").
This document is scoped to five sub-features of that epic: MCP server-initiated sampling, the per-server parallel-tool-calls flag, sandboxed MCP tool servers, a Firecracker sandbox backend, and sequential dispatch with per-result previews.
Out of scope, and not to be touched: the central registry
(internal/tools/registry.go), all three MCP transports (stdio/HTTP/SSE,
internal/tools/mcp/transport*.go), reconnect-with-backoff
(transport.go), guardrail loop detection
(internal/tools/guardrail.go), idempotent/mutating classification
(internal/tools/classification.go), concurrent tool dispatch (#183), and
progressive disclosure wiring (internal/app/archied). These are settled and
production-wired.
Problem
bd search "MCP client" shows five closed transport beads and one open:
server-initiated sampling (#151). internal/tools/mcp/client.go
holds a single callMu *sync.Mutex that serializes every tools/call
regardless of server — ParallelToolCalls does not exist on the MCPServer
config struct (internal/config/config.go), confirming #177 is a
real gap, not a stale bead. #178 (wire MCP tool servers for the chat agent,
sandboxed) and #179 (Firecracker substrate) have no corresponding code —
MCP servers run as whatever the config's Command/Args launches,
unsandboxed. #182 (sequential tool dispatch with per-result previews) is
open; concurrent dispatch (#183) is closed, so there are two dispatch paths
and this PRD decides how they coexist.
Design
Sub-features are independent; there is no new shared type this document introduces. Each section below stands alone.
MCP server-initiated sampling (#151)
Decision. Implement as a callback on mcp.Client, not a second
transport. The MCP spec's sampling/createMessage request flows server→client
over the same connection each transport already maintains
(transport.go's stdio/HTTP/SSE all multiplex request and response frames).
Add a SamplingHandler func(context.Context, SamplingRequest) (SamplingResult, error)
field to the client's config struct next to the existing transport fields,
defaulting to nil (server sampling requests get a JSON-RPC "not supported"
error when unset — never a silent drop).
Call site. internal/tools/mcp/client.go — add the handler field and a
dispatch branch in whatever function demuxes incoming server
messages by method name (the same switch that already routes
notifications/*). Wire a concrete handler in
internal/app/archied/main.go that routes the sampling request through the
same chat-model call path chatGenerateOptions already uses, so a
server-initiated sample gets the daemon's configured model, not a second
provider client.
Reuse check. The chat model invocation path already exists
(chatGenerateOptions, main.go); this reuses it rather than adding a
parallel model-calling path for MCP sampling.
Failure mapping.
| condition | contract error |
|---|---|
no SamplingHandler configured |
JSON-RPC method-not-found, per spec |
| handler returns error | JSON-RPC internal error, message from handler |
| handler timeout | JSON-RPC timeout error; use the transport's existing request-timeout config, not a new one |
Testing. Fakeable entirely — a stub SamplingHandler and a fake
transport that emits a sampling/createMessage frame. No real backend
needed; belongs in task check.
Per-server parallel-tool-calls flag (#177)
Decision. ParallelToolCalls bool (default false) goes on MCPServer
in internal/config/config.go, next to Transport/Command. The
mutex in client.go becomes per-server: when ParallelToolCalls is
false (default, and the only behavior), keep the single callMu
serializing that server's calls exactly as now; when true, drop the mutex for
that server's Client instance entirely and let the caller's own
concurrency (already proven by the closed concurrent-dispatch bead, #183)
handle it. This is additive — no server's behavior changes unless an operator
opts in.
Call site. internal/config/config.go (struct field),
internal/tools/mcp/client.go (make the mutex conditional on the
field), and wherever MCPServer configs are turned into Client instances
at daemon startup (the constructor that reads internal/config's MCP block).
config.example.toml's commented MCP block gets the new field documented
with its default.
Testing. Unit test asserting two concurrent Calls to the same
Client block on each other when the flag is false and don't when true —
fakeable with a slow fake transport. task check.
Sandboxed MCP tool servers for the chat agent (#178) and Firecracker substrate (#179)
Decision. These two beads are one design decision, not two: #179 is an
alternate execution backend for #178, not separate scope. Sandbox MCP
servers that a chat-turn config marks as untrusted (a new
Sandboxed bool field on MCPServer, default false — existing
configured servers are unaffected) behind the same ContainerPool the
daemon already uses to run agent work
(internal/container/pool.go, per CLAUDE.md's WriteTaskJSON trap and the
Acquire/Release lifecycle daemon.go's acquireTaskContainer already
proves). Do not build a second sandbox mechanism: an MCP stdio server is a
subprocess exactly like an agent task container's entrypoint, so launching it
via ContainerPool.Acquire with stdio piped to the mcp.Client transport is
the smallest change, not new plumbing.
Firecracker is not built now. ContainerPool's existing Docker-backed
isolation is the shipped backend; Firecracker becomes a second
implementation of the same acquire/release contract only if a concrete
escape or resource-isolation gap is measured against Docker-backed sandboxing
in production. Recording this as the deletion/promotion gate keeps #179
honestly OPEN instead of speculatively building an unused backend, per
CLAUDE.md's Architectural Simplicity rule.
Call site. internal/config/config.go (MCPServer.Sandboxed), the MCP
client constructor (route sandboxed servers' process launch through
container.Pool.Acquire instead of os/exec directly), and
internal/container/pool.go (confirm its Acquire contract accepts a
stdio-piped, non-worktree workload — if it assumes a git worktree
per CLAUDE.md's WriteTaskJSON note, add the narrower entrypoint variant
there rather than duplicating the pool).
Error/failure mapping.
| condition | contract error |
|---|---|
| pool exhausted (no container slot) | MCP client returns connection-refused equivalent; server marked unavailable in the registry until retried |
| container fails health/start | same as #151's handler-error path — surfaced through the client's existing reconnect/backoff (transport.go), not a new retry loop |
Testing. Sandboxed=false path is the existing, already-tested
unsandboxed flow — no change. Sandboxed=true needs a real
ContainerPool (Docker) — manual smoke command, not task check; document
the exact command in the runbook this PRD's issue links to once implemented.
Sequential tool dispatch with per-result previews (#182)
Decision. This coexists with concurrent dispatch (#183, closed) as a
second, explicit mode selected by the caller — not a replacement. Concurrent
dispatch is for independent tool calls in one turn; sequential-with-preview
is for a turn where each result should be surfaced to the operator (or the
next tool call) before the next call fires — e.g. a mutating tool chain where
showing intermediate state matters. Add a DispatchMode enum
(Concurrent/Sequential) to whatever type selects the closed
#183 concurrent path, defaulting to Concurrent (its only behavior).
Call site. The tool-dispatch entry point that #183's closed
implementation lives in (grep the concurrent-dispatch symbol added for
#183 — same file gets the sequential branch, not a parallel file). Preview
surfacing reuses whatever channel-adapter interface already streams
intermediate turn output (the same seam internal/channels/telegram/ and
other adapters use for streaming deltas) — do not invent a second preview
transport.
Testing. Fakeable with a fake tool that returns staged results; assert
preview callbacks fire in order before the next call starts. task check.
Call site inventory
| concern | file | change |
|---|---|---|
| MCP client transports (stdio/HTTP/SSE) | internal/tools/mcp/transport*.go |
none — already handles this |
| MCP client call serialization | internal/tools/mcp/client.go |
change (#177) |
| MCP server config | internal/config/config.go |
new fields: ParallelToolCalls, Sandboxed |
| Sampling dispatch | internal/tools/mcp/client.go |
new (#151) |
| Sampling handler wiring | internal/app/archied/main.go |
new (#151), reuses chatGenerateOptions |
| Sandboxed MCP launch | MCP client constructor + internal/container/pool.go |
new (#178/#179) |
| Concurrent tool dispatch | dispatch entry point (closed #183) |
none — already handles this |
| Sequential tool dispatch + previews | same dispatch entry point | new (#182) |
| Guardrails / classification / registry / disclosure | internal/tools/guardrail.go, classification.go, registry.go, disclosure.go |
none — already handles this |
config.example.toml MCP block |
config.example.toml |
doc update for new fields |
Execution: multi-agent team breakdown
| sub-feature | issue | implementer scope | suggested council lenses | why |
|---|---|---|---|---|
| Server-initiated sampling | #151 |
client.go dispatch branch, main.go handler wiring |
lens-contract |
new JSON-RPC method surface crossing the MCP wire contract |
| Parallel-tool-calls flag | #177 |
config field, conditional mutex, constructor wiring | lens-boundary |
per-server behavior change must not leak into other servers' serialization |
| Sandboxed MCP + Firecracker deferral | #178, #179 |
config field, constructor routing through ContainerPool, pool entrypoint variant |
lens-operator, lens-deletionist |
operator: sandbox-down failure path; deletionist: keeps #179 from becoming unused scaffolding |
| Sequential dispatch with previews | #182 |
DispatchMode enum, sequential branch, preview reuse of streaming seam |
lens-maintainer |
two coexisting dispatch modes need a reader to tell which applies without re-deriving both |
File and link the beads
#151,#177,#178,#179,#182each get their description updated to point at this doc's matching##heading instead of restating the design.- Close
#179as a design decision (link here) rather than leaving it open as separate scope — it is not built now, and the doc records why. - Add the suggested lenses to each issue directly.