subharness 0.0.1

package/sdk/message-delivery.md

@@ -0,0 +1,39 @@
+# Message Delivery
+
+`subharness send <session-id> --delivery <queue|steer|interrupt> --prompt <text>` controls delivery. `queue` is the default. Each session has one active library task and a FIFO queue; a library task can contain multiple native turns while coordinating descendants.
+
+| Mode | Effect |
+| --- | --- |
+| `queue` | Creates a task behind previously queued work |
+| `steer` | Adds guidance to the current task, or uses interrupt when active native steering is unavailable |
+| `interrupt` | Stops the active task and its descendants, then starts a replacement before independently queued work |
+
+## Queue advancement
+
+Queue dispatch follows task completion, not the return of a CLI command or every native turn. If A returns a response while a reviewer is running, A remains active and B waits. Once descendants and result processing finish, the parent's complete response releases B. The library uses native completion and task relationships, not text classification.
+
+A complete response asking a question finishes a task when no descendant work remains. B can then start. The coordinator decides whether its answer should be queued or applied to the current task with another delivery mode. A native approval/input request is different: it has not completed a turn. In v1, input the library cannot answer under native policy fails with `INPUT_REQUIRED`; it is never automatically approved.
+
+Execution failure pauses pending work. A successful explicit native recovery must finish the failed task before pending tasks proceed. Unsupported recovery leaves work paused. Queued command observers may remain waiting until their task starts or is explicitly cancelled.
+
+## Steering
+
+Native steering adds guidance without cancelling the active task or creating another task. The command acknowledges acceptance; it does not return a new agent response. Steering a task waiting between native turns starts a continuation of that task while its children keep running. No active task is an error.
+
+If active native steering is unavailable, the operation uses the full interrupt behavior. It cancels the active task and descendants, creates a replacement task with the correction, and preserves independently queued tasks. The output identifies both requested `steer` and effective `interrupt`. It returns the replacement's response under interrupt semantics. Other native errors do not trigger this fallback.
+
+There is no expected-task guard: if B has already become active, the correction applies to B. Unsupported steering is detected before native mutation so fallback does not deliver the correction twice.
+
+## Interruption and cancellation
+
+If A is active and B/C are queued, interrupting with X stops A and its delegated descendants, runs X, and then resumes B/C in their original order. A and its children are not automatically requeued. X cannot start while affected native execution might still be running.
+
+Cancellation applies recursively to recorded delegation relationships. Pending descendants are removed without execution; active descendants receive native interruption. Other tasks in the same queue, directory, or agent definition are not descendants solely for that reason. Completed results and tool effects remain. Already-admitted custom callbacks must settle before stop confirmation.
+
+`cancel` returns after affected work has stopped. Repeated cancellation of already-settled work returns its state. An unconfirmed stop reports a cancellation error and keeps dispatch paused; it does not authorize starting replacement or queued work. Invalid replacement input is rejected before existing work is cancelled.
+
+## Resume after an execution error
+
+`subharness resume <session-id>` addresses the existing failed task and requires no new prompt. It does not replay the original task, migrate to another harness, or skip the failure to release the queue. An unavailable native recovery operation returns `RECOVERY_UNSUPPORTED`. A session without failed work returns an error.
+
+V1 native adapters do not currently provide prompt-free recovery of failed work, so the command reports that limit. The caller can inspect results and explicitly cancel or create new work. Cancelling settled failed work releases its queue when no execution remains uncertain.

package/sdk/plugins/sub-agents.md

