Agent tools

Tools are actions the model can ask Orek to perform, such as reading a file or running a command. Listing a tool here doesn’t grant permission to use it: Orek decides which tools each model sees and checks your permission rules every time one runs.

Use orek chat --no-tools to turn off all tools in a chat. Tool exposure settings control which models see which tools, and Permissions and security explains the permission rules.

Tool discovery

When available, tool_search (query, optional limit, default 8) finds permitted tools and makes them available for the rest of the session. Core tools are available from the start: read_file, grep_files, search_replace, write_file, delete_file, shell, update_plan, write_tasks, tool_search, and, when enabled, run_python, code_graph_query, search_project, and apply_patch. Other tools (read_many_files, list_directory, search_files, ask_user_question, and MCP tools) are found through tool_search when needed.

Tools found this way stay available when you resume or fork the session, until compaction summarizes away the search. Plan mode, tools.tool_search.enabled = false, and profile or model tool lists without tool_search show every permitted tool from the start. The main agent and each subagent keep their own set of found tools.

Read and inspect tools

These tools read information. Reads can expose sensitive content, and some diagnostic tools contact a service or start a trusted program. Path, consent, output, and permission limits still apply.

Search project content

The model can call search_project with a follow-up question during a turn. It searches the project index by meaning and keywords. It is available from the start when index.enabled and tools.search_project.enabled are true, including in the built-in explore and reviewer profiles; tool exposure, profile tool lists, and permission rules still apply. Turning off indexing or the tool, or using --no-tools, removes it.

Without path, the whole project is searched. A valid path with no matches returns empty; the search never widens to the whole project on its own. Ignored files, sensitive files, and files outside the project stay excluded even when path points at them.

The result status is ok, empty, not_built, stale, unavailable, or error. A missing or out-of-date index is reported as such, not as an empty search, and the tool never builds the index itself.

Results contain source excerpts and related code. Paths are relative to the project and use / on every platform, such as src/auth/session.rs, so the model can pass one back as path to narrow a follow-up search. Line ranges start at 1, include both ends, point to the original file even when an excerpt is shortened or redacted, and are left unknown when Orek can’t confirm the location.

The whole result is limited by two saved settings: 4096 estimated tokens and 32768 bytes by default. Orek shortens excerpts and reports how many results it left out to fit.

index.retrieval.enabled, /retrieval off, and @!retrieve control only the automatic retrieval that runs before a turn; the model can still call search_project. Calls use the session’s current index, read only what Orek is allowed to read, and can use a cloud embedding provider when you have configured one. See Find and explore code.

Long results

A tool result longer than 12,000 tokens (about 48 KB) keeps only its beginning and end in the conversation; see oversized tool output.

Diagnostic and recovery limits

• lsp_diagnostics works in Plan mode when lsp.enabled = true and you trust the project’s language server. It waits up to twice lsp.settle_timeout_ms plus one second. A server that is starting, analyzing, untrusted, missing, crashed, or timed out reports that status instead of a clean file. See Language servers.
• read_exec_output can read only output that Orek still keeps for the session.
• Find resource URIs with /mcp resources. read_mcp_resource works in Plan mode; server access and permission rules still apply.

For code relationship queries, see Code graph and navigation.

Edit tools

These change files after permission checks.

apply_patch is hidden by default. Set tools.apply_patch.exposed (user setting, default false) and restart Orek to show it to every model. A model’s revealed list can show it to that model only, and its hidden list always wins. See model tool access.

The diff you approve for search_replace is exactly what Orek writes. If the file changes while approval is pending, Orek keeps the newer file and asks the model to reread it and try again. Edit cards in the TUI show the resulting diff.

Execution tools

Shell commands and background jobs

• Shell choice: bash and powershell are other names for shell. On Windows, Orek prefers PowerShell 7, then Windows PowerShell 5.1; on macOS and Linux, it prefers $SHELL, then bash. See shell settings. Each call starts a fresh shell. Shells that are neither POSIX-compatible nor PowerShell (such as fish) always ask for approval outside yolo.
• Python (run_python): On by default ([tools.run_python] enabled = true). Takes script (up to 16 KiB), optional input_command (its output becomes the script’s standard input), cwd, timeout (default 30 seconds), and max_output_bytes. On POSIX shells, a shell call that pipes into inline Python (... | python3 - <<EOF) is refused before approval and the model is told to use run_python.
• No interactive input: Commands run without a terminal, so prompts from ssh or sudo fail at once on macOS and Linux or time out on Windows. Use non-interactive options such as ssh -o BatchMode=yes or a credential helper.
• Foreground commands: Orek strips color codes, hides recognized secrets, and condenses passing tests and repeated lint lines, keeping a limited full copy for read_exec_output. A timeout stops the command and returns the output so far. Pass background: true to shell for long-running processes.
• Background jobs: Each job has a job_id that belongs to the session (not a process ID). A session can have up to exec.max_background_jobs jobs (default 64). read_background_output accepts wait_ms up to 600,000. Stopping a job stops all of its processes. Ending the session stops every job and deletes its output.
• Plan mode and preview modes: Plan mode allows list_background_processes, read_background_output, and read_exec_output, and blocks shell, run_python, kill_background_process, and cargo_check_diagnostics. The experimental exec.default_sandbox modes dry_run and simulation preview or describe changes without making them.

Network results

Web search and page fetching by the provider are on by default for the built-in OpenAI, Anthropic, and Google models; see provider web tools. Orek has no web search tool of its own. When the provider fetches pages, webfetch is not offered, and Orek doesn’t fall back to it if the provider’s fetch fails.

