← Reference

Tools

Every tool the agent can call.

Full notes from the app

Tools are registered into the global ToolRegistry. Permission rules can selectively allow/deny per-tool.

69 entries · kcode 0.6.5097

69 shown
ToolLibraryWhat it does
Bash
bashtool-bashRun a shell command in the agent's shell. It runs in kcode's shell host, which runs the brush interpreter in process (a hard fork: no /bin/bash). Substitutions beside a here-document delimiter stay one word, and nested here-documents keep their own bodies. Permission checks use the same Brush syntax parser: a backslash-led command on a new line is checked separately, while quoted newlines remain text. Unresolved command names, execution flags and scripts get no read-only or accept-edits credit; proven quoted data operands remain usable. Command allows require definite argv coverage, denies check possible expanded argv, and the last matching rule still wins. Brace-generated commands and argument lists are checked using the executor's pure generator, with quoted and escaped braces kept literal. Checks cover brace expansion enabled or disabled. If static brace analysis exceeds its budget, a broad tool allow cannot grant it automatically: it needs permission outside Plan and is refused in Plan; execution keeps its existing limits. Nothing is executed to make that decision. Shell state persists across calls like one continuous terminal: each run's cd and exported-env changes (including sourced venv activations) carry into the next call's seed (fresh_state: true opts out; tool_bash.persist_shell_state = false disables). Each agent has its own: a subagent's shell starts fresh and its changes never reach its parent's. Output is captured in full, and each stream of the result is limited to max_output_bytes (default tool_bash.default_truncate_bytes; a call may set up to 1 MiB, or more when the default is larger): a longer stream keeps its first quarter and last three quarters around a line naming the bytes left out and the exact shell_output_slice call that returns them, so the agent reads the rest instead of rerunning the command. A command that exceeds the timeout (120s default) keeps running in the background instead of being killed: the result carries background_exec_id to query/wait/kill via the shell_* tools. The result also carries env_changes, cwd_change, and redirects, the exported variables a command set (e.g. a sourced activate), where it cd'd, and the files it opened via redirection (resolved paths, so a runtime-computed target like > "$LOG" surfaces as the concrete file), so the agent can carry that state into later commands, plus per-stage pipeline exits and the run's observed footprint: pipestatus (each stage's own exit code for a 2+-stage pipeline, bash $PIPESTATUS semantics, so under the default pipefail you see which stage failed), signal (terminating signal), max_rss_bytes, cpu_user_ms/cpu_system_ms, and distinct_endpoints (count of remote peers contacted; the full endpoint list stays on shell_wait and on shell_status with resources: true). A PTY command that stops at an interactive prompt is handed back immediately (waiting_for_input: true + the detected prompt text + background_exec_id) so the agent answers via shell_write_stdin within seconds instead of burning the full timeout. Pass use_pty: true to run under a pseudo-terminal (so isatty() is true) for tools that refuse to run, colorize, or prompt without a TTY: this merges stdout and stderr into one stream. A sudo/su password prompt ([sudo] password for …: / Password:) is the one prompt that does NOT come to the model: it pops a masked password dialog for the user, the answer is typed straight to the command's stdin, and the value is never logged, never in the tool result, never in the transcript; dismissing the dialog kills the command (headless runs fall back to the generic waiting_for_input hand-back). A backgrounded command is exit-watched by default: when it exits, a pushed <cp:shell-exit> notification (exec id, exit code, output tail) wakes the session even from idle and continues a turn it lands in (unless the user stopped the command from /jobs: that notice waits for the next round and tells the agent not to restart it), the agent continues with other work or ends its turn instead of blocking on shell_wait (one-shot per command; a shell_wait on a watched exec is refused). The one exception is a command parked at an interactive prompt: it is waiting for shell_write_stdin, not an exit, so there the watch stays opt-in via notify_on_exit: true.
shell_spawntool-bashStart a command in the background; returns an exec_id to query later. Accepts use_pty: true for a PTY-backed run (isatty true), e.g. for a command that prompts. Accepts notify_on_exit: true for a pushed <cp:shell-exit> completion notice (exec id, exit code, output tail) instead of polling. Its command is judged like a bash command: the prompt names it, bash(…) rules match it, plan mode refuses it unless it only reads, and a command that only reads the project runs without a prompt.
shell_statustool-bashShow whether a command is still running, or how it ended. It covers the command exec_id names, or every known command when exec_id is omitted: running, exited, signaled or killed, with the exit code, command line and elapsed time. resources: true adds a fresh resource sample to each status: captured output bytes, aggregate RSS/CPU/fd/thread counts, open network endpoints (sockets with local/remote address and TCP state), and a per-process breakdown (one sample per live pipeline stage), sampled via proc-observe.
shell_waittool-bashBlock until a command finishes (or times out); returns its outcome. Stopping the turn ends the wait at once and leaves the command running.
shell_write_stdintool-bashWrite text to a running command's stdin (e.g. answer an interactive prompt).
shell_signaltool-bashSend a signal to a command's processes. The signal is a number, sent to the command's process groups: a running command's, or those of the background jobs a finished command left running. A finished command with no job still running is not signalled, since the ids of its ended process groups may since belong to other programs, and a number too large to be a signal is refused. Runs without a prompt in every mode unless a rule denies it, and can reach your own ! commands in the session, which run in the same shell.
shell_killtool-bashKill a command's whole process-group subtree, the background jobs it started included. A command that has already finished has the jobs it left running killed, and the answer says how many the kill stopped. Runs without a prompt in every mode unless a rule denies it, and can reach your own ! commands in the session, which run in the same shell.
shell_plantool-bashCheck what a command would do, without running it. It reads the command in the agent's shell as it stands (the folder and exported variables earlier bash calls left) and reports each command's words and the file it runs (none for a builtin the shell runs itself), read-only and sed-in-place flags, the predicted side-effect class, how many paths the filename patterns of a line that isn't read-only match now, in each folder a cd may reach, and parses (brush's own verdict on whether the command will parse). A quoted pattern, and one only the running shell can place such as $X/*.log, gets no count. Returns a plan_id.
shell_proceedtool-bashAct on a plan from shell_plan: run it as-is (proceed), drop it (abort), or run a replacement (modify). The command it runs is checked like a bash command, in the plan's folder, and only a plan this session's shell_plan made will run. A run goes as a bash call does and returns the same result: past tool_bash.default_timeout_seconds it keeps running in the background and the agent is woken when it exits, an interactive prompt comes back at once, stopping the turn kills it, its output is limited to tool_bash.default_truncate_bytes a stream, and its cd and exports carry into later calls. An abort runs nothing, so it runs without a prompt in every mode unless a rule denies it.
shell_whichtool-bashFind the file the agent's shell would run for a command. A name is looked up on the PATH its earlier commands' export and cd left, a path is read from the folder its shell is in, and the result adds canonical (the symlink-chain target when it differs, e.g. a Homebrew entry into its Cellar), and shim, when the path is a version-manager shim (asdf, mise, pyenv, rbenv, nodenv) the manager is named and the real binary it currently selects is reported via <manager> which. A name found on PATH is also run with --version for its version line and flavor (gnu/busybox from the version line; bsd inferred for versionless system binaries on macOS: best-effort); a path is never run, and a note says so.
shell_helptool-bashShow a command's help text. It runs the command's --help in the agent's shell: its folder and the PATH its earlier commands left, so it reaches the program a command would run, falling back to man when --help isn't supported, and returns the text (best-effort, capped); the result names its source (--help or man). Takes a program name, optionally followed by subcommand names (git commit); a path, a flag or shell text is refused.
shell_envtool-bashShow the agent's shell environment, without variable values. It reads the environment as earlier export and unset calls left it: PATH entries, $SHELL, and the names of the exported variables (values left out so no secret is shown).
shell_projecttool-bashList the project's build files and the targets they define. It looks in the shell's folder, where an earlier cd left it, or in cwd (Makefile, package.json, Cargo.toml, justfile, go.mod, …) and reads the targets the main runners define (Make targets, npm scripts, justfile recipes), so the agent knows what to run.
shell_globtool-bashExpand a glob pattern exactly as bash would. It expands with the brush engine's own filename expansion, in the shell's folder, where an earlier cd left it, or in cwd, and returns the matching paths (empty if none match).
shell_eventstool-bashRead the shell events the agent has not read yet. They cover commands starting and exiting, interactive prompts and host restarts, of the classes shell_subscribe chose. Each agent reads its own, so a subagent reading them never takes them from the session.
shell_subscribetool-bashChoose which shell events shell_events returns. The classes are started, process_group, process_group_ended, exit_code, cwd, env, prompt, sudo_prompt, command_terminated and host_restarted; an empty list returns every class. Each agent's choice is its own, and a class name the shell doesn't have is refused.
shell_output_headtool-bashFirst N lines of a command's captured output.
shell_output_tailtool-bashLast N lines of a command's captured output.
shell_output_slicetool-bashA byte range of a command's captured output.
shell_output_greptool-bashRegex search over a command's captured output (with context lines).
shell_output_bytestool-bashTotal captured bytes for a command's stream.
Tests
test_discovertool-testsFind the tests in one folder and suggest a runner, without running project code. It reads the build and test files there in name order: Cargo.toml; package.json, pnpm-workspace.yaml, deno.json and the npm, pnpm, yarn, bun and deno lock files; pyproject.toml and pytest.ini; go.mod; Gradle build and settings files and gradlew; pom.xml and mvnw; .sln, .slnx and .NET project files; CMakeLists.txt; meson.build; composer.json and phpunit.xml; Gemfile and .rspec; .busted and .rockspec; pubspec.yaml; Package.swift and the schemes an .xcodeproj or .xcworkspace shares; an R package's DESCRIPTION; and the Pester (.Tests.ps1) and Bats files in the directory and its test and tests folders. Reports packages, targets, test scripts and workspace members as written, never expanded; inspect a member directory to select its package. A file that is not a regular file, such as a pipe named like a manifest, is reported, never waited on. Does not prove a runner is installed.
run_teststool-testsRun one test scope in the background. It runs through the shared shell service, with one of 26 runners: cargo, pytest, unittest, go, npm, pnpm, yarn, bun, deno, gradle, maven, dotnet, ctest, meson, pester, phpunit, pest, busted, rspec, minitest, dart, flutter, swift, xcodebuild, testthat and bats. Each runner takes only some fields, and a refusal names the ones it does. Cargo requires one package (defaults to library tests); Gradle requires one project path (for the root) and Maven one module, with wrapper to run ./gradlew or ./mvnw; xcodebuild requires a scheme (platform=macOS by default); pytest, unittest, Go, ctest, meson, Pester, minitest and Bats require a target; npm, pnpm, yarn, bun and deno run one non-watch package.json script or deno task, optionally in one workspace package. No raw flags or implicit workspace runs. Returns run_id and shell exec_id; shell-exit notifies completion, then test_status reports the verdict. cwd is project-relative; the launch environment plus explicit env is used, not carried bash exports. CI and NO_COLOR are forced. An env variable that passes the runner more options (PYTEST_ADDOPTS, PYTEST_PLUGINS, GOFLAGS, NODE_OPTIONS, BUN_OPTIONS, DART_VM_OPTIONS, the JVM's, Gradle's and Maven's option variables, SPEC_OPTS, RUBYOPT, R's startup profiles, LUA_INIT, npm_config_* and pnpm_config_*, RUSTFLAGS and its Cargo forms) is refused, and the permission prompt names every variable the run gets before the command. Tests execute project code and require execution permission. Other runners remain runnable through bash.
test_statustool-testsRead a test run's state and results; omit run_id to list runs. It gives the run's process state, exit code, observed counts, failure names and log tails, each within a limit. Process success is separate from test success. Counts are read from both output streams: a JavaScript script's as Vitest, Jest, Mocha, the Node test runner, Bun, Deno or Playwright output, and, once a Gradle run has ended, from the JUnit XML reports it wrote, up to tool_tests.report_bytes; evidence.formats names what they were read from and reports says how many reports were read. Unrecognized or truncated output, zero passed tests, interrupted or lost runs never count as passed. Prefer completion notifications over polling.
test_outputtool-testsRead a page of a test run's stdout or stderr, by run_id. Offsets count raw bytes; omit start for the tail. ANSI is removed after slicing, so a boundary may split UTF-8. Reports missing bytes and more-output state. Reuses the shell output store and its retention; never reruns tests.
test_canceltool-testsStop a test run and every process it started. The stop goes to the run's process-group subtree on its original shell host. Never redirects a reused exec id to a replacement host or an unrelated user shell command. The acknowledgement is not the final test result. Runs without a prompt in every mode unless a rule denies it.
Fs
fs_readtool-fsRead a file's contents with line numbers. Supports optional offset (1-based) and limit (line count) for paginating large files. The byte cap applies to the requested page, including line numbers; lines_returned excludes truncation notices. A file of up to 1 MiB is read whole and total_lines counts all its lines; a larger one is read a line at a time up to the page, so total_lines is null until a page reaches the end of the file, and the result gives its size_bytes instead. Only the lines a page serves must be text: a line that is not UTF-8 is refused by its number. A folder, a pipe, a device or a socket is refused at once, without waiting for a pipe's writer. Repeat reads of an unchanged file return a short unchanged-since-last-read marker instead of re-streaming content, while the earlier read is still in the reading agent's conversation: a subagent reading a file its parent read gets the content, and so does a read after a compaction took the earlier read out; refresh=true re-streams the requested page, still subject to the byte cap.
fs_writetool-fsOverwrite a file with new contents. Creates parent directories if missing. Overwriting an existing file requires the agent writing it to have read its current contents first, in a read its conversation still holds: a subagent's parent's read doesn't count, a compaction that takes the read out undoes it, and a file the compaction puts back whole counts as read. Brand-new paths need no prior read. A path outside the folder it writes in (the session's, or the one project_root names) is refused before any permission prompt, and the error says to set project_root to write in another folder. A folder, a pipe or a device is refused at once, without reading it.
fs_edittool-fsReplace old_string with new_string in a file. Set replace_all=true for global replacement. Read-before-edit is enforced: edits to files whose current contents the editing agent has not read, in a read its conversation still holds, or that changed on disk since the read, are rejected with the remedy named, as for fs_write, a subagent's parent's read doesn't count, and a compaction that takes the read out undoes it. The lines it writes end the way the lines they replace do (LF or CRLF), whichever ending new_string uses. A folder, a pipe or a device is refused at once, without reading it.
apply_patchtool-fsApply a patch to one or more files; a failed write puts back the files already changed. Grammar: *** Begin Patch, then *** Add File: (lines prefixed +), *** Delete File:, and *** Update File: (optional *** Move to: rename; hunks of space-prefixed context, - removals, + additions, @@ anchors, and *** End of File after a hunk that ends the file), then *** End Patch. Hunks use whole-line fuzzy matching; an unmatched hunk writes nothing. A file's result row lists each hunk that matched only loosely in fuzzy_matches: its number, counted across the file's sections in patch order, and the matching step that placed it. A hunk's lines end the way the lines they replace do (LF or CRLF); a hunk that only adds lines ends them the way most of the file's lines end. Replacement bytes are staged and I/O failures roll back earlier changes. This is not crash-atomic or isolated from external writers: incomplete recovery reports retained backup paths, and cleanup_leftovers names any staging debris after a successful commit. Existing files, including move destinations, require a prior fs_read by the same agent, in a read its conversation still holds. Writes stay within the effective project_root; patches refuse leaf symlinks, so name their target files explicitly. Plan mode refuses it, as it refuses fs_write and fs_edit. In the other modes it is judged as a write to every file the patch names, move destinations included: AcceptEdits runs it when all of them lie in the project, a path(…) rule judges each file, one denied file refuses the patch, and allow rules run it only when they cover every file, and the prompt lists the files. A patch that doesn't parse needs permission, and the tool refuses it. A folder, a pipe or a device is refused at once, without reading it.
fs_replacetool-fsReplace one pattern across many files, in two calls. A call with pattern and replacement writes nothing: it returns a preview, each file that would change, how many matches it has and up to three sample lines before and after, and a preview_id. A call with only that preview_id writes every file the preview listed, or none when one changed since the preview, naming the changed files. The preview counts as reading the files, so they need no fs_read first; a preview is used once, and only by the agent that made it. pattern is plain text unless regex is true; a regex's ^ and $ match at each line's start and end, and its replacement may name groups as $1 or ${name} ($$ for a $). case_insensitive matches in any case. path takes a file, a folder or a list of them (default: the session folder), and glob_filter a glob or a list, a glob starting with ! leaving its paths out. A walk leaves out what .gitignore, .ignore and .rgignore files name, hidden files and .git; a file named in path is always searched. Symlinks, files that aren't UTF-8 text and files over tool_fs.replace_max_file_bytes are passed over and counted. A preview of more than tool_fs.replace_max_files files is refused. A preview is judged as a read, so Plan mode runs it; an apply is judged as a write to every previewed file, as apply_patch is: Plan mode refuses it, AcceptEdits runs it when every file lies in the project, and the prompt lists the files. Each written file gets the same pre-write capture and language-server diagnostics as fs_edit. Use fs_edit for a change in one place.
fs_globtool-fsFind files by name or path, skipping what .gitignore leaves out. Patterns are relative to path (default cwd): .rs matches that directory only; /.rs includes descendants. Returns sorted files, not directories, relative to search_root: at most 1,000 (tool_fs.glob_max_results), the first in sorted order, with count giving the files listed and omitted the files left out. A folder the walk can't read doesn't lose the files found elsewhere: the result lists the paths it couldn't read under unreadable (the first 20, with the count), each with its reason. Stopping the turn stops the walk. Use shell_glob for shell expansion including directories. Chat cards show the pattern, scope, the whole count and clickable file paths, and end with a line saying how many paths couldn't be read.
Grep
greptool-grepSearch code and text with regex patterns (ripgrep-backed). Returns matches as {file, line, match} entries. pattern, path, glob_filter and exclude each take one string or a list: a line matches when it matches any pattern, every path is searched, a glob starting with ! leaves its paths out, and a match whose line matches an exclude regex is left out, with excluded counting them. case_insensitive matches in any case. context, context_before and context_after add up to 20 lines a side around each match, as before and after; max_count caps the matches from each file and max_matches the matches in all. Structured ripgrep JSON preserves filenames in single-file searches and paths containing colons; the result keeps at most 1,000 lines (tool_grep.max_lines) (each match counting once for its own line and once for each context line) the first half of the matches and the last, with omitted counting the ones between, and a matched line over 2,000 characters is cut, saying how many characters it left out. Non-UTF-8 bytes are decoded lossily into text rather than dropping the hit. A folder or file the search can't read doesn't lose the matches found elsewhere: the result lists the paths it couldn't read under unreadable (the first 20, with the count), and the card ends with a line counting them; a pattern ripgrep can't parse is an error that quotes ripgrep's reason. Chat cards show the query, scope, result count and bounded previews with clickable file locations; expand to see more hits.
Sem Search
sem_searchtool-sem-searchFind code by meaning, with a local index. It uses Codevex embeddings, including leading comments and supported docstrings. Combine with grep/rg for text and LSP for symbols, references and callers. Optional language/kind/path_filter, limit, hybrid BM25 fusion, refresh and status_only. The index persists in project SQLite and is shared across sessions; reopening reuses unchanged vectors. First use may download a verified MiniLM model; no source or query is uploaded. ready=false is not no matches: phase and last_error distinguish not-started, indexing and failed. Ready/failed notices arrive through semantic-index at the next agent round without waking idle sessions. Refresh atomically publishes complete generations and preserves last-good results on failure. Chat cards show the query, scope, count, index state and bounded previews with clickable file locations. Scores are not confidence; stale candidates are omitted. Read with fs_read before editing. Disable with codevex_runtime.enabled; offline mode uses codevex_local.allow_download=false.
Lsp
lsptool-lspCode navigation and diagnostics from the project's language servers. Its operations: go_to_definition, find_references, workspace_symbol, hover, document_symbol, prepare_call_hierarchy, incoming_calls, outgoing_calls, prepare_rename, the workspace-wide lsp_outline, server_status, and diagnostics. Diagnostics require a path, not a cursor: sync the on-disk file, wait within the configured cap, and report rows plus versions, freshness, timeout and truncation. A server that takes save notices is told the file was saved after each change, and the wait includes the check the save starts, such as rust-analyzer's cargo check, so the rows are not the ones from before the edit; while that check still runs, freshness reads checking. Once rust-analyzer's check has ended, its last report counts for the new version, since it publishes nothing when an edit leaves its findings as they were. TypeScript and JavaScript findings come from tsserver, asked for the text just synced, since typescript-language-server's own reports carry no version. rust-analyzer's checks build in a folder of their own, the project's target/rust-analyzer, so they never wait on the agent's builds or hold them up. Missing, stale, unversioned, indexing or checking reports are not proof of a clean file; even current diagnostics do not replace a compiler/test run. Diagnostic positions are 1-based with UTF-16 columns, unlike navigation's 0-based input. A workspace_symbol without a path queries the server of the configured language the project has the most source files of, from a count the project's sessions share (lsp_client.language_recount_secs); stopping the turn stops that count. Servers are spawned from the per-language [lsp_client.servers] map; executables must be installed separately. Supported extensions are defined in lsp-client's language table; an unconfigured language returns an error. When kcode stops waiting on a request (the turn stopped, or the request ran out of time) it tells the server with $/cancelRequest, so the server can stop that work. In the GPU chat, results render as a per-operation view rather than raw JSON: a summary header (find_references · 3 references) over a location list, kind-labelled symbol rows (fn tick, struct SessionPresenter), a nested symbol tree for document_symbol/lsp_outline, cleaned hover markdown, or caller/callee rows for the call-hierarchy ops. Each result row with a file location and an available handler is clickable: click it to open that file at its line in your editor (the same editor resolution as /files, via session_panels.files.editor; VS Code-family, Zed, and Sublime jump to the exact line, other editors open the file).
Web
web_fetchtool-webFetch a URL and return its body as text. The request is an HTTP GET; the read stops at 1 MiB, so a larger or endless body is never held whole, and timeout_ms is held to tool_web.max_timeout_secs. An HTML response (detected by its Content-Type, not by sniffing the body) is converted to Markdown by default so the model reads prose instead of tag soup: <script>/<style> noise dropped, tables preserved; pass raw: true to get the original body untouched. Non-HTML content types (JSON, plain text, …) always pass through verbatim, and a conversion failure falls back to the raw body rather than losing content. A body is read in the encoding the response names: a byte-order mark, else the Content-Type charset, else an HTML page's <meta> tag or an XML document's declaration, else UTF-8. Bytes that aren't text show as U+FFFD; a body whose type isn't text and whose bytes aren't UTF-8 is refused, naming its type. The structured result carries content_type and format (markdown|raw), encoding when the body wasn't UTF-8, and replaced: true when some bytes weren't text. It follows a redirect only while it stays on the host, port and scheme it fetched (an http to https upgrade included); a redirect anywhere else comes back as a result naming redirect_url, and fetching that URL passes the permission check like any other fetch, so a url(…) rule judges every host the tool reaches. A fetch runs without a prompt in every mode unless a rule denies it. A redirect on the host is followed only when no rule denies a fetch of the URL it points to; a rule that does ends the fetch with a permission error, before that URL is requested, and the result's final_url names the URL the body came from.
web_searchtool-webSearch the web with the user's Brave, Tavily or Exa key. Results come back ranked, in one shape whichever backend serves them: rank/title/url/snippet, plus published_date and score when the provider reports them. Registered only when tool_web.search_provider is explicitly selected and a key resolves from tool_web.search_api_key or that provider's BRAVE_API_KEY, TAVILY_API_KEY, or EXA_API_KEY: no key means the tool is absent (and a key is never sent to a host you didn't name). Takes query (required), count (narrows, never widens, the tool_web.search_max_results cap), and (Tavily only) topic (general/news/finance), time_range (day/week/month/year) and include_domains (a domain list); an unknown topic/time_range is a validation error, never a silently dropped filter. With Tavily the request sets tool_web.search_depth and, under tool_web.search_include_answer, a short written answer that leads the tool's text as Answer: (structured answer). Each hit's text names its publish date after the URL. Results with no URL are dropped; the model is pointed at web_fetch to read a result's page. Same Network permission posture as web_fetch. LLM-vendor-native server-side search (Anthropic/OpenAI) is the decided follow-on fallback for keyless setups, not built yet.
Vision
view_imagetool-visionShow image files from disk to the model. It reads PNG, JPEG, GIF, WebP, BMP, TIFF and ICO files, for a model that reads images. path takes one file or a list of up to tool_vision.max_images (20). One file returns the image on the tool result plus its dimensions and mime; a list returns each image with its own, names each file it could not show under failed, and leaves out the images past tool_vision.max_total_bytes (12 MiB). sheet: true tiles up to tool_vision.max_sheet_images (100) images into one grid image, each tile labelled with its place in the list and its file name, so many images cost the model one image's tokens; columns sets the grid's columns. The chat's card shows a list's images side by side, each under its file name. On a non-vision model the images are dropped with a short note. An image wider or taller than 2,000 pixels is scaled down to that size before the model sees it, and the result then also names the file's original size. An image whose pixels would take more than 512 MiB once decoded is refused before any memory is set aside for it, and so is a file over 512 MiB, or a path that is not a regular file (a folder, a pipe or a device) before it is read. A PDF is refused, and pointed at read_pdf.
read_pdftool-visionRead a PDF's pages. pages picks them, such as "1-5, 8", counted from 1 and in the order given (each page once); without it every page, from the first. By default each page comes back as its text, in reading order (Arabic and Hebrew too), within tool_vision.max_pdf_text_bytes (256 KiB); a page whose letters give no text, or that has none, as a scanned page has, is named, with show: "images" suggested for it. show: "images" draws each page as an image of 2,000 pixels on its long edge, up to tool_vision.max_images (20) pages within tool_vision.max_total_bytes (12 MiB), shown side by side in the chat, each over a caption naming the page that opens the PDF; sheet: true tiles up to tool_vision.max_sheet_images (100) pages into one grid image labelled page N, and columns sets its columns. Pages past a limit are named under left_out in the form pages takes, with a note saying why, so the next call reads them. password opens a locked PDF. A file over tool_vision.max_pdf_file_bytes (512 MiB), or a path that is not a regular file, is refused before it is read. Pages are read and drawn with hayro, a PDF reader written in Rust; nothing is sent anywhere. fs_read on a PDF points at this tool.
Browser
browser_navigatetool-browserOpen a URL in the session's browser. The browser is a headless Chrome-family browser started per session on first use (on a fresh profile unless browser_host.profile names a saved one, and ended with the session or when kcode quits), shared by the agent's tools and any open /browser tile. A session has one browser, so a subagent is not offered the browser tools and reads pages with web_fetch. Takes url (https://…, file://…, or a data: URL for small test pages). Requires a Chrome-family browser installed (Chrome, Chromium, Edge, Brave, Arc): otherwise the call reports it plainly. Returns once the page's load event has fired (up to 15 s; a page that never fires it is still handed back), and a refused navigation (a DNS failure, a connection refused, a blocked scheme) is an error naming Chrome's reason rather than a silent success. The result gives the model the page's title, address and text, up to browser_host.page_text_bytes, and when the text runs past that, how much was left out and the browser_evaluate call that returns the next part. The chat shows a picture of the loaded page on the call; the model does not get it, and sees the page through browser_screenshot. Stopping the turn ends any browser call at once, and ends a browser that was still starting. A navigation to an http, https or data URL runs without a prompt in every mode unless a rule denies it (a url(…) rule judges it as it judges web_fetch) and one to any other scheme (file:, view-source:) asks.
browser_clicktool-browserClick an element in the session's browser by CSS selector. It is a real DOM click, so links, buttons and framework handlers all fire. A click that starts loading a page waits for the page to load, as browser_navigate does; one that loads nothing returns after a short wait (browser_host.click_load_wait_ms). The result gives the model the page's title, address and text after the click, as browser_navigate does. The chat shows a picture of the page after the click on the call; the model does not get it, and sees the page through browser_screenshot. Fails with a clear error when nothing matches. Part of the browser tools (see browser_navigate). Runs without a prompt in every mode unless a rule denies it.
browser_filltool-browserFill in an input in the session's browser by CSS selector. It sets the value and fires input and change events, so framework listeners (React/Vue) register it. Takes selector and text. Part of the browser tools. Runs without a prompt in every mode unless a rule denies it.
browser_evaluatetool-browserRun JavaScript in the session's browser page and return its value. The value comes back as JSON (promises awaited; 30 s cap). Use for reading page state, extracting data, or custom interactions. In the chat its entry starts folded; opened, it shows the script beside a > and its value below, with JSON indented. A failed call stays open with its error. Part of the browser tools. A script can change the page, so it's judged as a web action like a click: it runs without a prompt in every mode unless a rule denies it.
browser_screenshottool-browserTake a picture of the session's browser page. The picture is a JPEG of the viewport, saved under browser_host.screenshot_dir as <session>-<stamp>.jpg and named by path in the result, and shown to a model that reads images (the path and dimensions only otherwise), with the page URL and title alongside. The chat renders the capture inline labelled by its file, and the model can re-read the file with view_image. Read-only. Part of the browser tools.
Memory
memory_savetool-memorySave a fact that lasts across sessions. kind is one of user (who the user is), feedback (how to work, with the why), project (goals/constraints not in the code), or reference (external pointers); plus a short kebab-case name, a one-line description (used to judge relevance on recall), and the body. Memories are keyed by name, in any script and ignoring case (a name needs at least one letter or digit): re-saving a name updates it in place (never a duplicate), and if the body changed the result reports the memory it replaced. Optionally set confidence (0–1, default 1.0), source (user|model|tool), and scope: user (default; global, travels across every project) or project (stored with this project only). Storage is kcode's SQLite KV, not files. Runs without a prompt in every mode unless a rule denies it.
memory_searchtool-memoryFind the stored memories that match a query. A query returns each match's full body (plus confidence, source, and a written date) ranked by relevance × confidence × recency: a more-relevant, more-trusted, or more-recently-used match ranks higher. Words in any script match; in Chinese, Japanese, Korean or Thai text, where spaces don't mark word edges, a query word of two or more characters matches inside a longer sentence. Recency tracks use: each recall marks the memory used, so one you rely on stays near the top. The written date is when the content was last written: plain information, not a freshness verdict; judge an old memory's claims against current code for yourself. limit caps the hits (default 8). By default it spans both scopes (each hit is tagged [project] when project-scoped); pass scope (user|project|all, default all) to narrow, and the ranking and limit then cover that scope alone. The index of names + descriptions is already injected into the system prompt each session; this pulls the full content of the entries that matter for the task.
memory_listtool-memoryList stored memories (id, kind, name, description, confidence, source, scope), oldest first. Pass kind to filter to one category (user|feedback|project|reference), and/or scope (user|project|all, default all) to filter by store: spanning both scopes by default, tagging each project-scoped row [project]. Used to see what is remembered before saving a duplicate, or to find a name to update/delete.
memory_deletetool-memoryForget a stored memory by its name. Use it once a memory has turned out wrong or is no longer relevant; name is the name you saved it under, and memory_list shows the names. Pass scope (user|project, default user) to name which store to delete from. Runs without a prompt in every mode unless a rule denies it.
Sessions
session_searchtool-sessionsSearch past conversations, with their reasoning and tool results. It covers what compaction kept too. Pass query for literal case-insensitive matches (one hit per session, newest sessions first); pass session_id + around (the returned stable history sequence) + through (the returned watermark) for nearby display rows; pass neither to browse recent sessions and their latest anchor. Search and browse read the current project's sessions; project: "all" reads every project, naming each hit's project, and project: <path> reads that one. Sequence numbers can have gaps and do not change during compaction. Reuse through and the earlier/later anchors for consistent paging. Reads bounded canonical-history pages, not model context or a full-session cache. Model-only summaries and binary image payloads are not searched. Search matches the full stored text; scroll clips long entries with an explicit marker. Limit is capped at 50 sessions and radius at 24 rows. Cancellation stops the read; missing or corrupt history is reported, not treated as no matches. No LLM is involved. Runs without a prompt in every mode unless a rule denies it, and agent kinds held to reads are offered it, the advisor kind that lists it included.
session_managertool-sessionsList, rename, and delete past sessions. LIST (default, or action: "list"): scoped to the current project by default, project: "all" for every project, or project: <path> for one; returns each session's id, title, project, model, and created date, newest first. RENAME: action: "rename" with session_id + title; a running session's tile and the switcher show the new title at once. DELETE: action: "delete" with session_id (permanent); a running session is stopped and its tile closed first, as your own delete does; an id that names no session, or the calling session's own id, is refused. All sessions live in the one user-scope store, so listing spans projects with no cross-DB access. Reading a session's contents is session_search; resuming one onto the grid is the historical sessions: this tool only lists and manages the records. Listing and renaming run without a prompt; a delete, which is permanent, needs permission; a rule that denies the tool refuses all three.
Skills
skill_managetool-skillsWrite and change the agent's own skills. A skill records how to do a kind of task, captured once it was done well. Actions via the action arg: create (a new dir-form SKILL.md from name + description + body; refuses to overwrite, refuses a name another skill has in any case, since one of the two would be hidden, and refuses the name of any command the session has (kcode's own and their aliases, the built-in bundle's, yours and your plugins') since /<name> runs kcode's own commands before any skill and tries a skill before any other command; a create that fails leaves no file behind), edit (replace a skill's description and body; every other frontmatter key stays, and a frontmatter that can't be read is replaced by one holding only name and description, which the result says), patch (find-and-replace old → new, which must match exactly once), delete (remove a skill's folder, or its single file, confined to the skills root: refuses a built-in command's name, a path outside the root, or a symlinked folder or file), and list (the skills under each root as the skill loader reads them, each under the name and with the description /skills shows, and each file there that doesn't load, with why). edit, patch and delete reach a folder skill (<name>/SKILL.md) or a single-file one (<name>.md), and refuse a name both forms hold. The frontmatter is written with any text quoted, so a colon or a line break in a description stays in its key. scope picks where: user (default; <data>/skills, global) or project (this repo's .kcode/skills); any other scope is refused. After each change the session's skills load again from every skill folder, so a skill written here runs at once via run_skill / /<name>; the result says when it doesn't: another skill has its name and loads first (your skills load before the project's), or kcode doesn't read skills from that folder in this session. Guide-only skills only: the script-skill machinery (a bundled entry, capabilities, typed schemas) stays hand-authored. Reserve skills for repeatable procedures; use memory_save for a fact, session_search to recall a conversation.
Tasks
tasktool-tasksRecord and update the agent's task list for the current session. Send the ENTIRE list each call (todos: an array of {content, status, activeForm, body, blockedBy}); it replaces the session's list in one write (a call that fails leaves the earlier list) so completed items must be re-sent or they drop off. A subagent's list is its own: its calls leave the session's list alone and are not shown in /tasks. status is pending, in_progress, or completed, with at most one in_progress at a time; activeForm is the present-tense label shown while an item runs (e.g. "Adding tests"). body is optional markdown detail shown in the /tasks detail view; an item re-sent without body keeps the body it had, and one reworded in place (in a list of the same length and order) keeps the body of the item it replaced, which the result notes. An item that cannot start until others are done lists them in blockedBy, by their number in the same list counted from 1 (e.g. [1, 2]), and the call sends it again each time. blockedBy lists that loop are refused, and the result notes an item in progress or completed while one it waits on is not completed. Backed by the session tasks store (the same store /tasks reads), so the list surfaces to the user in the GPU side panel. An internal bookkeeping tool: it mutates only kcode-managed session state, so the permission engine auto-grants it in every mode; it never raises a permission prompt, even in an untrusted project. In the GPU chat its result renders as a real checklist: a N done · N in progress · N pending summary line over rows with status-coloured glyphs, the in-progress row leading with its activeForm caption, and a row that waits on unfinished items naming them after it.
See /tasks
Meta
meta_ask_user_questiontool-metaPause the turn and ask the user a question. The question can mix options (each with an optional description), a header, multi-select, free-text and number fields, and an 'Other' write-in, and shows in a form in the app. Each field needs its own label, since the answer keys the values by label. A subagent's question names it as its row does (from subagent general (catalog)), and one a plugin's own tool call asks names the plugin (from plugin tail). Returns the chosen option(s), any 'other' text, and any field values; with no answer it says why, the user dismissed the question, or no user is present to answer (a headless run), so the agent never blocks. Runs without a prompt in every mode unless a rule denies it: the question is itself the prompt.
set_timertool-metaSchedule the agent's own future turns, with no user prompt needed. after (one-shot delay), every (recurring interval), and repeat (fire cap) take the same cadence syntax as /loop (10m, 1h30m, bare seconds); omit all three for an after-each-turn on-idle loop. An optional instruction is the prompt run on each fire (omitted = a plain continuation nudge); each fire shows in the chat as a one-line kcode notice that opens to the full text, never as your message. Returns a t<n> id no other timer of the session has (or a caller-supplied id) to cancel later. Autonomous by design: no caps or guardrails beyond the context window, the same daemon-owned scheduler the user's /loop drives. cron gives a wall-clock cadence in local time, six fields, seconds first (second minute hour day month weekday, as in 0 0 9 * * Mon-Fri or 0 0 9 * * 1-5; weekday 1 is Monday, 0 or 7 Sunday), or @hourly, @daily, @weekly, @monthly or @yearly, fires only at the schedule's times and can't be combined with after/every; it keeps to the Mac's clock while the Mac sleeps or moves time zone, and a time passed while the Mac slept fires as scheduler.default_missed_tick_policy says (once, on waking, by default); the reply names the next fire in local time with its UTC offset, and a schedule kcode can't read, or one with no time left, is refused with the reason; durable: true persists the timer in the project store: it re-arms on the next spawn/resume after a stop or daemon restart, and a fire point that fell in the away window surfaces as a missed-fire notification (skip-past), never a surprise turn. The user's /loop stop stops every agent timer too, deleting a saved one. Offered only in the app: kcode -p runs no timers, so it offers neither timer tool. Runs without a prompt in every mode unless a rule denies it.
cancel_timertool-metaCancel a timer the agent previously set with set_timer, by its id. Stops that loop without touching the user's /loop or any other agent timer (each is namespaced separately). Offered only in the app, like set_timer. Runs without a prompt in every mode unless a rule denies it.
set_activitytool-metaShow what the agent is doing now, as a short line. text (required, max 80 chars) is a line like "committing to git" or "searching for API docs". While the turn runs, the line replaces the generic "working"/"Working…" label on the session's Mission Control tile marker and the chat panel's pinned working strip, and lands on the /control timeline as an activity row. While the session waits on the user, its tile keeps "needs input" and shows the line again once work resumes. Routine Activity tool calls do not create chat rows; failed or cancelled calls remain visible with tools shown. The recorded history and export retain every call. Turn-scoped: the display clears when the turn ends, so the agent re-declares as its focus changes. Reports are rate-capped per session (session_daemon.agent_activity_max_per_window per agent_activity_window_secs, default 20 per 60s); over-cap reports are silently dropped (a daemon warn log). Offered only in the app: kcode -p shows no tile, so it offers no set_activity. Runs without a prompt in every mode unless a rule denies it.
run_commandtool-metaRun one of a few session commands, as a user would with a slash command. The agent runs it on its own session. command is one of: compact (free context-window space now, like /compact: no value; publishes a request the agent-loop drains at the next round boundary and runs before the next provider call, so freed space benefits the very next step, and shows on the /control timeline as a <cp:compaction> event like any automatic one); model (switch model mid-session: value is a model id like claude-opus-4-8 or a display label like Claude Opus 4.8, resolved here, and refused with a tool error saying why when kcode doesn't know it or no connected provider serves it, the session keeping its model); effort (set reasoning effort: value is minimal, low, medium, high, xhigh or max); goal (set the session goal: value is the goal text, or omit/empty to clear it); rename (set the session's display title, like /rename: value is the title, or omit/empty to reset to the automatic one); consolidate (distil durable facts from recent sessions into memory now, like /memory consolidate: no value; the daemon spawns a background memory-consolidator subagent, visible on the /control timeline, and always runs regardless of the automatic-runner toggle). model, effort, goal, and rename apply to the live session and persist to the registry exactly like the user's /model, /effort, /goal, /rename, except the agent's goal skips the kickoff turn (the agent is already running) while still arming the self-driving goal driver. model and effort apply from the agent's next turn: the running turn finishes on the model and effort it started with; goal and rename apply at once. Folds in the former standalone compact tool. Autonomous by design: the agent decides when to free headroom, switch model, adjust effort, record a goal, retitle the session, or consolidate memory on a long run. It also fires an agent_invocable prompt-shortcut command (e.g. commit) by name: the command's body returns as the tool result for the agent to follow in-turn (the run_skill injection pattern), its placeholders filled from value as a user's /<name> fills them, $ARGUMENTS with the text, $1, $2, … with its words (a value in quotes is one word, the highest-numbered placeholder also takes the words after its own, and one past the words given is empty), and a body with neither gets the text as a new paragraph after it. A command that does not set agent_invocable: true is refused. The command's allowed-tools and disallowed-tools apply to the turn that runs it, as a skill's do, and the result's tool_lists says what took effect (see /commands). In kcode -p it takes only compact and prompt commands, and its schema and description name only those: the other actions need the app, and a headless run would have acknowledged a change nothing makes. Runs without a prompt in every mode unless a rule denies it.
fork_sessiontool-metaFork the agent's own session into a new one. It is the twin of the user's /fork: the daemon atomically copies the canonical history and active model selection at one committed watermark into a new live session in the same project, visible as a fresh Mission Control tile in any window showing the source session (an unshown source's fork stays switcher-reachable), inheriting the source's model/effort/autocompact params. title (optional) names the fork, else it falls back to the project directory; first_instruction (optional) is delivered to the fork as its first turn, shown in the fork's chat as a one-line kcode notice that opens to the full text, never as your message, so it starts working immediately: omitted, the fork waits for the user. The call waits for the fork, and the fork's copy of the conversation ends in this same call, so each side's result says which session it is: the source's answers this_session: "source" with the fork's id (fork_session_id, which manage_session takes), the fork's this_session: "fork" with the source's id. Its chat shows the call finished, and a notification-center entry announces the fork. Only the session's own agent forks; a subagent's call is refused. Distinct from subagents (a fork is a full user-visible session sharing the chat history, not a scoped delegate with fresh context). Agent forks are rate-capped per session family: the first session and every fork and worker made from it (session_daemon.agent_fork_max_per_window per agent_fork_window_secs, default 3 per 600s); an over-cap fork is refused with an error naming the cap. Offered only in the app: kcode -p forks no session. The fork starts in this session's permission mode. Runs without a prompt in every mode unless a rule denies it.
run_skilltool-metaRun one of the agent's skills, as a user would by typing /<skill>. It is the twin of run_command, and the skill goes through the same preparation. The four prompt routines (commit, init, review, security-review) are commands fired via run_command, so run_skill serves only skills: agent-capability bundles. A skill is an authored bundle: a SKILL.md guide plus optional code/templates, declared tool dependencies (tool-dependencies), a capability declaration ([capabilities], the plugin manifest shape), optional typed input_schema/output_schema, and a parallelizable flag. On invoke, the skill-runner prepares the environment: it refuses a skill whose input or output schema does not compile, naming the schema, before anything runs, then takes the (base, skill) concurrency lock (a non-parallelizable skill already running in any checkout of the repository fails fast), creates the state home at <base>/.kcode/skill-state/<skill>/, and validates inputs against the declared input schema, then returns the prepared guide (with ${KCODE_SKILL_STATE}, the state home, ${KCODE_SKILL_DIR}, a folder skill's folder, and ${KCODE_SESSION_ID} filled in) for the agent loop to drive step by step in-context (not a sub-agent). The agent's arguments text fills the guide's $ARGUMENTS and $1, $2, … by the rules a user's typed text follows. A skill with typed inputs (an input_schema, or a script) takes inputs and refuses arguments; any other skill takes arguments and refuses non-empty inputs. The base is the repository's main checkout, so a worktree session, a subagent in its own checkout and the main checkout share one state home and one lock, and removing a checkout loses no state; a bare repository's checkouts share <git folder>/kcode/base. The state home, tool deps, and output schema ride the tool result; a declared output schema is validated before the result returns. A failed check of either schema names every field at fault, up to twenty. A skill's allowed-tools and disallowed-tools take Claude Code's meaning in kcode's names: each entry is a kcode tool name (fs_read) or a permission rule (bash(git *), path(src/**), url(*.example.com), tool(fs_write), joined with && ), separated by commas or spaces. For the turn that runs the skill: a script skill's code and the agent's own calls after it alike, as the agent follows the skill's instructions with the result (allowed-tools approves the calls its entries cover as an allow rule you wrote would) a deny rule still wins, a call that reads or writes a secret location (permissions.secret_paths) still needs permission, and no approval applies in Plan mode. The first run of a skill whose list is new or lists more shows a prompt: Allow this time, Always for this list (remembered until the skill lists more) or Run without them, which runs the skill with its tools needing permission as usual. A project skill you trusted as it stands counts as accepted, and a run that can't show a prompt (kcode -p) goes without. disallowed-tools refuses the calls its entries claim for that turn in every mode, and a tool an entry names whole is not offered to the model. Subagents the turn starts are under the same lists while it runs. An entry kcode can't read, such as Claude Code's Read or Bash(git:*), approves or removes nothing: the run names it with kcode's form, and /doctor names the skill's file and list (the skill.tool-list finding, which never quotes an entry). The result's tool_lists and its transcript line say what took effect: the approvals in force or why not, the refusals, the entries not read. The result names the skill's model, which this run can't switch to mid-turn; the turn a user's /<name> or a hook starts runs on it. The descriptor lists the available skills, each with what it takes: the whole JSON Schema its inputs are checked against, so a first call can pass them, or the argument-hint its author wrote, and constrains skill to them; an unknown name is a tool error naming the valid ones. A guide skill runs without a prompt, since it only hands the agent instructions; a script skill needs permission before it runs, in every mode but Auto, because its code can write files. A skill the session doesn't hold, or one only the user may run, is refused before anyone is asked.
Essentials Bundle
notifyessentials-bundlePost a message to the user's notification center: a title and an optional body. The entry lands in the durable cross-project center (kind agent, glyph ◆, info blue) attributed to its plugin ("<title> — <body> (via kcode-notify)"), lights the right-edge seam like a completion (never outranking a blocked or errored session), and (because a reach-out exists to find the away user) escalates to a macOS banner when the kcode window is unfocused. Use it for milestones worth interrupting for (a long build finished, a decision is waiting), not progress chatter: agent notifies are rate-capped per session (session_daemon.agent_notify_max_per_window per agent_notify_window_secs, default 5 per 60s) and an over-cap post is not made (a daemon warn log, never a notification about notifications). The tool answers posted: true once the message is in the center, or posted: false with a reason when it was not (over the cap, say) so the agent never reports a message the user did not get. Not a native tool: it ships as the built-in kcode-notify Lua plugin bundle (the dogfooding proof that a real tool can be a plugin) whose handler calls the kcode.notify host API under the notify permission, blocklist kcode-notify in a project's plugin policy to remove it. The bundle declares the tool read-only, so a post runs without a prompt in every mode unless a rule denies it. kcode -p keeps no notification center, so it loads no kcode-notify and offers no notify; there a plugin's or script skill's own kcode.notify call fails with a 'not wired' error.
See /notifications fork_session
Subagent
spawn_subagenttool-subagentDelegate a focused task to a subagent. Runs one turn against the named AgentKind with its declared tool subset + permission mode, returning its final text. If the user stops the session's turn while the call waits, the call returns at once with the child's subagent_id and still_running: true, and the child runs on: its finish wakes the session with a <cp:subagent> notice. The turn ends after that round's tools, and the chat's card reads 'stopped waiting · reports when it finishes'. A subagent's own child stops with that subagent's turn. The child starts from the prompt it is given and nothing else: it does not see the parent's conversation, and nothing it does is written into the parent's transcript or --resume history. Its cost, tool sessions, and control-plane events still belong to the parent session. The child runs on the model argument, else its kind's model, else one from the /subagent pool, else the session's. A model from the first three must be one a connected provider serves: a name kcode doesn't know, a provider with no key or sign-in, or a model a ChatGPT sign-in's Codex backend can't serve (the error names the ones it can, e.g. gpt-5.5, gpt-5.4, gpt-5.4-mini, gpt-5.3-codex-spark) fails the spawn with a tool error saying why and where the model came from, before the child starts. A plugin's refusal at core.subagent.pre also fails the spawn before the child starts, with an error naming the plugin and its reason. A child that runs and fails returns 'the <kind> subagent couldn't finish: <reason>'. In the GPU chat, spawn/await calls render as a subagent card: kind header, a two-line prompt preview, a spawned / N rounds / stopped waiting · reports when it finishes meta line, and a foldable result preview, the prompt and result formatted from their Markdown as a reply is, a code block with its copy button, not raw JSON; a click on the card's name shows the subagent in the session's subagent tile (see /agents). An optional name gives the child a session-mailbox identity (addressable via send_message), and isolation: "worktree" runs it in a fresh checkout on a kcode-agent/<id> branch, kept and reported (path + branch) when it leaves changes behind, even when it fails or is stopped, whose error then names them: auto-removed otherwise. Its commands build in a Cargo build folder of its own, .kcode/target/subagent-<id> in the base project, deleted when the child finishes, kept checkout or not. While the child runs, no kcode removes its checkout or offers it to /worktree adopt; if its process ends mid-run, the next launch removes a work-free checkout and keeps one with work. output_schema: a JSON Schema the child's final answer must satisfy, the child turn gains a synthetic submit_result tool and only concludes on a validating payload (5 invalid attempts fail the turn), returned as structured_output in place of the child's final text, which the card still shows. The schema must be valid JSON Schema and describe an object (the answer is that tool call's arguments) and a spawn with any other schema is refused before the child starts, with the reason; null means no schema. Plan mode refuses it, even when a tool(spawn_subagent) rule allows it. In every other mode it runs without a prompt unless a rule denies it, and each call the subagent makes is judged on its own.
spawn_subagent_asynctool-subagentStart a subagent and carry on while it works. Returns the child's subagent_id, which await_subagent takes. Use it to run subagents side by side, or, as the session's own agent in the app, to start long work, tell the user, and end the turn, so the user can talk to the agent meanwhile: when the child finishes, a <cp:subagent> notice that names its task and carries its result wakes the session, unless an await_subagent is waiting for it. A spawn a plugin refuses at core.subagent.pre fails at once, with an error naming the plugin and its reason, and leaves nothing to await. A subagent's own child reaches it only through await_subagent, and in kcode -p the agent awaits every child, since nothing reads a notice once the run ends; the tool's description tells the agent which applies. A turn that would end with a child whose result only an await reads names it once, with its subagent_id, so the agent can await it before the result is lost. Accepts the same name (mailbox identity) and isolation: "worktree" (own checkout on a kcode-agent/<id> branch, kept on changes) parameters as spawn_subagent. output_schema: a JSON Schema the child's final answer must satisfy, the child turn gains a synthetic submit_result tool and only concludes on a validating payload (5 invalid attempts fail the turn), returned as structured_output in place of the child's final text, which the card still shows. The schema must be valid JSON Schema and describe an object (the answer is that tool call's arguments) and a spawn with any other schema is refused before the child starts, with the reason; null means no schema. Plan mode refuses it, even when a tool(spawn_subagent_async) rule allows it. In every other mode it runs without a prompt unless a rule denies it, and each call the subagent makes is judged on its own. When several subagents wait on a permission prompt or a question at once, the chat shows the newest, and the next once you answer it.
spawn_worktree_sessiontool-subagentStart a long-lived worker session in its own git worktree of the parent's base repo. Unlike spawn_subagent (one turn, disposable, result returned in-turn), the worker is a real session: its own tile and transcript, a fresh checkout on branch kcode/<slug> seeded from .worktreeinclude, its own isolation env ($PORT, KCODE_WORKTREE_*), and it keeps running after the call returns. task is delivered as the worker's first turn (a complete, self-contained brief: the worker cannot ask the parent questions), shown in the worker's chat as a one-line kcode notice that opens to the full text, never as your message; optional goal arms the goal driver so the worker self-drives until it declares done/blocked; optional base_ref starts the worker's branch at a specific commit (a full or unambiguous-short hash, branch, or tag, resolved on the base repo) instead of the base's HEAD: to reproduce a bug at a known commit, continue stale work, or bisect. Returns { session_id, slug, branch, path }. Parent and worker coordinate over cross-session mail: the parent steers with send_message to the worker's slug, the worker reports with to: "parent", and mail wakes an idle recipient; results land as commits on the branch, and completion/needs-input also reach the user through the notification triggers. A worktree parent spawns siblings under its own base repo (never a worktree of a worktree), sharing one slot pool. Rate-capped per session family: the first session and every fork and worker made from it (session_daemon.agent_worktree_max_per_window/agent_worktree_window_secs, defaults 3 per 600s); an over-cap or failed spawn returns as a readable tool error (request/response, as fork_session is). Offered only in the app: kcode -p has no daemon to run a second session, so it offers no spawn_worktree_session. Plan mode refuses it, even when a tool(spawn_worktree_session) rule allows it. In every other mode it runs without a prompt unless a rule denies it. The worker starts on the parent's model, effort and other session settings, in the parent's permission mode or permissions.default_mode, whichever lets less run without a prompt, and each call it makes is judged in its own session.
await_subagenttool-subagentWait for a previously-spawned async subagent to finish and read its result. Takes the subagent_id the spawn returned; each subagent may be awaited exactly once. While the wait lasts, the subagent's finish doesn't also wake the session. Stopping the turn ends the wait at once. A subagent the session's own agent started keeps running, the await returning its subagent_id with still_running: true, and a later await_subagent on the same subagent_id still waits for it, if none does, its finish wakes the session again with its result; a subagent's own children stop with its turn. An await of a subagent whose finished notice already gave the agent its result says so instead of repeating it, and its card in the chat still shows the result; an await of one whose notice gave its error fails with a line pointing to that notice, and of any other that failed with 'the <kind> subagent couldn't finish: <reason>'. Runs without a prompt in every mode unless a rule denies it.
advisortool-subagentGet a second opinion from a model other than the session's. A fixed read-only sub-agent (the built-in advisor kind: reads code/files, never writes) that takes question plus a self-contained context (it cannot see the conversation) and returns an independent read; stopping the turn that asked stops it. It always runs on the model pinned in subagent.advisor_model, which must differ from the session's current model (override else the default): a same-model call is refused, and a pin no connected provider serves is refused, saying why. A plugin's refusal at core.subagent.pre is the call's error as the plugin gave it, and an advisor whose run fails returns 'the advisor couldn't finish: <reason>'. Offered only once subagent.advisor_model is set (kcode never picks the model itself) and subagent.advisor_enabled (default on) removes it even then. Its transcript row is inline (a normal settled row, not floating over the composer) and, when it finishes, shows a one-line summary of the advice it returned. Runs without a prompt in every mode unless a rule denies it, Plan mode included, since the agent it starts is held to reads; each call that agent makes is still judged on its own.
Ask Model
ask_modeltool-ask-modelAsk another model one question and get its answer back as text. The answer comes with the call's tokens in and out and what it cost. model names any model a connected provider serves: its id, <provider>:<model> or its catalog name, as /model takes it; inherit is refused, since the call has no model of its own. prompt is the whole question: the asked model sees only it and images, no tools, files or conversation. images takes an image file or a list of them, relative to the project root or absolute, read and shrunk as an @file: image is; they go only to a model that reads images, and a model its provider says reads none is refused. One call sends at most tool_ask_model.max_images (20) images, tool_ask_model.max_total_bytes (12 MiB) together. effort sets how hard a model that takes it reasons. The question runs on the session's own providers and keys and is charged to the session, so /cost and /stats count it; stopping the turn stops it. Its transcript card names the model, the tokens and the cost over the answer. Runs without a prompt in every mode, as fs_read does, unless an image path names a place outside the project that fs_read would ask about or a rule denies it.
Mailbox
send_messagetool-mailboxSend a short message to another agent via the session mailbox. Address a named subagent (spawned with name), main (the primary agent), or * to broadcast, or another session: a live worktree worker by its slug, and, from inside a worker started by spawn_worktree_session, parent for the session that spawned it. Cross-session mail is daemon-routed into the target session's own mailbox and wakes the target when it is idle; it reaches live sessions only and is rate-capped (session_daemon.agent_mail_*). A name registered in this session wins over a matching slug. Used for mid-turn coordination between sibling subagents, subagent-to-main reporting, and parent↔worker steering. In kcode -p it reaches only the session's own agents: there are no other sessions, and a name the session doesn't know fails.
check_inboxtool-mailboxRead (and clear) the calling agent's session mailbox. Returns the messages sent to this agent by other named agents since the last check, including cross-session mail: a worker's message arrives from its slug, a spawning session's from parent. In kcode -p only the session's own agents write to it.
manage_sessiontool-mailboxAct on another session: a fork, a worktree worker, or any sibling in the project. action: "status" reads the target's live state from the registry (working / idle / needs-input, context fullness, last activity); action: "steer" sends text to the target as a <cp:steer> notice naming the sender, which it reads at its next round or wakes to when idle, to redirect a running worker; action: "interrupt" cancels its in-flight turn and ends any permission prompt or question it waits on, closing its prompt in every window. target is a session id, a worktree worker's slug, or a family relative read off the session's persisted origin: parent (the session that spawned this one), child (this session's most-recent child), or sibling (another live child of this session's parent). Unlike send_message, the daemon answers a manage request directly: a definite outcome, not a message the target's model reads later. It reaches only sessions in this project: a session id from another project is refused. A steer or an interrupt is rate-capped like the other cross-session tools (session_daemon.agent_mail_*); a status read is not. Offered only in the app: kcode -p has no other session to act on.