@@ -0,0 +1,57 @@
+# Subagents
+
+An agent's optional `subagents` map declares and authorizes the agents it can invoke. Values are ordinary `AgentDefinition` objects; children can have their own subagents. Declaration alone does not execute them or register them in a repository/global catalog.
+
+```ts
+import { agent, codex } from "subharness";
+
+const reviewer = agent({
+  name: "reviewer",
+  description: "Reviews changes for correctness.",
+  instructions: "Inspect the diff and report actionable findings.",
+  harness: codex({ model: "CODEX_MODEL_ID" }),
+});
+
+export default agent({
+  name: "developer",
+  description: "Implements and verifies features.",
+  instructions: "Implement the requested change, then ask reviewer to review it.",
+  harness: codex({ model: "CODEX_MODEL_ID" }),
+  subagents: { reviewer },
+});
+```
+
+## Invocation
+
+The adapter provides direct child names, descriptions, and CLI instructions to the parent. Managed agents receive the absolute path of a launcher for their session and use that executable for delegation and follow-ups. This avoids invoking another installed program named `agent` when a native shell changes PATH.
+
+The launcher restores its coordinator location and parent context before invoking the CLI, so delegation does not depend on the shell preserving integration environment variables. The launcher is stored with owner-only permissions and removed when its session worker closes. It contains only local orchestration context, never provider credentials. Commands and agent instructions do not contain parent tokens or credentials.
+
+For Claude Code, declaring at least one subagent adds native permission rules for the current session's exact launcher. Equivalent quoted or unquoted spellings are allowed only when they identify the same literal executable. These rules authorize `run subagent:<name>` for the declared names, plus the CLI's `list`, `--help`, `send`, `wait`, `status`, `queue`, `cancel`, and `resume` operations. They do not authorize launching repository or global agents through `run`, another executable, or arbitrary shell commands. Follow-up and observation commands retain their documented identifier-based behavior; the permission rules do not introduce a new task-access policy.
+
+The adapter combines these rules with declared custom-tool permissions. It does not write user/project permission settings or change the native permission mode. Native deny rules, explicit approval requirements, managed policy, and sandbox restrictions remain authoritative. A request that still requires approval returns `INPUT_REQUIRED`. Each child starts with its own native tool permissions; permission to launch it does not grant permission for its edits or shell commands. A session without declared subagents receives no delegation rules. If a launcher path cannot be represented as a literal command in the native permission syntax, startup fails with `INVALID_CONFIG` rather than adding a broader rule.
+
+The native execution environment must allow the CLI to read its private launcher and contact the coordinator over loopback HTTP. A native sandbox that blocks local networking also blocks CLI delegation. The library does not relax that policy; the caller configures the native harness or external execution environment.
+
+The command has the same arguments as an ordinary CLI invocation:
+
+```sh
+subharness run subagent:reviewer --cwd /repo/worktree \
+  --prompt "Review the implementation against the documented requirements."
+```
+
+The suffix is the local map key. It resolves only against the current parent's direct declarations, with no ancestor/global/repository fallback. Missing parent context or an undeclared name is an error. Parent context is passed privately by the integration; no public parent-token flag is required.
+
+Each invocation creates a child session and task. The same `send`, `wait`, `status`, `queue`, `cancel`, and `resume` commands apply. A caller can instead coordinate independently discovered agents directly; that does not implicitly create a nested pipeline.
+
+## Context and results
+
+A child receives its own instructions and explicit task input, without copying the parent's transcript or forking its native session. The parent supplies requirements, decisions, and relevant file references, including any skill files the child needs to read. Previously loaded skill contents are not inherited. Native repository instructions and skill discovery follow the selected harness's rules; Subharness does not install native subagent definitions or skills. The caller supplies an existing directory; no sandbox or worktree is created.
+
+Results return to the immediate caller. A child may itself return a pending response while its descendants run. A parent's task remains active until its descendant work and result processing finish, as defined in [response delivery](../completion-notifications.md). The library does not forward every child transcript to every ancestor.
+
+Cancellation or interruption of a task propagates through its recorded descendant tree, waits for affected execution to stop, and preserves independently queued tasks. Parent execution failure also cancels outstanding descendants; uncertain cancellation keeps dispatch paused. Child failure is delivered as an outcome the parent can interpret rather than automatically failing the parent.
+
+A follow-up sent from an active managed parent attaches the new child task to that current parent task. Reusing a child session does not attach new work to a previously completed parent. External follow-ups have no implicit parent. Delegation into the caller's own session or an ancestor session is rejected because it would deadlock completion.
+
+Nesting is limited to eight levels. Existing tools and file effects are not rolled back by cancellation. These relationships coordinate work; they do not isolate concurrent edits in the same directory.

package/sdk/project-team.md

