# Claw Code Agent Pipeline Review

Current-state review of the canonical implementation in /Users/cjerzak/Documents/claw-code/rust/, with emphasis on the main agent workflow, sub-agent path, MCP plumbing, and internet-facing logic.

Important scoping note: the Python files under src/ are a companion/reference workspace. The runtime that actually executes the agent pipeline is the Rust workspace described in README.md and CLAUDE.md.

Generated 2026-04-07 Canonical runtime: rust/ Primary loop: conversation.rs Internet tools: WebSearch, WebFetch Secondary surfaces: MCP, Agent, Worker, Task, Team, Cron

## Executive Summary

What the runtime actually is

The core agent is not a graph executor. It is a sequential conversation loop: user message into session state, provider stream produces assistant text and tool-use blocks, each tool-use is permission-checked and executed, tool results are appended back into session state, and the cycle repeats until the assistant stops without more tools.

Where internet logic lives

Internet access is implemented as built-in tools, not as a separate orchestration graph. WebSearch uses DuckDuckGo HTML search by default and parses links from returned HTML. WebFetch performs direct HTTP fetches, converts HTML to stripped text, and returns a prompt-conditioned summary.

confirmed review finding implemented runtime component implemented and actively wired path implemented surface with weaker or partial wiring

## Review Findings

High

### Built-in MCP tools are exposed, but they are not wired to the live CLI MCP state

The built-in tools ListMcpResources, ReadMcpResource, McpAuth, and MCP are part of the default tool manifest, but their handlers use global_mcp_registry() in the tools crate instead of the live RuntimeMcpState created by the CLI.

- tools/src/lib.rs:1058-1125 defines the built-in MCP tool surface.
- tools/src/lib.rs:1237-1243 dispatches those names to the built-in handlers.
- tools/src/lib.rs:1586-1654 resolves them through global_mcp_registry(), defaults omitted server to "default", and McpAuth only reports registry metadata instead of authenticating.
- rusty-claude-cli/src/main.rs:2821-2899 builds the actual connected MCP path as separate runtime tools: direct qualified tool names plus MCPTool, ListMcpResourcesTool, and ReadMcpResourceTool.

Impact: the model can see and call a dead or misleading MCP surface even when the real MCP path is available elsewhere. This is both a correctness issue and a tool-selection hazard.

Medium

### Task APIs are described as background execution, but the implementation is only an in-memory registry

TaskCreate and RunTaskPacket are described as background task launchers, but the handlers only allocate task records and return metadata. There is no subprocess spawn, worker thread, provider runtime, or scheduler integration behind these APIs.

- tools/src/lib.rs:746-843 describes background-task semantics.
- tools/src/lib.rs:1314-1425 shows the handlers only create, list, stop, update, and read records.
- runtime/src/task_registry.rs:1-190 is an in-memory registry with status and output fields, but no execution path.

Impact: higher-level orchestration can believe it has delegated work when it has only created bookkeeping entries. This is especially risky if later logic treats task status as operational truth.

Low

### Team and cron surfaces are metadata registries, not actual schedulers or parallel runners

The naming suggests operational behavior, but the current implementation only stores metadata. TeamCreate extracts incoming task_id values and creates a record; it does not launch sub-agents. CronCreate creates a schedule record; it does not install a scheduler or execute recurring work.

- tools/src/lib.rs:966-1010 advertises team and cron semantics.
- tools/src/lib.rs:1482-1528 shows the handlers just write registry state.
- runtime/src/team_cron_registry.rs:1-210 is registry-only backing.

Impact: this is less severe than the MCP mismatch because the behavior is at least internally consistent, but the tool descriptions currently overstate capability.

Design Note

### The actual sub-agent path is implemented and materially different from the task/team abstractions

The Agent tool is the real delegated execution path today. It writes an agent manifest, spawns a background thread, builds a dedicated provider-backed runtime with an allowed-tool subset, and persists terminal state on completion or failure.

- tools/src/lib.rs:3240-3358 shows manifest creation, thread spawn, and runtime execution.
- tools/src/lib.rs:3360-3478 shows sub-agent runtime assembly and per-agent tool allowlists.

## Canonical Runtime Topology

Entry

