subharness 0.0.3 → 0.0.5

package/sdk/permissions.md

@@ -1,6 +1,6 @@
 # Native Permissions
 
-Harness constructors accept optional native permission settings directly alongside model options. These settings configure the native session without modifying persistent native settings or creating a Subharness sandbox. The library never answers a later native approval request with a synthetic allow response. The installed harness evaluates the selected policy, and the external execution environment enforces its remaining restrictions.
+The Codex, Claude Code, and fx constructors accept optional native permission settings directly alongside model options. These settings configure the native session without modifying persistent native settings or creating a Subharness sandbox. OpenCode instead uses its isolated native ask policy, Copilot uses native manual permission mode, and neither exposes a public permission selector. Cursor exposes its documented SDK `sandboxMode` for API-key access; subscription ACP access rejects explicit sandbox settings and supports the documented once-only native approvals. Supported native tool approvals are surfaced to the caller through the [structured approval flow](approvals.md); an explicit valid caller decision is required before authorization. The installed harness evaluates the selected policy, and the external execution environment enforces its remaining restrictions.
 
 Omitted settings preserve native configuration. Explicit settings remain fixed for session follow-ups. A child uses its own definition and native configuration; it does not inherit the parent's explicit permission options. Invalid definitions fail before execution. Unsupported or observably rejected explicit settings fail without fallback to another harness or permission policy.
 
