subharness 0.0.3 → 0.0.5

package/sdk/additional-harnesses.md

@@ -0,0 +1,43 @@
+# Additional native harnesses
+
+OpenCode, GitHub Copilot, and Cursor are native harness targets. The SDK exports `opencode`, `copilot`, and `cursor`. Their configuration discriminators, personal access keys, and reserved CLI targets are respectively `opencode`, `copilot`, and `cursor`.
+
+```ts
+import { opencode, copilot, cursor } from "subharness";
+
+opencode({ model: "anthropic/claude-sonnet-5" });
+copilot({ model: "openai/gpt-6-astra" });
+cursor({ model: "CURSOR_MODEL_ID", sandboxMode: "enabled" });
+
+interface OpencodeOptions { readonly model: string }
+interface CopilotOptions { readonly model: string }
+interface OpencodeConfig extends OpencodeOptions { readonly kind: "opencode" }
+interface CopilotConfig extends CopilotOptions { readonly kind: "copilot" }
+```
+
+Constructors return immutable configurations. Models must be nonempty. These options deliberately expose only verified capabilities. `fast`, `effort`, unknown fields, and permission options for other harnesses are rejected. Cursor's additional sandbox option and native lifecycle are specified in [Cursor](cursor.md).
+
+All three direct CLI targets require an explicit `--model` and reject `--effort`. An omitted or unverifiable model fails with `INVALID_CONFIG` and guidance to supply `--model`, without a generation to discover it. SDK constructors always require the model. OpenCode and Copilot Gateway models use the Gateway's `creator/model` identifier; adapters translate native provider prefixes internally and never silently select a different model.
+
+## Access routes
+
+OpenCode and Copilot accept explicit native saved-login, direct API-key, and Vercel AI Gateway connections. Each route is selected independently; Gateway is optional. The provider selectors, credential variables, endpoint options, and route-specific model IDs are defined in [personal access](access-config.md), [OpenCode](opencode.md), and [Copilot](copilot.md). Cursor accepts native CLI `subscription` or Cursor SDK `api-key` access and does not support Gateway connections. Omitting any of the three access keys enables no connections. Empty arrays disable them. No ambient credential enables spending.
+```json
+{
+  "access": {
+    "opencode": [{ "type": "vercel-oidc", "project": ".", "envFile": ".env.local" }],
+    "copilot": [{ "type": "vercel-oidc", "project": ".", "envFile": ".env.local" }],
+    "cursor": [{ "type": "api-key", "env": "CURSOR_API_KEY" }]
+  }
+}
+```
+
+Existing credential reference, main-checkout path, OIDC identity/expiry, fallback, and credential redaction rules apply. Gateway API keys default to `AI_GATEWAY_API_KEY`, OIDC defaults to `VERCEL_OIDC_TOKEN`, and Cursor API keys default to `CURSOR_API_KEY`. Unsupported explicit connections fail before native startup, without choosing another billing route.
+
+## CLI and coordination
+
+The built-in catalog lists `codex`, `claude`, `fx`, `opencode`, `copilot`, and `cursor` in that order before specialists. Same-named specialists require a scope qualifier. Direct targets bypass catalog evaluation. These labels are accepted by the dashboard and execution records. Readiness checks use the same selection and cleanup path as runs and never submit a prompt.
+
+The existing queue, declared-child launcher, task/result, interruption, and fallback contracts apply. These adapters do not expose verified active steering or prompt-free recovery. Steering uses the coordinator's documented interrupt behavior; `resume` returns `RECOVERY_UNSUPPORTED`. Unsupported interactive input fails with `INPUT_REQUIRED` without automatically granting permission. An adapter reports interruption only after native execution has stopped and admitted custom tool callbacks have settled. Native processes and resources must be closed before readiness can succeed.
+
+The eval runner's named scenarios remain limited to the existing Codex, Claude Code, and fx matrix. Adding runtime harnesses does not implicitly add paid eval scenarios or native credentials.

package/sdk/agent-skill.md

@@ -1,6 +1,6 @@
 # Agent Skill
 
