Tools - o4

Tools are how the model acts: it reads and edits files, searches, runs commands, fetches web pages and starts other agents by calling them. This page lists every built-in tool by the name the model uses, what it does, its main parameters and its limits. You see these names in the transcript and in approval prompts, and you use them in permission rules.

Approval

Each tool has a default approval level. It decides what happens in the default ask permission mode:

Level	In `ask` mode
Never asks	Runs without a prompt.
Asks once	Asks the first time. After you approve, o4 doesn’t ask again this session for the same target: the same file for `write`, `edit` and `notebook_edit`, the same host for `fetch`, and the same set of attached files for `brief`. For the other tools, one approval covers the tool for the rest of the session.
Asks every time	Asks before every call.

Other modes change this:

accept-edits also runs write, edit and notebook_edit without asking.
review has the session model review each call that would ask, and asks you only if the review doesn’t approve it.
auto runs everything except package installs that run install-time scripts.
bypass runs everything.
plan blocks everything that isn’t “Never asks”.

Permission rules and hooks can allow, deny or require a prompt for a specific tool. Shell commands also run inside the sandbox, whatever the approval. Every tool’s text output is capped at 100,000 characters. Longer output keeps the first and last 10,000 characters with a note in between.

Files

The file tools work inside the project directory and your home directory. They refuse credential locations in your home directory, such as ~/.ssh, ~/.aws, ~/.config/gh, ~/.netrc and o4’s own ~/.o4/settings.json. When you pass -C, --add-dir, --sandbox read-only or --sandbox workspace-write, they work only inside the working directory and the added directories, and --sandbox read-only also refuses every write. See Sandbox.

Tool	What it does	Approval
`read`	Read a file with line numbers. Also reads images (PNG, JPEG, GIF, WebP, BMP) and Jupyter notebooks.	Never asks
`write`	Create or overwrite a file, creating parent folders as needed.	Asks once per file
`edit`	Replace an exact string in a file.	Asks once per file
`notebook_edit`	Edit a Jupyter notebook cell, or insert a new cell.	Asks once per file
`undo`	Undo the last `write` or `edit`, putting the file back as it was. o4 keeps the last 50 changes. `notebook_edit` changes aren’t recorded, so they can’t be undone this way. Not available in print mode.	Asks once

read

file_path (required): absolute path to the file.
offset: 1-based line to start from.
limit: number of lines to read. Default 2000.

Lines longer than 2000 characters are cut. Text files up to 25 MB can be read. SVG files are read as text.

write

file_path (required): absolute path to the file.
content (required): the full new content.

Writes up to 50 MB. Each write can be reversed with undo or /undo.

edit

file_path (required): absolute path to the file.
old_string (required): the text to replace. It must match exactly one place in the file unless replace_all is set.
new_string (required): the replacement.
replace_all: replace every occurrence.

Works on files up to 25 MB. The approval prompt shows a preview of the change.

notebook_edit

notebook_path (required): path to the .ipynb file.
new_source (required): the new cell content.
cell_id: the cell to edit. Leave it out to insert a new cell.
cell_type: code or markdown.
insert_after: insert the new cell after this cell ID.

Search

Tool	What it does	Approval
`glob`	Find files by glob pattern, such as `*/.rs`.	Never asks
`grep`	Search file contents with a regular expression.	Never asks
`ls`	List a directory’s entries with their type.	Never asks
`git_info`	Run read-only git commands: `status`, `diff` or `log`.	Never asks

glob

pattern (required): the glob pattern.

Returns at most 10,000 paths.

grep

pattern (required): the regular expression.
path: file or folder to search. Defaults to the current directory.
glob: only search files matching this pattern, such as *.rs.
case_insensitive: ignore case.
context: lines of context around each match, up to 100.
output_mode: content (the default), files_with_matches or count.

Output stops at 200 lines. It skips .git, node_modules, binary files and files over 1 MB, respects .gitignore, and gives up after 30 seconds. It uses rg (ripgrep) when it’s installed in a standard location such as /opt/homebrew/bin or /usr/bin.

path (required): the folder to list.

