# Tools


kli ships the tools the agent calls during a turn. Two run code: `bash` runs a shell command, `eval` runs Common Lisp in the live image. The rest are the file surface: `read`, `find`, and `search` look at files; `write` and `edit` change them.

Every tool carries a capability gate. A gate is a capability name the tool requires before it runs. By default kli grants every capability, so every tool runs. The `capabilities` array in `settings.json` overrides that: an empty array denies all gated tools, and an array of capability names grants exactly those (see [Capabilities](/kli/config/capabilities)). Each tool below lists its gate. A call whose gate is not granted returns an error and runs nothing.

## bash

Run a shell command in a child process. The command runs through `sh -c`, with stdout and stderr captured separately.

Capability gate: `process/exec`.

| Parameter | Type | Required | Effect |
| --- | --- | --- | --- |
| `command` | string | yes | The shell command to run. |
| `directory` | string | no | Working directory for the command. Defaults to the process working directory. |
| `input` | string | no | Text fed to the command's stdin. Defaults to empty. |
| `shell` | string | no | Shell binary invoked with `-c`. Defaults to `sh`. |
| `timeout` | integer | no | Wall-clock limit in seconds. Defaults to 30, clamped to a maximum of 300. |

Output limits and behavior:

- A command that runs past its timeout is killed (its whole process group when possible) and the call returns an error naming the timeout.
- stdout and stderr are each capped at 1 MiB (1048576 characters). Output past the cap is dropped and the result notes the truncation.
- The exit code rides in the result details. A non-zero exit returns an error result.
- Interactive programs are rejected before the command runs. kli inspects the first effective command word (skipping `env`, `command`, `exec`, `time`, `sudo`, `doas`, leading assignments, and their options) and refuses these names: `vi`, `vim`, `nvim`, `nano`, `emacs`, `less`, `more`, `man`, `top`, `htop`, `watch`, `ssh`, `mosh`, `tmux`, `screen`. The rejection returns an error and runs nothing.

## eval

Read and evaluate Common Lisp forms in the running kli image. The forms run on a dedicated thread under the requested package. The value of each form, and anything the forms print, comes back in the result.

Capability gate: `image/eval`.

| Parameter | Type | Required | Effect |
| --- | --- | --- | --- |
| `form` | string | yes | Common Lisp source. All forms in the string are read and evaluated in order. |
| `package` | string | no | Package the forms read and run in. Defaults to `CL-USER`. An unknown package name is an error. |

Output limits and behavior:

- Evaluation has the same time budget as `bash`: 30 seconds by default, 300 maximum. A form running past the deadline is interrupted, and the result notes that the interrupted form may have left image state partially modified.
- Captured output is capped at 1 MiB (1048576 characters), counted and dropped at the stream so a printing loop cannot exhaust the heap.
- Printed values are bounded: `*print-length*` is 100, `*print-level*` is 20, and `*print-circle*` is on, so a large or circular value prints to a finite string.

## read

Read a file and return its lines with anchors. Each line comes back as `LINE:HH|content`, where `LINE` is the 1-based line number and `HH` is a two-hex-digit hash of the line's content. These anchors are what `edit` references.

Capability gate: `file/read`.

| Parameter | Type | Required | Effect |
| --- | --- | --- | --- |
| `path` | string | yes | File to read. |
| `start` | integer | no | First line of an inclusive 1-based range. A start past end-of-file is an error. |
| `end` | integer | no | Last line of the range. An end past end-of-file clamps to the last line. |
| `raw` | boolean | no | When true, return line content with no `LINE:HH|` prefix. Defaults to false. |

A read over a file larger than 2 MiB is an error, and the error names `search` as the way to inspect a file that large. An empty file reads as `(empty file)`. Reading a file records its current line hashes for the session, which is the read-before-edit state `edit` requires.

## find

List file paths matching a glob pattern. Returns paths only, no file content.

Capability gate: `file/read`.

| Parameter | Type | Required | Effect |
| --- | --- | --- | --- |
| `pattern` | string | yes | Glob pattern, for example `src/**/*.lisp`. `*` spans a run of characters within one path segment; a bare `**` segment spans any depth, including zero. |