@@ -0,0 +1,57 @@
+# Repository Agent Team
+
+This repository keeps five reusable agents in `.agents/agents/`. An agent defines a stable responsibility, model, and tool access. A skill supplies task-specific instructions that the agent reads when relevant. Adding a technique or library does not require another agent definition.
+
+## Roles
+
+| Agent | Harness and model | Responsibility |
+| --- | --- | --- |
+| `architect` | Codex, `gpt-6-astra`, high effort | Evaluate architecture and API decisions; develop requested design concepts and assets; perform independent visual review when assigned. |
+| `developer` | Codex, `gpt-5.6-sol`, high effort | Implement documented behavior and application structure with focused TDD and independent review. |
+| `visual-engineer` | fx, `anthropic/claude-fable-5.1`, native default effort | Implement approved interface styling and native vgpu/WGSL effects using the relevant skill. |
+| `researcher` | fx, `google/gemini-3.8-flash`, native default effort | Answer a bounded technical or design question with primary-source evidence. |
+| `reviewer` | Claude Code, `claude-opus-5[1m]`, high effort | Independently review correctness, lifecycle, credential routing, and contract compliance without editing files. |
+
+Model identities are explicit. There is no automatic model downgrade or change to a paid API route. Fast mode is disabled for Codex and Claude Code; fx retains its native preference because its ACP interface has no selector. Codex and Claude Code use eligible native subscriptions unless personal access settings select another route. The fx roles require explicit personal `access.fx` configuration as described in [fx](fx.md); Gateway team policies can restrict model access.
+
+Skills are reusable across roles. The table records this repository's preferred allocation of work, not an SDK restriction on which agent may read a skill. A developer can use an interface skill for one task and a graphics skill for another without changing its definition or model. An omitted custom `tools` map does not disable the harness's native tools.
+
+Roles do not grant native capabilities or permissions. Browsing, image generation, image viewing, Blender, file writes, and shell access depend on the selected harness and execution environment. A missing capability must be reported before claiming a result.
+
+## Skills and task context
+
+Repository skills live in `.agents/skills/<name>/SKILL.md`. The short index in `AGENTS.md` explains when each skill applies. Agents read only the relevant skill and supporting references for their current task. Skill contents are not concatenated into every agent's instructions.
+
+These files are ordinary instructions consumed through the native harness. Subharness does not install skills, discover them on the caller's behalf, provide a `skills` definition field, or guarantee that every harness exposes the same skill command. Native automatic discovery depends on the harness and its settings. This repository's shared instructions explicitly require reading `AGENTS.md`, so the index remains usable through ordinary file reading even when a harness does not automatically discover `.agents/skills/`.
+
+The caller provides one bounded deliverable, governing contracts, input artifacts, working directory, and relevant skill paths. Each child receives its own task and instructions; it does not inherit the parent's transcript or previously loaded skills. A handoff therefore names required skills again.
+
+```sh
+subharness list
+subharness run repo:architect --prompt "Read website/design.md and .agents/skills/design-exploration/SKILL.md. Evaluate the supplied hero reference and report a composition recommendation."
+subharness run repo:visual-engineer --prompt "Use .agents/skills/web-interface/SKILL.md. Implement the hero layout documented in website/design.md. Limit changes to the hero styles."
+subharness run repo:developer --prompt "Use .agents/skills/web-interface/SKILL.md. Read website/design.md. Check the hero's semantic HTML and keyboard behavior without changing styles."
+subharness run repo:developer --prompt "Use .agents/skills/webgpu-graphics/SKILL.md. Read website/graphics.md. Verify the mascot camera's documented framing with focused tests."
+subharness run repo:researcher --prompt "Use .agents/skills/source-research/SKILL.md. Read sdk/fx.md and src/adapters/fx.ts. Explain cancellation behavior with file references."
+subharness run repo:reviewer --prompt "Review the mascot camera changes against website/graphics.md. Report actionable findings without editing files."
+```
+
+The website's three specialist labels, QA Tester, Developer, and Designer, demonstrate possible role configurations. They are not an inventory of this repository's agent definitions.
+
+## Delegation and review
+
+CLI and runtime work uses the existing architect, developer, and reviewer roles. Separate developer sessions can own independent modules; scope and governing contracts distinguish their assignments without adding permanent roles. The architect evaluates native protocol constraints, the developer implements and integrates behavior with TDD, and the reviewer independently checks user-facing behavior, lifecycle, and credential routing. The lead coordinates contracts, assignments, and final verification. Implementation and fixes run through repository agents whenever supported, so follow-ups, queues, and review cycles exercise Subharness itself. Reproducible coordination failures are evidence for library improvements under the same contract and review rules.
+
+The lead agent coordinates bounded tasks and resolves missing decisions under `AGENTS.md`. Skills do not authorize new features, public API shapes, permission changes, or undeclared children. Research findings and generated concepts are evidence, not implementation contracts. Source research and explorations belong in the ignored `.context/research/` directory.
+
+`developer` retains a declared `reviewer` child for independent code review after code changes. It supplies the scope, governing documents, and relevant skill paths, fixes actionable findings, and requests re-review. The lead can explicitly own this review cycle, including when native permissions prevent the developer from reaching the coordinator. In that case the developer returns its changes and verification evidence without starting a duplicate review or retrying a known blocked launcher. The lead must still obtain independent review and return findings to the developer. A read-only verification task returns its evidence without starting an unnecessary review cycle. The lead separately assigns visual review when needed. If delegation unexpectedly fails, the developer reports the exact operation; returning evidence alone does not establish a passed review. The other roles return work to the lead for independently assigned review and do not declare children. A task-specific specialization can use a fresh session of an existing role with an explicit skill; it does not require a new globally discoverable role.
+
+Delegation through either harness requires the native environment to read and execute the private session launcher and contact the local coordinator over loopback HTTP. Declaring a child does not override a Codex sandbox or native permission policy. The caller configures that access in the harness or external environment; Subharness does not change it. See [subagents](plugins/sub-agents.md) for the launcher and permission boundaries.
+
+A `subagents` declaration authorizes Subharness child sessions as described in [subagents](plugins/sub-agents.md). It does not install native harness subagent definitions or grant the child extra tools. Independent review uses a different session from the implementation or design author. Visual review requires actual rendered captures; code review and generated mockups do not establish visual correctness.
+
+## Visual evidence and native limits
+
+The fx researcher and visual engineer expose a `view_image` custom tool. It returns native image content through `toolResult`, rather than a path or base64 text. It reads supported image files up to 3 MiB only inside the execution repository's `.context/research/landing/`, `.context/site-verification/`, and `apps/docs/public/` directories. Canonical paths, including symlink targets, must stay within those roots. Symlinked allowed roots cannot redirect access elsewhere. The tool does not fetch URLs or alter permissions.
+
+Image tasks respect the native version limits in [fx](fx.md). When native fx is affected by the documented ACP image-result crash, the lead can supply images through native `fx ask --image` using the same role, model, and explicit connection. This is an external native-harness invocation, not a Subharness session or proof of CLI queue and coordinator behavior. Supported text tasks continue through Subharness. Missing capabilities never justify a silent model substitution or custom inference loop.