Lists at most 10,000 entries.

git_info

subcommand (required): status, diff or log.
ref: a ref or range, such as HEAD~3 or main..feature, for diff and log.
path: limit diff to a file or folder.
count: number of commits for log. Default 10.

It never changes the repository.

Shell and code execution

Tool	What it does	Approval
`bash`	Run a shell command and return its output.	Asks every time
`repl`	Run code in a persistent Python or Node.js session.	Asks every time
`test_run`	Run the project’s tests and return structured results.	Asks once
`format`	Format a file with a configured formatter.	Asks once

bash

command (required): the command to run.
timeout: milliseconds. Default 600,000 (10 minutes), maximum 1,800,000 (30 minutes). 0 turns the timeout off.
working_directory: folder to run the command in.
run_in_background: start the command as a background task and return a task ID right away. For dev servers, watchers and other long-running commands.
justification: one sentence shown on the approval prompt explaining why the command is needed.

The working directory carries over between calls; shell variables and other shell state don’t. Output is limited to 100,000 characters. Commands run inside the sandbox. A command that runs past its time limit can be moved to the background instead of failing; see Todos and background tasks.

repl

language (required): python (runs python3) or node.
code (required): the code to run.

Variables persist between calls in the same session. Each call times out after 30 seconds.

test_run

pattern: only run tests whose names match.
file: run the tests for one file.
timeout: seconds. Default 300, maximum 1,800; 0 turns it off.
impacted_only: run only the tests affected by the current changes, falling back to the full suite when unsure.
impact_set: a precomputed set of impacted tests to use with impacted_only.

It detects the project type from Cargo.toml, package.json, pyproject.toml, setup.py or go.mod, and returns each test’s name, status, duration, location and failure message.

format

file_path (required): the file to format.
timeout: milliseconds. Default 120,000.

Available only when you’ve configured at least one formatter. See Language servers and formatters.

Web

Tool	What it does	Approval
`fetch`	Download a URL with HTTP GET and return the body. HTML is converted to text.	Asks once per host
`web_fetch`	Fetch a public page and return its text together with a question to answer about it.	Asks once
`web_search`	Search the web and return titles, URLs and snippets.	Asks once

fetch

url (required): the URL.

Times out after 30 seconds and reads at most 10 MB. Only public addresses are allowed; private and internal addresses are refused.

web_fetch

url (required): a public URL.
prompt (required): the question to answer about the page.

The page content is cut to about 20,000 characters.

web_search

query (required): the search terms.
count: number of results. Default 5, maximum 10.

Uses the Brave Search API if you’ve saved a brave key in /config > Providers or set BRAVE_API_KEY, otherwise Tavily with a tavily key or TAVILY_API_KEY, otherwise DuckDuckGo on a best-effort basis. See Environment variables.

fetch and web_search follow the sandbox’s host rules, so in the guarded tier a request to a host that isn’t allowed prompts you first. See Sandbox.

Planning and goals

Tool	What it does	Approval
`enter_plan_mode`	Switch to plan mode, a read-only research mode.	Never asks
`exit_plan_mode`	Leave plan mode and restore the full tool set.	Never asks
`plan_create`	Save a multi-step plan as a draft for you to review. Takes a `title` and a list of `steps`.	Asks once
`plan_status`	Show a plan’s steps and progress.	Never asks
`plan_modify`	Rewrite a step that is still pending. Steps that have started, finished, failed or been skipped can’t be changed.	Asks once
`checkpoint_create`	Tag the current git `HEAD` as a checkpoint before a risky change.	Asks once
`checkpoint_restore`	Restore tracked files from a checkpoint tag. Refuses to overwrite uncommitted changes unless `force` is set.	Asks every time
`create_goal`	Start or replace the session goal. Takes an `objective` and an optional `token_budget`.	Never asks
`get_goal`	Read the current goal.	Never asks
`update_goal`	Mark the goal `complete` (with evidence) or `blocked`.	Never asks

See Plan mode and Goals.

Todos and background tasks

