tools.md

Tools

The built-in tools the model can call, their arguments, permissions and the modes that expose them. Names, argument names and permission flags are taken from the constructors under internal/tools and the optional packages; internal/tools.NewRegistryFor builds the registry from them, and internal/agent.ToolSetForMode in internal/agent/toolsets.go decides which definitions each mode sends to the model. Agent mode is unrestricted; plan and ask carry fixed allowlists, and ask re-checks its list at execution time so a call replayed from history cannot cross it. The reasoning behind the modes is in Operating modes; how to add a tool is in Custom tools.

Permissions

The Permission column uses the classes the gate in internal/agent/react.go applies under tools.permission_mode (ask by default, accept_edits, bypass; see Security and trust):

• none: never prompts;
• write: the file-write class - prompts under ask unless the path was granted in this session, auto-approved under accept_edits and bypass;
• command: run_command - prompts unless the command is covered by tools.command_allowlist or a session grant (including the program-wide grants a prompt can store, see Background tasks); bypass skips the prompt;
• config: config_commit and config_rollback - prompts under ask and accept_edits, since a commit can start MCP processes and change the permission policy itself; only bypass skips it;
• http: http_request - prompts under ask and accept_edits unless the destination is in tools.http_request.allowlist or was approved in this session and everything the request carries (local files, a proxy, an unchecked certificate, and under ask the file it saves) was approved with it; bypass skips it (HTTP requests);
• always: tools that set RequiresPermission outside those classes - the permission mode does not change them, and only a PreToolUse hook answering allow skips the prompt.

Files

Tool	Purpose	Arguments (short)	Permission	Modes
read	Read a file as text with an optional 1-based line range, or list a directory; text in another encoding (UTF-16, a legacy code page) is converted to UTF-8. A PNG, JPEG, GIF or WebP file (told by its content) is shown to a model with models[].multimodal: true as a picture, up to 3.75 MB and 8000 pixels a side and only a file whole to its end, a GIF as its first frame, and the web UI and a Telegram chat show it too (Images); any other binary file (a PDF, an archive), and a picture for a model without multimodal, is refused with its type and size	path, offset, limit, recursive, show_hidden, keep	none	agent, plan, ask
keep_result	Mark a page already read or a grep result as useful so result eviction keeps it (Context compaction)	path, offset, limit, pattern	none	agent, plan, ask
glob	Find files by glob pattern, newest first, at most 100 paths	pattern, path	none	agent, plan, ask
grep	Regular-expression search over file contents	pattern, path, glob, case_sensitive, max_results, keep	none	agent, plan, ask
print_tree	Print a directory tree like tree	path, depth	none	agent, plan, ask
edit	Replace an exact text range; line endings are preserved	path, oldString, newString, replaceAll	write	agent
write	Create or overwrite a file; parent directories are created	path, content	write	agent
apply_patch	Apply a unified diff or a Codex V4A patch	path, patch	write	agent
mkdir	Create a directory; parents works like mkdir -p	path, parents	write	agent
rmdir	Remove an empty directory	path	write	agent
touch	Create an empty file or refresh its modification time	path, create_parents	write	agent
rm	Remove a file, or a whole tree with recursive	path, recursive	write	agent
mv	Move or rename; destination parents are created	src, dst	write	agent

Shell and background tasks

The background_* tools are registered only while tools.background is enabled (the default), and preview_server while tools.preview_server is enabled as well. The guide is Background tasks.

