Tools

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

For implementation work, see extending tools.

How tools map to permissions

Each tool declares a risk kind; structured tools may choose it per operation. The tables describe Strict mode. In trusted Auto, edits and shell/code run directly. Protected-path checks, planning, and explicit review requirements still apply. See modes and permissions for the decision chain.

Filesystem

Dedicated read tools let Kin navigate directly. Edits are atomic and return a unified diff.

Text read_file results default to 2,000 lines with a 50,000-character body budget. The footer gives the exact offset for the next page. Whole-file mode checks a 500-line eligibility limit and still obeys the character budget; token totals in the footer are estimates. A single oversized line is shown partially with an explicit notice, and paging advances past it.

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.

The structured tool remains Kin’s stable route for one bounded exact search and for read-only profiles that do not have shell. A root session may instead use shell search when it needs batching or command composition. That path uses the ordinary shell permission policy and host commands; it does not inherit grep’s dedicated confinement, matching, or output contract.

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.

edit_file preserves an initial UTF-8 BOM and bytes outside the matched spans, including mixed line endings. LF and CRLF match equivalently; new lines use the starting line’s ending, or the preceding ending on an unterminated last line. Its labelled whitespace-tolerant fallback keeps requested leading and trailing line breaks in the match, so replacements do not add blank lines. A file with invalid UTF-8 is refused without modification. write_file remains the explicit full-content replacement operation.

Diagnostics after edit

Python writes can append bounded Ruff diagnostics: up to 20 lines or 2,000 characters on failure, nothing on a clean pass. Missing Ruff is a no-op; the diagnostic subprocess has a ten-second timeout. Set KIN_DIAGNOSTICS=0 or diagnostics_after_edit = false to disable it. The optional diagnostics_ty pass is off by default.

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

Shell and Python output is decoded in bounded UTF-8 fragments, so a long line does not have to fit in one pipe read. Foreground shell capture keeps a bounded prefix and tail; if a spill exceeds its store cap, the retrieval notice says that only the captured tail remains. A timeout still means the source did not finish, even when all bytes it produced were retained.

One gated shell tool, plus a background trio for long-running processes. Both launch /bin/sh; the login shell and $SHELL do not select the interpreter. Use portable shell syntax, or invoke bash -c '…' explicitly when a command needs Bash features such as arrays.

Tool	What it does	Kind	Auto-approves?
shell	Run a /bin/sh 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
read_spill	Read retained output behind a spill:<tool-call-id>:<index> ref shown in a truncated result. Resolves refs and only refs — there is no path argument. Returns a character window plus the stored size and next offset; explicitly says when the store cap retained only a tail.	read	Yes

Shell, run_code, Git/GitHub, web, MCP, and agent output share byte, line, estimated-token, and active-context-share limits. The bounded result stays inside those limits, preserves UTF-8, and names a read_spill ref when captured text is withheld from the model result. Source incompleteness is a separate fact: a timeout or running process says the producer did not return everything, and no spill claims to contain missing bytes.

Kin-authored completeness and retrieval notices remain outside frames that mark captured network or CLI text as untrusted. Git and GitHub structured checks validate the complete captured output, while only the bounded, redacted projection reaches the model; an inline elision cannot hide an authority-bearing ref, object ID, path, or JSON field from those checks.

Captured text is stored beside the session journal up to the human-set spill_max_bytes cap. If that cap retains only a tail, the marker and read_spill say so. A background shell spills where output leaves its buffer, not where you read it. Git and GitHub output is redacted before it is stored, and the store is purged with its journal. KIN_NO_SAVE (or any no-save route) disables it; spill_max_bytes = 0 turns it off explicitly. read_file is deliberately excluded: its truncation names an exact resume offset into a durable local file, which is a better door than a copy.

A foreground shell in strict auto-runs only when the command classifier proves it read-only; otherwise it asks. In trusted auto, foreground and background commands execute directly with the launching user’s real environment and authority. Lexical secret-path matches still force a non-reusable Ask, but that is a review rail rather than containment.

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); direct in trusted 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 trusted auto mode the persistent kernel runs directly with the launching user’s environment and authority; in strict it always asks, and while planning it is refused. Use a whole-process external boundary when Python must be isolated. run_code is the persistent subprocess for iterative computation.

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	Create or update the current work’s ordered checklist (a full rewrite each call); enforces at most one in_progress item and 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
enter_plan_mode	Ask you to put the session into plan mode, with a one-sentence reason. Approval begins the read-only freeze; a decline tells Kin to carry on normally. Top-level only; a headless run reports needs-human.	meta	Yes
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. Used in plan mode by the top-level model, or by the planner subagent when you ask for one. It never enters plan mode: outside it the top-level model is pointed at enter_plan_mode, and a planner’s file is a draft that your next entry adopts (see Planning).	meta	Yes
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)

