clawmates/docs/TOOL-CALL-ARCHITECTURE.md

Mission tool calls: what is actually true, and what to do

Research, 2026-08-19. Supersedes the claim "missions can't call tools at all", which I wrote and which is wrong.

The claim was wrong, and the truth is worse

Mission agents do call tools. Three of the four execution paths end in claude -p with Claude Code's own toolset and permissions pre-accepted:

Path	Command	Tools	Permission
Solo microVM	microvm_executor.rs:341	Read Edit Write Bash Agent	--permission-mode acceptEdits
Composed microVM	same, per node	same	same
Direct session	session_executor.rs:118	Read Edit Write Bash	acceptEdits
Container / ZeroClaw	claude -p --output-format json	see below	n/a

So the real position is not "no tools". It is:

Mission agents run Bash and Write with permissions pre-accepted, and nothing in this platform can gate them.

That is a stronger finding than the one it replaces. "Can't call tools" sounds like a missing feature. "Calls tools freely, ungated, and mostly unobserved" is a security posture, and it is the one we have.

Observe versus gate — they are different, and both are partial

As of 2026-08-21, with the container-tier hooks shipped:

Path	Has tools	We observe	We gate
Solo microVM	yes	yes — vm_tool_tap	yes — vm_tool_gate
Composed microVM	yes	yes — same tap	yes — same gate
Direct session	yes	no mechanism at all	no
Container / ZeroClaw	yes (see below)	yes — container_tool_hooks	yes — same

The direct-session row is the only remaining gap, and it is dormant: CLAWMATES_MISSION_EXECUTOR is unset in production, so that tier never runs. Checking that before building a tap for it is the reason there is no tap for it.

vm_tool_tap installs a PostToolUse hook, which fires after the tool has already run, and exit 0s unconditionally because a non-zero PostToolUse talks back to the model. It is telemetry and says so. It is structurally incapable of gating — which is why the gate is a separate PreToolUse hook rather than a stricter version of this one.

What the tap records. Until 2026-08-21 it kept the tool's name and the path its arguments named, and threw the arguments themselves away. A phase that recorded Bash × 6 could not answer whether it ran the tests, whether it committed, or whether it called an API a skill forbids. It now keeps the arguments, bounded: file bodies become a byte count, over-long strings are truncated with a marker. That is what makes skill_use able to score behaviour rather than the agent's own account of it.

The §15 GatePolicy has exactly one enforcement site — Runtime::drive, the chat loop — and its approvals are keyed to (session_id, message_id), which no mission phase can produce. A mission agent's Bash call is gated by nothing, anywhere.

Why the container tier looked tool-free

claude_cli builds claude -p … --output-format json, which returns a single final result object, and the provider then hardcodes tool_calls: Vec::new(). The tool calls happen; the transport discards them.

That is why ToolTrace.calls was empty on gw-04, and the comment in topology_exec.rs reads that emptiness as "§15 by construction: agents are provisioned tool-free". It is not by construction. It is the output format.

Proven, not assumed. Against the live runtime (Claude Code 2.1.228):

claude -p "Run the bash command: echo hello" \
  --output-format stream-json --verbose --allowedTools Bash

emits exactly what we need:

assistant block: tool_use  Bash
user block:      tool_result
assistant block: text
event: result success

The calls are fully observable. We ask for the wrong output format.

The door is deployed — 2026-08-21

Proven against the real binary in the runtime container, which is a two-minute loop rather than the ten-minute rebuild-and-run-a-mission one I reached for first:

claude -p --mcp-config <doc> --strict-mcp-config "List the MCP resources you can see"
  → lists skill:global/a11y-checklist, … (see the count caveat below)

claude -p … "Read skill:global/workspace-repo-commit-protocol, reply with its first heading"
  → # Mission repo + commit protocol

Connect, list and read all work. mission_orchestrator::install_skills_door writes the document at launch (mode 0600, under /root, never the checkout) and points the daemon at it in the same step.

No --allowedTools change was needed. That question was left open rather than guessed, and the guess would have been wrong in an expensive way: the daemon exposes no config read, so "adding" the MCP tools would have meant overwriting the seed's tools list and stripping Write and Bash from every mission agent — to solve a problem that does not exist.