Tool	Purpose	Arguments (short)	Permission	Modes
run_command	Run a shell command in the workspace through the host shell; optional cwd changes the directory for this command only. background: true returns a task id and wakes the agent on completion by default where available. A foreground command that outlives its timeout is handed to the pool and also wakes on completion by default; notify_on_finish: false disables either wake	command, cwd, permission_rationale, timeout_seconds, background, notify_on_finish, expected_seconds	command	agent, plan
share_file	Copy one regular, non-symlink file from the workspace into the current persisted session as an immutable downloadable artifact. The copy is content-addressed, capped at 25 MiB (100 MiB per session), and does not enter model prompt content or transcript exports. It is unavailable to subagents.	path	always	agent
worktree_create	Fetch origin, create or reuse a feature worktree from its default branch (creation needs a reachable origin), and move the session into it	branch	always	agent
background_list	List the session's background tasks with status, elapsed time and estimate	none	none	agent, plan
background_output	Return the captured stdout and stderr of a task	task_id, tail_lines	none	agent, plan
background_wait	Wait for a task to finish, bounded by a default and a maximum	task_id, timeout_seconds	none	agent, plan
background_stop	Terminate a task and everything it spawned	task_id	none	agent, plan
background_reap	Find and kill processes of this session that outlived the run which started them	none	always	agent
preview_server	Serve a directory of the project as a static website on a free localhost port and return the address for the user to open; the server is a background task that runs until it is stopped (Preview server)	path, timeout_seconds	none	agent
ssh_run_command	Run a command on a remote host over SSH, using the agent socket and then key files (Configuration)	host, command, port, timeout_seconds, permission_rationale	always	agent

Web

Tool	Purpose	Arguments (short)	Permission	Modes
websearch	Search several engines at once and merge the results, reporting each engine's outcome	query, page, max_results, site	none	agent, plan, ask
webfetch	Download a public page and return its main text as Markdown; private networks and localhost are refused, every redirect included	url, timeout_seconds, max_chars	none	agent, plan, ask
http_request	Send any HTTP or HTTPS request, like curl, and return the status line, headers and body, or save the body to a file (HTTP requests)	url, method, query, headers, one of body / body_base64 / body_file / json / form / form_data, output_file, follow_redirects, proxy, verify_tls, timeout_seconds, permission_rationale	http	agent

websearch asks the engines named in tools.websearch.engines (Brave then Bing by default) and reports each one's outcome next to the results, so an engine that answered a challenge page is named rather than counted as nothing found; a search where every engine was turned away fails instead of returning an empty list. Which engines exist, how the relevance gate discards an unrelated result set, and how to point it at your own SearXNG: Web search.

http_request is the tool for everything else over HTTP: APIs, services on localhost, uploads and downloads. It refuses no address, which is why it is gated; webfetch shares its client and differs in the SSRF guard, the fixed GET and the Markdown conversion (HTTP requests). Headers the operator wants on every request, such as a browser User-Agent, go into tools.http_request.default_headers, which only http_request sends and a call's own headers override (Default headers).

Interaction, skills and subagents

Tool	Purpose	Arguments (short)	Permission	Modes
question	Ask the user one or more multiple-choice questions and wait for the answers	questions[] of header, question, options[] (label, description), multiple, custom	none (the turn waits for the user)	agent, plan, ask
load_skill	Load the full instructions of a catalogued skill by name; registered only while skills.auto_discovery is on (Skills)	name	none	agent, plan, ask
coddy_docs_search	Search Coddy's own documentation, built into the binary, with BM25 over the sections (Built-in documentation)	query, limit	none	agent, plan, ask
coddy_docs_read	Read a page or a section of that documentation, or its contents without a page; long pages come in parts	page, offset	none	agent, plan, ask
spawn_agent	Delegate a self-contained task to a subagent, waiting for its report or running it as a background task. A detached child wakes the parent on completion by default where available; notify_on_finish: false disables it. resume continues a finished run in its own child session instead of starting over (Subagents)	agent, prompt, description, model, reasoning, background, expected_seconds, timeout_seconds, notify_on_finish, resume	none itself; the child's own calls prompt through the parent	agent, plan (the child of a plan-mode parent stays in plan mode); hidden in ask, at subagents.max_depth unless the session's own definition declared a spawns allowlist, and where no runtime exists, such as a scheduled run
switch_model	Change the model or reasoning level only when the user asks; applies from the next request for the session by default, or only this turn with scope: turn (Session settings)	model, reasoning, scope (session or turn)	none	agent, plan, ask; never offered to a subagent