Kin maintains the full checklist for multi-step work, with one active item and completion based on evidence. Tool success never marks an item complete automatically. The harness may remind the model once per unchanged active revision to reconcile progress. See tasks and todos.

Settings

Tools that let kin help tune settings in a visible conversation. The model can only write sampling/model knobs; authority knobs (mode / workspace_trust / shell_allowlist), retired inert sandbox* rows, secrets/endpoints (api_key / base_url / brave_api_key), and operator routing policy (model_routes / model_assignments) are refused. Open /config → settings for a guided turn, or turn on the optional per-turn guidance 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, thinking_type, cache_ttl, model). You review a diff and approve before anything is written; the change applies to new sessions. Any authority/secret/endpoint key is refused with a banner naming it. The effort knob is the per-serve picker vocabulary that /effort dispatches live; reasoning_effort is intentionally human-only. Top-level only and frozen during planning.	meta	Always asks (fresh diff)

Skills and project guidance

These structured proposal tools are the only model-authored publication seams for Kin skill text and root AGENTS.md. Both are top-level only, frozen during planning, produce needs_human in headless execution, and take a project snapshot for /rewind before applying project files.

Tool	What it does	Kind	Auto-approves?
propose_skill	Propose one complete skill-bundle transaction. Requires name, explicit project or user scope, and complete UTF-8 files including SKILL.md; delete names removals while unspecified resources survive. Validates the live loader and in-bundle links before a per-file diff. Project scope edits a project claim or creates an override; bundled sources stay immutable. The user scope is persistent and prominently warned. The reviewed target is rechecked under lock, with rollback/restart recovery.	meta	Always asks (fresh, non-reusable diff)
propose_agents_md	Propose the complete non-empty UTF-8 root <workdir>/AGENTS.md (50 KiB maximum). It may use CLAUDE.md as source material but never overwrites it or user guidance. A stale target aborts. The current parent keeps its system until the next root turn; later children get fresh guidance.	meta	Always asks (fresh, non-reusable diff)

Delegation

Tools for context-separated delegation, supervision, and reusable prompts. A task child shares the parent’s working directory and files, not its conversation history. The tool has no workdir or worktree-isolation argument; keep parent/child edits serial in the shared checkout, using read-only children for parallel work.

Tool	What it does	Kind	Auto-approves?
task	Delegate a focused job with separate conversation context but the parent’s working directory and files. 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 the current run’s prose by agent_id; all_runs=true includes earlier reports, and 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 complete descriptions for model-invocable skills, or load one current bundle through the shared <skill_content> renderer. Human-only skills are refused with a /name hint. A loaded skill adds instructions, never authority.	meta	Yes

See Skills for bundles and the model/slash doors, Subagents, Agents (foreground + background subagents + --agent) and Tasks for detail.

Local client handoffs

The optional present capability adds a root-only tool for showing a workspace file or loopback HTTP application in the client’s isolated view. These local variants use read permission. Create the artifact with ordinary file/build tools first, then supply a title and either path or url. It acknowledges display without granting the artifact approval or account authority.

A client also declaring present_depot can receive depot: {repo, commit_oid, path} instead. Supply a full commit OID and a repository-relative file path. This variant uses network permission and sends only the descriptor; the client fetches and verifies the saved file when opening it. Its display acknowledgement has the same current-writer ownership as other presentations. Clients declaring only present keep the local variants.

These tools are absent from ordinary terminal, headless, and child sessions. A kin --stdio local client must declare the matching capability before the root session can see one.

Tool	What it does	Kind	Auto-approves?
open_url	Ask the local environment to open one exact HTTP or HTTPS URL. It reports whether the environment did so and returns no page content.	meta	Yes
request_write_scope	Ask the person to approve one existing related directory for structured file writes in this conversation and its children. Root only, outside planning; revoke through /grants.	meta	Always asks for a new scope
open_workspace	Ask the local environment to confirm with the person and open a new conversation in one explicitly named, existing absolute directory. The calling conversation does not move.	meta	Yes, outside planning
get_workspace_context	Inspect bounded client observations about the attached work, saved versions, review, pending operations and document locations. Data can be incomplete or stale; no extra authority is granted.	meta	Yes
get_attention_context	Ask for an exact subset of the current window, workspace, output, or selection, only after the person’s request explicitly calls for current context. Returned values are bounded and untrusted-framed.	meta	Yes

