--- id: SMH-RESEARCH-RSCH0004 type: research title: "Coding Harness Tool Surface Research" --- # Coding Harness Tool Surface Research **Date:** 2026-05-25 **Status:** Verified comparison notes ## Scope Compare Pi, OpenAI Codex, Claude Code, and Cursor agent tool surfaces for Smith compatibility decisions. ## Verified findings ### Pi Pi has a small, regular coding-tool surface. Observed: - Built-in tools listed by Pi CLI/docs: `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`. - Default quick-start tools exposed to the model: `read`, `write`, `edit`, `bash`. - Extra deterministic discovery/search tools are available via explicit tool selection. - Extension tools use TypeBox parameter schemas plus an `execute()` function: ```ts pi.registerTool({ name: "my_tool", description: "...", parameters: Type.Object({...}), execute: async (toolCallId, params, signal, onUpdate, ctx) => ... }) ``` - Provider extensions use `pi.registerProvider(name, config)` with an adapter field such as `api: "openai-responses"`, `api: "anthropic-messages"`, or custom streaming. - Product features such as subagents, plan mode, permission gates, SSH/sandbox, custom UI, and MCP are extension/package work, not mandatory core tools. Sources: - `/opt/pi-coding-agent/README.md` - `/opt/pi-coding-agent/docs/extensions.md` - `/opt/pi-coding-agent/docs/sdk.md` ### OpenAI Codex Codex has a larger and more provider/runtime-specific tool model. Observed in `openai/codex` revision `9f42c89c0112771dc29100a6f3fc904049b2655f`: - Tool names include `exec_command`, `write_stdin`, `shell_command`, `apply_patch`, `update_plan`, `view_image`, and experimental `request_user_input`. - Tool serialization is OpenAI Responses-style. `ToolSpec` serializes tools as Responses API `function`, `namespace`, `tool_search`, `image_generation`, `web_search`, and `custom` tools. - `apply_patch` is a custom/freeform tool with Lark grammar, explicitly described as not JSON. - The shell/exec path is rich: examples include `cmd`, `shell`, `workdir`, `tty`, `yield_time_ms`, `max_output_tokens`, and persistent-session stdin via `write_stdin`. - Source tree includes MCP, tool search, and multi-agent/tool extras. Sources: - `~/.pi/research/repos/github.com.openai.codex` clone - `codex-rs/tools/src/tool_spec.rs` - `codex-rs/core/src/tools/handlers/apply_patch_spec.rs` - `codex-rs/protocol/src/plan_tool.rs` - `codex-rs/protocol/src/models.rs` - `codex-rs/core/tests/suite/unified_exec.rs` ### Claude Code Claude Code has PascalCase tool names and many product tools in core docs. Observed: - Official docs list tools including `Agent`, `AskUserQuestion`, `Bash`, `CronCreate`, `CronDelete`, `CronList`, `Edit`, `EnterPlanMode`, `EnterWorktree`, `ExitPlanMode`, `ExitWorktree`, `Glob`, `Grep`, `ListMcpResourcesTool`, `LSP`, `Monitor`, `NotebookEdit`, `PowerShell`, `PushNotification`, `Read`, `ReadMcpResourceTool`, `RemoteTrigger`, `ScheduleWakeup`, `SendMessage`, `ShareOnboardingGuide`, `Skill`, task tools, team tools, `TodoWrite`, `ToolSearch`, `WaitForMcpServers`, `WebFetch`, `WebSearch`, and `Write`. - `Edit` is exact string replacement with `old_string`, `new_string`, and `replace_all`; it is not regex/fuzzy matching. - `MultiEdit` was not present in the current official tools page checked here; keep it as an adapter alias only for older/unofficial Claude-compatible surfaces that expose it. - Product workflow features are first-class tool names: subagents, plan mode, cron/scheduled tasks, worktrees, notifications, LSP, MCP resources, skills, tasks, and teams. Source: - ### Cursor Cursor exposes IDE-oriented function tools, with semantic search and model-based apply as first-class pieces. Observed: - Captured tool/function names include `codebase_search`, `read_file`, `run_terminal_cmd`, `list_dir`, `grep_search`, `edit_file`, `file_search`, `delete_file`, `reapply`, `fetch_rules`, and `diff_history`. - The tools are injected through OpenAI-style function calling in the captured workflow. - `codebase_search` is semantic search, not deterministic grep. - `edit_file` proposes/sketches file edits; Cursor's public fast-apply research describes a separate apply phase/model that rewrites files conditioned on the current file, conversation history, and edit block. - `reapply` exists because apply can be wrong and may need retry. Sources: - - ## Compatibility notes Pi-style tools form a useful portable IR for deterministic coding operations: small lowercase names, JSON schemas, exact file mutation, deterministic search, and extension-first product features. Best bridge aliases: ```text Claude Read -> pi read Claude Bash -> pi bash Claude Edit -> pi edit, single edit Claude MultiEdit -> pi edit, edits[] (legacy/unofficial surfaces) Claude Write -> pi write Claude Glob -> pi find Claude Grep -> pi grep Claude LS -> pi ls Cursor read_file -> pi read Cursor run_terminal_cmd -> pi bash Cursor list_dir -> pi ls Cursor grep_search -> pi grep Cursor file_search -> pi find-ish Cursor edit_file -> not equivalent; fuzzy/apply-model adapter needed Codex shell_command/exec_command -> pi bash Codex apply_patch -> pi edit/write adapter or apply_patch parser Codex update_plan -> extension tool Codex view_image -> image attachment/read adapter, not a core special tool ``` Non-equivalences: - Cursor `edit_file` is not exact replacement. - Codex `apply_patch` is freeform grammar, not JSON schema. - Codex `exec_command` includes persistent TTY/session/yield semantics beyond a simple subprocess call. - Claude Code product tools should map to Smith plugins, not built-ins. - Semantic search is an extension concern, not a deterministic core search tool. ## Candidate Smith takeaway Smith should preserve a Pi-compatible core stance: - small core tool set, - exact file operations, - provider-neutral JSON schemas, - extension/plugin-first product workflows, - no special-case freeform tool semantics unless a plugin explicitly adapts them.