Subagents

Give a child one independently finishable task, then keep the main conversation responsible for its result. Use ++ctrl+o++ or /agents to inspect it. Kin’s model-specific guidance weighs specialization, context cost, and useful parallel work; you can state your own delegation preference in the request.

Choosing the context

Tool	Context	Use
task	Self-contained brief plus Kin/workspace instructions.	Independent research, review, or specialist work.
fork_agent	Represented conversation through the current request, then the focused brief.	Work that depends on earlier decisions and corrections.

Both share the parent’s files. task has no public workdir/worktree argument. Keep parent/child writes serial; use read-only children for parallel work and separate checkouts for concurrent writers.

For change review, supply the base, scope, and complete assigned diff, including new files. Put it in the brief or an explicitly named patch the child can read. A read-only reviewer cannot use a commit id to run Git. Missing comparison material limits the review. A requested review of current files alone needs no change baseline.

A fork inherits summaries already present after compaction. Its unresolved parent tool batch is excluded; Kin does not silently compact its inherited prefix just to fit the fork.

The task tool

Argument	Required	Meaning
prompt	Yes	Complete task brief.
subagent_type	Yes	Agent profile.
model	No	Legacy model override on the current endpoint; exclusive with route.
route	No	Operator-defined route selectable for task; exclusive with model.
run_in_background	No	Return an id immediately instead of waiting for the result.

Route precedence is profile assignment, task assignment, allowed requested route, legacy model override, then the parent’s backend. Operator bindings win. The model sees selectable route descriptions, not their endpoints or keys. Existing children retain their backend snapshot after a root reload.

A child’s tools are the intersection of parent availability, profile allowance, and child restrictions. It inherits permission mode and planning limits but cannot ask the person directly or gain root-only tools. The parent handles needed questions. Tool review remains at the root’s human decision boundary.

Foreground activity folds into its task row. Results are bounded by 32 KiB plus line/token/context limits, with explicit truncation and spill recovery where available. Every child has a registry id, including foreground children.

The fork_agent tool

fork_agent(prompt, run_in_background?) keeps the parent’s exact backend, model/route, represented context, workdir, mode, and child-safe live tool registry. It has no profile or model override. Dynamic/MCP tools remain when available; ask, write_plan, present_plan, and recursive fork_agent are removed. Nested task remains possible.

A foreground fork returns its answer; a background fork returns an id. Both use the same supervision and retention as task children. Restart uses the frozen launch conversation under a new linked id; a replacement prompt changes only the focused instruction.

Agent profiles

Profile	Work	Available tool families
general	General bounded task	All child-available tools.
researcher	Sourced research	Read, media, web, citations, todos, skills.
coder	Implement and verify	Read, media, edit, shell, todos, skills.
explorer	Local orientation	Read, media, workspace search, todos, skills.
planner	Research and draft a plan	Read, media, search/web, todos, skills, write_plan.
critic	Plan review	Read, media, search/web, todos.
critic-code	Code/output review	Read, media, search/web, todos.
security-auditor	Attack-path review	Read, media, search/web, todos.

Only profiles with skill receive the skill catalog. Actual availability still follows the parent registry. The tool reference names capabilities; profiles do not bypass their permissions.

To add or override a profile, place <name>.md in one of these roots, highest priority first:

1. <workdir>/.kin/agents/
2. <workdir>/.claude/agents/
3. ~/.kin/agents/
4. ~/.claude/agents/
5. Bundled defaults.

---
name: reviewer
description: Review the supplied diff for correctness and risk.
tools:
  - read_file
  - grep
---

Read the supplied comparison and relevant source. Report concrete bugs,
evidence, and any limits in the material provided.

Field	Rule
name	Required; ^[a-z][a-z0-9-]*$, with filename stem canonical.
description	Model-readable scope.
tools	Exact allowed names; omitted/empty means all child-available tools.
max-turns	Optional leash: 0/omitted is unlimited; positive values clamp to 1–1000.

Use --- frontmatter; TOML-style +++ is skipped with a warning. The body supplies working instructions. Discovery updates for new rounds/spawns; existing children retain their launch context. See Agents for main-session --agent launches.

Limits

Limit	Default/behavior
Nesting depth	4; excessive dispatch is refused.
Parallel children	3, or 4–7 for selected MiniMax/Z.ai tiers.
Background capacity	Separate provider-aware root limit; foreground children use their own concurrency/depth limits.
Result	32 KiB ceiling plus shared output bounds.
Steering mailbox	16 messages / 64 KiB; overflow is refused.
Inactivity	600 seconds marks an active non-paused child stale; never cancels it.

Bundled profiles have no round cap. Shared token budgets and loop guards remain; a custom positive max-turns is an explicit leash. Each child gets its own nested parallelism budget. Provider tier changes do not lift the depth limit. See cloud capacity.

Lifecycle and control

Lifecycle (running, pause/interrupt requested, paused, idle, closed), outcome, and health (healthy/stale) are separate. Paused children still count against capacity.

Tool	Use
agent_list	Metadata snapshots; no child prose.
agent_inspect	State/lineage/usage and explicitly framed diagnostics.
agent_output	Current-run prose; all_runs=true includes earlier reports.
agent_wait	Wait for needed state, bounded to 10–60 seconds.
agent_message	Queue steering or continue an idle child.
agent_control	Pause, resume, interrupt, restart, or close.
agent_kill	Cancel and close a child.

Lifecycle events regain the main agent’s attention automatically. Healthy work needs no polling or human relay. Read reports explicitly when integrating them. The panel’s Enter opens a transcript; o opens buffered output; x kills a running row or dismisses a finished one.

Pause is background-only and occurs at a model boundary, never midway through a tool. A foreground child would block the parent that must resume it, so that pause is refused. Interrupt retains the Session and becomes idle only after cleanup joins; no second run can start during cancellation. Killing a child leaves the parent turn available, while Escape on the parent cancels foreground children and leaves independent background work running.

When a subagent fails

Failure results identify the child, mark partial output, and point to recovery:

Outcome	Meaning and next step
error	Backend failure after retries; inspect retained output.
turn_cap	Custom round limit; continuation grants a fresh window.
loop_detected	Repeated no-progress work; revise the instruction before continuing.
capacity	Hosted admission exhausted retries; retained work can continue when capacity frees.
crashed	Harness exception; inspect exact diagnostics.
killed	Explicit stop; parent can continue.

agent_output and agent_inspect expose retained evidence without rerunning work. Truncated output names a spill ref where captured text is recoverable. An incomplete report is never presented as a complete answer.

Retention: spawn → run → idle → closed

Completed and failed children park with their Session and transcript retained. Kill, explicit close/dismissal, and app exit clean up owned kernels and shells. Closing releases processes; retained data remains inspectable until registry teardown. Child journals are saved beside the root but hidden from ordinary resume pickers.

Continuing a parked subagent: agent_message

agent_message(agent_id, message, run_in_background?) queues FIFO steering for running or paused children. Messaging does not resume a pause. An idle child runs a new turn, either foreground or background; unknown, closed, or interrupt-settling targets refuse.

Continuation retains depth and launch configuration even if the profile is later renamed or removed. It returns only the new run’s prose; an empty run never substitutes an older report. Use agent_output(all_runs=true) for history. A restart is different: it creates a linked fresh attempt from the launch specification rather than continuing the retained conversation.