Tool	What it does	Approval
`todo_write`	Replace the session todo list. Each item has `content`, `status` (`pending`, `in_progress` or `completed`) and an optional `activeForm` label.	Never asks
`task_list`	List background tasks with their ID, type, status and running time.	Never asks
`task_get`	Show one background task.	Never asks
`task_output`	Read the end of a task’s output, 50 lines by default.	Never asks
`task_wait`	Wait for a task to finish, then return its status and output. Waits up to 300 seconds by default and 1800 at most.	Never asks
`task_create`	Register a new background task entry.	Asks every time
`task_update`	Change a task’s state: `start`, `pause`, `resume`, `complete`, `fail`, `kill` or `notify`.	Asks every time
`task_stop`	Stop a running background task.	Asks every time

See Todos and background tasks.

Agents and teams

Tool	What it does	Approval
`agent`	Start a subagent with its own context to handle a task.	Asks once
`campaign`	Start a multi-agent campaign with several workers.	Asks every time
`send_message`	Send a message to another agent or team.	Asks once
`team_create`	Create a named team with 1 to 10 members under `.o4/teams/<name>/`. It sets up the roster and mailboxes but doesn’t start workers.	Asks every time
`team_delete`	Disband a team and remove its working directory.	Asks every time
`brief`	Send a summary, and optionally files, from a subagent back to the session that started it.	Asks once
`ask_user_question`	Ask you a question with 2 to 5 options to choose from. Only available in the interactive interface.	Never asks

agent

prompt (required): the task for the subagent.
agent: the agent definition to use, such as Explore, Plan, General or one of your own. Leave it out to fork the current conversation.
description: a short label for the display.
model: a provider:model reference to use instead of the current model.
background: run it in the background and return a task ID right away.
name: a name other agents can use to reach it with send_message.
isolation: worktree runs it in its own git worktree.
structured_output_schema: a JSON Schema. The subagent then gets a StructuredOutput tool and must call it once with a result that matches.
contract: a task contract with task, context, done_when (a shell command and the result that proves the work is done), touch_only (the files it may change) and on_failure. When touch_only names more than one file, o4 checks done_when itself by default.
verify: a shell command that replaces that check, or false to turn it off. A failing check goes back to the subagent, up to 2 retries.

See Subagents.

campaign

description (required): the overall goal.
workers (required): the workers, each with a role (the agent to use) and a task, and optionally a model.
strategy: parallel (the default), sequential, map_reduce or collaborative.
timeout_secs: a time limit per worker. No limit if left out.
auto_approve: accepted, but o4 0.2.74 doesn’t use it.

See Campaigns.

brief

summary (required): the report, up to 100,000 characters.
files: paths to attach, up to 1 MB each and 5 MB in total.

Outside a subagent, it returns the report directly.

Code intelligence

Tool	What it does	Approval
`codebase_query`	Query the project’s code index for callers, callees, symbols, imports, types and files that change together.	Never asks
`show_architecture`	Draw the codebase as a Mermaid diagram: `modules`, `files`, or the `calls` from one function.	Never asks
`lsp`	Ask a language server for definitions, references, hover information, symbols, implementations or call hierarchy.	Asks once

codebase_query takes an operation (such as callers_of, find_symbol or changed_together) and a target. The index lives in .o4/index/codebase.db and is built in the background when a session starts. lsp takes an operation, a filePath, and a 1-based line and character. It needs a language server for that file type installed; by default o4 looks for rust-analyzer, typescript-language-server, pyright-langserver and gopls. In 0.2.74 o4 doesn’t send the server the initialize request, so standard servers such as rust-analyzer answer with an LSP error -32002. See Code intelligence and Language servers and formatters.

Memory

Tool	What it does	Approval
`memory_save`	Save a memory with `content`, a `type` (`fact`, `decision`, `pattern` or `preference`) and optional `tags`.	Asks every time
`memory_search`	Search memories. Returns 10 results by default, 50 at most.	Asks every time
`memory_list`	List memories, optionally filtered by type, including `session_summary`. Returns 20 by default, 50 at most.	Asks every time
`memory_forget`	Delete a memory by its `id`.	Asks every time

