Tools

The catalog of tools kin can call — what each one does, its risk kind, and whether it runs without asking.

Adding a tool? See Extending kin — tools, kinds, and profiles for the step-by-step walkthrough (subclass Tool, set kind, implement async run(args, ctx), route untrusted output through frame_untrusted, register in default_registry(), add tests/test_harness/ coverage).

How tools map to permissions

Every tool declares a risk kind — read, edit, shell, meta, mcp, network, publish, or outpost — and the active mode maps that kind to a decision. A structured multi-operation tool may resolve its kind from the specific operation. So whether a tool auto-runs, asks, or is refused depends on the mode and concrete call, not just the tool name. Read and meta tools never prompt; edits auto-apply in auto and ask in strict; shell runs sandboxed in auto, while in strict it auto-allows only commands proven read-only and asks otherwise. Bounded publication auto-runs in auto and asks in strict. (The workflow tool sets its kind to ask directly, so it always asks — you approve the model-authored script before it runs.) See Modes & permissions for the full matrix.

The “auto-approves?” column below describes strict mode (the ask-first posture); in auto — the launch default — edits auto-apply and shell runs sandboxed.

Filesystem

Dedicated read tools so the model can navigate without going through gated shell. Edits are atomic and return a unified diff.

Tool	What it does	Kind	Auto-approves?
read_file	Read a text file, PDF, Word (.docx) or Excel (.xlsx) document, or image (PNG/JPEG/GIF/WebP returned as image blocks; SVG as text), with line numbers. Macros in .docm/.xlsm are ignored, not analyzed. Defaults to the first 2,000 lines; page with offset/limit.	read	Yes
inspect_media	Ask the operator-assigned vision route a self-contained question about image paths or deterministic media:<tool-call-id>:<index> refs. The route receives only the question and images; the returned observation is provenance-labelled and untrusted-framed.	read	Yes
write_file	Create missing parent directories, then create or overwrite a file atomically (temp file + rename). Returns a unified diff.	edit	Asks
edit_file	Replace an exact old_string with new_string (must match exactly and be unique unless replace_all). Returns a unified diff.	edit	Asks
ls	List a directory’s entries (directories first, with sizes). Workspace-confined.	read	Yes
glob	Find files by glob pattern (**/*.py), newest first. Workspace-confined.	read	Yes
grep	Search file contents for a known string, symbol, or regular expression; returns path:line: text. Workspace-confined, deterministic, binary/secret-safe, and bounded.	read	Yes

grep keeps pattern as its only required argument. path narrows to a file or directory and glob filters filenames. fixed_strings = true treats regex metacharacters literally; case_sensitive defaults to true; limit defaults to 50 and clamps to 1–200. Patterns over 4,096 characters are refused. Every regex match receives the remaining share of one eight-second operation budget, so catastrophic backtracking returns a narrowing hint instead of running unbounded. Explicit credential-store targets are refused without revealing whether they exist; recursive searches silently omit secrets and NUL-detected binary files. Exact grep intentionally may inspect ordinary .gitignored workspace content—the ranked search below is the noise-filtered route.

write_file treats a nested destination as one operation: after the normal permission checks and any applicable workspace-containment check pass, it creates missing parent directories and then writes the file. A denied write creates neither the parents nor the file. Protected targets such as .kin/settings.toml keep their normal approval behavior, including when a nested path would create a protected target as a directory; other project .kin/ files are ordinary workspace files.

Diagnostics after edit

write_file and edit_file append a lint pass’s output when it fails — v1 covers .py via ruff check (an opt-in ty typecheck pass layers on top, default off — see diagnostics_ty). A clean pass appends nothing; a failing one appends diagnostics (ruff): N issue(s) plus up to 20 lines / 2000 chars of output, so the model can often self-correct in the same turn without a separate shell call. shutil.which-gated (a project without ruff installed degrades to a silent no-op) and bounded by a 10s timeout — diagnostics can never fail or delay-block a write. This is a subprocess pass, not an embedded LSP (see DR 0066 for why). On by default; KIN_DIAGNOSTICS=0 / diagnostics_after_edit = false disables it.

Notebooks

Jupyter .ipynb tools using nbformat. Edits address cells by a stable cell_id from read_notebook.

Tool	What it does	Kind	Auto-approves?
read_notebook	Read a notebook as structured cells (source, cell_id, execution_count, outputs). Matplotlib image/png outputs return as image blocks.	read	Yes
edit_notebook	Edit a cell in place by cell_id, or append a new cell. Preserves nbformat metadata and untouched execution counts.	edit	Asks

The notebook and document readers’ format packages are part of a normal Kin install. If one is reported missing, repair Kin with kin update (or re-run the installer if Kin is already current); do not add Kin’s dependency to the project you happen to be working in. When running uv run kin from a source checkout, use uv sync inside that checkout. An editable tool install instead uses uv tool install --reinstall --editable <checkout>.

Shell

One gated shell tool, plus a background trio for long-running processes.

Tool	What it does	Kind	Auto-approves?
shell	Run a bash command, foreground or (with run_in_background) detached.	shell	Only if provably read-only
shell_list	List live background shells and their last output line.	meta	Yes
shell_output	Read a background shell’s output by shell_id; wait=true blocks until it exits.	meta	Yes
shell_kill	Kill a background shell by id.	meta	Yes

A foreground shell auto-runs only when the command classifier proves it read-only; otherwise it asks. In auto, it instead runs inside the OS sandbox. The call may proactively include typed sandbox_permissions for an external writable directory, network, or the SSH agent. If a foreground or background command hits a recognized sandbox denial, its result exposes an opaque denial id for request_sandbox_access; Kin retains and retries the exact original arguments. See Scoped sandbox access.

Code interpreter (Python)

A stateful Python REPL for iterative computation and data work — one persistent interpreter per session, so variables, imports, and files survive across calls (the difference from running python -c through shell, which forgets everything between calls). The value of a trailing expression is echoed like a REPL.

Tool	What it does	Kind	Auto-approves?
run_code	Run Python in the session’s persistent kernel. Exceptions come back as a readable traceback and the kernel (with its state) survives; a timeout (default 30 s, max 600 s) kills the kernel — state lost, next call starts fresh.	shell	Never in strict (arbitrary code is never provably safe); sandboxed in auto
run_code_reset	Kill the kernel; the next run_code call starts a fresh interpreter. The escape hatch for memory growth or a polluted environment.	meta	Yes

run_code shares the shell kind on purpose: in auto mode the kernel is spawned inside the same OS sandbox shell commands run under (writes confined to the workspace, networking follows sandbox_network, secrets scrubbed — see Auto mode & the OS sandbox); in strict mode it always asks; it is refused while planning. It accepts the same proactive sandbox_permissions profile as shell. A reactive expanded retry uses a fresh kernel and reports that state loss rather than silently carrying authority into the persistent interpreter. Under KIN_SANDBOX=container (Outpost) it runs unwrapped in-container like shell does. It is not the workflow tool — that runs an in-process orchestration script that fans out subagents; run_code is the OS-sandboxed subprocess for the code itself.

If code raises ModuleNotFoundError, the result explains that this persistent kernel uses Kin’s sys.executable, which may not share packages with a bare pip or pip3 command. Kin does not install into its own environment automatically. Keep installation and consumption on one explicit shell interpreter—python -m pip install …, then that same python …, following pip’s interpreter guidance—or install to a workspace/temp target and explicitly add that target to sys.path in run_code.

Both tools are stdlib-only and registered by default; set KIN_RUN_CODE=0 (or run_code_enabled = false) to remove them.

Planning & interaction

Harness-internal tools that plan, ask you, or hand off a finished plan. See Planning for the lifecycle.

Tool	What it does	Kind	Auto-approves?
todos	Update the turn’s task list (a full rewrite each call); drives the pinned task panel.	meta	Yes
ask	Ask you a question and wait — single-select, multi-select, or free text. Labeled choices may include a one-sentence description; both the modal and transcript render them as literal human text (brackets are not markup), including when a resumed or less-constrained model emits the legacy string shape.	meta	Yes
request_sandbox_access	Ask for a capability subset and lifetime after shell or run_code returned an opaque sandbox denial id. The harness retries the retained exact operation; the model does not resubmit command/code. Present only when Kin owns a usable local sandbox.	meta	Yes (it is the approval flow)
write_plan	Write or revise the plan file under .kin/plans/. A fresh plan or broad rewrite uses full content; a focused critic finding can use plan-scoped old_string → new_string replacement (defaulting to the tracked plan) without enabling general write_file during the freeze. Usually called by the planner subagent — task(subagent_type='planner', ...) — for non-trivial changes; the top-level model can also call it inline for a small fully-converged one-file change (see Planning). The first call in a planning sequence auto-enters the read-only planning freeze on the top-level session; only a human leaves it (via present_plan’s modal or a bare /plan).	meta	Yes (capability reduction)
present_plan	Present the tracked plan file (read fresh off disk) for approval — only your choice at the modal (or a bare /plan) lifts the planning freeze. The modal offers three choices — approve & execute (keep context), approve, clear & re-inject (reseed just the plan + an execution preamble), or review first (the model dispatches an adversarial critic subagent itself, applies fixes with write_plan, and re-presents — staying frozen).	meta	Yes (it is the approval flow)

Settings

Tools that let kin help tune your settings mid-conversation — the same diff-approval gate as the artifact editor, but reachable by the model. The model can only ever write sampling/model knobs; containment knobs (mode / sandbox* / shell_allowlist), secrets/endpoints (api_key / base_url / brave_api_key), and operator routing policy (model_routes / model_assignments) are refused. See Modes & permissions § Model-writable settings and turn the guidance on with /settings.

Tool	What it does	Kind	Auto-approves?
read_settings	Read the live settings — sampling/model values plus which knobs are changeable. Credentials are masked to [SET]/[NOT SET]; each knob is tagged model-writable / human-only. Includes a short settings guide.	read	Yes
propose_settings	Propose a partial patch of sampling/model settings (temperature, top_p, top_k, max_tokens, context_window, enable_thinking, effort, cache_ttl, model). You review a diff and approve before anything is written; the change applies to new sessions. Any containment/secret/endpoint key is refused with a banner naming it. The effort knob is the per-serve picker vocabulary (Anthropic 5-value, OpenAI 3-value, Z.ai 7-value, Qwen 3-value, Poolside 2-value) that the /effort command dispatches live — reasoning_effort is intentionally human-only so the picker stays the single cross-wire source of truth. Top-level only (a subagent can’t propose); frozen during planning.	meta	Asks (you approve the diff)

Delegation

Tools that spin up isolated work or load reusable prompts.

Tool	What it does	Kind	Auto-approves?
task	Delegate a focused job to a subagent with its own isolated context. Supports an operator-authorized route or legacy model override (mutually exclusive). Set run_in_background=true to detach; lifecycle events automatically return MCA attention.	meta	Yes (spawn only)
fork_agent	Delegate with the full represented conversation through the current user request. Keeps the parent identity/model/route and child-safe live tools; supports foreground/background supervision.	meta	Yes (spawn only)
agent_list	List every agent (foreground + background) with lifecycle, outcome, health, mailbox, tool, and usage metadata—never child prose.	meta	Yes
agent_output	Read an agent’s buffered output by agent_id; wait=true blocks until it finishes.	meta	Yes
agent_kill	Kill an agent by id — works on a running foreground child too (cancels the child, not the parent). Idempotent on a finished agent.	meta	Yes
agent_message	Queue steering for a running/pausing/paused child, or continue an idle retained child. A paused child stays paused until agent_control(resume).	meta	Yes
agent_inspect	Inspect one agent’s structured lifecycle, lineage, activity, tools, usage, output size, session id, and error availability. Exact diagnostics are untrusted-framed.	meta	Yes
agent_wait	Wait on 1–16 agents for any/all settlement or any change; returns snapshots and claims the reported events.	meta	Yes
agent_control	Pause/resume, interrupt while retaining the session, restart as a linked fresh attempt, or close an idle agent.	meta	Yes
tasks	Maintain a session-long DAG of work items (add / update / complete / remove / list / blocked). Cycle-checked; auto-unblocks downstream on complete.	meta	Yes
skill	List available skills, or load a named skill’s instructions into the conversation.	meta	Yes
workflow	Run a model-authored async def main() that fans out subagents over deterministic control flow; only its returned string re-enters context. Each agent() may use an authorized route or legacy model override. Read/analysis fan-out, or parallel edits via isolation: "worktree"; supports structured schema output and within-run resume (resume_from_run_id). Capped at 6 concurrent / 64 total agents per run (the caps are also stated to the model in the tool description).	ask	Asks (you approve the script)

See Subagents, Workflows (fan-out orchestration), Agents (foreground + background subagents + --agent) and Tasks for detail.

Workspace search

One default-on search_workspace tool — ranked, chunk-aware lexical full-text search over workspace content, complementing exact-match grep. See Workspace search for how it works.

Tool	What it does	Kind	Auto-approves?
search_workspace	Ranked (BM25) full-text search over chunked workspace content; returns path:line hits best-first. Filters by path prefix and kind (markdown / text). Query must be ≥ 3 characters.	read	Yes

search_workspace is registered by default. Set search_enabled = false or KIN_SEARCH_ENABLED=0 to remove it entirely from new sessions. It’s a local stdlib SQLite FTS5 index—no network and no egress. The index DB lives outside the workspace under ~/.kin/index/ (so it’s never committed or surprise-tracked); secret files (.env, ~/.ssh, .mcp.json, …) and .gitignored paths are excluded from both the index and results. It is ranked lexical search, not semantic/vector search. Because results are in-workspace content the model already reads freely, they carry the same trust as grep output. See Workspace search.

Memory

One memory tool over the persistent cross-session store under ~/.kin/memory/ — Anthropic’s memory-tool command set, so models trained against it drive it natively. See Memory for categories, recall, and the end-of-run reflection pass.

Tool	What it does	Kind	Auto-approves?
memory	view / create / str_replace / insert / delete / rename over markdown files under the virtual /memories root. create overwrites; delete/rename refuse the root itself; every path is canonicalized and confined to the memory root.	edit	view always; mutations auto-apply in auto, ask in strict

memory is registered by default; memory_enabled = false / KIN_MEMORY=0 unregisters it (project-ok — the knob only removes the tool; containment lives in the path guard). Mutations are confined to the memory root instead of the workspace — that root is the global-only memory_dir setting. See Memory.

Web

web_fetch is always available. The two Brave-backed tools are registered only when BRAVE_API_KEY is set, so the model is never shown a tool it cannot use.

Tool	What it does	Kind	Auto-approves?
web_fetch	Fetch a URL and return its main content as markdown (or extracted PDF text). SSRF-safe.	read	Yes
web_search	Search the web (Brave) and return a list of results. Requires BRAVE_API_KEY.	read	Yes
web_context	Search and return model-ready, re-ranked context chunks (Brave LLM Context). Requires BRAVE_API_KEY.	read	Yes
cite_check	Check a batch of cited URLs for liveness (HEAD-first, no body downloads) with a Wayback-snapshot substitute for dead ones. Same SSRF guard as web_fetch.	read	Yes

See Web tools for enabling Brave and choosing between them, and Deep research for the citation-liveness gate cite_check backs.

Rig

Kin’s persistent semantic computer beside Outpost: a headful browser, isolated shell, and machine-local memory. The browser reads compact ARIA snapshots and acts by role/name; screenshots are available explicitly when visual judgment is useful.

Tool	What it does	Kind	Auto-approves?
rig	Semantic browser and AT-SPI desktop actions, tabs, downloads, on-demand screenshot/set-of-marks, and reset over the versioned Rig service.	rig	Yes in auto (asks in strict)
rig_shell	Bounded commands in Rig’s separate persistent shell workspace; network is off by default.	rig	Yes in auto (asks in strict)
rig_memory	The six memory commands over machine-local durable knowledge.	edit	Reads yes; mutations follow mode.

Registered only when rig_enabled is on and global rig_url + rig_token are present. browser remains a dispatch alias for rig; old browser settings are accepted no-ops. Rig actions are denied while planning. See Rig for actions, deployment, credential handoff, and its enforced boundaries.

Git and GitHub

Ordinary root sessions get two structured tools for the work that otherwise causes repeated shell and credential approvals:

Tool	What it does	Kind	Auto-approves?
git	status, diff, log, branches, create_branch, switch_branch, stage, commit, fetch, clean-tree safe sync (update is an alias), and same-name push.	Dynamic: read, edit, network, or publish	Normal calls follow the active mode; force-push always asks
github	List/view PRs, read checks, and open a PR through the installed gh CLI.	network for reads; publish for open	Yes in auto; asks in strict

The model supplies an operation and bounded fields, not a command line. The tools assemble fixed argv without a shell and refuse arbitrary flags, URLs, refspecs, tags, branch deletion, caller-directed merge/rebase/reset, stash, PR merge, review, comment, edit, or close. github.open_pr never pushes implicitly: the branch must first be published with git.push. Retrying the same head/base pair returns the existing open PR instead of creating a duplicate.

Remote Git accepts one effective SSH or HTTPS push URL. It refuses embedded credentials, multiple push URLs, local/custom transports, and repository-owned credential, HTTP, include, proxy, askpass, SSH-command, remote-program, mirror, or server-option configuration. Before the first remote operation, Kin shows a separate Git credential modal naming the resolved host, port, transport, repository, and auth route. Once permits one call, Session trusts that exact route until Kin closes, and Trust host stores only a host-wide, secret-free route fingerprint in global settings. If SSH config or the trusted global/system HTTPS helper route changes—even while the approval is open—Kin refuses the stale call and asks again for the new route. SSH may expose the agent socket and public client metadata; HTTPS may expose only the credential store selected by the approved route. Private key files and credential values never enter model context.

For github.com, Kin prefers the active gh account over the saved transport. An SSH remote therefore works without exposing private key files: Kin leaves the remote unchanged, uses canonical HTTPS for that one command, and installs gh auth git-credential as the only command-scoped helper. If gh is not yet connected, the current operation opens one Connect GitHub modal, completes the human web login, and resumes automatically. The model does not need to retry the call or troubleshoot SSH.

git.sync handles the ordinary clean divergence case as well as fast-forward. It may replay at most 32 linear, non-empty local commits that are absent from both the pre-fetch remote object and every current remote-tracking ref. The pre-fetch checkpoint prevents a remote rewrite from making published work look new. Before replay Kin records the exact original HEAD in refs/kin/recovery/…; conflicts and interruptions restore the original clean branch automatically, including when rebase temporarily detached HEAD. An advisory lock keeps two Kin processes from sharing that recovery state; the second gets a wait-and-retry result. Dirty trees, merge commits, empty commits, known published work, a foreign rebase, or a changed premise stop for review.

A normal push publishes only the checked-out branch to the same branch name. Force is available only as force_with_lease=true; each call requires a fresh approval, reads the exact remote object ID after approval, and pins that ID into --force-with-lease. There is no reusable Always grant for force. An executable pre-push hook under a writable workspace gets its own content-hash-scoped approval, and Kin rechecks the hash immediately before credential use.

GitHub authentication remains owned by gh, not Kin. Usually the blocked tool offers the login itself; /github connect is the proactive human path, while /github repair verifies both the login and a real read-only Git transport call. Kin asks gh for a token-free account projection, strips inherited GH_* / GITHUB_* tokens, and runs model-facing calls non-interactively. See Modes & permissions for the publish policy and Auto mode & the OS sandbox for credential containment.

Beam Git checkpoint

A Beam child keeps its existing internal git-push / git-pull / git-fetch trio because the exact push call is the bounded Outpost approval/resume checkpoint. Those schemas are disjoint from the ordinary git / github tools and are not widened by the host-trust grant above. git-push and git-pull remain always-ask mcp operations; git-fetch remains network (allow in auto, ask in strict).

Outpost

A tool pair speaking to your Outpost’s v1 HTTP API — the always-on automation layer (scheduler, job runs, inbox) kin can check on and drive from the local loop. outpost reads; outpost-send acts.

Tool	What it does	Kind	Auto-approves?
outpost	Read the automation layer: jobs (list runs, cursor-paginated), job (one job + its runs), report (a run’s markdown report), inbox (open items awaiting an answer), schedules (standing/upcoming schedules), profiles (available execution profiles and models). Structured args only — op + that op’s fields.	outpost	Yes in auto (asks in strict)
outpost-send	Act on the automation layer: submit (hand off a new job — workspace + prompt), answer (answer an open inbox item), cancel (cancel a job), return (fast-forward a locally recorded settled Beam and emit its durable return marker; partial=true is explicit).	mcp	Never (always asks)

jobs and schedules answer different questions — jobs is a runs-backed listing (“what ran”), schedules reads schedule definitions directly (“what’s due to run”: standing cron/every jobs regardless of enabled state, plus a future one-shot). A standing schedule that hasn’t fired yet is invisible to jobs; use schedules for “what’s scheduled today”/cron questions. inbox, schedules, and profiles need the operator scope on your Outpost service (set from More → Advanced) — a non-operator token gets refused.

Both tools register only when outpost_url and outpost_token are both set (global-only — see settings), so the model is never shown a tool it can’t back. outpost gets its own outpost kind; outpost-send reuses the always-ask mcp kind since its operations mutate either the remote scheduler or, for Beam return, the local feature branch. Both are refused while planning. Every response — a job’s metadata, a run’s report, an inbox question — is framed as untrusted data before it re-enters context.

Note

Journals written before three tool renames reference view_file, view_notebook, and exit_plan. The registry keeps dispatch-only aliases (view_file → read_file, view_notebook → read_notebook, exit_plan → present_plan) so an old session still resumes, while the model only ever sees the current names. See Sessions.