Extending kin — tools, kinds, and profiles

Add a tool when the existing surface cannot express the required operation clearly. Keep permissions, output framing, and cleanup part of its contract. The maintainer walkthrough owns detailed extension procedures.

Adding a tool

1. Subclass Tool from src/kin/harness/tools/registry.py and declare its name, description, parameters, and risk kind.
2. Implement async run(args, ctx) and return text or content blocks. Validate arguments at this boundary; model-side schemas are not sufficient.
3. Use shared coercers for permissive model values and shared framing for untrusted external text. Keep status and retrieval notices outside that untrusted frame.
4. Register the instance in default_registry() and decide which child profiles should receive it. A profile cannot grant a tool absent from its parent’s live registry.
5. Add focused tests for the result, refusal paths, side effects, and cleanup. Regenerate the tool catalog with its owning task.

Use ToolContext for workspace, cancellation, event emission, and session services. Propagate parent_tool_call_id for child activity. Subprocess tools must own and clean up their process groups on timeout or cancellation.

Choosing a kind

Existing kinds are read, edit, shell, meta, mcp, network, and publish. A structured multi-operation tool may resolve its kind for the concrete call. Choose by effect, then test the relevant Auto, Strict, and planning decisions. A new kind requires updating every mode and permission mapping; a new tool usually does not.

Risk kind alone does not bypass protected paths, exact-call approval, workspace trust, or other policy checks. See permissions.

Agent profiles

Profiles select instructions, allowed tools, routing, and optional limits. Use bundled, user, or project agent directories according to the intended scope. The profile schema and agent guide describe discovery and launch behavior.

Verification

Run the new focused test through task verify-one, then task check. Update user documentation and the owning bundled self-reference when behavior changes. Finish with a fresh task ship, plus the relevant live gate if the change crosses a live boundary.