### CLI entrypoint

rust/crates/rusty-claude-cli/src/main.rs

Parses command mode, selects prompt vs REPL vs slash-command behavior, loads config, plugin state, and MCP state.

Prompt

### System prompt assembly

runtime/src/prompt.rs

Builds static instructions, environment context, git snapshot, discovered CLAUDE files, and rendered runtime config.

Policy

### Config and permissions

runtime/src/config.rs

runtime/src/permissions.rs

Merges user, project, and local settings, resolves permission mode, MCP config, hooks, sandbox, and allow/deny/ask rules.

Loop

### Conversation runtime

runtime/src/conversation.rs

Owns session state, streams assistant events, executes tools, records usage, and optionally auto-compacts context.

Providers

### LLM transport

api/src/providers/anthropic.rs

api/src/providers/openai_compat.rs

Converts session messages into provider requests, streams text/tool events back into the runtime, and tracks usage.

Tools

### Built-in, runtime, and plugin tools

tools/src/lib.rs

Defines built-in tools, merges plugin/runtime tools, enforces permissions, and executes the selected tool path.

CLI action -> load prompt/config/plugins/MCP -> build ConversationRuntime -> provider stream -> assistant events -> permission gate -> tool execution -> tool_result messages -> repeat until MessageStop without more tool uses

## Main Turn Workflow

User | | text prompt v ConversationRuntime::run_turn | push user message into Session | build ApiRequest { system_prompt, messages } v ApiClient::stream | CLI path: AnthropicRuntimeClient | Sub-agent path: ProviderRuntimeClient | both translate Session -> provider messages + tool definitions v Provider SSE / streaming response | text deltas | tool-use blocks | usage | message stop v build_assistant_message(...) | append assistant message to Session | extract pending tool uses v for each tool use in assistant message | pre-tool hook | permission authorize / ask / deny | execute tool | post-tool or failure hook | append tool_result to Session v loop again if tool uses were present | | no more tool uses v TurnSummary + optional auto compaction

Confirmed in runtime/src/conversation.rs:296-420. The loop is sequential over pending tool uses inside a single assistant message.

## Internet Logic

WebSearch

### Current search path

- tools/src/lib.rs:2544-2595 fetches search HTML and builds the result payload.
- tools/src/lib.rs:2622-2632 targets https://html.duckduckgo.com/html/ by default, unless CLAWD_WEB_SEARCH_BASE_URL overrides it.
- tools/src/lib.rs:2555-2568 parses hits from DuckDuckGo markup, falls back to generic link scraping if needed, applies allowed/blocked domain filters, dedupes, and truncates to 8 hits.
- The tool returns both human commentary and a structured hit list in one JSON object.

WebFetch

### Current fetch path

- tools/src/lib.rs:2510-2541 performs direct fetch, captures final URL, status, content-type, byte count, and a text summary.
- tools/src/lib.rs:2607-2619 upgrades http to https for non-localhost targets.
- tools/src/lib.rs:2635-2640 converts HTML bodies to plain text via a lightweight stripper; non-HTML is passed through as trimmed text.
- tools/src/lib.rs:2643-2650 and below make the returned summary depend on the prompt, mainly special-casing title and summary requests.

HTTP client defaults

tools/src/lib.rs:2598-2604 builds a blocking reqwest client with a 20 second timeout, redirect limit 10, and a fixed user-agent string.

Provider network path

The built-in internet tools are separate from model-provider transport. Provider calls happen in api/; web search and fetch happen in the tools crate.

Boundary

There is no separate research graph. Internet access is just another tool-use branch inside the same conversation loop and permission model.

## MCP Logic

Actively wired MCP path

The CLI loads MCP config, creates a live RuntimeMcpState, and turns discovered MCP tools into runtime tool definitions. When servers are present, it also exposes wrapper tools for generic MCP invocation and resource access.

- rusty-claude-cli/src/main.rs:2821-2899
- rusty-claude-cli/src/main.rs:6570-6688 executes runtime MCP tools through live state.

Partially wired MCP bridge

The runtime crate also contains runtime/src/mcp_tool_bridge.rs, a stateful registry abstraction that can register servers, list resources, and call tools through an McpServerManager. In the current CLI path, that bridge is not the object actually feeding model-visible MCP tools.