@@ -21,6 +21,8 @@ codex({
 
 `approvalPolicy: "never"` suppresses approval prompts; it does not grant operations blocked by the selected sandbox. `danger-full-access` removes Codex's native sandbox boundary, subject to external restrictions.
 
+By default, `workspace-write` keeps `.git`, `.agents`, and `.codex` read-only inside the writable workspace. It also protects the Git directory named by a `.git` pointer file, even when that directory is inside the workspace; for a linked worktree, that directory is in the main checkout's Git directory and holds the worktree's index. Git index updates such as `git add` can therefore fail in ordinary checkouts and linked worktrees. subharness does not add writable roots or change the native policy to permit these operations.
+
 ## Claude Code
 
 ```ts
@@ -33,7 +35,7 @@ claudeCode({
 
 `ClaudeCodeOptions` and `ClaudeCodeConfig` expose `permissionMode?: "default" | "acceptEdits" | "bypassPermissions" | "plan" | "dontAsk" | "auto"`, `allowedTools?: readonly string[]`, and `disallowedTools?: readonly string[]`. Rule arrays contain nonempty strings and are copied into immutable configuration. Unknown modes, non-string rules, and fields belonging to another harness are invalid definitions. An empty rule list adds no rules.
 
-The adapter passes these settings to the native Agent SDK. Explicit allowed rules are combined with the existing rules for declared custom tools and exact child-launcher operations. Disallowed rules remain authoritative under native permission evaluation. Selecting `bypassPermissions` also supplies the native SDK's required explicit bypass enablement. The library does not synthesize an allow response in its unresolved approval callback.
+The adapter passes these settings to the native Agent SDK. Explicit allowed rules are combined with the existing rules for declared custom tools and exact child-launcher operations. Disallowed rules remain authoritative under native permission evaluation. Selecting `bypassPermissions` also supplies the native SDK's required explicit bypass enablement. Unresolved callbacks use the structured approval flow; the library never chooses an allow decision automatically.
 
 Native permission mode and rule evaluation depend on the installed SDK, executable, and managed settings. Observable rejection or a reported different explicit mode is an error. A native initialization event that reports the active mode must agree with the explicit request. Startup success does not claim that every native rule or future command was verified. Diagnostics identify rejected options without exposing rule contents or tool arguments.
 
@@ -54,12 +56,12 @@ fx({
 
 ## Readiness and failures
 
-`check` uses the same permission configuration as execution. Its success establishes startup readiness and only the native settings observable during startup. It does not execute a shell or child launcher, prove arbitrary tool access, or claim unobservable native policy values. Native approval requests that remain unresolved fail with `INPUT_REQUIRED`; the library does not offer an interactive approval-answer command.
+`check` uses the same permission configuration as execution. Its success establishes startup readiness and only the native settings observable during startup. It does not execute a shell or child launcher, prove arbitrary tool access, or claim unobservable native policy values. Startup-time interactive requests still fail with `INPUT_REQUIRED`. During execution, supported permission requests surface through the [structured approval flow](approvals.md), without changing native configuration.
 
-A caller reports the affected harness and operation, then changes the explicit configuration or resolves the native restriction before starting a new attempt. Retrying unchanged permission failures, broadening policy automatically, or silently selecting another harness is not a recovery strategy.
+For a surfaced permission request, the caller inspects the action and responds to its schema, then observes the original task. For an unsupported interaction or hard native denial, the caller reports the affected harness and operation and resolves that restriction before starting a new attempt. Retrying unchanged permission failures, broadening policy automatically, or silently selecting another harness is not a recovery strategy.
 
 ## Background delegation
 
 The caller reads the Subharness skill and prefers one ordinary `subharness run <target>` through known host background-command controls. It continues independent work and later collects that hosted command's output, which already contains the first response or terminal outcome. When those controls are unavailable or uncertain, it uses `run --detach`, retains the returned task and session identifiers, continues other work, and later collects the result with `wait`. `status` is optional when a snapshot or additional state is needed. Shell `&` and an unobserved process do not replace managed task records. Both paths require collecting the result and confirming its terminal outcome before reporting completion; detached admission alone is not completion.
 
-The native caller needs permission to execute the private launcher and reach the local coordinator. Each child needs permission for its own task. This remains true for Codex, Claude Code, and fx; no constructor option promises native desktop notifications or automatic chat reactivation.
+The native caller needs permission to execute the private launcher and reach the local coordinator. Each child needs permission for its own task. This remains true for all six native harnesses; no constructor option promises native desktop notifications or automatic chat reactivation. OpenCode and Copilot can surface supported active permission requests through the structured approval flow. Cursor subscription sessions also expose supported once-only ACP permissions. Other Cursor interactive requests fail with `INPUT_REQUIRED`.

package/sdk/pr-integration.md

@@ -22,7 +22,7 @@ After every mutation, the integrator reads GitHub state again. Merge success req
 
 The report identifies merged, already merged, blocked, and unattempted entries, their reviewed heads, resulting merge commits when known, and exact blockers. It includes the observed final destination-branch SHA and command outcomes. The integrator writes a nonsecret progress journal only when the assignment names its path. It never exports credentials, dumps the environment, or claims local integration tests ran merely because hosted checks passed.
 
-The caller supplies the existing native GitHub authentication and any explicitly authorized native network profile. Model billing continues to use the caller's selected access configuration. Permission failures are reported without bypasses or silent changes of execution route. Native approval requests that require host interaction can produce `INPUT_REQUIRED`, as specified in the [adapter contract](adapter-contract.md).
+The caller supplies the existing native GitHub authentication and any explicitly authorized native network profile. Model billing continues to use the caller's selected access configuration. Permission failures are reported without bypasses or silent changes of execution route. Supported native permission requests use the [structured approval flow](approvals.md). A permission response does not expand the integrator's assigned merge authority. Unsupported host interactions can still produce `INPUT_REQUIRED`, as specified in the [adapter contract](adapter-contract.md).
 
 The allowlist is an instruction-level delegation contract, not a GitHub token scope or a new runtime security boundary. The agent retains native tools; neither the model's instructions nor an API-domain allowlist mechanically limits a credential to those PRs. Native sandbox policy, credential scopes, and GitHub protections remain the enforcement boundaries.
 

package/sdk/project-team.md

@@ -21,6 +21,8 @@ Role instructions alone do not grant native capabilities or permissions. Browsin
 
 The repository's Codex roles explicitly select `approvalPolicy: "never"`, `sandboxMode: "workspace-write"`, and `networkAccessEnabled: true` for local development and coordinator access. The reviewer selects Claude `permissionMode: "dontAsk"` with `Read`, `Glob`, `Grep`, and `Bash` allowed. Its read-only review responsibility remains an instruction; allowing Bash is not a filesystem read-only boundary. The fx roles explicitly select `permissionMode: "auto"`. These policies use [native permission options](permissions.md), preserve native restrictions, and do not guarantee that every operation is permitted. Protected paths and rejected automatic reviews can still require a lead-managed execution path.
 
+Implementation roles return unstaged working-tree changes and verification evidence. Local Git staging and commits belong to the lead unless the assignment explicitly authorizes them. When an implementation task requires moving or deleting ordinary files, roles use filesystem operations; subsequent Git staging records the renames. By default, Codex workspace-write protects `.git`, `.agents`, and `.codex` inside the writable workspace. It also protects the Git directory named by a `.git` pointer file, even when that directory is inside the workspace; for a linked worktree, that directory is in the main checkout's Git directory and holds the worktree's index. A required change under those protected paths is reported with the exact operation, affected paths, and partial effects for lead-managed execution. A copied replacement does not complete a move while the original remains.
+
 ## 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.

package/sdk/sessions.md

@@ -10,6 +10,7 @@ Each `run` creates a new session; `send` creates follow-up tasks or steers the a
 | --- | --- |
 | `queued` | Admitted but not yet dispatched |
 | `running` | Native startup or generation is active |
+| `awaiting_approval` | A native operation is waiting for a structured permission answer |
 | `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 |
@@ -24,8 +25,10 @@ Every complete response receives a response identifier and returns control to it
 
 ## 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.
+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. Task records remain available for its lifetime; they are not silently evicted. Settled permission-request records have a separate bounded retention policy defined in [Responding to Native Permission Requests](approvals.md).
 
 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).
+
+Supported native permission requests follow [Responding to Native Permission Requests](approvals.md). Observing an approval returns control without completing or restarting the task.

package/sdk/tools.md

@@ -70,6 +70,6 @@ function toolResult(result: { readonly content: readonly ToolContent[] }): ToolR
 
 `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.
+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. Claude Code, fx, and OpenCode use MCP image blocks; Codex and Cursor SDK sessions use native image content items; Cursor subscription sessions use MCP image blocks. [Copilot](copilot.md) groups content by type in its native result envelope: text blocks are joined in their original text order, images retain their original image order as binary image results, and interleaving between the text and image groups is unavailable. 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

@@ -1,10 +1,10 @@
 # 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.
+The first usable version supplies a TypeScript definition SDK and the `subharness` CLI with Codex, Claude Code, fx, OpenCode, GitHub Copilot, and Cursor adapters. 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.
+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`, `opencode`, `copilot`, `cursor`, 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";
@@ -20,7 +20,7 @@ Global definitions live in `~/.subharness/agents/`; repository definitions live
 
 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` for `run` and `check`; specialist targets reject those overrides.
+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` for `run` and `check`. Codex, Claude Code, and fx also accept `--effort`; OpenCode, Copilot, and Cursor reject it. Specialist targets reject both overrides.
 
 `run` and task-creating `send` commands accept `--detach` with every prompt source. The option ends the requesting command's observation immediately after successful admission, so the command returns exactly the existing `started` record and exits `0`. The service explicitly completes that observation response; it does not rely on a caller abandoning a response body. Admission errors keep their records and exit codes, while later failures remain available through `wait` and `status`. Interrupt delivery confirms affected execution has stopped before replacement admission even when detached. Steering rejects `--detach` with `INVALID_ARGUMENT`. The option is an observation request and is never retained as session configuration.
 
@@ -38,9 +38,9 @@ Closing a response-reading command does not cancel work. The coordinator retains
 
 ## Task states and responses
 
-The coordinator supplies the terminal dashboard with a read-only snapshot of current session work followed by retained finished tasks, including failed active tasks that pause a queue. Each task appears at most once, and retained history is available to newly opened dashboards for the coordinator’s lifetime. The private snapshot includes an explicit finished-history and grouped-context capability markers so the CLI can reject older incompatible coordinators. It carries only session/task identity, selected harness, bounded prompt title, task state, canonical checkout/repository paths, and timestamps needed by the display; it excludes environment variables, credentials, definitions, transcripts, and native diagnostics. Reading it does not acknowledge responses or change task execution. Workers report the actual selected harness to the coordinator after native startup succeeds. Task timing records the first dispatch, latest failure, and terminal completion or confirmed-stop time without resetting on native continuations. Finished rows retain a fixed elapsed duration; recovery clears terminal timing for the resumed task. Snapshot observation adds no public SDK execution method or persistent history. The display contract is defined in [CLI](cli/index.md#live-dashboard).
+The coordinator supplies the terminal dashboard with a read-only snapshot of current session work followed by retained finished tasks, including failed active tasks that pause a queue. Each task appears at most once, and retained history is available to newly opened dashboards for the coordinator’s lifetime. The private snapshot includes an explicit finished-history and grouped-context capability markers so the CLI can reject older incompatible coordinators. It carries only session/task identity, selected harness, bounded prompt title, task state, canonical checkout/repository paths, and timestamps needed by the display; it excludes environment variables, credentials, definitions, transcripts, and native diagnostics. Reading it does not acknowledge responses or change task execution. Workers report the actual selected harness to the coordinator after native startup succeeds. Task timing records the first dispatch, latest failure, and terminal completion or confirmed-stop time without resetting on native continuations. Finished rows retain a fixed elapsed duration; recovery clears terminal timing for the resumed task. Snapshot observation adds no public SDK execution method or persistent history. The inspector uses a separate authenticated, read-only session-history projection for retained work requests, stable admission ordinals, queue state and direct child sessions. Full prompt/response content is fetched only for the expanded request through the task-detail projection. It omits already-cached prompt and response text on refresh and never acknowledges delegated outcomes or changes execution. The private transport is defined in [Dashboard inspection](cli/dashboard-inspection.md); presentation is defined in [CLI](cli/index.md#live-dashboard).
 
-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`.
+Task states are `queued`, `running`, `waiting`, `awaiting_approval`, `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` without `--after` returns the first retained response in order, including one that arrived before the command started, or awaits it. Omission does not select the latest response or begin observation at the current time. `wait --after <response-id>` returns the next retained response after that cursor. If no selected response 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.
 
@@ -60,7 +60,7 @@ New follow-up tasks in a child session belong to the currently invoking parent t
 
 ## 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. These delegation rules do not themselves change native modes, managed policy, or sandbox boundaries. Explicit constructor options separately select session-native permissions under [Native Permissions](permissions.md); persistent user/project settings are unchanged. 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.
+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. These delegation rules do not themselves change native modes, managed policy, or sandbox boundaries. Explicit constructor options separately select session-native permissions under [Native Permissions](permissions.md); persistent user/project settings are unchanged. Supported native approval requests remain open and surface through the [structured approval flow](approvals.md). The caller answers the request-specific schema with `respond`, then observes the original task. The permission callback never automatically approves the request. Unsupported input and startup-time interactions still fail with `INPUT_REQUIRED`. Hard native denials remain subject to the selected native policy.
 
 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, while `wait` observes the first response or a subsequent response selected by a cursor. 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.