Symlinks to files match; symlinked directories are not descended. At most 1000 paths are reported, sorted, with any overflow counted in the output. The walk stops and returns a partial result if it visits 100000 entries or runs longer than 10 seconds; the stop is surfaced in the text.

## search

Search file contents with a regular expression across one file or a glob. Match lines come back as `*LINE:HH|content`, surrounding context lines as ` LINE:HH|content` (space-prefixed). Each matching file is read whole, so its anchors are recorded and ready for `edit` with no separate `read`.

Capability gate: `file/read`.

| Parameter | Type | Required | Effect |
| --- | --- | --- | --- |
| `pattern` | string | yes | Regular expression matched against each line. |
| `path` | string | yes | A single file or a glob, for example `src/**/*.lisp`. |
| `context` | integer | no | Number of surrounding lines to show around each match. Defaults to 0. |

Files that fail to read as text are skipped. Files over 2 MiB are skipped, with the count surfaced in the result. The result is capped at 100 matching files and 1000 rendered match lines; the same 100000-entry and 10-second walk bounds as `find` apply.

## write

Write content to a file, replacing it whole. Missing parent directories are created. The file's prior content rides in the result details so the change can render as a diff.

Capability gate: `file/write`.

| Parameter | Type | Required | Effect |
| --- | --- | --- | --- |
| `path` | string | yes | File to write. |
| `content` | string | yes | Full new content of the file. |

## edit

Apply a hashline patch to one or more files, or accept a pending Common Lisp repair preview. A patch is whole-or-nothing: every anchor is validated against current disk content before any file is written, and a single stale or unread anchor rejects the entire patch. No file is partially modified.

Capability gate: `file/edit`.

| Parameter | Type | Required | Effect |
| --- | --- | --- | --- |
| `input` | string | mode-specific | A hashline patch (grammar below). Required unless accepting a repair preview. |
| `repair` | string | no | Common Lisp repair policy for unbalanced patch output: `safe` (default), `preview`, or `reject`. |
| `accept_repair` | string | mode-specific | Candidate id returned by a repair preview. Required only when accepting a preview. |
| `path` | string | with `accept_repair` | Target path for the candidate; used for authority gating and stale-content checks. |

A patch is one or more sections, each opened by a `@@ PATH` header and followed by ops:

| Line | Effect |
| --- | --- |
| `@@ PATH` | Section header. One or more sections per patch. |
| `+ LINE:HH` | Insert the following payload after the anchored line. |
| `+` | Insert payload at end of file (bare `+`). |
| `< LINE:HH` | Insert the following payload before the anchored line. |
| `<` | Insert payload at beginning of file (bare `<`). |
| `- A:HH..B:HH` | Delete the inclusive line range. |
| `= A:HH..B:HH` | Replace the range with the payload; no payload deletes the range. |
| `~content` | A payload line. Everything after `~` is verbatim. |

Anchor validation:

- The target file must have been read this session (by `read` or by a `search` that matched it). An unread file rejects the patch with a prompt to read it first.
- Each `LINE:HH` anchor is re-hashed against current disk content at edit time. A hash that no longer matches is stale and rejects the whole patch instead of overwriting changed content; the error names the file and line to re-read.
- Overlapping range ops, and an insert that falls inside a range op, are rejected, and the error names both spans.

On success the result reports each file as `Edited PATH (+added -removed)` and prints fresh `LINE:HH|content` anchors for the changed regions. Those anchors are valid for a follow-up edit with no intervening read. Edited files end with a trailing newline.

For Common Lisp source, `edit` checks the patched file for balanced delimiters before writing. Balanced output writes normally. Unbalanced output is repaired in memory according to `repair`: `reject` errors without writing, `preview` returns a candidate without writing, and `safe` writes only repairs classified as local to the edited range with a stable top-level form count. Unsafe repairs return a preview and must be accepted with `accept_repair` plus `path`; acceptance rechecks that the file has not changed since the preview.