Tools
The built-in tools the agent uses to read, edit, search, run commands, delegate and ask, and how they vary by model family.
The agent acts through tools. Cusp's tool names and input fields (Read, Edit, Bash, file_path, old_string, …) are the ones existing hooks, permission rules and skills are written against, so they work unchanged.
Every call goes through the same gate: input validation and repair, PreToolUse hooks, the permission engine, the tool itself, then PostToolUse hooks. Read-only calls in the same batch run in parallel.
Built-in tools
Files
| Tool | What it does |
|---|---|
Read | Reads a file with line numbers. Up to 2,000 lines by default; offset and limit for ranges, and a negative offset reads from the end. Also reads images, PDFs (up to 20 pages per call) and Jupyter notebooks |
Write | Creates or overwrites a file, creating parent directories as needed |
Edit | Replaces an exact string in a file. Fails if the text isn't unique unless replace_all is set |
MultiEdit | Several replacements in one file, applied atomically |
ApplyPatch | Applies a V4A patch that can add, update, move and delete several files atomically. GPT-family models see it as apply_patch |
EditLines | Edits by line anchors from the latest Read. Used for weaker and local models |
NotebookEdit | Replaces, inserts or deletes a single cell in a .ipynb notebook |
Search
| Tool | What it does |
|---|---|
Grep | Searches file contents with a regular expression (ripgrep semantics). Uses rg when installed, otherwise a built-in engine with identical output |
Glob | Finds files by name pattern, such as src/**/*.{ts,tsx} |
LS | Lists a directory as a tree, with file sizes |
Shell
| Tool | What it does |
|---|---|
Bash | Runs a shell command and returns its output. Default timeout 120 s, maximum 600 s |
Process | Starts and manages long-running processes such as dev servers and watchers. Waits until a port, URL or log line says the process is ready |
Terminal | Drives an interactive program on a pseudo-terminal: REPLs, debuggers, ssh, prompts, terminal UIs |
Web
| Tool | What it does |
|---|---|
WebFetch | Fetches a public page and returns it as Markdown. Refuses private network addresses, and reports cross-host redirects instead of following them |
WebSearch | Searches the web and returns titles, URLs and snippets |
Planning and conversation
| Tool | What it does |
|---|---|
TodoWrite | Maintains the session's task list. GPT-family models use UpdatePlan (update_plan) instead |
AskUserQuestion | Asks you one to four multiple-choice questions when the agent is blocked on a decision that is yours |
EnterPlanMode, ExitPlanMode | Switch into plan mode, and present a plan for approval |
Skill | Loads a skill |
ToolSearch | Loads deferred tools by name or keyword |
Agents
| Tool | What it does |
|---|---|
Agent | Starts a subagent with a fresh context for a self-contained task |
SendMessage | Sends a message to another agent: a subagent, a teammate, or another session |
ListAgents | Lists the agents you can message |
Code intelligence
| Tool | What it does |
|---|---|
Diagnostics | Reports compiler and language-server errors and warnings for files |
LSP | Read-only language-server queries: go to definition or implementation, find references, hover, document and workspace symbols, call hierarchy |
Behavior worth knowing
Read before edit. The agent must read a file before editing it. Cusp records the file's size and modification time at read time and checks them again right before writing, so an edit never lands on a file that changed underneath it. A partial read only allows editing the lines that were seen.
Fuzzy matching, reported. If Edit's old_string doesn't match exactly, Cusp tries a ladder of increasingly lenient matches (normalized whitespace, trimmed line ends, re-indented, block-anchored). It reports which tier it used, and refuses matches that are suspiciously different in size.
Diagnostics after edits. After an edit, Cusp runs the relevant checker (tsgo or tsc for TypeScript, or a language server) and appends new errors to the tool result. The agent sees a type error it introduced in the same step.
A shell that behaves. Each Bash command runs non-interactively: stdin is closed and pagers are disabled (PAGER=cat, GIT_PAGER=cat), so nothing hangs waiting for input. The working directory carries over between calls while it stays inside the workspace. Secrets are stripped from the environment. A command that runs past its timeout is moved to the background instead of being killed, and the agent is notified when it exits.
Exit codes in context. Exit code 1 from grep, rg, find, diff, test and git diff means "no matches" or "different", and isn't treated as an error.
Large outputs spill to artifacts. Output over about 30,000 characters is cut to its head and tail, and the full text is saved as an artifact. The agent can Read or Grep it as artifact:<id>, so nothing is lost and the context stays small.
Tools per model family
Each model family gets the tool set it was trained to use. Hooks and permission rules always see the canonical name in the first column.
| Tool | Claude | GPT | Gemini | Weaker and local models |
|---|---|---|---|---|
Read | ✓ | ✓ | ✓ | ✓ (with line anchors) |
Edit, MultiEdit | ✓ | — | ✓ | — |
ApplyPatch | — | as apply_patch | — | — |
EditLines | — | — | — | ✓ |
Write | ✓ | ✓ | ✓ | ✓ |
TodoWrite | ✓ | — | ✓ | ✓ |
UpdatePlan | — | as update_plan | — | — |
| Everything else | ✓ | ✓ | ✓ | ✓ |
Deferred tools
Every tool definition costs context on every turn. Tools that are useful but rarely needed are deferred: the model sees only their names, and loads the full definition with ToolSearch when it needs one.
Deferred by default: Terminal, NotebookEdit, Diagnostics, LSP, and all MCP tools.
Loaded tools are appended after the core tools, so the start of the prompt stays byte-identical from turn to turn and the provider's prompt cache keeps working.
MCP tools
Tools from MCP servers appear as mcp__<server>__<tool>. They are deferred unless the server marks them as always loaded. Two extra tools, ListMcpResourcesTool and ReadMcpResourceTool, read resources the servers expose.
Limiting tools
- Deny a tool for everyone with a permission rule:
"deny": ["WebSearch"]. - Deny it for one run:
cusp --disallowedTools WebFetch. - Give a subagent or skill a narrower set with
tools:orallowed-tools:in its frontmatter.
Full specification
The exact descriptions and JSON schemas the model sees are generated from the tool registry and published in the repository as docs/specs/harness-tools.md.