Agent tools reference

Tools are functions the LLM can call with JSON arguments. Results are returned as JSON strings (errors include an error field). Only advertised tools are sent to the model for a given mode.

Aliases: search_code also answers to grep; shell to terminal / run_process; todo to plan.

Mode summary

Capability	Ask	Plan	Agent
Read/search/list/glob/git/diagnostics read	Yes	Yes	Yes
todo (session task list)	Yes	Yes	Yes
create_plan_file	No	Yes	Yes
write_file, apply_patch, edit_file, shell	No	No	Yes

Path rules

Read/search tools may target paths outside the workspace (absolute paths or .. segments are allowed after canonicalization).
Write tools and shell cwd default to the workspace root only. Per chat session, enable Allow modify outside the working directory to lift that write sandbox.
create_plan_file and chat image attachments always stay under the workspace (.plan/ and .lca/attachments/).

Tools

read_file

Read text from a file with optional line offset and limit (large file and line caps apply). Modes: Ask, Plan, Agent.

write_file

Write or overwrite a file; creates parent directories as needed. Modes: Agent only.

list_directory

List immediate children of a directory (sorted, capped entry count). Modes: Ask, Plan, Agent.

glob

Find paths matching a wildcard pattern. On Windows and macOS, matching is case-insensitive; on Linux it is case-sensitive. Modes: Ask, Plan, Agent.

search_code

Search file contents (literal or regex, optional path glob). Skips files larger than 16 MiB and extremely long lines. Alias: grep. Modes: Ask, Plan, Agent.

apply_patch

Apply a unified diff after validation (create, modify, delete files). On success, the JSON may include a warnings array when the tool corrected minor format issues. Modes: Agent only.

Patch format pitfalls

One-line change: @@ -N,1 +N,1 @@ then exactly one - line and one + line.
The number after the comma in @@ -start,count is how many old-side hunk lines follow, not “lines start through end.”
Failures return error_kind such as context_mismatch, invalid_hunk, incomplete_hunk, or hunk_count_mismatch; many errors include a hint field.

edit_file

Replace exactly one occurrence of old_text with new_text in a file (strict byte match). Modes: Agent only.

shell

Run a shell command in the project directory with timeout limits (Unix: /bin/sh -c; Windows: cmd.exe /C). Modes: Agent only.

diagnostics

Read cached compiler/linter output; in Agent mode can run a build/check and refresh the cache. Auto-detected builds run with cwd set to the directory that contains the manifest. Modes: Ask, Plan, Agent (build side effects in Agent).

git

Inspect repository: status, diff, log, or show. No commits or pushes. Modes: Ask, Plan, Agent.

todo

Read or replace a session-local task list (pending / in_progress / completed). Alias: plan. Modes: Ask, Plan, Agent.

create_plan_file

Save plan markdown under <workspace>/.plan/plan-*.md. Modes: Plan, Agent.

Educational note

When you add or change tools in the application source, update this page and How the agent works so documentation stays aligned with behavior.