Todo checklist

The session's plan document as a checklist, persisted in the bundle and shown as the ACP plan update (Sessions). Agent mode only.

Tool	Purpose	Arguments (short)	Permission	Modes
coddy_todo_plan_read	Read the checklist without changing it	none	none	agent
coddy_todo_plan_replace	Replace the whole checklist from Markdown	markdown	none	agent
coddy_todo_plan_archive	Finalise the checklist: incomplete items are marked completed and the plan is archived	none	none	agent
coddy_todo_item_add	Add one item, at the end or after an index	content, status, after_index	none	agent
coddy_todo_item_remove	Remove one item by zero-based index	index	none	agent
coddy_todo_item_update	Change the content or the status of one item	index, content, status	none	agent
coddy_todo_item_move	Move one row	from_index, to_index	none	agent

Design plans

Plan documents live at plans/<slug>.plan.md inside the session bundle (Operating modes, ACP protocol).

Tool	Purpose	Arguments (short)	Permission	Modes
plan_write	Write or replace a plan document	slug, content	none	agent, plan
plan_list	List the plan documents of the session	none	none	agent, plan
plan_read	Read one plan document	slug	none	agent, plan
plan_exit	Switch the session from plan mode to agent mode	none	none	agent (not in the plan allowlist)

Context

Tool	Purpose	Arguments (short)	Permission	Modes
compact_context	Fold the older history into a summary so the session keeps fitting the model's context window (Context compaction)	instructions, model (the summariser for this one call, passed only when the user named one: a configured model id, its name without the provider, or a part of one that matches exactly one)	none	agent, plan; not in ask, whose tools stay read-only; hidden when compaction.enable is false

The session's own filing

The title a conversation is listed under and the tags it is grouped by (Sessions). The session the tool files is the one it runs in - a subagent files its own child session, never its parent's.

Tool	Purpose	Arguments (short)	Permission	Modes
session_describe	Read the session's title and tags, and change either; called with no arguments it only reports them	title, tags, add_tags, remove_tags	none	agent, plan; not in ask, whose tools stay read-only

Self-configuration

Staged edits to the live config.yaml (config.yaml reference). The editing family is offered only when the surface wired a configuration reloader; without one, config_get is the only member left.

Tool	Purpose	Arguments (short)	Permission	Modes
config_get	Read a redacted value by dotted uci-style path; . is the whole file	path	none	agent, plan
config_changes	List the staged commands a commit would apply	none	none	agent, plan
config_set	Stage uci-like commands against the active file: set <path>=<value>, add_list <path>=<value>, del_list <path>=<value>, delete <path>	commands[]	none	agent
config_revert	Discard staged commands, all of them or those under a path	path	none	agent
config_commit	Validate the batch, snapshot the previous file and apply; hot-reloads the running process	none	config	agent
config_rollback	Restore the snapshot written by the last commit	none	config	agent

Scheduler

Compiled in with the scheduler tag and registered only while the scheduler is enabled (internal/tools/scheduler_hook.go, external/scheduler/tools/register.go). job_id is the file basename; every per-job tool takes scope, user (default, ${CODDY_HOME}/scheduler) or project (<session cwd>/.coddy/scheduler, a job that runs only once the operator approved it; no tool approves one); the job fields are those of the frontmatter (Scheduler). Agent mode only.