It needed a credential first, and that was not "config"

The section below called this "config, not code". That was wrong, and the reason is authentication. /mcp/skills authenticated via AuthService::authenticate, which returns a full AuthedUser carrying the user's role; there was no narrower credential in the system. The document sits in a file the agent can cat — it runs Bash with egress — so the documented approach meant handing an owner-privileged API token to something explicitly untrusted. Checked before concluding: no such credential was in a mission container, so it would have been a new exposure rather than an existing one.

auth_sessions.scope fixes it. authenticate delegates to authenticate_scoped(token, SCOPE_FULL), so every existing caller rejects a narrow token and a route opts in by name; /mcp/skills is the only opt-in. Measured live with one token:

POST /mcp/skills   → 53 skill resources
GET  /api/missions → 401

And confirmed from inside a real mission

Run 8, all three agents, per-agent attributed:

Pedro  ListMcpResourcesTool  ReadMcpResourceTool  Write …
Ebele  ListMcpResourcesTool  ReadMcpResourceTool  Read …
Ahmad  ListMcpResourcesTool  ReadMcpResourceTool  Write …

The agent's own report: "53 MCP resources are available, all from the clawmates_skills server … skill:global/workspace-repo-commit-protocol was read and its first heading is # Mission repo + commit protocol."

Count caveat, and it is the usual lesson. The first probe's transcript said "58 MCP resources" and that number went into this document as though it were a measurement. It was the model's own paraphrase. The authoritative count is 53 — resources/list returns 53 and SELECT count(*) FROM skills is 53. A model's self-report is not an observation, which this project has now learned three separate times.

What this does NOT yet buy

Trigger is still not measured. pinned_skills_text still inlines full skill bodies, so the agent is still handed skills rather than reaching for them. The door makes retrieval possible; Trigger becomes real only when delivery switches to progressive disclosure — and that could regress Compliance, so it wants an A/B rather than a flip.

How it looked before it was plugged in

claude_cli.rs is ours — upstream zeroclaw-labs/zeroclaw has no such file. So is the feature that solves this, our own commit 88eef99d4 feat(providers): claude_cli --mcp-config + allow/disallow tools (act via door).

The provider already accepts:

• mcp_config → claude -p --mcp-config <file> --strict-mcp-config, so Claude Code's own MCP client connects to our door;
• tools → --allowedTools, auto-approving door tools;
• disallowed_tools → --disallowedTools, locking out Bash, Write, Edit, Read, … so the gated door is the only actuator.

deploy/clawmates-runtime/agent.config.example.toml documents the whole shape as [providers.models.claude_cli.door].

And in the live runtime: /zeroclaw-data/clawmates-mcp.json does not exist, the config has no [providers.*] block at all, and every mission claw is bound to claude_cli.default — which sets none of the three fields.

So my earlier conclusion that "claude_cli cannot reach MCP, therefore the skills server is unreachable" was wrong in its reasoning. The capability is built, documented by us, and simply never deployed.

Related: we have been setting agents.<alias>.mcp_bundles, which configures ZeroClaw's own MCP client for its native agent loop. A claude_cli agent's actuator is the claude subprocess, which reads mcp_config on the provider. We were turning a knob connected to a loop that does not run.

Upstream: nothing that solves this, one thing worth taking

We are 218 commits behind upstream/master. Scanning for anything relevant:

Superseded 2026-08-27 — now 331 behind, and the egress conclusion below is wrong: net_guard cannot see a mission's tool calls. See UPSTREAM-SCAN.md and MISSION-EGRESS.md.

