add-tool

Add a First-party Tool

Define the Behavioral Contract

1. Confirm the capability belongs in a first-party tool rather than an existing tool action, MCP server, plugin, or domain API.
2. Read Execution boundaries and inspect the nearest tool, its taxonomy entry, resolver path, renderer, and tests.
3. Write the failing invariant test first. Cover the public result, permission/capability behavior, cancellation, and state change that matter to callers.

Implement the Backend

1. Define the tool with Tool.define(id, init, options?) under the owning business package’s domain tools/ directory. Harness owns generic definitions, discovery, execution and scheduling; concrete file/shell tools belong to runtime-local.
2. Use precise Zod parameters and descriptions. Model-facing parameters must serialize to a JSON Schema object at the root; wrap a discriminated action union in an object field such as input. The production tool resolver excludes schemas without an object root. Test this boundary as well as individual variants. Return the established { title, metadata, output, attachments? } shape.
3. Honor ctx.abort, use ctx.ask() for operation-specific permission requests, and route filesystem, shell, network, remote, or external-write work through existing boundaries.
4. Register through the owning package’s explicit tool contribution using ToolRegistry.registerToolProvider. Keep selection and ordering in the capability registration; only generic built-ins belong in the Harness registry.
5. Add an exact tool/taxonomy.ts entry with the correct domain kind and stateful / externalIO traits. Verify enforcement classification when arguments change the operation, such as local versus remote execution.
6. Add persisted-state migrations in the owning domain when the tool changes stored data shape.
7. Bound subprocess output while reading it: stream records, cap individual records and retained bytes, drain stderr concurrently, honor cancellation, and terminate the child when the consumer has enough results. Never call text() on potentially unbounded output and truncate only afterward.