Tool	Purpose	Arguments (short)	Permission	Modes
coddy_scheduler_jobs_list	List the user jobs and the project jobs of the session's workspace and of the workspaces the scheduler runs, each with its scope and trust	include_body	none	agent
coddy_scheduler_job_get	Load one job	scope, job_id	none	agent
coddy_scheduler_job_runs	List the runs of a job, newest first: the task under the job session, the run session that holds the transcript, trigger, status and timing	scope, job_id, limit	none	agent
coddy_scheduler_job_create	Create a job file	scope, job_id, description, schedule, paused, cwd, model, mode, agent, permission_mode, body	always	agent
coddy_scheduler_job_replace	Replace every field of a job	scope, job_id, description, schedule, paused, cwd, model, mode, agent, permission_mode, body	always	agent
coddy_scheduler_job_patch	Change only the given fields, optionally renaming the job	scope, job_id, new_job_id, description, schedule, paused, cwd, model, mode, agent, permission_mode, body	always	agent
coddy_scheduler_job_pause, coddy_scheduler_job_resume	Set or clear paused	scope, job_id	always	agent
coddy_scheduler_job_delete	Delete a job, its .state sidecar and its run history when no run is in flight	scope, job_id	always	agent
coddy_scheduler_job_run	Start one run now, as a background agent task under the job session; answers with the task and the run session	scope, job_id	always	agent
coddy_scheduler_job_cancel	Stop the run of a job that is in flight	scope, job_id	always	agent

Memory subagent

With the memory tag, every user turn starts a memory subagent, a child agent run in the background task pool, and these are its tools: they are registered into that child's registry only (internal/agent/memory_hooks.go, external/memory/tools), so the main model never sees them. A recall-only child (an ask-mode turn) gets the first three, every other child all six. Paths are scope:relative/path.md (Long-term memory).

Tool	Purpose	Arguments (short)	Permission	Modes
coddy_memory_search	Rank the notes under the chosen roots against a query	query, scope	none	memory child
coddy_memory_list	List directories and notes one level under a path	path	none	memory child
coddy_memory_read	Read one note	path	none	memory child
coddy_memory_mkdir	Create nested folders under a scope	path	none	memory child
coddy_memory_save	Write or overwrite a note	title, body, scope, relative_path	none	memory child
coddy_memory_delete	Delete a note or a folder with everything under it, never a root	path	none	memory child

MCP tools

Every enabled tool of every connected MCP server joins the same function-calling list under the name server__tool, with the server's own input schema and a description prefixed with [server] (internal/mcp/client.go; MCP servers). Because __ is the separator, a server name may not contain it. The definitions are appended in agent and plan mode and never in ask mode, where a call to such a name is refused at execution time. A call whose name contains __ bypasses the registry: the agent routes it to the owning server and applies the default output limit to the result. There is no built-in permission prompt for MCP calls; whether a server may start is the workspace trust decision, and the per-server and per-tool disable switches bound what a running server may do (MCP servers).

Such a call reads as an action like every built-in one rather than as its registry id: the transcript row and the console box say calling browser_navigate on the MCP server playwright (Russian: запускаю browser_navigate на MCP-сервере playwright), and the live status line spends its target on playwright/browser_navigate, since the generic verb cannot say what the call does. The mcp__server__tool spelling other agents use is read the same way. Beside the label the row names what the call acts on, from its path, url or name argument as for a built-in tool; a server that names its arguments otherwise falls back to the first one that reads as a label - single-line, not a body (Web UI).

What runs before a tool call

Operator hooks see every call, MCP tools included, before the permission gate and whatever the permission mode (Hooks). A PreToolUse hook answering permissionDecision: deny stops the call; it is never executed and the model reads blocked by hook: <reason> as the tool result. allow skips the prompt a tool would otherwise raise, ask forces one even under accept_edits or bypass, and updatedInput replaces the argument object before the call runs. Several matching hooks all run, and the most restrictive decision wins.

A subagent's tool set is narrowed from the parent's (Subagents): a definition's tools and disallowed_tools only remove names, and question, the five config editing tools and plan_exit are excluded from every child, so a child can neither ask the user nor rewrite the configuration nor leave plan mode. Results are capped by tools.output_limits before they reach the model, for built-in and MCP tools alike.