Each memory tool takes a scope: project (the default, stored in .o4/memory/memory.db) or global (stored in ~/.o4/memory/global.db). The global store is available only in a trusted workspace. See Memory.

Skills

Tool	What it does	Approval
`skill`	List skills (no parameters), search them with `query`, or load one’s instructions with `name`. Includes skills from installed plugins.	Never asks

See Skills.

MCP

Tool	What it does	Approval
`list_mcp_resources`	List the resources an MCP server offers. Takes a `server` name.	Never asks
`read_mcp_resource`	Read one resource by `server` and `uri`.	Asks every time
MCP server tools	Each tool from a connected MCP server, named `<server>__<tool>`, for example `github__create_issue`.	Asks once per server
`tool_search`	Search the MCP tools that were held back, and load them. Takes a `query` and optional `max_results` (default 5).	Never asks

If your built-in and MCP tools add up to more than 64, o4 doesn’t send the MCP tools to the model up front. It adds tool_search instead, and the model loads MCP tools as it needs them. See MCP servers.

Worktrees

Tool	What it does	Approval
`enter_worktree`	Create a git worktree for the session and move into it. Takes an optional `name`.	Asks once
`exit_worktree`	Leave the worktree and go back to the original folder. `merge` merges the changes first; `force` discards uncommitted changes.	Asks once

Other tools

Tool	What it does	Approval
`sleep`	Wait for `seconds`, from 0.1 to 300.	Never asks
`harness_audit`	Check `.o4/harness.toml` for problems, without changing files. See Harness guides and sensors.	Never asks
`synthetic_output`	Return JSON `data` after checking it against a JSON `schema`.	Asks once
`remote_trigger`	Send a `prompt` to a remote agent endpoint (`target`, a URL) with HTTP POST, optionally with a `model`. Private and internal addresses are refused.	Asks every time

CodeMode

Tool	What it does	Approval
`exec`	Run a JavaScript program that calls o4’s other tools as functions. Offered only when CodeMode is on.	Never asks; each tool call inside asks as usual
`wait`	Collect the result of an `exec` program that’s still running. Offered only when CodeMode’s `background` option is on.	Never asks

See CodeMode.

Where each tool is available

Not every tool is offered in every kind of session:

Plan mode. The model can only use read, glob, grep, ls, fetch, task_create, task_update, task_list, enter_plan_mode and exit_plan_mode. Other tools are hidden from it, and a call to one is blocked. See Plan mode.
Print mode (o4 -p). There’s no one to ask, so ask_user_question isn’t offered, and neither are undo, todo_write, the task_* tools, the plan_*, checkpoint_* and goal tools, lsp, format, list_mcp_resources, read_mcp_resource and tool_search. MCP server tools are still offered. See Print mode and scripting.
Subagents. A subagent gets read, glob, grep, ls, write, edit, bash, fetch, web_search, git_info and your MCP server tools, narrowed by its agent definition, plus agent when its definition allows it, and StructuredOutput when it was started with a structured_output_schema. Inside a subagent, MCP server tools ask every time. A subagent started without an agent type, a fork, gets the same tools as the session that started it. See Subagents.
Daemon runs. When a client of the o4 daemon starts a run with an output schema, the model also gets a structured_output tool whose input is that schema. A call that doesn’t match the schema returns an error to the model, and a run that ends without a valid call fails with model did not produce valid structured output.
Configuration. format needs at least one formatter, and tool_search appears only when MCP tools were held back.

Plugin tools and turning tools off

Installed plugins can add their own tools. Plugin tools ask for approval every time, and a plugin tool with the same name as a built-in tool isn’t added. To leave tools out of the model’s tool set in a project, built-in or MCP, list their names under disabled_tools in the [scout] section of .o4/config.toml; /scout can write this for you. This applies to the interactive interface. See the configuration reference.

​Approval

​Files

​Search

​Shell and code execution

​Web

​Planning and goals

​Todos and background tasks

​Agents and teams

​Code intelligence

​Memory

​Skills

​MCP

​Worktrees

​Other tools

​CodeMode

​Where each tool is available

​Plugin tools and turning tools off