package/sdk/sessions.md

@@ -0,0 +1,31 @@
+# Sessions and Tasks
+
+An agent definition describes reusable behavior. A session is one native conversation in a fixed execution directory. A task is a unit of work within that session. Tasks and sessions have separate opaque identifiers and are not shell process IDs.
+
+Each `run` creates a new session; `send` creates follow-up tasks or steers the active task. A session retains native conversation state and its loaded instructions, tools, and harness configuration between tasks. The external harness owns its context and compaction.
+
+## State
+
+| Task state | Meaning |
+| --- | --- |
+| `queued` | Admitted but not yet dispatched |
+| `running` | Native startup or generation is active |
+| `waiting` | Between native turns while delegated work or result processing remains |
+| `completed` | Native response and descendant completion boundary are satisfied |
+| `failed` | Execution or cancellation failed; queue dispatch is paused |
+| `cancelled` | Explicit cancellation confirmed |
+| `interrupted` | Replacement cancellation confirmed |
+
+Failure is a terminal observation, not proof that uncertain native cancellation succeeded. Such execution remains owned and its queue stays paused until stop can be confirmed.
+
+Every complete response receives a response identifier and returns control to its caller. A response may ask a question or report failing tests; neither its text nor command exit `0` proves objective success. The task can remain pending after that response if descendants or their results remain.
+
+`wait --after` observes later responses without creating another task. `status` reports current state independently of earlier response snapshots. Completing a task does not delete its conversation. Returning a command does not cancel the task or descendants.
+
+## Lifetime and recovery
+
+The on-demand coordinator retains task records and native session workers beyond individual command exits. Task IDs resolve from other working directories using that coordinator. Records remain available for its lifetime; they are not silently evicted.
+
+Restarting the coordinator does not restore queues or automatically replay tasks. Native harness history can exist separately, but this version does not reconstruct library sessions from it. Unavailable identifiers return an error. `resume` is limited to supported native recovery of a retained failed task; it does not imply recovery after coordinator loss.
+
+Cancellation, interrupt propagation, and queue behavior are defined in [Message Delivery](message-delivery.md). The detailed ownership and bounds are defined in the [runtime contract](v1-runtime.md).