config -> RuntimeMcpState::new(...) -> discovered qualified MCP tool names + MCPTool/ListMcpResourcesTool/ReadMcpResourceTool -> CliToolExecutor runtime tool path

## Sub-agents, Workers, and Auxiliary Surfaces

Agent tool

This is the real delegated execution path. The tool writes an agent manifest, spawns a background thread, builds a provider-backed runtime, constrains tools by subagent type, and persists terminal state.

- tools/src/lib.rs:3240-3358 manifest and spawn path
- tools/src/lib.rs:3360-3478 per-subagent runtime and allowlists

Worker boot control plane

Worker tools are not themselves coding agents. They are a startup and delivery state machine for external coding workers: trust-gate detection, ready-for-prompt handshakes, prompt misdelivery detection, replay arming, restart, and terminate.

- runtime/src/worker_boot.rs
- Statuses include spawning, trust_required, ready_for_prompt, running, finished, and failed.

## Current Implementation Map

1

### Command selection

main.rs chooses prompt, REPL, slash command, status, auth, or support surface.

2

### Context assembly

prompt.rs discovers instruction files up the directory tree and embeds git snapshots plus merged config.

3

### Tool catalog build

tools/src/lib.rs combines built-in tools with plugin tools and runtime MCP tools.

4

### Permission policy build

main.rs:6704-6713 folds tool requirements and config-driven allow/deny/ask rules into one policy.

5

### Provider stream

The runtime sends the current session plus tool definitions to Anthropic or another provider-compatible adapter.

6

### Assistant event translation

Streaming responses are normalized into text deltas, tool-use events, usage records, and message stop markers.

7

### Tool execution

Each tool call is hook-checked, permission-gated, executed, and written back as a tool_result conversation block.

8

### Loop or finish

If tool-use blocks were present, the runtime loops. Otherwise it returns a turn summary and may auto-compact session history.

## Source of Truth Files

Area | Primary file(s) | What it controls
--- | --- | ---
CLI dispatch | rust/crates/rusty-claude-cli/src/main.rs | Program entry, command mode selection, runtime assembly, live MCP integration, interactive permission prompting.
Prompt/context | rust/crates/runtime/src/prompt.rs | System prompt scaffold, environment section, instruction-file discovery, git status/diff snapshots, rendered config section.
Settings merge | rust/crates/runtime/src/config.rs | User/project/local settings precedence, sandbox config, plugin config, MCP config, permission-mode decoding.
Permission engine | rust/crates/runtime/src/permissions.rs | Required tool modes, allow/deny/ask rules, prompt escalation, hook overrides.
Conversation loop | rust/crates/runtime/src/conversation.rs | Turn execution, session updates, hook callbacks, tool execution cycle, usage tracking, auto compaction.
Built-in tools | rust/crates/tools/src/lib.rs | WebSearch, WebFetch, file/search tools, Agent, Worker, Task, Team, Cron, MCP built-ins, REPL, config, notebook editing.
Provider adapters | rust/crates/api/src/providers/anthropic.rs | Anthropic transport and SSE event normalization.
Provider adapters | rust/crates/api/src/providers/openai_compat.rs | OpenAI/xAI-compatible transport, tool-definition translation, streaming normalization.
Live MCP bridge | rust/crates/runtime/src/mcp_stdio.rs | Configured stdio MCP server launch, discovery, tool calling, and manager lifecycle.
Worker boot plane | rust/crates/runtime/src/worker_boot.rs | Trust-gate detection, ready state, prompt replay, failure classification for external coding workers.
Reference-only graph | src/bootstrap_graph.py, src/command_graph.py | Useful for conceptual orientation, but not the canonical runtime path used by the Rust CLI.

## Bottom Line

The current Claw Code implementation is a session-centric, tool-augmented conversational runtime rather than a LangGraph-style planner. The core turn loop is coherent and the sub-agent path is real. The most important correctness gap today is the duplicated MCP surface: model-visible built-in MCP tools do not line up with the live CLI MCP plumbing. The next most important gap is naming fidelity: task, team, and cron APIs currently promise operational behavior that their implementations do not yet perform.