mirror of
https://github.com/ruvnet/RuVector.git
synced 2026-05-25 23:24:03 +00:00
930fca916f
SSE Proxy Decoupling (ADR-130): - Fix ruvbrain-sse proxy: proper MCP handshake, session creation, drain polling - Fix internal queue endpoints: session_create keeps receiver, drain returns buffered messages - Add response_queues to AppState for SSE proxy communication - Skip sparsifier for >5M edge graphs (was crashing on 16M edges) - Add SSE_DISABLED/MAX_SSE env vars for configurable connection limits - Route SSE to dedicated mcp.pi.ruv.io subdomain (Cloudflare CNAME) - Serve SSE at root / path on proxy (no /sse needed) - Update all references from pi.ruv.io/sse to mcp.pi.ruv.io - Fix Dockerfile consciousness crate build (feature/version mismatches) Claude Code CLI Source Research (ADR-133): - 19 research documents analyzing Claude Code internals (3000+ lines) - Decompiler script + RVF corpus builder for all major versions - Binary RVF containers for v0.2, v1.0, v2.0, v2.1 (300-2068 vectors each) - Call graphs, class hierarchies, state machines from minified source Integration Strategy (ADR-134): - 6-tier integration plan: WASM MCP, agents, hooks, cache, SDK, plugin - Integration guide with architecture diagrams and performance targets Co-Authored-By: claude-flow <ruv@ruv.net>
150 lines
4.5 KiB
Markdown
150 lines
4.5 KiB
Markdown
# Claude Code CLI: Tool System Architecture
|
|
|
|
## Built-in Tools
|
|
|
|
Claude Code registers tools with the Anthropic Messages API using the standard
|
|
tool_use / tool_result content block protocol.
|
|
|
|
### Tool Registry
|
|
|
|
The internal tool name map (display names for UI):
|
|
|
|
```javascript
|
|
{
|
|
Read: "Reading",
|
|
Write: "Writing",
|
|
Edit: "Editing",
|
|
MultiEdit: "Editing",
|
|
Bash: "Running",
|
|
Glob: "Searching",
|
|
Grep: "Searching",
|
|
WebFetch: "Fetching",
|
|
WebSearch: "Searching",
|
|
Task: "Running task",
|
|
FileReadTool: "Reading",
|
|
FileWriteTool: "Writing",
|
|
FileEditTool: "Editing",
|
|
GlobTool: "Searching",
|
|
GrepTool: "Searching",
|
|
BashTool: "Running",
|
|
NotebookEditTool: "Editing notebook",
|
|
LSP: "LSP"
|
|
}
|
|
```
|
|
|
|
### Tool Name Variables (Internal References)
|
|
|
|
| Variable | Tool Name |
|
|
|----------|-----------|
|
|
| `Yq` | Bash |
|
|
| `Bq` | Read |
|
|
| `c7` | Write |
|
|
| `wK` | Edit |
|
|
| `Gf` | Glob |
|
|
| `f9` | Grep |
|
|
| `sw` | WebFetch |
|
|
| `nE` | WebSearch |
|
|
| `IL` | NotebookEdit |
|
|
| `WX` | ToolSearch |
|
|
| `lI` | TodoWrite |
|
|
| `nj` | Skill |
|
|
| `tXH` | SendUserMessage |
|
|
|
|
### Tool Categories
|
|
|
|
**File Operations**:
|
|
- `Read` / `FileReadTool` -- Read files, images, PDFs, notebooks
|
|
- `Write` / `FileWriteTool` -- Create or overwrite files
|
|
- `Edit` / `FileEditTool` -- String replacement edits in existing files
|
|
- `MultiEdit` -- Multiple edits in a single tool call
|
|
- `NotebookEdit` / `NotebookEditTool` -- Jupyter notebook cell operations
|
|
|
|
**Search**:
|
|
- `Glob` / `GlobTool` -- File pattern matching (fast, sorted by mtime)
|
|
- `Grep` / `GrepTool` -- Content search via ripgrep with regex support
|
|
|
|
**Execution**:
|
|
- `Bash` / `BashTool` -- Shell command execution with sandbox support
|
|
- `Task` -- Spawn subagent for parallel work
|
|
|
|
**Web**:
|
|
- `WebFetch` -- HTTP fetch with content extraction
|
|
- `WebSearch` -- Web search integration
|
|
|
|
**Agent/System**:
|
|
- `ToolSearch` -- Discover deferred tools (MCP tools loaded on demand)
|
|
- `Skill` -- Execute registered skills/slash commands
|
|
- `SendUserMessage` -- Agent-to-user communication (brief mode)
|
|
- `TodoRead` / `TodoWrite` -- Task list management
|
|
- `EnterWorktree` / `ExitWorktree` -- Git worktree management
|
|
- `LSP` -- Language Server Protocol integration
|
|
|
|
### Tool Schema Pattern
|
|
|
|
Each tool is defined with:
|
|
```javascript
|
|
{
|
|
name: "ToolName",
|
|
description: `Template literal with ${otherToolNames} interpolated`,
|
|
input_schema: {
|
|
type: "object",
|
|
properties: { ... },
|
|
required: [ ... ]
|
|
}
|
|
}
|
|
```
|
|
|
|
Tool descriptions dynamically reference other tool names so the model knows
|
|
the full toolkit available. For example, Bash's description says "Avoid using
|
|
this tool to run grep, find, cat... instead use the appropriate dedicated tool."
|
|
|
|
### Tool Validation
|
|
|
|
Tools have category-based validation:
|
|
- **filePatternTools**: `["Read", "Write", "Edit", "Glob", "NotebookRead", "NotebookEdit"]`
|
|
- Validate file paths
|
|
- **bashPrefixTools**: `["Bash"]`
|
|
- Validate command prefixes against allowed/denied patterns
|
|
- **customValidation**: Per-tool validators (e.g., WebSearch rejects wildcards)
|
|
|
|
### Tool Permission Flow
|
|
|
|
```
|
|
User prompt -> Model generates tool_use -> Permission check -> Execute -> tool_result
|
|
```
|
|
|
|
Each tool call goes through the permission system before execution.
|
|
See `04-permission-system.md` for details.
|
|
|
|
### MCP Tool Integration
|
|
|
|
MCP (Model Context Protocol) tools extend the built-in set:
|
|
- MCP tools are prefixed with `mcp__<server-name>__<tool-name>`
|
|
- `ReadMcpResourceTool` -- Read MCP server resources
|
|
- MCP tools can be deferred (loaded on-demand via `ToolSearch`)
|
|
- Tool output size controlled by `MAX_MCP_OUTPUT_TOKENS` env var
|
|
- Large outputs can be saved to files (`ENABLE_MCP_LARGE_OUTPUT_FILES`)
|
|
|
|
### Tool Concurrency
|
|
|
|
`CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY` controls parallel tool execution.
|
|
Multiple tool calls in a single response can execute concurrently.
|
|
|
|
### Content Block Types
|
|
|
|
The API supports these content block types in messages:
|
|
|
|
| Type | Direction | Purpose |
|
|
|------|-----------|---------|
|
|
| `text` | Both | Text content |
|
|
| `thinking` | Response | Extended thinking |
|
|
| `redacted_thinking` | Response | Safety-redacted thinking |
|
|
| `tool_use` | Response | Tool call request |
|
|
| `tool_result` | Request | Tool execution result |
|
|
| `image` | Request | Image content |
|
|
| `file` | Request | File content |
|
|
| `server_tool_use` | Response | Server-side tool calls |
|
|
| `web_search_tool_result` | Response | Web search results |
|
|
| `code_execution_tool_result` | Response | Code execution results |
|
|
| `mcp_tool_use` | Response | MCP tool calls |
|
|
| `mcp_tool_result` | Response | MCP tool results |
|