package/sdk/tools.md

@@ -0,0 +1,73 @@
+# Custom Tools
+
+`tool({ description, inputSchema, execute })` defines a function that a native harness can invoke. The map key in `agent.tools` is its public name. Declaring a tool does not execute it.
+
+```ts
+import { agent, codex, tool } from "subharness";
+import { z } from "zod";
+
+const uppercase = tool({
+  description: "Convert text to uppercase.",
+  inputSchema: z.object({ text: z.string() }),
+  execute: ({ text }) => text.toUpperCase(),
+});
+
+export default agent({
+  name: "editor",
+  description: "Edits text using the supplied tools.",
+  instructions: "Use uppercase when the task requests uppercase text.",
+  harness: codex({ model: "CODEX_MODEL_ID" }),
+  tools: { uppercase },
+});
+```
+
+All three fields are required. `description` is a nonempty string. `inputSchema` is a Zod 4 object schema representable as JSON Schema. `execute(input)` receives the parsed value, with TypeScript inference, and returns text, JSON-serializable data, or an explicit rich tool result synchronously or asynchronously. No second execution-context argument is supplied.
+
+Validation runs before execution; invalid arguments never reach the function. Unsupported schemas fail during definition validation. Non-serializable or oversized outputs and thrown exceptions become tool errors. Tool results are limited to 1 MiB. Errors do not masquerade as successful outputs.
+
+Tools run in their session worker's execution directory with that worker's environment. The adapter registers them in a native namespace without replacing the harness's native tools or model loop. Declaring a custom tool authorizes that agent to invoke it. Native tool permission policies remain with the harness.
+
+## Image results
+
+`toolResult({ content })` creates an explicit result containing text and image blocks. Plain objects remain JSON data even when they have a `content` property. This preserves existing tools and avoids guessing whether a JSON value is an image response.
+
+```ts
+import { readFile } from "node:fs/promises";
+import { tool, toolResult } from "subharness";
+import { z } from "zod";
+
+const inspectReference = tool({
+  description: "View the approved design reference.",
+  inputSchema: z.object({}),
+  execute: async () => toolResult({
+    content: [
+      { type: "text", text: "Approved hero reference." },
+      {
+        type: "image",
+        mimeType: "image/png",
+        data: (await readFile("references/hero.png")).toString("base64"),
+      },
+    ],
+  }),
+});
+```
+
+The public signatures are:
+
+```ts
+type ToolContent =
+  | { readonly type: "text"; readonly text: string }
+  | {
+      readonly type: "image";
+      readonly data: string;
+      readonly mimeType: "image/png" | "image/jpeg" | "image/webp" | "image/gif";
+    };
+
+function toolResult(result: { readonly content: readonly ToolContent[] }): ToolResult;
+```
+
+`ToolResult` is an opaque value created by `toolResult`; callers must return it directly from `execute`. It is not a JSON transport format. Content must be nonempty, contain only the supported block fields, and include at most eight images. Image data is canonical padded standard base64 without a data-URL prefix. The decoded file signature must match its declared MIME type. Each encoded image is limited to 5 MiB; the complete rich result's JSON content is limited to 8 MiB, and combined text is limited to 1 MiB. Ordinary text and JSON results retain their 1 MiB limit.
+
+The SDK validates rich results at the tool execution boundary. Malformed blocks report `TOOL_RESULT_INVALID`; exceeded limits report `TOOL_RESULT_TOO_LARGE`. Native adapters pass images as image content, never as base64 inside a text result: MCP image blocks for Claude Code and fx, and image content items for Codex. Model-specific image support and lower native limits still apply; a text-only model cannot perform visual inspection. The [fx contract](fx.md) records a native image-tool crash affecting fx 0.0.9. The tool author controls which files are read. This helper does not grant filesystem access or fetch remote images.
+
+Cancellation waits for already-admitted callbacks to settle. There is no cancellation signal in `execute(input)`, and completed effects are not rolled back. Streaming tool results and arbitrary external tool-definition objects are outside this API.

package/sdk/v1-runtime.md