webfetch converts HTML pages to Markdown, keeping headings, lists, full links, and code blocks, or falls back to the visible text when it can’t find the main article. It formats JSON, leaves out PDF and image content, and passes other text through unchanged.

webfetch checks every URL and redirect against the URL allowlist and blocks private and local network addresses. Provider web tools are checked once before the request is sent, because Orek can’t see each search or fetch the provider makes. See URL allowlist.

Work-management tools

write_tasks entries can be plain text or objects with an optional status, blocked_reason, and id. The statuses are pending, in_progress, blocked, completed, and cancelled; like completed, cancelled counts as finished. An empty list clears the checklist, except while an approved plan is Active, when clear: true is required. Passing an entry’s ID to a subagent as work_item_id gives the subagent that entry’s text, blocked reason, and any earlier result, and links the subagent’s result to the entry. The checklist is saved before the tool reports success.

In the TUI, and in orek run or editor sessions that resume saved work, a request keeps going until no task is pending, in_progress, or blocked and no subagent is running. update_plan and write_tasks are blocked while a plan is being drafted in Plan mode. See Track multi-step work.

Memory

The memory tool saves and reads lasting facts outside your projects:

Facts live in the memory folder next to your user config.toml (orek config path shows where). scope is global (memory/, the default for user facts) or project (memory/projects/<hash>/, the default for every other kind). Orek reads both together; neither hides the other. Each fact is a Markdown file you can edit, with YAML front matter for name, a one-line description, and metadata.type. Only a short index (up to 120 entries and 16 KiB) goes into the model’s instructions; the model reads a full fact with get.

Memory writes work in Plan mode and don’t ask for approval in default, auto_review, or yolo unless a permission rule says so. Set tools.memory.enabled to false (user setting, default true) and restart Orek to turn off both the tool and the index. Subagents share the same memory.

Subagent tools

list_agents and wait_agent report each subagent’s task (up to 500 characters), status, what it is doing right now, turns and tokens used, and the files it changed with write_file, search_replace, delete_file, and apply_patch (up to 100 files). Files changed through shell commands are not listed.

An empty final answer is retried once, and an answer that doesn’t match its result_schema up to agent.max_result_schema_retries times. These retries can’t run tools, so the subagent answers in text.

Every agent below the depth limit (agent.max_subagent_depth) has these tools and can reach any subagent in the session by ID or name. close_agent can’t close the agent that calls it.

send_input takes a target (an agent ID, name, or main), the message input, and an optional interrupt (not allowed for main or the sender itself), which replaces a running subagent’s current turn. See Messages between agents for delivery and limits, and When a subagent finishes for how results arrive.

The built-in profiles are explore, edit, reviewer, and tester; see Choose a profile for their tools. A profile’s allowed_tools list keeps a subagent focused; it is not a security boundary, and every subagent works directly in the session’s workspace.

Depth, concurrency, and wait limits come from agent settings. A subagent started past max_live_subagents waits for a free slot instead of failing. spawn_agent and fanout accept a result_schema (JSON Schema Draft 7 by default, or Draft 2020-12 when $schema says so) and return the checked result as validated_result. fanout closes subagents that haven’t finished when it times out. See Subagents for examples.

Adversarial verification

adversarial_verify takes a single claim, skeptics (2 or 3), and an optional timeout_ms from 1 to 86,400,000; the default is 15 minutes. Each skeptic works alone, without starting or messaging other agents, and must return an assessment, a reason, and one to three pieces of evidence.

Two valid refutations give refuted. Only unanimous, valid non-refutation gives not_refuted, which is not proof. Disagreement, missing evidence, malformed answers, model or startup failures, timeouts, and cancellation give inconclusive.

The user setting agent.adversarial_verify_models lists models to use, in order; each must be configured and able to use tools, and each skeptic gets a different one, so list at least as many models as skeptics. When the list is empty, every skeptic uses the active model and the result says so.

Plan-mode tools

Enter Plan mode with /plan. It ends when you approve the model’s final plan or run /plan exit or /plan clear. Plan mode applies to the whole session: every subagent is in Plan mode while the session is.

No agent has a tool that enters or leaves Plan mode. Edits and commands are blocked in Plan mode, while permitted read tools and memory still work. See Plan mode.

Skills

To find, complete, and use skills, start with Use skills. This section lists exact activation rules and limits.

Prompt example:

Use $code-review to review the changes in this project.

Skill mentions take no arguments, and the rest of your prompt is unchanged. There is no /skill-name command. A loaded skill enters the conversation just before the message that asked for it and stays for the rest of the session.

The built-in code-review and performance-investigation skills have the lowest priority; a project or user skill with the same name replaces them. Turning off skills.enabled removes all skills, built-in ones included, and $ activation. Skills from other tools aren’t available to the model until you import them.

Mention parsing and limits

Index inspection

These index commands run in the TUI; they are not tools the model can use:

/index status

/index query where is the retry policy implemented?

Automatic retrieval runs before a turn only when it is enabled and the index is available; @!retrieve skips it for one turn. /retrieval off applies to the current session; /retrieval persist off saves it as your default. Explicit @ references and code_graph_query work either way. See Find and explore code.

Approval and policy

Seeing a tool doesn’t let a model skip the checks: every time a tool runs, Orek applies the approval mode, tool and path rules, sensitive file checks, and the URL allowlist.

Enter /doctor to see your effective rules. See Permissions and security for settings, coverage, and limits.