• No upstream work on claude_cli — the file is ours; upstream has none.
• ACP (Agent Client Protocol) exists in the fork already (zeroclaw-gateway/src/acp.rs, zeroclaw-channels/src/acp_channel.rs); the three upstream commits since our merge are workspace-default and tool-approval-localization fixes, not new capability. ACP does surface tool calls natively and is a credible long-term transport, but it is a bigger move than the two fixes below and buys the same observability.
• feat(plugins): add shared egress policy foundation (#9137) — a network guard in zeroclaw-infra::net_guard with DNS pinning, IPv4-mapped metadata blocking, proxy-conflict surfacing. This is the one upstream item genuinely worth pulling: it is defence for the egress problem we have not solved, and it is hardening we would otherwise write ourselves.

RESOLVED 2026-08-21 — hooks, not the transport

Everything above the line is still an accurate account of how mission tools work. The recommendation that followed it was wrong, and this is what actually happened.

stream-json was necessary-looking and useless

Shipped, deployed, and driven with a real mission: zero tool.call events, with the parser working perfectly. TurnEvent::ToolCall — the thing the gateway turns into a frame — is emitted from tool_execution.rs, i.e. only for tools ZeroClaw itself executes. Claude Code runs its tools inside its own subprocess, so the event never fires. A provider that knows about the calls changes nothing.

Worse, v1 was harmful: it returned the observed calls as ChatResponse.tool_calls, meaning "execute these", so the loop tried to run Bash, got Unknown tool: Bash, and fed that back to the model — an extra LLM round-trip per call, telling the agent its own work failed. The mission completed correctly anyway, which is why it would have gone unnoticed. Fixed in fork 295d6d3b8 (log them, never return them); the corrected image streamjson2 was built and deliberately not deployed, since it delivers nothing on its own.

What worked: hooks

claude -p --settings <doc> honours PreToolUse and PostToolUse, so the gate blocks and the tap records without ZeroClaw being involved at all. That sidesteps the entire TurnEvent problem instead of trying to solve it.

Shipped, and verified end to end on a real mission:

tool.call   10    Bash 6, Read 3, Write 1
file.touch   4    research/tapproof.md

• --settings on claude_cli — fork be9c34b1c
• container_tool_hooks writes both hook scripts and one settings document into the mission container
• set_claude_cli_settings points the provider at it
• phase_runner::drain_finished_container_phases collects the tap into mission_events, idempotent by truncation

The lesson worth keeping

Two of the three ranked recommendations below were written from reading the code, and the first one was confidently wrong in a way that took a deployment and a live mission to discover. The gate (§2) was right. The transport fix (§1) was not — the evidence for it was an absence, and an absence had another explanation.

The original recommendations, kept for the record

1. Observability — switch claude_cli to stream-json (WRONG — see above)

In our fork: --output-format stream-json --verbose, parse tool_use / tool_result blocks into ChatResponse.tool_calls instead of Vec::new().

Unblocks: real tool.call events on the container tier; ToolTrace.calls non-empty; Skill-Use Trigger becomes observable on that tier for the first time. Risk: the parser must handle a stream rather than one object, and --verbose is required alongside it.

2. A real gate — use the PreToolUse hook (small, mechanism already proven)

vm_stop_gate.rs records that PreToolUse fires under claude -p in our image, and it is used nowhere — one doc-comment mention, zero call sites. Same install pattern as the tap, but exit-2-to-deny instead of exit-0.

This is the only pre-execution gate available to the microVM and direct-session paths, and it is the one thing that would let §15 mean something for missions. It must be added to vm_tool_tap::guest_settings, the single settings writer, or it will clobber Stop and PostToolUse.

Also: give the direct-session path the tap at all. It is the same settings file, written into a container instead of a VM, and today that tier is completely dark.

3. Deploy the door we already built (config, not code)

Create /zeroclaw-data/clawmates-mcp.json, define a door-shaped provider alias, and bind mission claws to it. Gets the container tier a gated actuator and makes the clawmates_skills MCP server genuinely reachable — which would let skills move from inlined bodies to progressive disclosure, and make Trigger measurable the way the paper defines it.

Sequencing note: (1) and (2) are independent of (3) and worth doing first, because they make the container tier legible before we change what it can do.

Not recommended yet

Replacing the mission executor with ProviderExecutor or the chat Runtime. The blockers are real and structural, not wiring: Runtime::send_message requires a chat session row, an agent row, two message rows and an agent_runs row, and its approval key is (session_id, message_id); ToolContext carries no path, checkout, container or VM handle; cm-runtime's files tool is a blob store that rejects absolute paths by construction, and its shell tool executes in a per-agent sandbox with zero egress and no mission mount. Every mission-shaped concept would have to be invented first.

The cheap fixes above deliver the observability and the gate. The executor swap is a different project, and it should be justified by something other than tool calls — which, it turns out, we already have.