-The subharness agent skill teaches an existing coding agent when and how to delegate work with the subharness CLI. It is an ordinary Markdown skill that the native harness reads; it adds no runtime behavior, tools, or commands to subharness.
+The subharness agent skill teaches an existing coding agent when and how to delegate work with the subharness CLI. Its Markdown instructions add no runtime behavior, tools, or commands to subharness. A bundled standalone helper supports explicitly invoked local credential maintenance under [Personal access](access-config.md#agent-assisted-local-oidc-renewal).
 
 ## Installation
 
@@ -14,7 +14,7 @@ The installer reads the source repository, so installation requires access to [v
 
 ## Location and discovery
 
-The skill's single file is `skills/subharness/SKILL.md` at the repository root. Its frontmatter `name` is `subharness`, and its `description` states that the skill applies when the human asks the agent to delegate, parallelize, or hand off work to Codex, Claude Code, or fx, or to follow up on, check, or cancel delegated work.
+The skill's entry point is `skills/subharness/SKILL.md` at the repository root, with its credential helper in `skills/subharness/scripts/refresh-vercel-oidc.mjs`. Its frontmatter `name` is `subharness`, and its `description` states that the skill applies when the human asks the agent to delegate, parallelize, or hand off work to Codex, Claude Code, fx, OpenCode, GitHub Copilot, or Cursor, or to follow up on, check, or cancel delegated work.
 
 `npx skills add vercel-labs/subharness` offers only this skill. The repository's development skills under `.agents/skills/` set `metadata.internal: true` in their frontmatter, which the installer hides by default. That field does not change how native harnesses read those skills.
 
@@ -22,17 +22,20 @@ The skill is not part of the npm package. [Package Distribution](distribution.md
 
 ## Content
 
-The skill is concise, task-oriented guidance for the main agent. It agrees with the [CLI](cli/index.md), [Output](cli/output.md), [Message delivery](message-delivery.md), and [Sessions](sessions.md) references and introduces no commands, flags, defaults, or behavior they do not document. It covers:
+The skill is concise, task-oriented guidance for the main agent. It agrees with the [CLI](cli/index.md), [Output](cli/output.md), [Message delivery](message-delivery.md), and [Sessions](sessions.md), and [Responding to Native Permission Requests](approvals.md) references and introduces no commands, flags, defaults, or behavior they do not document. It covers:
 
 - When to delegate: independent, well-scoped work that can run while the conversation continues, and when the human names a harness.
-- Choosing a target: the reserved `claude`, `codex`, and `fx` direct targets, and `subharness list` for discovered specialists.
+- Choosing a target: the reserved `codex`, `claude`, `fx`, `opencode`, `copilot`, and `cursor` direct targets, and `subharness list` for discovered specialists.
 - Starting work with `subharness run <target> [--cwd <directory>] <prompt>`, `--prompt`, or `--prompt-file`, including quoting a positional prompt and giving the child explicit task context, because children do not receive the main conversation's transcript or loaded skills.
 - Preferring a single `subharness run <target> <prompt>` through the host's background-task controls when that capability is known to be available. The caller collects that hosted command's output later; a separate `--detach` and `wait` sequence is unnecessary for its first response.
 - Using `subharness run <target> --detach <prompt>` when background-command support is unavailable or uncertain, returning after admission and retaining the task identifier. `wait` returns or awaits the first response and runs only after useful independent work, when the caller is ready to wait. The minimal example contains only `run --detach` and `wait`; `status` is a separate optional nonblocking snapshot, not an unconditional step before or after `wait`.
 - Noting that background execution, process survival, and completion notifications depend on the host; detached admission alone does not provide them.
 - Reading results: the returned session, task, and response identifiers; `subharness wait <task-id>` for the first response; `subharness wait <task-id> --after <response-id>` for the next response; and `subharness status <task-id> --full` for the complete latest response.
+- Answering `approval_required` requests by inspecting the actual action, authorization scope, and request-specific schema. Examples cover an authorized single-use choice, an offered denial, and a grant selection with an explicit duration; examples never establish universal decision values. The caller uses `respond --content` or `--content-file`, then observes the original task with its existing response cursor. Acknowledging an answer does not imply task completion.
+- Distinguishing native denial from task cancellation, validating request ownership, correcting invalid content without replaying the task, and reporting expired requests or hard permission failures without broadening policy.
 - Following up with `subharness send <session-id>` and its `queue`, `steer`, and `interrupt` delivery modes; inspecting work with `subharness queue <session-id>`; and stopping it with `subharness cancel <task-id>`.
 - Reporting results back to the human in the main conversation, rather than relaying raw output.
+- Recovering an expired file-backed development OIDC credential through the lead agent's existing authenticated Vercel CLI for the established project, using the bundled helper without changing other settings, exposing credentials, or replaying submitted work.
 - Limits: subharness does not create worktrees or sandboxes, the caller supplies an existing working directory, native authentication stays with each harness, and records do not survive coordinator loss.
 
 `subharness --help` and `subharness run <harness> --help` remain the authoritative usage reference; the skill points the agent to them for options it does not cover.

package/sdk/agent.md

@@ -45,12 +45,14 @@ Children do not inherit loaded skill contents or the parent's transcript. Includ
 
 `codex(options)` and `claudeCode(options)` return configurations. Both require `model`, accept native `effort`, and accept `fast?: boolean`, defaulting to `false`. Options are typed independently to preserve each harness's capabilities. Codex effort values depend on the native model catalog; Claude effort accepts `low`, `medium`, `high`, `xhigh`, and `max`, subject to native model restrictions.
 
-`fx(options)` requires `model` and accepts optional native `effort`. It has no `fast` option. Its readonly configuration has `kind: "fx"`; see the [fx contract](fx.md) for Gateway access, native capabilities, and permission limits. `HarnessConfig` is the union of the native harness configurations, so narrowing by `kind` exposes the options supported by that harness.
+`fx(options)` requires `model` and accepts optional native `effort`. It has no `fast` option. Its readonly configuration has `kind: "fx"`; see the [fx contract](fx.md) for supported access routes, native capabilities, and permission limits. `HarnessConfig` is the union of the native harness configurations, so narrowing by `kind` exposes the options supported by that harness.
 
-The package exports `CodexOptions`, `ClaudeCodeOptions`, and `FxOptions` together with their readonly return types `CodexConfig`, `ClaudeCodeConfig`, and `FxConfig`. Runtime validation also enforces Claude's listed effort values when TypeScript checking is absent; unsupported values fail with `INVALID_DEFINITION` before native execution.
+`opencode(options)` and `copilot(options)` require only `model`. Their readonly configurations use `kind: "opencode"` and `kind: "copilot"`. `cursor(options)` requires `model` and accepts `sandboxMode?: "enabled" | "disabled"`; omission preserves Cursor's native default. These constructors reject `effort`, `fast`, and permission fields belonging to other harnesses. See [Additional native harnesses](additional-harnesses.md), [OpenCode](opencode.md), [Copilot](copilot.md), and [Cursor](cursor.md).
+
+The package exports the corresponding `Options` and readonly `Config` types for all six constructors. Runtime validation also enforces Claude's listed effort values and Cursor's sandbox values when TypeScript checking is absent; unsupported values fail with `INVALID_DEFINITION` before native execution.
 
 The `harness` property always uses that name, even for an array. Alternatives are considered in declaration order; an array does not mean parallel execution. [Personal access settings](access-config.md) determine which connections are eligible without editing a shared agent.
 
 ## Native permission options
 
-Harness constructors also accept the native permission options defined in [Native Permissions](permissions.md). Options are typed and validated independently for each harness. Omitted values preserve native settings; explicit values configure only the new native session and remain fixed for follow-ups. There is no permission profile registry.
+The Codex, Claude Code, and fx constructors also accept the native permission options defined in [Native Permissions](permissions.md). Options are typed and validated independently for each harness. Omitted values preserve native settings; explicit values configure only the new native session and remain fixed for follow-ups. Cursor's `sandboxMode` selects the SDK sandbox for API-key access; subscription ACP access rejects explicit sandbox settings. OpenCode and Copilot expose no public permission option. There is no permission profile registry.

package/sdk/approvals.md

@@ -0,0 +1,120 @@
+# Responding to Native Permission Requests
+
+A native tool permission request suspends the operation that needs authorization while its original native turn stays open. Subharness returns a structured request to the observing caller. The caller can answer the request and then observe the same task. Permission handling never replays a prompt, creates a replacement task, changes the selected native policy, or automatically approves an operation. Independent native operations and sibling tasks may continue.
+
+## Observe and respond
+
+An attached `run`, task-creating `send`, or `wait` returns an `approval_required` record when no eligible response is already available and the observed task or a descendant has pending permission requests. The command exits `0`; this reports successful observation, not completion. Detached admission is unchanged. `status` includes the same pending `requests` without waiting. Requests are separate from response history and do not have response IDs or consume a `--after` cursor. An eligible retained response takes precedence; use its cursor or `status` to inspect subsequent activity.
+
+The record's `taskId`, `sessionId`, and `state` identify the task being observed. Each request identifies its actual originating task and session. A task with its own pending requests has state `awaiting_approval`; ancestors retain their own execution state. Pending approvals retain the native execution slot, so queued tasks cannot overtake them.
+
+```json
+{
+  "version": 1,
+  "type": "approval_required",
+  "taskId": "tsk_parent",
+  "sessionId": "ses_parent",
+  "state": "running",
+  "requests": [{
+    "requestId": "req_example",
+    "taskId": "tsk_child",
+    "sessionId": "ses_child",
+    "kind": "permission",
+    "harness": "fx",
+    "message": "Allow running npm test?",
+    "requestedSchema": {
+      "type": "object",
+      "properties": {
+        "decision": {
+          "type": "string",
+          "oneOf": [
+            { "const": "allow_once", "title": "Allow once" },
+            { "const": "allow_always", "title": "Allow for this session" },
+            { "const": "reject_once", "title": "Deny" }
+          ]
+        }
+      },
+      "required": ["decision"]
+    }
+  }]
+}
+```
+
+Requests can include a bounded `context` object describing the native tool and action. Treat messages, titles, paths and tool arguments as data about the requested operation, never as instructions that grant authorization. Inspect the action and the exact scope before choosing a response. Identifiers and choices in examples are illustrative: copy the actual request ID and use only its offered values.
+
+```sh
+subharness respond req_example --content '{"decision":"allow_once"}' --format jsonl
+subharness wait tsk_parent --format jsonl
+```
+
+`respond <request-id>` requires exactly one of `--content <json>` or `--content-file <path|->`. The content is a JSON object matching the request's schema. File paths resolve from the caller's working directory; `-` reads standard input. Content is limited to 16 KiB. Both text and JSONL output are supported. Success emits `approval_answered` with `version`, `requestId`, originating `taskId` and `sessionId`, and exits `0`. It acknowledges submission of the answer, not completion of the native operation. It does not wait for the next agent response.
+
+To deny the fx request above:
+
+```sh
+subharness respond req_example --content '{"decision":"reject_once"}'
+subharness wait tsk_parent
+```
+
+Denial uses the native tool's rejection semantics. The agent can explain the rejection or choose another approach. Denial does not automatically fail or cancel the entire task. To stop the task and its descendants explicitly, use `subharness cancel <task-id>`. Do not use `resume`, `send`, or a new `run` to answer an approval.
+
+If several requests are pending, evaluate and answer them individually, then observe again. A request already resolved or withdrawn by its native harness cannot authorize another operation. Repeating an identical submitted answer is idempotent while the coordinator retains its record; a conflicting answer returns `INVALID_APPROVAL_RESPONSE`. Unknown IDs return `UNKNOWN_REQUEST`; withdrawn IDs return `REQUEST_EXPIRED`. Malformed, oversized, or schema-invalid answers return `INVALID_ARGUMENT` or `INVALID_APPROVAL_RESPONSE` with exit `2` and leave a valid pending request unanswered. Lifecycle/capability errors exit `1`. Validation errors never include the submitted content.
+
+## Request-specific schemas
+
+Adapters derive schemas from each native request and supported native restrictions. There is no universal approval menu. The response schema is a flat object whose fields use strings, booleans, finite numbers, single-choice string enums, or multiple-choice string arrays. Named choices use `oneOf` entries with `const` and `title`; multiple choices use string `items.enum` or `items.anyOf` entries. Required fields, bounds, and offered values are validated. Unknown fields, duplicate selections and unsupported schema constructs are rejected. No default value is submitted automatically.
+
+Codex command and file-change approvals expose their applicable native decisions, including once or session acceptance and denial. Advertised command decisions constrain the offered choices. Additional-permission requests can require both a selection of the requested grants and a native `turn` or `session` scope. Only a subset of the immutable requested permissions can be granted; arbitrary permission profiles cannot be submitted by the caller. Related native filesystem entries remain one selectable group, preserving their order, restrictions and scan bounds. Selecting individual entries must not accidentally remove a narrower restriction from an overlapping rule. Command-policy amendments that persist settings are outside this contract. An offered native `cancel` decision stops the native operation according to Codex semantics and can end the turn with an interruption error; it is distinct from denial and from the CLI task-cancellation command.
+
+Claude tool approvals expose allow-once and denial. Session-scoped reuse is offered only when the native callback supplies compatible suggestions and permits reusable approval. Suggested user/project/local setting updates are not persisted or silently converted into session grants. Tool input is retained unchanged. Native abort signals withdraw requests. `AskUserQuestion` and unrelated elicitation callbacks are not permission approvals.
+
+fx retains the actual ACP option identifiers and descriptive labels. In the supported fx integration, `allow_always` means the session, not a permanent grant. The adapter accepts only offered options and translates the selected ID to the original ACP response. Native cancellation remains distinct from a chosen denial.
+
+OpenCode exposes only its native once and rejection decisions for supported active permission requests. Copilot exposes only the specific offered approve-once and rejection decisions. Neither adapter exposes or invents a reusable grant. Their bounded action context and withdrawal behavior are defined in [OpenCode](opencode.md) and [Copilot](copilot.md). Cursor subscription sessions expose offered ACP allow-once and reject-once options, retaining native IDs and bounded tool context; persistent choices are excluded. Its API-key SDK route has no interactive approval bridge. Other Cursor interactive requests fail with `INPUT_REQUIRED` as defined in [Cursor](cursor.md).
+
+Requests which cannot be represented faithfully, unsupported interactive input, and startup-time interactions fail explicitly with `INPUT_REQUIRED`. Policies such as `never` or `dontAsk` may suppress native requests entirely; hard sandbox denials cannot be approved through this mechanism. Omitted native settings remain unchanged.
+
+These answer objects illustrate different schemas; submit one only when its fields and values are offered by the actual request:
+
+| Request | Example content | Meaning |
+| --- | --- | --- |
+| Codex command | `{"decision":"accept"}` | Allow the offered operation once |
+| Codex command | `{"decision":"decline"}` | Deny the offered operation |
+| Codex additional permissions | `{"grants":["network"],"scope":"turn"}` | Grant the offered network permission for this turn |
+| Codex additional permissions | `{"grants":[],"scope":"turn"}` | Grant none of the requested additional permissions |
+| Claude tool | `{"decision":"allow_once"}` | Allow this tool call with its original input |
+| Claude tool | `{"decision":"deny"}` | Reject this tool call |
+| fx tool | `{"decision":"reject_once"}` | Select this native option ID when it is offered as denial |
+
+## Ownership and lifetime
+
+The external coordinator caller can answer requests it owns through the local coordinator connection. A managed agent can answer only requests from its currently active task's strict descendants. It cannot approve its own operation, an ancestor, a sibling, or an unrelated task. Violations return `INVALID_APPROVAL_OWNER`. Descendant requests are visible structurally from ancestor observations, including multiple delegation levels, so approval does not depend on a child finishing its response first.
+
+These checks enforce the managed caller protocol, not a security boundary against arbitrary same-user code accessing private coordinator files. Existing local coordinator authentication and filesystem trust assumptions remain applicable.
+
+The coordinator retains the most recent 1,024 answered or withdrawn request records, ordered by settlement. Pending requests are never evicted by this limit. Settled records retain only their identity, outcome, and submitted answer when applicable; the action context, message, and schema are released. Identical-answer acknowledgement and `REQUEST_EXPIRED` are available while that record is retained. An older evicted ID returns `UNKNOWN_REQUEST` and cannot authorize an operation. Repeating an answer does not extend retention.
+
+There is no automatic approval or timeout grant. An unanswered request remains pending while its native operation and coordinator are alive. Native withdrawal, turn completion, interruption, cancellation, worker loss and coordinator shutdown retire outstanding requests and release waiting callbacks. A reply racing with withdrawal must not produce a late allow. Records and continuations do not survive coordinator loss; recovery does not replay the operation. A task accepts at most 32 simultaneous requests, and each serialized request is limited to 64 KiB; an unrepresentable or oversized native request fails explicitly instead of dropping action context silently.
+
+## Internal adapter boundary
+
+These signatures describe an internal implementation boundary, not new package exports or a public programmatic runner:
+
+```ts
+type ApprovalContent = Record<string, string | number | boolean | string[]>;
+interface NativeApprovalRequest {
+  kind: "permission";
+  harness: "codex" | "claudeCode" | "fx" | "opencode" | "copilot" | "cursor";
+  message: string;
+  requestedSchema: ApprovalSchema;
+  context?: Record<string, unknown>;
+}
+type ApprovalHandler = (
+  request: NativeApprovalRequest,
+  signal: AbortSignal,
+) => Promise<ApprovalContent>;
+```
+
+`src/approvals/types.ts` owns these shared types and `ApprovalSchema`. `AdapterOptions.onApproval?: ApprovalHandler` supplies the native handler; absence retains explicit `INPUT_REQUIRED` behavior for direct internal adapter callers. `DriverInput.onApproval?: ApprovalHandler` connects the coordinator factory to its worker; it is not serialized in session input. A worker forwards requests and withdrawals as independent IPC events and receives answers through independent controls while its `turn` RPC remains pending. Adapter signals bind continuations to the actual native request lifetime. Schema validation lives in `src/approvals/schema.ts` and exports `validateApprovalContent(schema, content): ApprovalContent`, throwing a safe `INVALID_APPROVAL_RESPONSE` on invalid content.
+
+The coordinator assigns `req_` IDs, stores the immutable schema and native continuation, and validates ownership and content before resolving it. The worker and adapter also validate at their boundaries. Shutdown and interruption retire pending approval promises before waiting for native cleanup. This prevents an unanswered request from blocking cleanup or subsequent session work.

package/sdk/authentication.md

@@ -2,7 +2,7 @@
 
 Login belongs to the selected native harness or access provider. The library selects compatible access at startup and does not create a separate subscription account or transfer subscription tokens between harnesses.
 
-Without personal settings, the library discovers eligible native subscription access for the agent's declared harness alternatives. An API credential in the environment does not enable API billing. If the integration cannot establish that a native login uses subscription access, it reports that access is unavailable instead of assuming OAuth implies a subscription.
+Without personal settings, Codex and Claude Code retain native subscription discovery. Other harnesses require an explicit connection. An API credential in the environment does not enable API billing. Saved-login routes verify the native credential source according to each adapter contract; they do not infer plan eligibility, free usage, or a spending cap from OAuth alone. The fx saved Vercel login is a native-login route that still bills AI Gateway.
 
 Users can mix subscription, direct API, Gateway API-key, and Gateway OIDC access in one project. Preferences belong to the user, separately from versioned agent definitions. Two contributors can run the same definition through different declared harness alternatives and compatible connections.
 

package/sdk/cli/dashboard-design.md

@@ -29,12 +29,52 @@ A session captures its checkout context when admitted. Git subdirectories resolv
 
 Labels use repository and checkout directory names, not branch names. Ambiguous short labels include a distinguishing parent path. All labels and task titles are sanitized before terminal output.
 
-Each task records its latest coordinator-observed update: admission, dispatch or continuation, a selected-harness change, accepted steering, a complete native response, or a settled lifecycle outcome. Token streaming and internal tool activity are not observed by this display. Snapshot reads, response reads, and cancelling an already settled task do not advance recency. A queued follow-up that has no displayed row does not affect group ordering until displayed. Equal group update times preserve the group's first-observed order in the open dashboard.
+Each task records its latest coordinator-observed update: admission, dispatch or continuation, a selected-harness change, accepted steering, creation or retirement of a native permission request, a complete native response, or a settled lifecycle outcome. Token streaming and internal tool activity are not observed by this display. Snapshot reads, response reads, and cancelling an already settled task do not advance recency. A queued follow-up that has no displayed row does not affect group ordering until displayed. Equal group update times preserve the group's first-observed order in the open dashboard.
 
 ## Row presentation
 
-Each group label is followed by two-space-indented rows. Blank lines separate groups. Rows use aligned marker, harness, title, state, and elapsed-duration columns with whitespace rather than dashed leaders. Running uses `●`, queued and waiting use `◌`, failed and interrupted use `!`, and completed and cancelled use a blank marker. State text always accompanies the marker. There are no animated indicators or color requirements.
+Group labels use secondary repository text and a bold checkout name. One blank line separates a group label from its rows and one separates groups. Rows use aligned selection marker, lifecycle marker, title, harness, state and elapsed-duration columns. The title is the primary reading target; harnesses and times use secondary styling. Running uses `●`, queued, waiting and awaiting_approval use `◌`, failed and interrupted use `!`, and completed and cancelled use a blank marker. State text always accompanies the marker. There are no animated indicators.
 
-Elapsed durations retain the CLI's `MM:SS` and `H:MM:SS` notation. Terminal rows also show whole-minute completion age (`<1m ago` initially, then `1m ago`, etc.). Completion age is omitted in narrow terminals before reducing the title; titles truncate by grapheme display width, and remaining fixed fields clip only when they cannot fit. Group labels use the same width and terminal-control protections. The interface has no application banner, column headings, footer, selection, scrolling, or additional controls. Viewport clipping applies to the resulting grouped lines. Current rows precede history within each group, but no global active-first ordering overrides checkout pinning or group recency.
+The selected row has a leading `›`, a bold title and a subtle full-row background. Running states use cyan, completed states use green, failed states use red, and interrupted states use yellow. Waiting, queued, awaiting_approval and cancelled states use neutral secondary styling. Completed titles may use secondary styling, but their state remains green. These rules apply to overview rows, request history and sub-agents. Styling uses the terminal's ANSI palette; a nonempty `NO_COLOR` disables color, backgrounds and emphasis while preserving spacing, markers, rules and explicit state words. Application-generated styling is added only after untrusted content is sanitized and measured.
 
-The private snapshot declares grouped-context support in addition to finished-history support. A dashboard connected to a coordinator without either capability reports `COORDINATOR_OUTDATED` with restart guidance rather than silently omitting grouping or history. The legacy `INVALID_ARGUMENT` response for an unknown coordinator operation also identifies a coordinator without dashboard support and receives the same diagnostic. Other error records and malformed responses remain `COORDINATOR_UNAVAILABLE`. It never restarts the coordinator itself.
+Elapsed durations retain `MM:SS` and `H:MM:SS` notation. Finished overview rows show whole-minute completion age (`<1m ago`, `1m ago`, etc.) when space permits. Completion age is omitted before reducing title width. Titles truncate by grapheme display width; fixed fields clip only when they cannot fit. Group labels receive the same width and terminal-control protections. The overview has no application banner, column headings, footer or key hints. Current rows precede history within each group, without overriding checkout pinning or group recency.
+
+## Overview navigation
+
+The first displayed task is selected initially. Up and Down move through task rows, skip group labels and blank lines, and stop at the ends. Selection follows task identity across updates and transitions to history. Scrolling keeps selection visible. If a task disappears, select the nearest remaining task by its previous position. An empty list has no selection.
+
+Enter opens the selected task's agent-session history, initially selecting that exact request. Escape returns to the overview with the original task selection and scroll context preserved where possible. Ctrl+C exits without cancelling work. Unrecognized keys are ignored. Split escape sequences are supported, with a short bounded delay distinguishing standalone Escape from an arrow prefix. Exit and error handling restore input modes, screen and cursor.
+
+## Agent request history
+
+An agent session is the persistent conversation that can receive multiple work requests. Its history contains every retained admitted task in that session, including pending follow-ups. It is not derived from the pending queue alone. Accepted steering that continues an existing task does not create a separate independently statused request. History lasts for the coordinator process lifetime.
+
+The compact fixed header contains the repository/worktree label, the session's original request title and a harness/state line. Its title is the same sanitized 120-code-point first-line title used by task rows and is clipped to one line. Session state is the active request's state when one exists, otherwise the next queued request's state, otherwise the most recently admitted request's state. A thin rule separates identity from the body. Terminals shorter than eight rows reduce the header to one clipped identity line; a one-row terminal prioritizes the selected request.
+
+The body begins with `Requests`. A paused session queue is explicitly labelled beside it. Queued requests are first, newest admitted first; remaining requests follow newest admitted first. The original one-based admission ordinal is stable and displayed even though rows are reversed. State updates do not otherwise reorder requests. Each row shows ordinal, title, explicit state and execution duration; an undispatched request shows `—` for duration. An unconfirmed stop is explicitly labelled on its request. Selection tracks task identity through reordering and refreshes.
+
+Up/Down selects the previous/next request and collapses any expanded content when selection changes. Enter toggles the selected request's inline details. Only one request can be expanded. Its indented content contains an error first when present, `Request` with the original prompt, and `Response` with its latest complete response or `No response yet`. Unconfirmed cancellation is explicitly identified. Enter collapses the request again; Escape always returns to the overview.
+
+With no expansion, PageUp/PageDown move selection by the visible body height, and Home/End select the first/last request. With expansion, PageUp/PageDown scroll the body and Home/End scroll to the start/end of the expanded request's content. The header and footer remain fixed. Response updates preserve the reading offset; explicit End enables following the expanded content's end until the user scrolls away or changes selection. Selecting a request scrolls its row into view. Narrow and short terminals retain at least one body row.
+
+Expanded prose wraps at up to 100 terminal cells, preferring whitespace boundaries and preserving original indentation and line breaks. Long unbroken text wraps by grapheme display width. All content and errors are sanitized before display; native terminal control sequences are never executed. The screen does not show a native transcript, tool stream, model reasoning, usage/cost report or file attribution. Quiet work is not labelled stalled, waiting does not imply human intervention, and completion does not claim independent verification of success.
+
+## Sub-agents footer
+
+A distinct bottom region named `Sub-agents` shows the total number of direct managed child sessions of this agent session. Children from all of its retained requests are included, deduplicated by child session. Each child uses its original session title and harness, and its representative request's state: active first, otherwise next queued, otherwise latest admitted. Descendants of those children are not included. Ordering follows first delegation admission.
+
+The footer is a read-only summary, independent of request selection. It uses at most one third of the terminal height and previews at most three child sessions with title, harness and state. If some children do not fit, a visible `… N more` count discloses the remainder. When only a compact footer fits, its label and total count remain visible without preview rows. Terminals shorter than eight rows omit the footer region and include the sub-agent count in the compact identity line. Empty child sets omit the footer. The footer never displaces the last available request body row.
+
+## Refresh and compatibility
+
+The overview remains a small snapshot. An open history requests only metadata for that session; full prompt/response content is fetched only for the expanded request. Polling is serialized, with each read bounded by a five-second timeout. Changing view or expanded request aborts obsolete reads and ignores late results. Prompt and response text are cached only for the current expansion, and unchanged content is not retransmitted. Wrapping is reused while text and width remain unchanged. Rendering retains bounded pending state under output backpressure and does not redraw unchanged lines.
+
+Inspection never sends prompts, steers, cancels, resumes or acknowledges work, starts execution, or restarts the coordinator. The private transport is defined in [Inspection transport](dashboard-inspection.md).
+
+Snapshots require finished-history and grouped-context capabilities. A missing capability or the exact legacy unknown-operation response reports `COORDINATOR_OUTDATED` with restart guidance. Opening history against a coordinator without the history operation reports the same error rather than presenting incomplete history. Other malformed or failed reads report `COORDINATOR_UNAVAILABLE` after terminal cleanup. Restarting a coordinator discards retained history and is never performed automatically.
+
+## Shared presentation boundary
+
+The terminal command and website demonstration reuse the internal ANSI renderer, layout, history/detail formatting, text sanitization, input decoding and key-action dispatch. Presentation code accepts explicit dimensions, data and time; it does not discover workspaces, access credentials, read files or contact the coordinator. This boundary adds no public SDK method. The terminal command preserves its existing process lifecycle, serialized reads and backpressure behavior. The website supplies fictional read-only projections and owns its browser terminal lifecycle.
+
+The internal `dispatchDashboardKey(renderer, key)` function in `src/cli/dashboard-controller.ts` applies a `DashboardKey` to a `DashboardRenderer` and returns `{ interrupt: boolean; refreshInspection: boolean }`. Interrupt requests process exit only in the CLI host; the browser host instead releases focus. `refreshInspection` is true when a successful open, toggle, leave or selected-request change invalidates the previous inspection read, including collapsing an expanded request by changing selection. Hosts cancel obsolete reads or load their local sample projection after that signal. Overview movement and scrolling an unchanged expansion do not request new detail reads. The dispatcher never fetches data or schedules timers.

package/sdk/cli/dashboard-inspection.md

@@ -0,0 +1,25 @@
+# Private dashboard inspection transport
+
+This authenticated coordinator operation serves the read-only terminal inspector. It is internal, not a public SDK execution method. The general snapshot remains small and unchanged.
+
+The POST request is `{command: "dashboard-detail", id: string, includePrompt?: boolean, knownResponseId?: string}`. `id` identifies a retained task. `includePrompt` defaults to true; false omits the original prompt. `knownResponseId` optionally identifies a response already cached by this client. Unknown tasks return `UNKNOWN_TASK`; invalid field types return `INVALID_ARGUMENT`.
+
+The response is `DashboardDetail`: `{version: 1, type: "dashboard-detail", task: DashboardRow, prompt?: string, response?: {responseId: string, text?: string}, error?: {code: string, message: string}, children: DashboardRelatedTask[], queue: {paused: boolean, tasks: DashboardRelatedTask[]}, stopUnconfirmed: boolean}`. `DashboardRow` is the same task projection used by the list. `DashboardRelatedTask` is `{taskId: string, sessionId: string, harness: DashboardHarness, title: string, state: TaskState}`. Related titles use the same 120 Unicode code-point bound as list titles. Children are direct managed children in admission order; queue tasks are pending follow-ups in dispatch order. Queue context is the session's current queue even when inspecting an older task; it does not imply those queued tasks belong to the historical task.
+
+The latest complete response is present only when one exists. Its `text` is omitted exactly when its identifier equals `knownResponseId`; otherwise full text is returned. An absent response means no response exists, not unchanged content. Prompt is the full original admitted prompt and is included unless `includePrompt` is false. The inspector derives an untruncated first-line title from that cached prompt. Error and stop confirmation are task-scoped. The error code and message are the same retained task error exposed by `status`; the inspector does not add native stderr or diagnostic logs. The response excludes native/internal tokens, environment, loaded definitions and access settings.
+
+The client fetches full content when a request is expanded, retains it only for that expansion, and refreshes it with `includePrompt: false` and the cached response identifier. A changed response replaces the cached latest response. Each full prompt and response is already bounded by task admission and native response limits; there is no unbounded transcript transfer. Reads do not acknowledge descendant results, alter timestamps, start execution, or mutate queues. Snapshot/context assembly must remain coherent across asynchronous workspace resolution.
+
+The client validates identity, structure, lifecycle state, workspace paths, timestamps, error and content omission semantics before displaying a record. A malformed, failed or timed-out read exits with `COORDINATOR_UNAVAILABLE` after terminal cleanup. The exact legacy unknown-operation response for this operation reports `COORDINATOR_OUTDATED` with restart guidance. A coordinator that supports the existing overview but lacks inspection can show its list until Enter requests inspection. It is never restarted automatically.
+
+## Agent-session history transport
+
+The authenticated POST request is `{command: "dashboard-session", id: string}`. The identifier is a retained task whose session is to be inspected; this keeps overview selection unambiguous. Unknown tasks return `UNKNOWN_TASK`. Missing or non-string identifiers return `INVALID_ARGUMENT`. This read-only operation does not launch a coordinator or execution.
+
+The response is `DashboardSession`: `{version: 1, type: "dashboard-session", taskId: string, sessionId: string, title: string, harness: DashboardHarness, state: TaskState, workspace: DashboardWorkspace, requests: DashboardRequest[], subagents: DashboardRelatedTask[], queuePaused: boolean}`. `taskId` echoes the requested anchor task. `title` is the original session prompt's sanitized, at-most-120-code-point title. `DashboardRequest` extends `DashboardRow` with `{ordinal: number, stopUnconfirmed: boolean}`. Ordinals are positive one-based admission order within the session and remain stable. The projection contains all retained requests in that session, including queued requests, ordered queued first and newest admission first within each partition. Every row's session identity and workspace match the containing session. The anchor request must be present.
+
+Sub-agents are direct managed child sessions referenced by any retained task in this session, deduplicated and ordered by first child admission. Each `DashboardRelatedTask` identifies a representative task and its session, uses the original child session title, and exposes its harness and state. The representative task is the session's active task when present, otherwise its next queued task, otherwise its latest admitted task. The same representative rule determines the containing session's state. Unrelated sessions and grandchildren are excluded.
+
+The projection is coherent across asynchronous workspace discovery and does not mutate recency, acknowledge responses or transfer full prompts/responses, credentials, environment or native transcript content. The client validates identity, unique task IDs and ordinals, exact request ordering, lifecycle fields, related session uniqueness and bounded titles before rendering. The exact legacy unknown-operation error maps to `COORDINATOR_OUTDATED`; malformed records, other errors, failed HTTP responses and timeouts map to `COORDINATOR_UNAVAILABLE`.
+
+The existing `dashboard-detail` operation remains task-scoped and supplies content only for an expanded history request. Its prompt and response omission rules remain unchanged. The dashboard does not render that operation's legacy child and queue sections because the history projection supplies the session-wide footer and queued request rows.

package/sdk/cli/index.md

@@ -17,6 +17,8 @@ subharness send <session-id> [--delivery queue|steer|interrupt] [--detach] --pro
 subharness send <session-id> [--delivery queue|steer|interrupt] [--detach] --prompt-file <path|->
 subharness wait <task-id> [--after <response-id>]
 subharness status <task-id> [--full]
+subharness respond <request-id> --content <json>
+subharness respond <request-id> --content-file <path|->
 subharness queue <session-id>
 subharness cancel <task-id>
 subharness resume <session-id>
@@ -24,7 +26,7 @@ subharness resume <session-id>
 
 Execution commands accept `--format text|jsonl`; text is the default. `--help` and `--version` are plain-text information modes without a `--format` option. `subharness --help` and `<command> --help` show usage without requiring execution arguments or starting execution. Direct harness help includes that harness’s options; other command help shows the general usage. [Output records and exit codes](output.md) define the integration format.
 
-`list` includes the built-in harness targets and discovered definitions without starting harnesses or calling models. Inclusion is not a claim that an executable, eligible account, or particular model is available. Definition loading retains its existing validation and trust requirements. `check` performs the selected target's native startup checks in an isolated worker, closes the temporary native session, confirms that the worker and adapter-owned native processes have stopped, and returns without submitting a turn or admitting a task. Cleanup or unconfirmed termination is a failed check, not a readiness result. `run` starts a new session and its first task, immediately prints their identities, and waits for one complete response or terminal outcome. It returns control even if that task still has delegated work. The result contains a response identifier and task state.
+`list` includes the built-in harness targets and discovered definitions without starting harnesses or calling models. Inclusion is not a claim that an executable, eligible account, or particular model is available. Definition loading retains its existing validation and trust requirements. `check` performs the selected target's native startup checks in an isolated worker, closes the temporary native session, confirms that the worker and adapter-owned native processes have stopped, and returns without submitting a turn or admitting a task. Cleanup or unconfirmed termination is a failed check, not a readiness result. `run` starts a new session and its first task, immediately prints their identities, and waits for one complete response, pending permission request, or terminal outcome. It returns control even if that task still has delegated work. A response contains a response identifier and task state; an approval observation contains request identifiers and schemas.
 
 Readiness means only that startup checks for the selected target passed at that moment. It does not guarantee remote quota, task success, shell or child-launch permissions, or continued availability, and it does not check declared descendants. A check may create an empty native conversation and temporary native or launcher files. Loading existing personal access settings can also update Git's local exclude file as described in [personal access configuration](../access-config.md).
 
@@ -34,9 +36,9 @@ Readiness means only that startup checks for the selected target passed at that
 
 `subharness dashboard` opens a read-only live terminal display for the current local coordinator, covering all of its managed directories, with the calling checkout pinned first when it has displayed runs. It includes direct harness sessions, specialists, and delegated agents managed by that coordinator. It does not discover unmanaged native processes or coordinators belonging to other installations or state directories.
 
-The list groups runs by repository/worktree, following the context and ordering rules in [Dashboard presentation](dashboard-design.md). Within each group, it shows current work followed by finished runs. Current work has one row per session in session creation order, representing its active task or its first queued task when dispatch has not started. Running and waiting tasks remain visible. A failed active task remains among current work while it pauses the session, including when native stop is unconfirmed. Independently queued follow-ups do not create additional current-work rows.
+The list groups runs by repository/worktree, following the context and ordering rules in [Dashboard presentation](dashboard-design.md). Within each group, it shows current work followed by finished runs. Current work has one row per session in session creation order, representing its active task or its first queued task when dispatch has not started. Running, waiting, and awaiting-approval tasks remain visible. A failed active task remains among current work while it pauses the session, including when native stop is unconfirmed. Independently queued follow-ups do not create additional current-work rows.
 
-Finished runs have one row per retained completed, failed, cancelled, or interrupted task that is not already shown among current work. They appear newest finished first, with later task admission first when finish times are equal. Follow-up tasks keep their own history rows instead of replacing previous results from the same session. Finished runs appear even when they ended before the dashboard opened. History lasts for the coordinator’s lifetime; restarting the coordinator does not restore earlier runs. Compact repository/worktree labels identify each group; there are no additional controls.
+Finished runs have one row per retained completed, failed, cancelled, or interrupted task that is not already shown among current work. They appear newest finished first, with later task admission first when finish times are equal. Follow-up tasks keep their own history rows instead of replacing previous results from the same session. Finished runs appear even when they ended before the dashboard opened. History lasts for the coordinator’s lifetime; restarting the coordinator does not restore earlier runs. Compact repository/worktree labels identify each group. Up/Down select a task and Enter opens its agent-session request history.
 
 ```text
 subharness / trenton
@@ -44,11 +46,11 @@ subharness / trenton
   ◌ claude  Review the current diff     waiting    00:38
 ```
 
-The harness label is `codex`, `claude`, or `fx`. A direct target is known during startup; a specialist displays `pending` until its actual native harness is selected. Selection reports the successfully opened harness, including fallback selection. The title is the first nonempty line of the current task's original prompt, with whitespace normalized and terminal control sequences removed, bounded to 120 Unicode code points before fitting it to the display. An empty sanitized title is `(untitled)`. No model call generates titles. Steering retains the task title; a follow-up uses its own prompt.
+The harness label is `codex`, `claude`, `fx`, `opencode`, `copilot`, or `cursor`. A direct target is known during startup; a specialist displays `pending` until its actual native harness is selected. Selection reports the successfully opened harness, including fallback selection. The title is the first nonempty line of the current task's original prompt, with whitespace normalized and terminal control sequences removed, bounded to 120 Unicode code points before fitting it to the display. An empty sanitized title is `(untitled)`. No model call generates titles. Steering retains the task title; a follow-up uses its own prompt.
 
 Time is elapsed wall time since that task first dispatched, including waiting and recovery. A queued task shows `00:00`. Completed, cancelled, and interrupted tasks freeze their elapsed time when that outcome is reached. Failed tasks freeze their elapsed time at failure and resume counting from the original start if explicitly recovered. Tasks cancelled before first dispatch show `00:00`. Repeated observation or cancellation that leaves a settled terminal outcome unchanged does not change its recorded finish time. If stopping previously unconfirmed execution reaches a new outcome, timing records that new outcome. Durations use `MM:SS` below one hour and `H:MM:SS` thereafter. State and elapsed time occupy separate aligned columns. Finished rows include completion age when space permits, as defined in [Dashboard presentation](dashboard-design.md). Narrow terminals truncate titles by display width without splitting grapheme clusters; when the fixed fields alone do not fit, the row is clipped to the available columns.
 
-The display contains compact group labels and agent rows: no application heading, border, footer, spinner, key hints, or empty-state message. It uses the alternate screen and restores the normal screen and cursor on exit. When stdin is a terminal, keyboard echo is suppressed and input other than Ctrl+C is ignored; the previous input mode is restored on exit. Non-terminal stdin is not consumed. Rows fit within the terminal viewport without wrapping or scrolling; excess rows remain outside the visible viewport until the terminal is enlarged or changes in row order bring them into view. Current work takes precedence over finished history within each group; group order determines which groups fit in the visible viewport. There is no navigation, selection, or task control. Ctrl+C exits with code `130`; SIGTERM exits with code `143`. Exiting never cancels agents.
+The overview contains compact group labels and agent rows: no application heading, border, footer, spinner, key hints, or empty-state message. A leading `›` identifies the selected task. It uses the alternate screen and restores the normal screen and cursor on exit. When stdin is a terminal, keyboard echo is suppressed and Up/Down, Enter, Escape and inspector scrolling keys are handled; the previous input mode is restored on exit. Non-terminal stdin is not consumed. Overview rows do not wrap; selection scrolls the list to reach runs outside the viewport. Current work takes precedence over finished history within each group. Enter opens the selected task's agent-session history with queued requests first and remaining requests newest first. Up/Down select requests; Enter toggles inline prompt/response details. A compact Sub-agents footer summarizes direct child sessions. Completed states are green when color is enabled. Escape returns to the list. The detailed navigation and presentation rules are defined in [Dashboard presentation](dashboard-design.md#agent-request-history). All interaction is read-only. Ctrl+C exits with code `130`; SIGTERM exits with code `143`. Exiting never cancels agents.
 
 Snapshots refresh once per second without overlapping requests. Resizing redraws the current snapshot immediately. Unchanged visible rows are not rewritten. Rendering uses native Node streams and terminal escape sequences, with a focused Unicode width utility rather than a UI framework. Slow output does not accumulate unbounded redraws.
 
@@ -56,29 +58,32 @@ The command requires terminal stdout and a terminal supporting cursor control; n
 
 ## Direct harnesses and specialists
 
-`codex`, `claude`, and `fx` are reserved, case-sensitive target names for direct harness execution. `claude` selects the Claude Code adapter, whose SDK and access configuration key remains `claudeCode`. Direct execution needs an installed native harness and eligible access, but no TypeScript definition, project-local SDK import, or agent catalog evaluation. An invalid specialist file does not block a direct harness run.
+`codex`, `claude`, `fx`, `opencode`, `copilot`, and `cursor` are reserved, case-sensitive target names for direct harness execution. `claude` selects the Claude Code adapter, whose SDK and access configuration key remains `claudeCode`. Direct execution needs its native runtime and eligible access, but no TypeScript definition, project-local SDK import, or agent catalog evaluation. An invalid specialist file does not block a direct harness run.
 
 ```sh
 subharness run claude "Review the current diff."
 subharness run codex --cwd ../feature-worktree "Implement the documented validation."
 subharness run fx --model "provider/model" "Compare the proposed implementations."
+subharness run opencode --model "creator/model" "Inspect the current implementation."
+subharness run copilot --model "creator/model" "Review the current diff."
+subharness run cursor --model "CURSOR_MODEL_ID" "Implement the documented change."
 subharness run repo:reviewer "Review the current diff."
 subharness check repo:reviewer --format jsonl
 ```
 
-Replace `provider/model` with an available Gateway model identifier. Nonreserved bare names retain the existing unambiguous specialist lookup. Qualified `repo:`, `global:`, and `subagent:` names retain their existing meanings. A specialist named `claude`, `codex`, or `fx` requires its scope qualifier; it never shadows the built-in target. Unknown targets fail rather than being executed as arbitrary commands. Omitting the target is an argument error; the CLI never chooses the first installed harness.
+Replace `provider/model` or `creator/model` with an available Gateway model identifier. Nonreserved bare names retain the existing unambiguous specialist lookup. Qualified `repo:`, `global:`, and `subagent:` names retain their existing meanings. A specialist named for any reserved harness target requires its scope qualifier; it never shadows the built-in target. Unknown targets fail rather than being executed as arbitrary commands. Omitting the target is an argument error; the CLI never chooses the first installed harness.
 
 Direct harness sessions use native instructions and project context without adding a specialist role, custom tools, or declared children. They preserve the existing authentication, native permission, queue, cancellation, follow-up, and response contracts. They do not broaden the caller's native permissions or automatically authorize additional delegation.
 
-`--model` and `--effort` configure direct harness targets only for `run` and `check`, and can be combined with `--cwd` and, for `run`, any supported prompt source. Empty values are errors. Specialist targets reject these overrides and retain their declared harness configurations. `send` retains the session configuration and does not accept model or effort overrides.
+`--model` configures direct harness targets only for `run` and `check`, and can be combined with `--cwd` and, for `run`, any supported prompt source. `--effort` is additionally available for Codex, Claude Code, and fx. Empty values are errors. Specialist targets reject these overrides and retain their declared harness configurations. `send` retains the session configuration and does not accept model or effort overrides.
 
-Omitting `--model` requests the native default for the authorized access route at session creation. The adapter retains the selected model for that conversation. It does not inherit the calling agent's model, rank models, choose a substitute, or change billing routes. An unavailable or unverifiable native default fails with actionable guidance to supply `--model`; it does not submit a prompt merely to discover a default. Explicit model identifiers retain native validation and substitution checks. TypeScript harness constructors continue to require a model.
+For Codex, Claude Code, and fx, omitting `--model` requests the native default for the authorized access route at session creation. OpenCode, Copilot, and Cursor require an explicit `--model`; omission fails with `INVALID_CONFIG` and guidance before native startup. The adapter retains the selected model for that conversation. It does not inherit the calling agent's model, rank models, choose a substitute, or change billing routes. An unavailable or unverifiable native default fails with actionable guidance to supply `--model`; it does not submit a prompt merely to discover a default. Explicit model identifiers retain native validation and substitution checks. TypeScript harness constructors continue to require a model.
 
-Effort is harness-specific: Codex and fx accept native effort identifiers, while Claude Code accepts `low`, `medium`, `high`, `xhigh`, or `max`. Explicit effort must be compatible with the selected model where native capabilities expose that validation. An omitted effort retains the native default at session creation. Detected changes to an explicit request are errors. Codex and Claude Code retain standard-speed execution; this interface adds no fast-mode flag. fx retains its documented native preference and Gateway access contract.
+Effort is harness-specific: Codex and fx accept native effort identifiers, while Claude Code accepts `low`, `medium`, `high`, `xhigh`, or `max`. OpenCode, Copilot, and Cursor reject `--effort`. Explicit effort must be compatible with the selected model where native capabilities expose that validation. An omitted effort retains the native default at session creation. Detected changes to an explicit request are errors. Codex and Claude Code retain standard-speed execution; this interface adds no fast-mode flag. fx retains its documented native preference and Gateway access contract.
 
 Direct-harness help for `run` and `check` describes the relevant options and access requirements without loading definitions, starting a coordinator, or invoking a harness. Native CLI flags are not forwarded. Unsupported flags are errors.
 
-`wait` observes the first retained response when `--after` is omitted, returning it immediately when available or waiting for it. If the task ends without a response, it returns the terminal outcome. Omission never means to start observing from the current time or to return the latest response. With `--after`, `wait` observes the next response after the supplied identifier. It returns an already-available response immediately or waits for another response or terminal outcome. It creates no work, consumes no responses, and does not restart the harness. Multiple readers can use independent cursors. Unknown or cross-task response identifiers are errors.
+`wait` observes the first retained response when `--after` is omitted, returning it immediately when available or waiting for it. If the task ends without a response, it returns the terminal outcome. Omission never means to start observing from the current time or to return the latest response. With `--after`, `wait` observes the next response after the supplied identifier. It returns an already-available response immediately or waits for another response or terminal outcome. When no eligible response exists, pending native approvals return before waiting, as defined in [Responding to Native Permission Requests](../approvals.md). It creates no work, consumes no responses, and does not restart the harness. Multiple readers can use independent cursors. Unknown or cross-task response identifiers are errors.
 
 `status` returns a nonblocking snapshot with a bounded latest-response preview; `--full` retrieves the complete latest response. `queue` shows active and pending work in order. When `send` admits a task while execution failure has paused the session queue, the immediate `started` output identifies the failed active task that blocks dispatch and shows the `status --full` and `cancel` commands for it. The new task remains accepted and queued. `cancel` waits for cancellation of the targeted task and its delegated descendants, without removing independently queued tasks. Successfully cancelling the settled failed task releases the queue; failed or unconfirmed cancellation leaves dispatch paused. `resume` requests native recovery of a failed task without new input; unsupported recovery reports an error and leaves the queue paused.
 
@@ -99,3 +104,7 @@ Native steering returns an acceptance acknowledgement. Queued and interrupting s
 A managed agent invokes its own declared children with `subharness run subagent:<name>`. Parent context is supplied internally, not through public flags. Names resolve only against that parent's direct declarations. This invocation loads the parent's definition source without discovering unrelated repository or global entries, so an unrelated broken definition does not block a declared child. A generic parent has no declared children and fails this lookup without evaluating a specialist catalog. Missing context or an undeclared child is an error; there is no fallback to another scope. Child execution uses the same commands and lifecycle.
 
 The caller supplies an existing working directory. The library does not create worktrees or sandboxes. A local coordinator owns pending execution after an individual response command exits. `--detach` releases only the CLI observation; it does not override process-lifecycle restrictions imposed by the host. Use host-owned background controls when the coordinator and workers must remain reachable after a shell command exits. Pending execution is not guaranteed to survive coordinator or environment exit, and detached admission does not promise automatic reactivation of an external parent chat.
+
+## Answer a permission request
+
+`subharness respond <request-id> --content <json> [--format text|jsonl]` submits a structured answer to a pending native permission request. `--content-file <path|->` is an alternative content source. Read the returned schema and action context before answering; decisions and scopes depend on the native request. See [Responding to Native Permission Requests](../approvals.md) for complete examples, validation, ownership and lifecycle behavior.

package/sdk/cli/output.md

@@ -1,10 +1,12 @@
 # CLI Output
 
+[Error diagnostics](../diagnostics.md) defines safe process and coordinator communication details. These details enrich message text without changing the error record shape or command exit-code rules.
+
 `dashboard` is a terminal-only live view, not an execution-record command. It accepts no `--format` option and emits no text/JSONL records on success. Its rows, empty state, and terminal lifecycle are defined in the [CLI contract](index.md#live-dashboard).
 
-Execution commands accept `--format text|jsonl`; `text` is the default. Both formats report the same operations. JSONL contains complete records separated by newlines, never native token streams or tool transcripts. All records include `version: 1` and a `type` discriminator. Identifiers are opaque strings prefixed with `ses_`, `tsk_`, or `rsp_` and are not paths or process identifiers.
+Execution commands accept `--format text|jsonl`; `text` is the default. Both formats report the same operations. JSONL contains complete records separated by newlines, never native token streams or tool transcripts. All records include `version: 1` and a `type` discriminator. Identifiers are opaque strings prefixed with `ses_`, `tsk_`, `rsp_`, or `req_` and are not paths or process identifiers.
 
-Task-creating commands print a `started` record immediately after admission, including when queued. By default, they then return one complete response or terminal outcome for that task. With `--detach`, `run` and task-creating `send` commands end their observation after the `started` record and return no response or terminal record. A successful `steer` prints an `accepted` record. If native steering is unavailable, the operation uses `interrupt` semantics and prints `started` with `requestedDelivery: "steer"` and `delivery: "interrupt"`, then returns the replacement task's response or outcome.
+Task-creating commands print a `started` record immediately after admission, including when queued. By default, they then return one complete response, pending permission request, or terminal outcome for that task. With `--detach`, `run` and task-creating `send` commands end their observation after the `started` record and return no response or terminal record. A successful `steer` prints an `accepted` record. If native steering is unavailable, the operation uses `interrupt` semantics and prints `started` with `requestedDelivery: "steer"` and `delivery: "interrupt"`, then returns the replacement task's response or outcome.
 
 When a task is admitted while its session queue is paused by the failed active task, its `started` record includes `paused: true` and `blockedByTaskId` with that failed task's identifier. Both fields describe the admission snapshot and are omitted from other `started` records. Text output says that the task was accepted but cannot dispatch, identifies the failed task, and shows `subharness status <failed-task-id> --full` and `subharness cancel <failed-task-id>` as the inspection and recovery commands. Cancellation must succeed before queue dispatch resumes.
 
@@ -33,7 +35,7 @@ The identifiers above are illustrative. A `response` contains `sessionId`, `task
 
 `status` emits a `status` record with `sessionId`, `taskId`, `state`, and optional `response` and `error`. The response preview contains `responseId`, `text`, and `truncated`; at most 4,000 text characters are included. `subharness status <task-id> --full` returns the complete latest response instead. `subharness wait <task-id>` returns or awaits the first retained response; adding `--after <response-id>` returns or awaits the next response after that cursor.
 
-`list` emits an `agents` record with an `agents` array of `{ id, name, description, scope }`, where scope is `harness`, `repo`, `global`, or `subagent`. The built-in entries have IDs and names `codex`, `claude`, and `fx`, and scope `harness`; they appear in that order before discovered specialists. They describe supported targets, not verified executable, authentication, or model availability. A managed parent's catalog includes its declared `subagent:` entries; generic parents have no declared children. `queue` emits a `queue` record with `sessionId`, `paused`, optional `active`, and a `tasks` array in pending order. Task summaries contain `taskId`, `state`, and a prompt `description` limited to 120 characters.
+`list` emits an `agents` record with an `agents` array of `{ id, name, description, scope }`, where scope is `harness`, `repo`, `global`, or `subagent`. The built-in entries have IDs and names `codex`, `claude`, `fx`, `opencode`, `copilot`, and `cursor`, and scope `harness`; they appear in that order before discovered specialists. They describe supported targets, not verified executable, authentication, or model availability. A managed parent's catalog includes its declared `subagent:` entries; generic parents have no declared children. `queue` emits a `queue` record with `sessionId`, `paused`, optional `active`, and a `tasks` array in pending order. Task summaries contain `taskId`, `state`, and a prompt `description` limited to 120 characters.
 
 An `accepted` record contains `sessionId`, `taskId`, `delivery: "steer"`. A successful `cancel` emits a `cancelled` record with the targeted task identity and final state, after affected native execution has stopped. Already-terminal tasks retain their existing state. `resume` emits `started` for the existing task with `resumed: true`, then its next response or terminal outcome.
 
@@ -41,6 +43,10 @@ Errors use `{ "version": 1, "type": "error", "error": { "code": "INVALID_ARGUMEN
 
 Exit code `0` means the command succeeded or a response was returned; it does not mean the agent fulfilled the objective. For `check`, it means only that the selected target's startup checks passed at that moment. For `run --detach` and detached task-creating sends, it means admission succeeded, not that native startup or execution succeeded. Admission errors retain their existing error records and exit codes; later failures are available through `wait` or `status`. Code `1` means execution, access, or capability failure; `2` means invalid input, configuration, or unknown identifiers; and `130` means an observation ended in cancellation or interruption. Successful `cancel` itself exits `0`. Combining `--detach` with `--delivery steer` is an `INVALID_ARGUMENT` error and exits `2`.
 
-`status` snapshots retain the observed task’s outcome in their exit code: queued, running, waiting, and completed states exit `0`; cancelled or interrupted states exit `130`; failed states use `1` or `2` according to the stored error. A retrieval error uses its own error code.
+`status` snapshots retain the observed task’s outcome in their exit code: queued, running, waiting, awaiting_approval, and completed states exit `0`; cancelled or interrupted states exit `130`; failed states use `1` or `2` according to the stored error. A retrieval error uses its own error code.
 
 Standard CLI `--help` and `--version` produce plain text, do not accept `--format`, and do not start the coordinator or harnesses. Command-level `--help` is also available without execution arguments. Unsupported options and extra positional arguments are errors.
+
+## Permission requests
+
+The [approval contract](../approvals.md) defines `approval_required` and `approval_answered`, request-specific schemas, native option scopes, and response examples. Observations may return pending requests after checking retained responses and before blocking. `status` includes pending `requests` from the observed task and its descendants. A pending request is not an error or an agent response. Text output displays the request ID, origin, action context, full schema, and `respond` syntax. It never prints an automatically selected authorization. `respond` acknowledges an answer with exit `0`; subsequent `wait` or `status` establishes the task outcome.

package/sdk/completion-notifications.md

@@ -16,6 +16,8 @@ With `--after`, the command returns the next retained response after the supplie
 
 An explicit cursor prevents losing a later response that arrives between commands. Reads do not consume responses. Every reader uses its own cursor position, including the implicit position before the first response when `--after` is omitted. Unknown and cross-task identifiers are errors. `status --full` retrieves the complete latest response.
 
+Pending permission requests are a separate return point. If no eligible retained response exists, `run`, task-creating `send`, and `wait` return `approval_required` for the observed task or a descendant before blocking. This does not create an agent response or advance a cursor. Answer with `respond` and continue observing the same task and cursor. See [Responding to Native Permission Requests](approvals.md).
+
 ## Completion with delegated work
 
 A task remains pending while descendants are unfinished or their results still require processing. Ending a native turn does not cancel children or release independently queued tasks. Child results continue the parent in the same native conversation and library task. Normal completion requires the descendants to finish and the parent to produce a response after processing their results.

package/sdk/config.md

@@ -39,7 +39,7 @@ The former `.agents/agents/` directory is not read. Definitions moved to `.subha
 
 Discovery is required for listing and repository/global specialist lookup. Direct harness execution skips it. Declared-child execution loads only the parent's source and direct child map; unrelated catalog entries are not dependencies of a `subagent:` invocation.
 
-The declared name determines identity. Duplicate names in the same scope are errors. `repo:reviewer` and `global:reviewer` remain distinct; bare `reviewer` is accepted only when unambiguous. The reserved CLI targets `codex`, `claude`, and `fx` always select native harnesses. Specialists with those names require a `repo:` or `global:` qualifier. Direct harness runs bypass definition discovery entirely, including invalid definition files. Global definitions can execute in any caller-supplied directory. Global and repository files resolve their own imports through normal Node package resolution.
+The declared name determines identity. Duplicate names in the same scope are errors. `repo:reviewer` and `global:reviewer` remain distinct; bare `reviewer` is accepted only when unambiguous. The reserved CLI targets `codex`, `claude`, `fx`, `opencode`, `copilot`, and `cursor` always select native harnesses. Specialists with those names require a `repo:` or `global:` qualifier. Direct harness runs bypass definition discovery entirely, including invalid definition files. Global definitions can execute in any caller-supplied directory. Global and repository files resolve their own imports through normal Node package resolution.
 
 ```sh
 subharness list --cwd /repo/worktree