A capable client’s environment reminder points to get_workspace_context without fetching observations. Interrupted work may have a retained client request even after Git or the forge confirms a saved commit. The existing environment opt-out also suppresses that pointer.

open_workspace allows five minutes for the person’s review. A successful handoff means the destination conversation opened; a draft there remains unsent until the person sends it.

The attention tool is pull-only. A client being able to observe the compositor is not a reason to add ambient context to an ordinary turn, and the client cannot return a kind Kin did not request.

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.

Web

web_fetch is always available. web_search and web_context are registered only when an explicit local Brave key resolves or an authenticated official kinra-api profile advertises that hosted operation. Login, logout, and profile refresh reconcile them live, keeping the model-facing registry aligned with Kin’s current local credential and last validated service capability.

Tool	What it does	Kind	Auto-approves?
web_fetch	Directly fetch one exact public URL and return retrieval metadata plus markdown, extracted PDF text, or verbatim text. SSRF/DNS-pinning protections apply on every redirect. focus performs deterministic local passage selection while offering the complete extracted capture to the bounded read_spill store when persistence is available.	read	Yes
web_search	Return provider-labelled result metadata through hosted Brave/Exa routing or the explicit local-Brave override. Hosted strategies are auto, semantic, and diverse.	read	Yes
web_context	Return provider-labelled, question-focused extractive passages grouped by source through the same hosted/local capability boundary.	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 hosted capability, the local Brave override, and choosing between them, and Deep research for the citation-liveness gate cite_check backs.

Git and GitHub

When a repository’s canonical origin is Depot, publish and review through depot. Structured Git push and GitHub PR creation refuse direct publication, including a retained GitHub destination. Depot owns synchronization to that destination. Importing a copy alone does not change the canonical origin.

The personal GitHub connection remains available for ordinary repositories, source discovery and permitted reads. It supplies neither Depot roles nor the credentials for Depot’s synchronization worker. The ordinary Git/GitHub flow below continues for repositories that do not use Depot as their canonical home.

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 & trusted workspaces for the local authority boundary.

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.

Personal Depot custody

An environment that installs the native Depot companion exposes the optional root-only depot tool without MCP registration. Your Kinra connection must explicitly include Depot access. Opening a folder does not copy it anywhere; you choose private custody before Kin establishes it.

Kin maintains ordinary Git underneath: inspect a workspace, commit named files, synchronize, publish and open a Change. Human review stays attached to the exact revision in Depot. New custody, new managed workspaces, access termination, deletion requests and reviews require fresh approval; planning prevents those effects. Existing workspace edits respect the current write scope. Child agents report custody needs to their parent.

Use depot with op=help and a topic to inspect an operation’s required fields. Mutations carry request IDs and observed state so an interruption can be inspected and retried deliberately. Exports produce ordinary Git bundles of canonical branches; unpublished local files stay separately retained. Revoking Kin’s access preserves the human owner. A deletion request records intent and keeps data until explicit removal; it is not immediate erasure.

Kin discovers operation schemas from the fixed executable’s depot hosted help without account credentials. The personal operation, field and permission registry still belongs to Kin: an advertised administrative operation does not become available. Each model round keeps its discovered schema unchanged.

kin depot status reports executable and catalog identities and supported features such as custody_status, saved files and review inspection. Installed capabilities are separate from verified server support. A missing or incompatible companion leaves a clear explanation; it does not substitute a bundled contract. Structured failures retain their code, observed state and request ID for exact recovery. custody_status reports the actual owner, connected peer and durable retention state independently of local workspace inspection.

With a compatible companion and server, Kin can inspect external check state, GitHub synchronization, incoming contributions and LFS custody. It can prepare checks for the exact source and target revisions. Changing synchronization configuration requires fresh approval; a connected GitHub account is not that approval. Read the reported state before treating a publication as synchronized.

For interrupted local work, workspace_reconstruct uses the inspected original head, index and operation identities to restore the retained intended files. Retry the original pending request afterward. Reconstruction does not silently complete that request or recover files that were never recorded.

workspace_uses provides inspection only. Destructive workspace_close is currently unavailable in Kin while the complete conversation, writer, terminal and preview exclusion protocol is being qualified. An empty use list does not authorize removal. See Depot custody and recovery for the owning recovery guidance.