From 1abd951e575c12440d958f04438f7915d51eef21 Mon Sep 17 00:00:00 2001 From: Jobdori Date: Fri, 3 Apr 2026 08:27:02 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20add=20PARITY.md=20=E2=80=94=20honest=20?= =?UTF-8?q?behavioral=20gap=20assessment?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Catalog all 40 tools as real-impl vs stub, with specific behavioral gap notes per tool. Identify missing bash submodules (18 upstream vs 1 Rust), file validation gaps, MCP/plugin flow gaps, and runtime behavioral gaps. This replaces surface-count bragging with actionable gap tracking. --- PARITY.md | 321 ++++++++++++++---------------------------------------- 1 file changed, 84 insertions(+), 237 deletions(-) diff --git a/PARITY.md b/PARITY.md index ff46200..b05c436 100644 --- a/PARITY.md +++ b/PARITY.md @@ -1,253 +1,100 @@ -# PARITY Gap Analysis +# Parity Status — claw-code Rust Port -Date: 2026-04-01 +Last updated: 2026-04-03 (`03bd7f0`) -Scope compared: -- Upstream TypeScript: `/home/bellman/Workspace/claude-code/src/` -- Rust port: `rust/crates/` +## Tool Surface: 40/40 (spec parity) -Method: -- Read-only comparison only. -- No upstream source was copied into this repo. -- This is a focused feature-gap report for `tools`, `hooks`, `plugins`, `skills`, `cli`, `assistant`, and `services`. +### Real Implementations (behavioral parity — varying depth) -## Executive summary +| Tool | Rust Impl | Behavioral Notes | +|------|-----------|-----------------| +| **bash** | `runtime::bash` 283 LOC | subprocess exec, timeout, background, sandbox — **strong parity**. Missing: sedValidation, pathValidation, readOnlyValidation, destructiveCommandWarning, commandSemantics (upstream has 18 submodules for bash alone) | +| **read_file** | `runtime::file_ops` | offset/limit read — **good parity** | +| **write_file** | `runtime::file_ops` | file create/overwrite — **good parity** | +| **edit_file** | `runtime::file_ops` | old/new string replacement — **good parity**. Missing: replace_all was recently added | +| **glob_search** | `runtime::file_ops` | glob pattern matching — **good parity** | +| **grep_search** | `runtime::file_ops` | ripgrep-style search — **good parity** | +| **WebFetch** | `tools` | URL fetch + content extraction — **moderate parity** (need to verify content truncation, redirect handling vs upstream) | +| **WebSearch** | `tools` | search query execution — **moderate parity** | +| **TodoWrite** | `tools` | todo/note persistence — **moderate parity** | +| **Skill** | `tools` | skill discovery/install — **moderate parity** | +| **Agent** | `tools` | agent delegation — **moderate parity** | +| **ToolSearch** | `tools` | tool discovery — **good parity** | +| **NotebookEdit** | `tools` | jupyter notebook cell editing — **moderate parity** | +| **Sleep** | `tools` | delay execution — **good parity** | +| **SendUserMessage/Brief** | `tools` | user-facing message — **good parity** | +| **Config** | `tools` | config inspection — **moderate parity** | +| **EnterPlanMode** | `tools` | worktree plan mode toggle — **good parity** | +| **ExitPlanMode** | `tools` | worktree plan mode restore — **good parity** | +| **StructuredOutput** | `tools` | passthrough JSON — **good parity** | +| **REPL** | `tools` | subprocess code execution — **moderate parity** | +| **PowerShell** | `tools` | Windows PowerShell execution — **moderate parity** | -The Rust port has a solid core for: -- basic prompt/REPL flow -- session/runtime state -- Anthropic API/OAuth plumbing -- a compact MVP tool registry -- CLAUDE.md discovery -- MCP config parsing/bootstrap primitives +### Stubs Only (surface parity, no behavior) -But it is still materially behind the TypeScript implementation in six major areas: -1. **Tools surface area** is much smaller. -2. **Hook execution** is largely missing; Rust mostly loads hook config but does not run a TS-style PreToolUse/PostToolUse pipeline. -3. **Plugins** are effectively absent in Rust. -4. **Skills** are only partially implemented in Rust via direct `SKILL.md` loading; there is no comparable skills command/discovery/registration surface. -5. **CLI** breadth is much narrower in Rust. -6. **Assistant/tool orchestration** lacks the richer streaming concurrency, hook integration, and orchestration behavior present in TS. -7. **Services** in Rust cover API/auth/runtime basics, but many higher-level TS services are missing. +| Tool | Status | Notes | +|------|--------|-------| +| **AskUserQuestion** | stub | needs user I/O integration | +| **TaskCreate** | stub | needs sub-agent runtime | +| **TaskGet** | stub | needs task registry | +| **TaskList** | stub | needs task registry | +| **TaskStop** | stub | needs process management | +| **TaskUpdate** | stub | needs task message passing | +| **TaskOutput** | stub | needs output capture | +| **TeamCreate** | stub | needs parallel task orchestration | +| **TeamDelete** | stub | needs team lifecycle | +| **CronCreate** | stub | needs scheduler runtime | +| **CronDelete** | stub | needs cron registry | +| **CronList** | stub | needs cron registry | +| **LSP** | stub | needs language server client | +| **ListMcpResources** | stub | needs MCP client | +| **ReadMcpResource** | stub | needs MCP client | +| **McpAuth** | stub | needs OAuth flow | +| **MCP** | stub | needs MCP tool proxy | +| **RemoteTrigger** | stub | needs HTTP client | +| **TestingPermission** | stub | test-only, low priority | -## Critical bug status on this branch +## Slash Commands: 67/141 upstream entries -Targeted critical items requested by the user: -- **Prompt mode tools enabled**: fixed in `rust/crates/rusty-claude-cli/src/main.rs:75-82` -- **Default permission mode = danger-full-access**: fixed in `rust/crates/rusty-claude-cli/src/args.rs:12-16`, `rust/crates/rusty-claude-cli/src/main.rs:348-353`, and starter config `rust/crates/rusty-claude-cli/src/init.rs:4-9` -- **Tool input `{}` prefix bug**: fixed/guarded in streaming vs non-stream paths at `rust/crates/rusty-claude-cli/src/main.rs:2211-2256` -- **Unlimited max_iterations**: already present at `rust/crates/runtime/src/conversation.rs:143-148` with `usize::MAX` initialization at `rust/crates/runtime/src/conversation.rs:119` +- 27 original specs (pre-today) — all with real handlers +- 40 new specs — parse + stub handler ("not yet implemented") +- Remaining ~74 upstream entries are internal modules/dialogs/steps, not user `/commands` -Build/test/manual verification is tracked separately below and must pass before the branch is considered done. +### Missing Behavioral Features (in existing real tools) ---- +**Bash tool — upstream has 18 submodules, Rust has 1:** +- [ ] `sedValidation` — validate sed commands before execution +- [ ] `pathValidation` — validate file paths in commands +- [ ] `readOnlyValidation` — block writes in read-only mode +- [ ] `destructiveCommandWarning` — warn on rm -rf, etc. +- [ ] `commandSemantics` — classify command intent +- [ ] `bashPermissions` — permission gating per command type +- [ ] `bashSecurity` — security checks +- [ ] `modeValidation` — validate against current permission mode +- [ ] `shouldUseSandbox` — sandbox decision logic -## 1) tools/ +**File tools — need verification:** +- [ ] Path traversal prevention (symlink following, ../ escapes) +- [ ] Size limits on read/write +- [ ] Binary file detection +- [ ] Permission mode enforcement (read-only vs workspace-write) -### Upstream TS has -- Large per-tool module surface under `src/tools/`, including agent/task tools, AskUserQuestion, MCP tools, plan/worktree tools, REPL, schedule/task tools, synthetic output, brief/upload, and more. -- Evidence: - - `src/tools/AgentTool/AgentTool.tsx` - - `src/tools/AskUserQuestionTool/AskUserQuestionTool.tsx` - - `src/tools/ListMcpResourcesTool/ListMcpResourcesTool.ts` - - `src/tools/ReadMcpResourceTool/ReadMcpResourceTool.ts` - - `src/tools/EnterPlanModeTool/EnterPlanModeTool.ts` - - `src/tools/ExitPlanModeTool/ExitPlanModeV2Tool.ts` - - `src/tools/EnterWorktreeTool/EnterWorktreeTool.ts` - - `src/tools/ExitWorktreeTool/ExitWorktreeTool.ts` - - `src/tools/RemoteTriggerTool/RemoteTriggerTool.ts` - - `src/tools/ScheduleCronTool/*` - - `src/tools/TaskCreateTool/*`, `TaskGetTool/*`, `TaskListTool/*`, `TaskOutputTool/*` +**Config/Plugin/MCP flows:** +- [ ] Full MCP server lifecycle (connect, list tools, call tool, disconnect) +- [ ] Plugin install/enable/disable/uninstall full flow +- [ ] Config merge precedence (user > project > local) -### Rust currently has -- A single MVP registry in `rust/crates/tools/src/lib.rs:53-371`. -- Implemented tools include `bash`, `read_file`, `write_file`, `edit_file`, `glob_search`, `grep_search`, `WebFetch`, `WebSearch`, `TodoWrite`, `Skill`, `Agent`, `ToolSearch`, `NotebookEdit`, `Sleep`, `SendUserMessage`, `Config`, `StructuredOutput`, `REPL`, `PowerShell`. +## Runtime Behavioral Gaps -### Missing or broken in Rust -- **Missing large chunks of the upstream tool catalog**: I did not find Rust equivalents for AskUserQuestion, MCP resource listing/reading tools, plan/worktree entry/exit tools, task management tools, remote trigger, synthetic output, or schedule/cron tools. -- **Tool decomposition is much coarser**: TS isolates tool-specific validation/security/UI behavior per tool module; Rust centralizes almost everything in one file (`rust/crates/tools/src/lib.rs`). -- **Likely parity impact**: lower fidelity tool prompting, weaker per-tool behavior specialization, and fewer native tool choices exposed to the model. +- [ ] Permission enforcement across all tools (read-only, workspace-write, danger-full-access) +- [ ] Output truncation (large stdout/file content) +- [ ] Session compaction behavior matching +- [ ] Token counting / cost tracking accuracy +- [ ] Streaming response support ---- +## Migration Readiness -## 2) hooks/ - -### Upstream TS has -- A full permission and tool-hook system with **PermissionRequest**, **PreToolUse**, **PostToolUse**, and failure/cancellation handling. -- Evidence: - - `src/hooks/toolPermission/PermissionContext.ts:25,222` - - `src/hooks/toolPermission/handlers/coordinatorHandler.ts:32-38` - - `src/hooks/toolPermission/handlers/interactiveHandler.ts:412-429` - - `src/services/tools/toolHooks.ts:39,435` - - `src/services/tools/toolExecution.ts:800,1074,1483` - - `src/commands/hooks/index.ts:5-8` - -### Rust currently has -- Hook data is **loaded/merged from config** and visible in reports: - - `rust/crates/runtime/src/config.rs:786-797,829-838` - - `rust/crates/rusty-claude-cli/src/main.rs:1665-1669` -- The system prompt acknowledges user-configured hooks: - - `rust/crates/runtime/src/prompt.rs:452-459` - -### Missing or broken in Rust -- **No comparable hook execution pipeline found** in the Rust runtime conversation/tool execution path. -- `rust/crates/runtime/src/conversation.rs:151-208` goes straight from assistant tool_use -> permission check -> tool execute -> tool_result, without TS-style PreToolUse/PostToolUse processing. -- I did **not** find Rust counterparts to TS files like `toolHooks.ts` or `PermissionContext.ts` that execute hook callbacks and alter/block tool behavior. -- Result: Rust appears to support **hook configuration visibility**, but not full **hook behavior parity**. - ---- - -## 3) plugins/ - -### Upstream TS has -- Built-in and bundled plugin registration plus CLI/service support for validate/list/install/uninstall/enable/disable/update flows. -- Evidence: - - `src/plugins/builtinPlugins.ts:7-17,149-150` - - `src/plugins/bundled/index.ts:7-22` - - `src/cli/handlers/plugins.ts:51,101,157,668` - - `src/services/plugins/pluginOperations.ts:16,54,306,435,713` - - `src/services/plugins/pluginCliCommands.ts:7,36` - -### Rust currently has -- I did **not** find a dedicated plugin crate/module/handler under `rust/crates/`. -- The Rust crate layout is only `api`, `commands`, `compat-harness`, `runtime`, `rusty-claude-cli`, and `tools`. - -### Missing or broken in Rust -- **Plugin loading/install/update/validation is missing.** -- **No plugin CLI surface found** comparable to `claude plugin ...`. -- **No plugin runtime refresh/reconciliation layer found**. -- This is one of the largest parity gaps. - ---- - -## 4) skills/ - -### Upstream TS has -- Bundled skills registry and loader integration, plus a `skills` command. -- Evidence: - - `src/commands/skills/index.ts:6` - - `src/skills/bundledSkills.ts:44,99,107,114` - - `src/skills/loadSkillsDir.ts:65` - - `src/skills/mcpSkillBuilders.ts:4-21,40` - -### Rust currently has -- A `Skill` tool that loads local `SKILL.md` files directly: - - `rust/crates/tools/src/lib.rs:1244-1255` - - `rust/crates/tools/src/lib.rs:1288-1323` -- CLAUDE.md / instruction discovery exists in runtime prompt loading: - - `rust/crates/runtime/src/prompt.rs:203-208` - -### Missing or broken in Rust -- **No Rust `/skills` slash command** in `rust/crates/commands/src/lib.rs:41-166`. -- **No visible bundled-skill registry equivalent** to TS `bundledSkills.ts` / `loadSkillsDir.ts` / `mcpSkillBuilders.ts`. -- Current Rust skill support is closer to **direct file loading** than full upstream **skill discovery/registration/command integration**. - ---- - -## 5) cli/ - -### Upstream TS has -- Broad CLI handler and transport surface. -- Evidence: - - `src/cli/handlers/agents.ts:2-32` - - `src/cli/handlers/auth.ts` - - `src/cli/handlers/autoMode.ts:24,35,73` - - `src/cli/handlers/plugins.ts:2-3,101,157,668` - - `src/cli/remoteIO.ts:25-35,118-127` - - `src/cli/transports/SSETransport.ts` - - `src/cli/transports/WebSocketTransport.ts` - - `src/cli/transports/HybridTransport.ts` - - `src/cli/transports/SerialBatchEventUploader.ts` - - `src/cli/transports/WorkerStateUploader.ts` - -### Rust currently has -- Minimal top-level subcommands in `rust/crates/rusty-claude-cli/src/args.rs:29-39` and `rust/crates/rusty-claude-cli/src/main.rs:67-90,242-261`. -- Slash command surface is 15 commands total in `rust/crates/commands/src/lib.rs:41-166,389`. - -### Missing or broken in Rust -- **Missing major CLI subcommand families**: agents, plugins, mcp management, auto-mode tooling, and many other TS commands. -- **Missing remote/transport stack parity**: I did not find Rust equivalents to TS remote structured IO / SSE / websocket / CCR transport layers. -- **Slash command breadth is much narrower** than TS command inventory under `src/commands/`. -- **Prompt-mode parity bug** was present and is now fixed for this branch’s prompt path. - ---- - -## 6) assistant/ - -### Upstream TS has -- Rich tool orchestration and streaming execution behavior, including concurrency/cancellation/fallback logic. -- Evidence: - - `src/services/tools/StreamingToolExecutor.ts:35-214` - - `src/services/tools/toolExecution.ts:455-569,800-918,1483` - - `src/services/tools/toolOrchestration.ts:134-167` - - `src/assistant/sessionHistory.ts` - -### Rust currently has -- A straightforward agentic loop in `rust/crates/runtime/src/conversation.rs:130-214`. -- Streaming API adaptation in `rust/crates/rusty-claude-cli/src/main.rs:1998-2058`. -- Tool-use block assembly and non-stream fallback handling in `rust/crates/rusty-claude-cli/src/main.rs:2211-2256`. - -### Missing or broken in Rust -- **No TS-style streaming tool executor** with sibling cancellation / fallback discard semantics. -- **No integrated PreToolUse/PostToolUse hook participation** in assistant execution. -- **No comparable orchestration layer for richer tool event semantics** found. -- Historically broken parity items in prompt mode were: - - prompt tool enablement (`main.rs:75-82`) — now fixed on this branch - - streamed `{}` tool-input prefix behavior (`main.rs:2211-2256`) — now fixed/guarded on this branch - ---- - -## 7) services/ - -### Upstream TS has -- Very broad service layer, including API, analytics, compact/session memory, prompt suggestions, plugin services, MCP service helpers, LSP management, policy limits, team memory sync, notifier/tips, etc. -- Evidence: - - `src/services/api/client.ts`, `src/services/api/claude.ts`, `src/services/api/withRetry.ts` - - `src/services/oauth/client.ts`, `src/services/oauth/index.ts` - - `src/services/mcp/*` - - `src/services/plugins/*` - - `src/services/lsp/*` - - `src/services/compact/*` - - `src/services/SessionMemory/*` - - `src/services/PromptSuggestion/*` - - `src/services/analytics/*` - - `src/services/teamMemorySync/*` - -### Rust currently has -- Core service equivalents for: - - API client + SSE: `rust/crates/api/src/client.rs`, `rust/crates/api/src/sse.rs`, `rust/crates/api/src/types.rs` - - OAuth: `rust/crates/runtime/src/oauth.rs` - - MCP config/bootstrap primitives: `rust/crates/runtime/src/mcp.rs`, `rust/crates/runtime/src/mcp_client.rs`, `rust/crates/runtime/src/mcp_stdio.rs`, `rust/crates/runtime/src/config.rs` - - prompt/context loading: `rust/crates/runtime/src/prompt.rs` - - session compaction/runtime usage: `rust/crates/runtime/src/compact.rs`, `rust/crates/runtime/src/usage.rs` - -### Missing or broken in Rust -- **Missing many higher-level services**: analytics, plugin services, prompt suggestion, team memory sync, richer LSP service management, notifier/tips ecosystem, and much of the surrounding product/service scaffolding. -- Rust is closer to a **runtime/API core** than a full parity implementation of the TS service layer. - ---- - -## Highest-priority parity gaps after the critical bug fixes - -1. **Hook execution parity** - - Config exists, execution does not appear to. - - This affects permissions, tool interception, and continuation behavior. - -2. **Plugin system parity** - - Entire install/load/manage surface appears missing. - -3. **CLI breadth parity** - - Missing many upstream command families and remote transports. - -4. **Tool surface parity** - - MVP tool registry exists, but a large number of upstream tool types are absent. - -5. **Assistant orchestration parity** - - Core loop exists, but advanced streaming/execution behaviors from TS are missing. - -## Recommended next work after current critical fixes - -1. Finish build/test/manual verification of the critical bug patch. -2. Implement **hook execution** before broadening the tool surface further. -3. Decide whether **plugins** are in-scope for parity; if yes, this likely needs dedicated design work, not a small patch. -4. Expand the CLI/tool matrix deliberately rather than adding one-off commands without shared orchestration support. +- [ ] `PARITY.md` maintained and honest +- [ ] No `#[ignore]` tests hiding failures (only 1 allowed: `live_stream_smoke_test`) +- [ ] CI green on every commit +- [ ] Codebase shape clean for handoff