pi.registerTool({
  name: "my_tool",
  description: "...",
  parameters: Type.Object({...}),
  execute: async (toolCallId, params, signal, onUpdate, ctx) => ...
})

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

---
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:

- <https://code.claude.com/docs/en/tools-reference>

### 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:

- <https://roman.pt/posts/cursor-under-the-hood/>
- <https://cursor.com/blog/instant-apply>

## 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.