@@ -0,0 +1,63 @@
+# V1 Runtime Contract
+
+The first usable version supplies a TypeScript definition SDK and the `subharness` CLI with Codex, Claude Code, and fx adapters. Other harnesses remain compatibility requirements outside this version's adapter set. The library coordinates existing harnesses; it does not implement a model loop, sandbox, worktree manager, or native permission system.
+
+## Package and definitions
+
+The package is `subharness`, with the primary executable `subharness` and identical `agent` compatibility alias. Node.js 22.18 or newer is required. ESM exports include `agent`, `tool`, `toolResult`, `codex`, `claudeCode`, `fx`, and their definition/configuration types. The public SDK defines reusable specialists; direct CLI harness targets also execute without a definition. Execution in v1 uses the CLI. Definition objects have readonly configuration fields and no execution methods. They contain functions and schemas and are not a serialization format.
+
+```ts
+import { agent, codex, claudeCode, tool } from "subharness";
+```
+
+Names and tool/subagent map keys match `[a-zA-Z][a-zA-Z0-9_-]{0,63}`. Descriptions, instructions, and model identifiers must be nonempty strings. Unknown configuration fields are errors. Definitions cannot contain recursive subagent references. Harness arrays are nonempty and retain declaration order. `fast` defaults to `false`.
+
+Custom tools accept Zod 4 object schemas that can be represented as JSON Schema. Input validation runs before execution. Functions return strings, JSON-serializable values, or explicit rich results created with `toolResult`. Rich results preserve image blocks through the native harness. Unsupported schemas and name collisions are rejected before a native turn starts. Tool exceptions and invalid arguments return tool errors; they do not masquerade as successful results. Declaring a tool authorizes its invocation by that agent. Native harness tools retain their native permission rules.
+
+## Discovery and loading
+
+Global definitions live in `~/.agents/agents/`; repository definitions live in `.agents/agents/` at the execution worktree root. Outside Git, the supplied directory is the project root. Bare repositories are unsupported execution directories. Nested repositories use the nearest Git worktree root. Symlink directories are not traversed during discovery.
+
+Definitions are trusted executable TypeScript. Loading a catalog evaluates its modules, so callers must trust the selected project and global definition files. Imports resolve relative to each definition through normal Node package resolution, with TypeScript loading supplied by the CLI. Missing imports, invalid exports, and duplicate names fail with the source filename. A session retains its loaded instructions, tools, and harness configuration for follow-ups; new sessions load current definition sources.
+
+An omitted `--cwd` uses the command's working directory. `--prompt-file` paths resolve against the calling command's directory, independently of `--cwd`; files use UTF-8. Prompts must contain non-whitespace text and cannot exceed 1 MiB. One quoted positional prompt, `--prompt`, and `--prompt-file` are mutually exclusive. `--prompt-file -` reads bounded UTF-8 stdin to EOF and rejects a terminal input stream. Direct harness targets accept `--model` and `--effort`; specialist targets reject those overrides.
+
+## Execution ownership
+
+An on-demand local coordinator owns sessions, queues, task relationships, and response records independently of individual CLI commands. It starts automatically; users do not install or manage a service. Each native session runs in a separate worker process whose working directory is the selected execution directory. Definition loading and custom tool execution in that worker use the same directory. Direct harness sessions carry a built-in target descriptor instead of a definition source reference and do not load TypeScript modules. They supply no specialist instructions, custom tools, or declared children; native instructions and project settings remain effective. Workers inherit the submitting environment, subject to the adapter's explicit authentication selection.
+
+The coordinator accepts local connections only. Its endpoint and access token are stored with owner-only permissions under `~/.agents/state/`. Task and session identifiers resolve through this coordinator from any working directory. Child invocation context is supplied privately by a session launcher that restores the coordinator location and parent context even when native shells change the inherited environment. Launchers use owner-only permissions, contain no provider credentials, and are removed when the session worker closes. Users do not supply parent identifiers or tokens in command flags. A context is accepted only while its parent task allows delegation.
+
+Closing a response-reading command does not cancel work. The coordinator retains responses and session records for its lifetime. A coordinator restart does not replay tasks or reconstruct queues; unavailable identifiers return an explicit error. Native harness history may still exist, but this version does not promise recovery of library sessions after coordinator or environment exit. Responses are not consumed by readers; each reader supplies its own position. Records are not silently evicted while the coordinator is running.
+
+## Task states and responses
+
+Task states are `queued`, `running`, `waiting`, `completed`, `failed`, `cancelled`, and `interrupted`. `waiting` means the library task remains active between native turns while delegated work or child-result processing is pending. A native permission request is not a completed response. Terminal outcomes are `completed`, `failed`, `cancelled`, and `interrupted`.
+
+Each complete native response has an opaque response identifier, text, and the task state at that response. `wait --after` returns the next retained response in order, including one that arrived before the command started. If none remains and the task is terminal, it returns the terminal outcome. Unknown response identifiers, including identifiers from another task, are errors. Multiple observers can independently read the same response.
+
+## Queue and recovery rules
+
+Each session admits task-creating requests in the order the coordinator receives them. It executes one native turn at a time. Normal task completion dispatches the next queued task. A task failure preserves and pauses the queue; a successful explicit `resume` of the failed task releases it only after that task completes. Native recovery that cannot continue the failed work without replay is reported as unsupported. Calling `resume` without a failed task is an error.
+
+Steering an actively generating native turn uses native steering when available; otherwise it follows the interrupt contract: cancel the active task and its descendants, then create a replacement task with the supplied message while preserving independently queued work. The output reports the effective delivery mode. Steering a `waiting` task starts a native continuation of that same task with the new input, leaving descendants running. With no active task, steering fails; callers can submit a queued task. Acceptance means the native integration accepted the input, not that the model has acted on it.
+
+Cancellation closes admission of new descendants, removes queued descendants, and requests native interruption for running descendants. `cancel` returns after affected executions have stopped. Repeating cancellation of a terminal task is a harmless status read. Interruption uses the same boundary before the replacement starts; independently queued tasks keep their order. A failed cancellation leaves dispatch paused and returns an error rather than claiming execution stopped. Concurrent interrupts are serialized in admission order.
+
+On parent execution failure, affected descendants are cancelled before reporting the settled failure. A failed or cancelled child is delivered to its parent as an outcome the parent can interpret; it does not automatically fail the parent. Parent continuation uses the existing native session and original task. Child results received while the parent is busy are retained until they can be delivered without interrupting its turn. Results available together may be delivered in one continuation, once each.
+
+When a child CLI command returns its terminal response to a still-running parent, that response already reaches the parent's native tool interaction. The coordinator marks it delivered and does not duplicate it in another turn. A child that finishes after its earlier pending response was returned requires explicit result delivery and continuation. The coordinator tracks delivery receipts, not the text's meaning.
+
+New follow-up tasks in a child session belong to the currently invoking parent task when invoked from an active managed parent. They do not remain attached to a completed task merely because the child session was originally created there. External follow-ups have no implicit parent. Cancellation affects recorded task lineage, not every task in a session.
+
+## Permissions and bounds
+
+Adapters preserve native permission restrictions. Declaring subagents authorizes their invocation: Claude Code receives session-only native allow rules for the exact launcher and documented delegation operations, combined with permissions for declared custom tools. This does not change the native permission mode, user/project settings, explicit deny or approval rules, managed policy, or sandbox. This version does not provide an interactive permission-answer CLI: a native approval or input request that still cannot be handled under that policy fails the task with `INPUT_REQUIRED` and actionable guidance. The permission callback never automatically approves the request. The caller can configure its harness and explicitly recover where supported.
+
+Ordinary text/JSON tool results and complete responses are limited to 1 MiB. Rich tool results have the image and aggregate limits defined in [custom tools](tools.md). Oversized results produce explicit errors rather than silent truncation. `status` includes at most 4,000 characters of the latest response and marks truncation; `status --full` retrieves the complete latest response and `wait` observes subsequent complete responses. Delegation depth is limited to 8, and each session admits at most 100 pending tasks. Exceeding a bound fails admission without dropping existing work. No automatic task-duration deadline is imposed.
+
+A managed task cannot delegate follow-up work into its own session or an ancestor's session. Such an admission returns `INVALID_PARENT` before changing any execution: that queued work would otherwise wait for the very task whose completion depends on it. Invalid delegation and replacement requests never cancel existing work.
+
+Coordinator startup recovers stale local startup locks whose recorded owner is absent or invalid. It never removes a lock owned by a live process and rechecks the file before removing it. An interrupted coordinator response is reported as unavailable without exposing native diagnostics or automatically repeating the request. Disconnecting an observer detaches that observation; it does not cancel execution.
+
+Catalog discovery evaluates TypeScript in a short-lived process with the selected execution directory as its working directory. Module stdout and stderr are not mixed into CLI output. Session workers retain their loaded instructions, tools, and harness configuration. New sessions, including delegated child sessions, load the current definition source; the library does not serialize or freeze arbitrary TypeScript closures across sessions.