subharness 0.0.5 → 0.0.7

package/sdk/execution.md

@@ -0,0 +1,743 @@
+# Connected and embedded execution
+
+The Node.js SDK runs native agents inside an application or connects to the shared local coordinator used by the CLI. It provides task states, complete responses, and structured approvals. Native harness executables remain required. Applications own their UI transport and user authorization; this is not a browser/edge runtime or an implementation of the A2A wire protocol.
+
+Two entry points serve different ownership needs. **`connect()` connects to the same selected local coordinator as the CLI, starting it if absent**: it finds existing conversations without recreating agents, or connects to a newly started empty coordinator. `connect({ start: false })` requires that coordinator to exist already. **`createRunner()` embeds execution in the application process**: it owns isolated sessions and can use application tool closures. Both expose the same session and task handles. A session is a native conversation with a queue; a task is coordinated work including child agents and parent continuations.
+
+A connected client disconnects without stopping the shared coordinator or its agents. A coordinator started by `connect()` also survives the calling application exiting. An embedded runner closes by cleaning up its owned execution. Neither mode adds durable restart recovery. These are Node.js APIs used behind a UI; coordinator/model credentials remain on the server, not in browser code.
+
+Read the examples in order, or jump to [connection startup](#connect-without-running-the-cli-first), [agent discovery and creation](#discover-check-and-create-connected-sessions), [CLI attachment](#connect-to-cli-work), [paged inspection](#list-and-inspect-execution), [reconnection](#disconnect-and-reconnect), [embedded teams](#define-an-embedded-team), [queueing](#follow-up-or-queue-work), [steering](#correct-or-replace-active-work), [UI controls](#serve-a-ui), [approval buttons](#render-approval-buttons), [grant forms](#select-permission-grants), [chat tools](#consult-from-a-chat-tool), [response replay](#replay-complete-responses), [signatures](#signature-reference), or [CLI/library parity](#one-library-for-sdk-and-cli).
+
+Examples awaiting only `task.result` assume no interactive approval is needed, or a separate UI/component handles requests. Pending approvals never auto-resolve. Helpers identified as application-owned are illustrative, not SDK exports. The first version exposes task states, complete responses, and approvals; live tokens and native tool-progress events are outside its scope.
+
+## Connect without running the CLI first
+
+The SDK does not require a prior CLI command. By default, `connect()` reuses the selected shared local coordinator or starts it when it is confirmed absent. Starting a coordinator creates no sessions or agents and invokes no model.
+
+```ts
+import { connect } from "subharness";
+
+const client = await connect(); // Equivalent to connect({ start: true }).
+try {
+  const { items: sessions } = await client.sessions.list();
+  console.log(sessions); // [] when no sessions have been created.
+} finally {
+  await client.disconnect(); // The shared coordinator keeps running.
+}
+```
+
+Use strict attachment when the application should observe only an existing coordinator:
+
+```ts
+const client = await connect({ start: false });
+try {
+  console.log((await client.sessions.list()).items);
+} finally {
+  await client.disconnect();
+}
+```
+
+Strict attachment fails when the selected coordinator is absent. A running coordinator with no sessions is still a successful connection. Both forms authenticate and validate the selected instance and protocol support. Authentication failure, protocol incompatibility, or uncertain reachability fails the call; it does not authorize starting a replacement coordinator. Concurrent connection calls that need startup converge on one selected coordinator. The discovery, protocol, and startup rules are specified below under ownership and transport.
+
+## Discover, check, and create connected sessions
+
+The agent catalog describes selectable definitions; it is separate from sessions already running. Discovery uses the given existing absolute directory on the coordinator host. Here `cwd` is the application's selected project directory, and `client` is an open connected client.
+
+```ts
+import { codex } from "subharness";
+
+const { items: agents } = await client.agents.list({ cwd });
+console.log(agents); // IDs, names, descriptions, and harness/repo/global scope.
+
+await client.agents.check({ agent: "repo:researcher", cwd }); // Optional startup check.
+const session = await client.sessions.create({ agent: "repo:researcher", cwd });
+const { task } = await session.prompt("Find the queue's documented guarantees.");
+console.log((await task.result).text);
+
+// Alternatively, configure a direct native harness without a definition file.
+const direct = await client.sessions.create({
+  agent: codex({ model: "CODEX_MODEL_ID", effort: "high" }),
+  cwd,
+});
+```
+
+A string selects a discovered qualified reference or unambiguous name. Reserved strings `"codex"`, `"claude"`, and `"fx"` select direct harnesses with native defaults. OpenCode, Copilot, and Cursor require their existing explicit model configuration through a harness constructor; their bare reserved names reject with `INVALID_CONFIG`. All six implemented harnesses retain their documented access and capability limits. Existing harness constructors accept explicit model/options; their model identifiers remain required. `subagent:` references belong to the private managed-agent context, not unrestricted public creation. Unknown or ambiguous references reject with `UNKNOWN_AGENT` or `AMBIGUOUS_AGENT`.
+
+Catalog discovery imports trusted definition modules in isolated coordinator-owned evaluation; it does not start native harnesses or call models. The finite discovered-definition inventory remains unpaginated; there is no artificial catalog-size cap. Discovery is not proof of readiness. `check` opens and closes a disposable native startup session without a prompt, retained conversation, or task; it rejects safely on startup/authentication/configuration/cleanup failure and does not promise a later model call will succeed.
+
+`create` resolves the target and captures its loaded definition graph and environment once, then returns an empty session. Editing definition files affects newly created sessions, not an existing captured conversation. Definition functions live on the coordinator host; client closures cannot be transferred. Native harness startup stays lazy until dispatch. Invalid creation returns no session. A separate invalid `prompt` can leave a valid empty session, which the caller may reuse or close. The CLI's atomic first-prompt boundary is preserved separately below.
+
+For connected creation/check, omission of `env` snapshots the calling process environment at that operation. An explicit `env` replaces it, with undefined entries omitted. Inherited `AGENT_PARENT_TOKEN` and `AGENT_CLI_PATH` are stripped, and the selected coordinator supplies `AGENT_STATE_DIR`; managed authority is bound separately. This resulting environment governs definition resolution and module evaluation as well as native startup/execution, so environment-dependent imports use the same chosen values. Catalog listing evaluates definitions with its implicit caller snapshot under the same stripping/injection rules. Existing cwd-based project discovery and personal-settings conventions still apply. The environment is privately transferred and captured for the session; follow-ups do not replace it. No caller-supplied environment grants parent authority. Neither the host cwd nor the shared daemon's `process.env` is mutated, and environment/access values never appear in metadata or errors.
+
+Connected and CLI-created sessions retain their loaded definition graph in an isolated owner process. Custom-tool callbacks execute in that graph owner's creation directory and captured environment, including callbacks used by managed children. A child's native harness may use a different requested working directory and native environment; that does not change the captured callback's ambient `process.cwd()` or `process.env`. Tools that operate on a child-specific location must use explicit paths or arguments. The graph owner does not inherit caller-supplied managed parent or launcher authority; native delegation instructions and launchers are bound separately to each session. This preserves closure state and avoids re-importing changed source or mutating shared process context.
+
+Connected sessions retain the CLI's existing per-project personal-settings and native-worker access resolution. Embedded runners retain their explicit `RunnerOptions.env`/`access` behavior and do not start reading those personal settings. Model credentials remain in the server/coordinator execution path, not UI payloads.
+
+## Connect to CLI work
+
+Start a task using the existing CLI. This example uses the repository's configured `repo:architect` agent; use a valid discovered agent reference in another repository.
+
+```sh
+subharness run repo:architect --prompt "Review the SDK contract." --detach --format jsonl
+```
+
+The admission receipt includes `sessionId` and `taskId`. Supply those values to the SDK; the names below represent those returned strings. The connected API retrieves the same records and native conversation, without loading the agent definition again or invoking a model merely to inspect it.
+
+```ts
+import { connect, AgentError } from "subharness";
+
+const client = await connect();
+try {
+  const { items: sessions } = await client.sessions.list();
+  console.log(sessions);
+  const { items: tasks } = await client.tasks.list({ sessionId });
+  console.log(tasks);
+
+  const session = await client.sessions.get(sessionId);
+  const task = await client.tasks.get(taskId);
+  console.log(await session.snapshot());
+  console.log(await task.snapshot());
+  console.log((await task.result).text);
+
+  // Continue the same conversation started by the CLI.
+  const { task: followup } = await session.prompt("Explain the main tradeoff.");
+  console.log((await followup.result).text);
+} finally {
+  await client.disconnect();
+}
+```
+
+The client uses the selected shared local coordinator; working directory alone does not select one, and independent embedded runners do not appear in these lists. Use `connect({ start: false })` to attach without starting a coordinator; retrieving the receipt's IDs still requires the original coordinator to retain them. Default `connect()` may start an empty coordinator after the previous one has exited; it cannot restore the receipt's old IDs.
+
+Lists expose retained summaries, including terminal tasks and closed sessions. The snippets above show the first page; use `nextCursor` to enumerate more. `tasks.list()` without a session filter covers all retained tasks in the selected coordinator. A supplied session ID must exist. `get` verifies existence asynchronously. Snapshot reads are asynchronous in **both** modes so the same consuming code works locally or through a connection.
+
+## List and inspect execution
+
+Use metadata for lists and request expanded task detail only when needed. This example enumerates one session's tasks; `renderRow` and `openDetails` are application-owned UI helpers.
+
+```ts
+let cursor: string | undefined;
+do {
+  const page = await client.tasks.list({ sessionId, limit: 100, cursor });
+  for (const summary of page.items) {
+    renderRow(summary.taskId, summary.title, summary.state, summary.updatedAt);
+  }
+  cursor = page.nextCursor;
+} while (cursor !== undefined);
+
+const task = await client.tasks.get(taskId);
+const details = await task.inspect();
+openDetails({ prompt: details.prompt, response: details.latestResponse });
+```
+
+Session/task pages default to 100 entries, with integer `limit` from 1 through 1,000. Entries follow admission insertion order. The first page captures a membership watermark; later pages exclude newly admitted records. Each page contains current state when read, not a transactionally frozen state snapshot. Opaque cursors bind the collection, coordinator instance, and filter; repeat the same `sessionId` filter when continuing. The limit may change between pages. Invalid or mismatched cursors reject with `INVALID_CURSOR`; cursors remain valid while that coordinator retains its records. No cursor means a fresh traversal.
+
+There is no collection-watch API in this version. Poll paged lists to find new work, and attach `task.watch()` for race-free current-state observation of selected tasks. Per-task revisions are not global list cursors. Lists contain no full prompts, responses, credentials, or environment values. `task.inspect()` adds the original admission prompt to the task snapshot; it is separate from every watch update. Steering does not overwrite that original prompt.
+
+Task titles use the existing first nonempty prompt line, normalize whitespace/remove terminal controls, and cap at 120 Unicode code points. Task ordinals count admission within a session from one; steering retains the task's ordinal. Timestamps are Unix milliseconds. `updatedAt` starts at admission and records the coordinator's latest task activity update, not an observer read. `dispatchedAt` records first dispatch and is retained across native continuations and private recovery; it is absent for never-dispatched work. `failedAt` records the latest execution or stop-confirmation failure, and `finishedAt` records the terminal transition. Both terminal timestamps are cleared when private recovery reopens the task and are populated again on its next failure/terminal transition. Session summaries include execution cwd and workspace identity. Connected sessions can resolve repository grouping using existing CLI behavior; embedded sessions use their directory without introducing Git discovery.
+
+## Disconnect and reconnect
+
+This independent example starts with the CLI receipt's IDs. An existing client may exit while its task continues, including while an approval is pending.
+
+```ts
+const firstClient = await connect({ start: false });
+const firstHandle = await firstClient.tasks.get(taskId);
+console.log(await firstHandle.snapshot());
+await firstClient.disconnect();
+// firstHandle is now invalid. Execution was not cancelled.
+
+const nextClient = await connect({ start: false });
+try {
+  const task = await nextClient.tasks.get(taskId);
+  console.log(await task.snapshot());
+  console.log((await task.result).text);
+} finally {
+  await nextClient.disconnect();
+}
+```
+
+This example uses strict attachment because it needs retained IDs, not a new empty coordinator. Reconnection works only while the same coordinator retains those IDs. Disconnect releases transport and observers, invalidates that client's handles, and rejects pending connected observations, including `result`, with a safe transport error. This does not fail the server task. A new handle can observe its retained outcome. Coordinator loss/replacement surfaces unavailable records; connection never replays a prompt or substitutes a new session. A new default `connect()` call can start an empty coordinator after the previous instance is confirmed gone, but never restores its sessions, tasks, or queues. Existing handles remain bound to their original instance.
+
+## Define an embedded team
+
+These static definition helpers already exist. Model IDs below are placeholders: select real models and supported effort levels through the configured native harness. Cost follows those explicit choices; Subharness does not infer a budget or silently choose another model.
+
+```ts
+import { agent, codex, createRunner, tool, AgentError } from "subharness";
+import { z } from "zod";
+
+const researcher = agent({
+  name: "researcher",
+  description: "Finds source evidence for a bounded question.",
+  instructions: "Find relevant sources. Return evidence and uncertainty concisely.",
+  harness: codex({ model: "LOW_COST_CODEX_MODEL_ID", effort: "low" }),
+});
+
+// Application state captured by a custom-tool closure stays in this process.
+const notes = new Map<string, string>();
+const remember = tool({
+  description: "Save a short research note in this application scope.",
+  inputSchema: z.object({ key: z.string(), text: z.string() }),
+  execute: ({ key, text }) => {
+    notes.set(key, text);
+    return "Saved";
+  },
+});
+
+const team = agent({
+  name: "lead",
+  description: "Reasons about the problem and coordinates its solution.",
+  instructions: "Delegate source lookup to research. Evaluate the evidence yourself.",
+  harness: codex({ model: "ADVANCED_CODEX_MODEL_ID", effort: "high" }),
+  subagents: { research: researcher },
+  tools: { remember },
+});
+```
+
+The declaration lets the lead call its research specialist through managed delegation. The runner owns child execution and exposes child state and approvals through the parent. The notes map and tool closure stay in the embedding application; `connect()` does not serialize them into the coordinator. Defining a child does not guarantee the model will delegate every suitable task.
+
+## Run an embedded script
+
+This example assumes the operation needs no interactive approval, or another application component handles requests. Awaiting `result` alone never auto-approves a request and can remain pending until one is answered.
+
+```ts
+const runner = createRunner();
+try {
+  const session = await runner.createSession(team, { cwd: process.cwd() });
+  const { task } = await session.prompt("Explain how this repository queues tasks.");
+  const { text } = await task.result;
+  console.log(text);
+} finally {
+  await runner.close();
+}
+```
+
+Runner options retain their current environment and access semantics. Native harness executables remain required. The library runs in Node.js behind the UI, not in the browser. Closing cancels unfinished owned work and waits for cleanup; it does not undo file or tool effects. Cleanup failures remain explicit, and uncooperative application tool callbacks can delay close.
+
+## Follow up or queue work
+
+This and the steering examples use an open `session`, obtained either from `client.sessions.get(id)` or `runner.createSession(...)`. Keep its owner alive for the chat/job scope; the embedded script above closes its own separate scope.
+
+```ts
+const { task: explanation } = await session.prompt("Explain the task queue.");
+console.log((await explanation.result).text);
+
+const { task: followup } = await session.prompt("Give an example of that behavior.");
+console.log((await followup.result).text);
+
+// Submitting before earlier work finishes queues a separate task by default.
+const { task: first } = await session.prompt("Review the approval contract.");
+const receipt = await session.prompt("Summarize that review in three points.");
+const second = receipt.task;
+if (receipt.paused) console.log("Blocked by:", receipt.blockedByTaskId);
+try {
+  await first.result;
+  console.log((await second.result).text);
+} catch (error) {
+  console.error(error);
+  console.log(await session.snapshot());
+}
+```
+
+The native conversation retains history. Default delivery is FIFO `queue`, with one active task and the existing 100-task queue limit. A failed task pauses dispatch; queued results may remain pending. The optional receipt pair `paused: true` and `blockedByTaskId` captures that condition atomically at admission; both fields are absent otherwise, including native steering acceptance. A later snapshot is current state, not a replacement for that admission evidence. Inspect the session before retrying. Under the existing recovery contract, cancelling retained failed work confirms stop and releases its paused queue without erasing its failure. There is no prompt-free SDK resume method. Sending another prompt does not answer an approval.
+
+## Correct or replace active work
+
+To correct work, first submit a task and then steer it without awaiting completion:
+
+```ts
+const { task: original } = await session.prompt("Review the public API and propose improvements.");
+const correction = await session.prompt("Keep the existing public API unchanged.", {
+  delivery: "steer",
+});
+console.log(correction.requestedDelivery, correction.effectiveDelivery);
+console.log("Same task:", correction.task.id === original.id);
+console.log((await correction.task.result).text);
+```
+
+In a separate case, start work and then explicitly replace the active task:
+
+```ts
+const { task: original } = await session.prompt("Review the implementation and the docs.");
+const replacement = await session.prompt("Stop that approach and review only the docs.", {
+  delivery: "interrupt",
+});
+console.log(original.id, replacement.task.id, replacement.effectiveDelivery);
+console.log((await replacement.task.result).text);
+```
+
+These examples assume an initially idle session and that the submitted work remains active when the control is handled. Steering requires an active task; otherwise it rejects with `NO_ACTIVE_TASK`. There is no expected-task guard: control applies to whichever task is active when handled, so completion and queued dispatch can race with the call. Supported native steering can return the same task. Unsupported steering falls back to confirmed interruption and reports `effectiveDelivery: "interrupt"`; unrelated errors do not trigger fallback. Interruption replaces the active task after stopping it and its descendants, preserving unrelated queued work. The interrupted task's result rejects with `INTERRUPTED`. The receipt therefore describes this particular prompt submission, separately from its task.
+
+## Serve a UI
+
+This example uses a shared, server-owned connected `client` kept alive across HTTP requests. `User`, `publish`, `authorizeSession`, `authorizeTask`, and `authorizeApproval` belong to the application. Each authorization helper verifies that the specific resource belongs to the authenticated user's chat, including any permitted descendant resources. Local coordinator authentication and opaque IDs do not provide application multi-user authorization.
+
+```ts
+async function submitMessage(user: User, chatId: string, sessionId: string, text: string) {
+  await authorizeSession(user, chatId, sessionId);
+  const session = await client.sessions.get(sessionId);
+  const { task } = await session.prompt(text);
+  return { taskId: task.id, sessionId: task.sessionId };
+}
+
+async function watchTask(
+  user: User, chatId: string, taskId: string,
+  signal: AbortSignal, publish: (value: unknown) => Promise<void>,
+) {
+  await authorizeTask(user, chatId, taskId);
+  try {
+    const task = await client.tasks.get(taskId);
+    for await (const snapshot of task.watch({ signal })) {
+      await publish(snapshot);
+      // Render state, latestResponse, children, and requests authorized for this chat.
+    }
+  } catch (error) {
+    if (error instanceof AgentError && error.code === "OBSERVATION_CLOSED") return;
+    throw error; // Route maps transport failures separately from task failures.
+  }
+}
+
+async function answerApproval(
+  user: User, chatId: string, requestId: string, response: ApprovalResponse,
+) {
+  await authorizeApproval(user, chatId, requestId);
+  await client.approvals.respond(requestId, response);
+}
+
+async function stopTask(user: User, chatId: string, taskId: string) {
+  await authorizeTask(user, chatId, taskId);
+  return (await client.tasks.get(taskId)).cancel();
+}
+```
+
+A browser disconnect aborts only that watch. Do not disconnect the shared client in an HTTP request's `finally` block. The server disconnects it when its connection scope ends; explicit `task.cancel()` stops a task, and `session.close()` closes server-side execution for that session. An embedded backend instead owns a bounded runner, uses its local lookups and `respond`, and closes that runner when its chat/job scope ends.
+
+An initial list followed by each selected task's `watch()` gives a current view and race-free per-task observation: watch begins with the latest snapshot. It does not subscribe to newly created tasks; refresh the list as needed. There is no collection-watch API or global revision cursor. Parent snapshots include descendant approvals even when the parent is `running`. Authorize those relationships and treat displayed native content as untrusted data.
+
+## Render approval buttons
+
+For a decision-only request, selecting an action needs only its ID. This illustrative JSX uses application components `Button` and `GrantApprovalForm`, plus an application-owned `submitApproval` function that calls the authenticated approval route above. They are not SDK exports.
+
+```tsx
+function ApprovalButtons({ request }: { request: ApprovalRequest }) {
+  if (request.grants !== undefined) {
+    return <GrantApprovalForm request={request} />;
+  }
+  return (
+    <section>
+      <p>{request.message}</p>
+      {request.actions.map(action => (
+        <Button key={action.id}
+          onClick={() => submitApproval(request.id, { actionId: action.id })}>
+          {action.label}
+          {action.description && <small>{action.description}</small>}
+        </Button>
+      ))}
+    </section>
+  );
+}
+```
+
+The UI might display “Allow once”, “Allow for this session”, and “Deny”, but it renders only the supplied actions. Each action includes a normalized `decision` and, for allow/deny, a `scope` for presentation. Labels and descriptions explain what the choice covers. A generic consumer needs no Codex, Claude Code, or fx branches. The application owns layout, handles submission errors, and refreshes withdrawn requests.
+
+An application can use a menu or dialog instead of buttons. Its selected action still comes from the request; it does not construct a decision/scope answer or infer an ID from a label. This server-side example assumes the same explicit authorization as the route above. An embedded owner substitutes `runner.respond` for `client.approvals.respond`.
+
+```ts
+async function answerSelectedAction(request: ApprovalRequest, action: ApprovalAction) {
+  if (request.grants !== undefined) {
+    throw new Error("Use the grant form for this request.");
+  }
+  await client.approvals.respond(request.id, { actionId: action.id });
+}
+```
+
+## Select permission grants
+
+For `GrantApprovalForm`, render one checkbox per `request.grants` entry, using its ID, label, and optional description. Start with no checked boxes and require an explicit submit action. The application-owned helpers below prepare the answer without interpreting native paths or permission profiles.
+
+```ts
+function createGrantFormState(request: ApprovalRequest) {
+  const selectedGrantIds = new Set<string>(); // Nothing selected for this request.
+  return {
+    toggle(id: string, checked: boolean) {
+      if (!request.grants?.some(grant => grant.id === id)) {
+        throw new Error("Unknown grant for this approval request.");
+      }
+      if (checked) selectedGrantIds.add(id);
+      else selectedGrantIds.delete(id);
+    },
+    async submit(action: ApprovalAction) {
+      const response: ApprovalResponse = action.decision === "allow"
+        ? { actionId: action.id, grants: [...selectedGrantIds] }
+        : { actionId: action.id };
+      await submitApproval(request.id, response);
+    },
+  };
+}
+```
+
+Create one form state for each request ID and bind its handlers to that request's checkboxes and actions. Different requests cannot share selections. Only IDs from that request's grants are selectable; the server validates the selected action and grants again. With no boxes selected, an allow submission explicitly contains `grants: []`, meaning no offered additional grants. Deny/cancel selections never include that array. An action requiring grant selection cannot be submitted without an explicit selection.
+
+## Consult from a chat tool
+
+An ordinary callback can be registered with the host chat's tool mechanism. `specialistSession` is an explicitly authorized existing connected session or a session created by this chat's embedded runner, possibly with declared children. `publishTask` is the application's notification helper so its UI can observe and answer approvals while the tool waits.
+
+```ts
+async function consultSpecialist(prompt: string): Promise<string> {
+  const { task } = await specialistSession.prompt(prompt);
+  await publishTask({ taskId: task.id, sessionId: task.sessionId });
+  const { text } = await task.result;
+  return text;
+}
+```
+
+The host chat supplies its own input schema and error handling when registering this callback. It receives the final answer or a rejected call; Subharness does not replace the host model loop. Submitting a public prompt from an application callback does not establish managed child lineage. Declared `subagents` use the separate hosted delegation mechanism with its existing ownership rules.
+
+The packaged [chat-tool example](examples/chat-tool.ts) exposes an application-owned `onTask(task: TaskHandle)` callback immediately after admission, so a UI can begin watching approvals and offer cancellation before the host tool finishes.
+
+For background consultation, the application can return the admitted task ID immediately and await its result separately. The application must then schedule any later host-chat continuation and correlate the result to the original tool call. UI disconnect or a failed notification does not cancel an admitted task.
+
+## Replay complete responses
+
+`responses` is useful when every complete reply matters. `CompleteResponse` retains its current `{ responseId, text, state }` fields. `lastSeenResponseId`, `displayResponse`, and `saveCursor` below are application-owned; omit `after` to start from the first retained response.
+
+```ts
+try {
+  for await (const response of task.responses({ after: lastSeenResponseId })) {
+    await displayResponse(response);
+    await saveCursor(response.responseId);
+  }
+  const final = await task.result;
+  console.log("Final answer:", final.text);
+} catch (error) {
+  if (error instanceof AgentError) {
+    if (error.code === "COORDINATOR_UNAVAILABLE") {
+      console.error("Connection lost; the task may still be running.");
+      throw error; // Reconnect and obtain a fresh handle before further reads.
+    }
+    if (error.code === "CANCELLED" || error.code === "INTERRUPTED") {
+      console.log("Task stopped:", error.code);
+    } else {
+      console.error(error.code, error.message);
+    }
+  } else {
+    throw error;
+  }
+  console.log(await task.snapshot());
+}
+```
+
+The iterator drains retained replies and ends normally after task termination; `task.result` reports execution failure. A waiting reply is not the final answer, and the final result can refer to a response already displayed; deduplicate by `responseId`. Unknown or cross-task cursors reject with `UNKNOWN_RESPONSE`. Passing `signal` aborts only observation with `OBSERVATION_CLOSED`; breaking the loop also releases only the observer. Response readers are independent and do not consume each other's records. Histories remain retained within their execution owner's lifetime; embedded runner scopes should be bounded. Connected transport failure can interrupt this observation without changing the task outcome, and even a snapshot read can then fail.
+
+## Signature reference
+
+Agent and harness definitions retain their [definition contracts](agent.md). The signatures below describe execution handles and display data; `TaskSnapshot.requests` contains normalized approval requests. Native [access configuration](access-config.md) remains separate.
+
+```ts
+interface RunnerOptions {
+  readonly env?: Readonly<Record<string, string | undefined>>;
+  readonly access?: AccessSelection;
+}
+type AccessSelection = Readonly<Partial<Record<HarnessKind, readonly AccessConnection[]>>>;
+type AccessConnection =
+  | { readonly type: "subscription"; readonly provider?: string }
+  | { readonly type: "api-key"; readonly provider?: string; readonly env?: string; readonly envFile?: string;
+      readonly baseUrl?: string; readonly wireApi?: "completions" | "responses";
+      readonly apiVersion?: string; readonly wireModel?: string }
+  | { readonly type: "vercel-api-key"; readonly env?: string; readonly envFile?: string }
+  | { readonly type: "vercel-oidc"; readonly env?: string; readonly envFile?: string; readonly project?: string };
+
+interface ConnectOptions {
+  readonly start?: boolean; // Default: true. Start the shared coordinator if absent.
+  readonly stateDirectory?: string; // Explicit absolute local state directory.
+}
+declare function connect(options?: ConnectOptions): Promise<Client>;
+interface ConnectedSessionOptions {
+  readonly agent: string | HarnessConfig;
+  readonly cwd: string;
+  readonly env?: Readonly<Record<string, string | undefined>>;
+}
+interface AgentSummary {
+  readonly id: string;
+  readonly name: string;
+  readonly description: string;
+  readonly scope: "harness" | "repo" | "global";
+}
+interface PageOptions { readonly limit?: number; readonly cursor?: string }
+interface Page<T> { readonly items: readonly T[]; readonly nextCursor?: string }
+interface Client {
+  readonly agents: {
+    list(options: { readonly cwd: string }): Promise<{ readonly items: readonly AgentSummary[] }>;
+    check(options: ConnectedSessionOptions): Promise<void>;
+  };
+  readonly sessions: {
+    create(options: ConnectedSessionOptions): Promise<SessionHandle>;
+    list(options?: PageOptions): Promise<Page<SessionSummary>>;
+    get(id: string): Promise<SessionHandle>;
+  };
+  readonly tasks: {
+    list(options?: PageOptions & { readonly sessionId?: string }): Promise<Page<TaskSummary>>;
+    get(id: string): Promise<TaskHandle>;
+  };
+  readonly approvals: {
+    respond(requestId: string, response: ApprovalResponse): Promise<void>;
+  };
+  disconnect(): Promise<void>;
+}
+
+declare function createRunner(options?: RunnerOptions): Runner;
+type Delivery = "queue" | "steer" | "interrupt";
+
+interface Runner {
+  createSession(
+    definition: AgentDefinition,
+    options: { readonly cwd: string },
+  ): Promise<SessionHandle>;
+  session(id: string): SessionHandle;
+  task(id: string): TaskHandle;
+  respond(requestId: string, response: ApprovalResponse): Promise<void>;
+  close(): Promise<void>;
+}
+
+interface SessionHandle {
+  readonly id: string;
+  prompt(text: string, options?: { readonly delivery?: Delivery }): Promise<PromptReceipt>;
+  snapshot(): Promise<SessionSnapshot>;
+  close(): Promise<void>;
+}
+
+interface PromptReceipt {
+  readonly task: TaskHandle;
+  readonly requestedDelivery: Delivery;
+  readonly effectiveDelivery: Delivery;
+  readonly paused?: true;
+  readonly blockedByTaskId?: string;
+}
+
+interface TaskHandle {
+  readonly id: string;
+  readonly sessionId: string;
+  readonly result: Promise<TaskResult>;
+  snapshot(): Promise<TaskSnapshot>;
+  inspect(): Promise<TaskDetails>;
+  watch(options?: { readonly signal?: AbortSignal }): AsyncIterable<TaskSnapshot>;
+  responses(options?: {
+    readonly after?: string;
+    readonly signal?: AbortSignal;
+  }): AsyncIterable<CompleteResponse>;
+  cancel(): Promise<TaskSnapshot>;
+}
+
+interface TaskSummary {
+  readonly taskId: string;
+  readonly sessionId: string;
+  readonly state: TaskState;
+  readonly selectedHarness?: HarnessKind;
+  readonly title: string;
+  readonly ordinal: number;
+  readonly updatedAt: number;
+  readonly dispatchedAt?: number;
+  readonly failedAt?: number;
+  readonly finishedAt?: number;
+}
+interface WorkspaceInfo { readonly directory: string; readonly repository?: string }
+interface SessionSummary {
+  readonly sessionId: string;
+  readonly state: "open" | "closing" | "closed";
+  readonly paused: boolean;
+  readonly cwd: string;
+  readonly workspace: WorkspaceInfo;
+  readonly active?: TaskSummary;
+}
+interface SessionSnapshot extends SessionSummary { readonly queued: readonly TaskSummary[] }
+type TaskState = "queued" | "running" | "waiting" | "awaiting_approval"
+  | "completed" | "failed" | "cancelled" | "interrupted";
+type TerminalState = "completed" | "failed" | "cancelled" | "interrupted";
+interface ErrorInfo { readonly code: string; readonly message: string }
+interface CompleteResponse {
+  readonly responseId: string;
+  readonly text: string;
+  readonly state: TaskState;
+}
+interface TaskSnapshot extends TaskSummary {
+  readonly revision: number;
+  readonly parentTaskId?: string;
+  readonly children: readonly TaskSummary[];
+  readonly requests: readonly ApprovalRequest[];
+  readonly latestResponse?: CompleteResponse;
+  readonly error?: ErrorInfo;
+  readonly stopUnconfirmed: boolean;
+}
+interface TaskDetails extends TaskSnapshot { readonly prompt: string }
+interface TaskResult {
+  readonly taskId: string;
+  readonly sessionId: string;
+  readonly responseId: string;
+  readonly text: string;
+}
+```
+
+`createSession` validates and captures the definition and existing absolute working directory, but starts native execution lazily when work is dispatched. A prompt must contain non-whitespace text and fit the existing 1 MiB limit. `prompt` returns after admission or acceptance of steering, not after native startup or completion. Invalid admission rejects without creating a task. A native startup failure after admission is a failed task.
+
+`task.result` resolves only when the parent task reaches `completed`, after children, child-result delivery, and parent continuations finish. Its text comes from the final parent response, not the first waiting response, a child response, or concatenated history. Empty text is valid. Completion reports execution completion, not proof that the requested objective succeeded: an answer explaining a failing test can still be complete.
+
+Pending approvals and children keep the promise pending. A child failure that the parent handles does not automatically reject the parent's result. Execution failures reject with a safe `AgentError`; explicit cancellation rejects with `CANCELLED`, and interruption with `INTERRUPTED`. Detailed outcomes remain in snapshots, including `error` and `stopUnconfirmed`. First access to `result` starts observation and memoizes its promise. For a connected task, the coordinator atomically reads current state and registers the observer when it handles that request; the interval does not begin at the earlier JavaScript property-access time. An interval is the current execution through its next terminal state, or the terminal outcome already present at registration. It captures that first terminal outcome even if private recovery occurs before awaiting code resumes; a failure already superseded before registration is not observed retroactively. Embedded observation uses the equivalent atomic in-process boundary. Repeated awaits reuse that promise; a connected transport rejection is not the retained server task outcome. Reconnect and obtain a fresh handle to observe again after connection loss. Settled results and ended iterators never reopen. A previously settled result promise stays settled after client disconnect; first result access on a disconnected handle rejects with `COORDINATOR_UNAVAILABLE`. Snapshot/inspection reads always show current state; a fresh watch or response iterator starts a new observation, while retained response replay remains cursor-based. An unused result promise must not produce an unhandled-rejection side effect; explicitly awaiting it still rejects on failure.
+
+`watch` immediately yields a snapshot, then coalesces changes for slow readers and ends after a terminal snapshot. Snapshots expose `state`, `latestResponse`, direct `children`, and pending `requests` throughout the descendant tree. They preserve existing task states and ownership. `responses` yields every retained complete response in order and then waits for more until termination. Both are optional observers; neither drives execution or acknowledges managed child-result delivery.
+
+### Unified approval types
+
+Applications receive the actions available for each request and submit the selected action's opaque ID. Normalized decisions and scopes describe actions for presentation; they are not response payloads. Adapters translate the selected action into its exact native response, so applications do not branch on `harness`.
+
+```ts
+type ApprovalScope = "once" | "turn" | "session";
+interface ApprovalResponse {
+  readonly actionId: string;
+  readonly grants?: readonly string[];
+}
+
+type ApprovalAction = {
+  readonly id: string;
+  readonly label: string;
+  readonly description?: string;
+} & (
+  | { readonly decision: "allow" | "deny"; readonly scope: ApprovalScope }
+  | { readonly decision: "cancel"; readonly scope?: never }
+);
+
+interface ApprovalGrant {
+  readonly id: string;
+  readonly label: string;
+  readonly description?: string;
+}
+
+interface ApprovalRequest {
+  readonly id: string;
+  readonly taskId: string;
+  readonly sessionId: string;
+  readonly harness: HarnessKind;
+  readonly message: string;
+  readonly actions: readonly ApprovalAction[];
+  readonly grants?: readonly ApprovalGrant[];
+  readonly context?: Readonly<Record<string, unknown>>;
+}
+```
+
+`id` is the SDK name for the existing request identifier. An action ID is opaque, stable and unique within its request, including across clients observing that request. The application submits it as `actionId`; it is not a native decision string. Distinct native choices retain distinct IDs even when their normalized decision and scope match. Labels and optional descriptions explain the actual operation or permission coverage and reuse duration. A description is required when the label alone cannot communicate a material difference. Optional `context` contains bounded display information about the native operation, not instructions or authority.
+
+| Action metadata | Meaning |
+| --- | --- |
+| Allow once | Permit the requested operation once. |
+| Allow for this turn | Permit the offered grants for the current native turn, which can be shorter than the coordinated task. |
+| Allow for this session | Reuse the offered permission within the originating native conversation, not globally, permanently, or across child sessions. |
+| Deny once | Reject this operation using native denial semantics; the agent may continue. |
+| Deny for this turn/session | Reuse the offered denial for the stated native turn/conversation when supported. For fx, an offered `reject_always` is session-scoped denial. It is not silently reduced to denial once. |
+| Cancel | Select a native cancellation option, only when explicitly offered; its effect follows that operation's native semantics. This is distinct from `task.cancel()`. |
+
+Only an action ID belonging to the original request is accepted. The coordinator resolves its native mapping from the retained request; caller-supplied labels, decisions, scopes, native payloads, and other extra fields are rejected. An unknown action or invalid grant selection returns `INVALID_APPROVAL_RESPONSE` and leaves a pending request unanswered. A denied operation does not automatically cancel its task. Native policies still determine whether a request can appear; hard sandbox denials cannot be approved.
+
+If the request's `grants` is absent, submit only `actionId`; a response containing `grants` is invalid. If the request's `grants` is present, selecting an allow action requires an explicit `grants` array, including `[]` when selecting none. Deny/cancel selections accept no grants. Nothing is preselected or silently granted. Grant IDs are opaque, request-local references to the adapter's immutable permission groups, not caller-defined filesystem paths or profiles. Related restrictions remain grouped so selecting a subset cannot accidentally broaden a permission. Only listed IDs, without duplicates, are valid. Grant order has no semantic meaning: validated selections are canonicalized in the request's grant order before native translation and idempotency comparison.
+
+Adapters own exact native mappings and expose the supported choices they can faithfully execute. Unrepresentable native requests fail with `INPUT_REQUIRED` rather than receiving fabricated semantics. Reusable denial and distinct native options are preserved through separate action IDs. The v1 boundary retains original tool arguments and excludes persistent settings changes. Permission approval, argument editing, answering a question, and accepting a plan remain distinct interactions; this API covers permission approval only.
+
+`runner.respond` and `client.approvals.respond` acknowledge validated answer submission, not operation completion. They preserve [approval ownership and lifecycle rules](approvals.md): withdrawal races cannot cause late allows; identical answers remain idempotent while retained; conflicting answers fail with `INVALID_APPROVAL_RESPONSE`; withdrawn requests return `REQUEST_EXPIRED`, and unknown request IDs return `UNKNOWN_REQUEST`. No automatic answer or timeout grant is introduced, including when a UI disconnects. Existing schema/size limits and retention of 1,024 settled records remain. SDK normalization does not require changing CLI or hosted-agent tool wire formats; those entry points and SDK action selection resolve the same native requests.
+
+The normalization covers the existing adapters without extending their native permission capabilities. Codex maps supported command/file choices and turn/session grants; Claude maps allow-once, conditional session reuse, and denial; fx maps its offered ACP choices including session denial. OpenCode maps its existing `once`/`reject`, Copilot its `approve-once`/`reject`, and Cursor subscription ACP its offered once-only choices. Cursor API-key SDK execution retains its documented lack of an interactive permission callback. Constructor support does not imply every access route can emit every action.
+
+### Ownership and transport boundaries
+
+Discovery precedence is explicit `ConnectOptions.stateDirectory`, then `AGENT_STATE_DIR`, then `~/.subharness/state/shared`. Explicit paths must be nonempty absolute local paths and are canonicalized. The CLI uses the same environment/default selection rule; installation location and cwd do not create separate default coordinators. Endpoint metadata is owner-private, with a private authentication token and loopback-only transport. Invalid state-directory or endpoint configuration rejects with `INVALID_CONFIG`.
+
+The handshake validates the endpoint's coordinator instance ID, SDK protocol version `1`, and the `sdk-v1` capability; the private CLI bridge additionally requires `cli-v1`. Package versions need not match. A missing/incompatible protocol or required capability rejects with `COORDINATOR_INCOMPATIBLE`; authentication rejection uses `COORDINATOR_AUTH_FAILED`. Missing strict-attachment targets and uncertain reachability use `COORDINATOR_UNAVAILABLE`. A live incompatible or unreachable coordinator is never replaced to make connection succeed.
+
+`connect()` defaults to start-or-connect; `start: false` never starts. The entire discovery, health check, handshake, and startup path has a 15-second deadline, including attachment without startup. Final confirmation may add at most one second for unpublished-candidate retirement and 250 milliseconds for a final endpoint check. The final check distinguishes a candidate that published at the deadline from one that retired, without replacing uncertain execution. Attach/health/handshake deadline failures use `COORDINATOR_UNAVAILABLE`; startup failure uses `STARTUP_FAILED`. Neither path can wait indefinitely.
+
+Exclusive startup ownership serializes contenders for the selected directory. Under that ownership, absence is established only when endpoint metadata is missing, or when a well-formed stale record names an owner PID proven nonexistent and its endpoint is not responsive. A live owner, unknown owner state, permission-denied PID check, connection refusal, or timeout alone is not proof of absence and yields `COORDINATOR_UNAVAILABLE`. Malformed metadata is `INVALID_CONFIG`. A responsive endpoint with authentication or protocol mismatch returns the corresponding explicit error above; instance mismatch returns `COORDINATOR_UNAVAILABLE`. None is treated as absence.
+
+A candidate process may be spawned to acquire startup ownership, but it must prove absence under that ownership before starting/publishing a shared service. The winner publishes one authenticated endpoint atomically. Losers connect to that instance and retire only their own unpublished candidate. Failure to confirm candidate retirement is reported without killing or replacing a process that might have published. Starting a coordinator creates no agents, and the coordinator survives client disconnect and application exit.
+
+Embedded `runner.session(id)` and `runner.task(id)` remain synchronous local lookups. Connected `get` methods verify existence asynchronously. All snapshot and inspection methods return promises. Unknown IDs fail rather than constructing records. Connected handles remain bound to the validated coordinator instance and never silently switch after replacement.
+
+`client.disconnect()` releases client resources and invalidates its handles without stopping the coordinator or changing tasks or pending approvals. Transport failure rejects affected reads/observations with safe errors such as `COORDINATOR_UNAVAILABLE`; explicit observer signal cancellation uses `OBSERVATION_CLOSED`. Neither implies task cancellation. `task.cancel()` retains confirmed-stop semantics in both modes, including descendant handling and `CANCEL_FAILED` on uncertain stop. `session.close()` explicitly closes execution for that session; `runner.close()` closes all locally owned sessions. Successful closes are idempotent; failed embedded cleanup retains ownership for retry. Application tool callbacks are drained, not force-stopped.
+
+There are no automatic mutation retries or public idempotency keys in this version. Losing a creation/prompt/control acknowledgement leaves its outcome uncertain; it is not proof of nonadmission. The application reconnects and inspects authoritative state before deciding what to do, without claiming inspection can always identify the lost operation. Reads and observers can be reissued explicitly against the same instance; automatic transport reconnection is not promised. Approval resubmission retains its separately documented identical-answer idempotency.
+
+## One library for SDK and CLI
+
+The CLI consumes the same library connection, discovery, admission, observation, and control core. Its argument parsing, prompt-file/stdin reading, text/JSONL rendering, truncation, and dashboard grouping remain presentation concerns. It does not maintain a parallel direct-HTTP client. A private bridge preserves CLI semantics that are intentionally absent from ordinary application handles.
+
+| Private operation | Preserved behavior |
+| --- | --- |
+| Catalog and readiness | Ordinary top-level CLI `list`/`check` use the same library helpers behind `client.agents` without requiring or starting a coordinator. Managed calls carrying `AGENT_PARENT_TOKEN` must first attach to the existing coordinator, validate the active parent, and narrow the child capability before discovery/check. Validation failure never falls back to external-owner authority. Definition loading and disposable readiness startup keep their existing side effects. |
+| Atomic `run` | Resolve/capture the target, environment, and first prompt before publishing one session and its first task together. Invalid input publishes neither; native failure after admission becomes task failure. It is not two independently visible public calls. |
+| Attached run/send and `wait` | Use a one-observation helper returning the existing response, approval, or terminal record. Preserve response-cursor precedence, detach boundaries, and steering acknowledgement. Do not replace first-response waiting with final `task.result`. |
+| Managed delegation | Bind the active parent capability out-of-band. Preserve declared-child discovery, lineage, maximum depth, self/ancestor restrictions, and strict-descendant authority. The public client neither accepts raw parent tokens nor infers them from environment variables. |
+| Managed wait acknowledgement | Only the private active-parent observation path acknowledges delivered terminal child results under existing rules. Public result/watch/replay never perform that coordination effect. |
+| CLI `resume` | Retain the private operation and receipt/observation compatibility with a fresh observation scope. Codex, Claude Code, and fx all reject prompt-free native recovery with `RECOVERY_UNSUPPORTED`; no public resume method or successful recovery guarantee is added. |
+| Status and queue | Preserve the existing status response projection: default response text is sliced to 4,000 characters with its truncation flag, while `--full` returns the complete response. Queue descriptions remain the raw admission prompt's first 120 characters (`prompt.slice(0, 120)`), with existing active/queued records and paused state. Normalized public titles are not a substitute for this CLI output. |
+| Dashboard inspection | Derive summaries and expanded detail from the common records; keep terminal-specific grouping, truncation, and efficient private payload formatting outside the public model. |
+
+CLI connection policy stays command-specific: `run` can start the coordinator; follow-up, observation, and control commands attach only. An absent coordinator leaves the dashboard in its existing waiting view without auto-start. These policies use the shared connection implementation, not a second transport.
+
+Private recovery does not reset a settled promise or reopen an ended iterator. Its fresh observation scope is registered at the accepted recovery boundary, so it observes the current retained task from that boundary without a later registration race. A fresh public `get` yields a fresh handle; the old handle's snapshot remains a current-state read, but its previously accessed result stays settled. There are no public attempt IDs, automatic prompt replay, or restart recovery. Cancelling retained failed work releases a paused queue only after stop is confirmed.
+
+Connected direct harness strings preserve native defaults. Existing public harness constructors retain their required model field. The private CLI bridge keeps its existing direct `HarnessRequest` support for flags such as effort without a model; that CLI compatibility does not require adding another public configuration type. Public connected calls are external-owner operations under local coordinator authentication; applications still enforce their own user/chat authorization.
+
+## SDK and coordinator compatibility
+
+CLI syntax and documented output, waiting, and control behavior remain supported through the private bridge.
+
+The new shared directory does not scan, migrate, or terminate older installation-specific coordinators. Explicit `stateDirectory` or `AGENT_STATE_DIR` can select an old directory, but connection still requires the new handshake. Incompatible old work remains owned by its old coordinator and can be inspected or finished with the matching old CLI. No existing task IDs are imported into a new instance, and a new empty coordinator is never presented as restored execution.
+
+## Embedded configuration and cleanup
+
+Construction validates options synchronously and starts no native processes or listeners. Unknown option fields are invalid. An omitted `env` copies `process.env` at construction. A supplied `env` replaces, rather than merges with, that environment; values must be strings or undefined. Inherited Subharness launcher/parent/state variables are removed from native SDK sessions so they cannot attach to an unrelated CLI parent. The SDK never assigns to `process.env` or changes the host's working directory.
+
+Native adapter dependencies are loaded only when selected. Claude's SDK operations run in a private per-session worker with a copied environment so dependency initialization cannot change the application's environment. Tool schemas and callbacks remain in the application process with their original identities. The host continues to own native-process termination and callback draining; a worker exit does not establish that a session has stopped. This internal boundary follows the [native adapter contract](adapter-contract.md).
+
+Access is copied and validated at construction. Provider, endpoint, and wire-protocol fields retain the per-harness requirements and restrictions in [access configuration](access-config.md); exposing a field in the union does not enable it for every harness. Omission preserves the native access defaults defined in [access configuration](access-config.md); an explicit empty array disables a harness. Embedded runners do not read CLI personal settings. An explicit selection uses the existing [connection rules](access-config.md), including empty-array disablement, ordered pre-submission fallback, variable/file references, and OIDC validation. The SDK does not implicitly read personal settings or modify Git excludes. Relative credential-file/project paths retain their existing resolution against the main checkout or project root. Agent definitions do not contain credentials.
+
+SDK access diagnostics identify the runner's explicit access selection or native discovery. They do not tell applications to configure a CLI personal settings file that the runner does not read.
+
+Embedded definitions and their child graphs are captured structurally when creating a session; tool functions and schema objects retain their identity. Later changes to caller-owned maps or harness options do not change admitted configuration. Application objects captured by closures remain live. Embedded admission does not perform Git discovery for dashboard metadata.
+
+`cancel` stops the target and its recorded descendants, removes affected queued tasks, waits for native execution and admitted callbacks to stop, and preserves unrelated queued work. Cancellation does not roll back file/tool effects. Failed confirmation rejects with `CANCEL_FAILED`, retains `stopUnconfirmed: true`, and pauses dispatch. Repeated cancellation of confirmed terminal work returns its current snapshot.
+
+`session.close` immediately stops new admission to that session, cancels its active and queued tasks and their recorded descendant tasks, then closes its native resources. Independently queued work in another session survives. A closed session remains inspectable. `runner.close` immediately stops all admission, closes all its sessions, retires pending approvals, and settles pending observations. Queued/active tasks become cancelled after confirmed stop; previously terminal responses and outcomes remain intact. Startup racing with close must be awaited and cleaned; it cannot publish an unowned process or submit a model turn after close begins.
+
+Concurrent closes share one cleanup attempt. A successful close is idempotent. A failed close rejects with an `AggregateError` of safe `AgentError` entries, retains ownership of uncertain resources, and permits a subsequent close to retry cleanup; admission stays closed. No cleanup failure is silently swallowed. Read-only snapshots and retained response observations remain available after close. Unknown native or callback details are not copied into public failure messages.
+
+Host custom tools keep the existing `execute(input)` signature. They run in the application's unchanged working directory and environment; use explicit paths or captured services. They are trusted application code and are not restricted by a native harness sandbox. Callback admission is limited to the active native turn. Cancellation first retires managed waits, then stops native work and drains admitted callbacks. An arbitrary JavaScript callback cannot be force-stopped; uncooperative tools can delay cancellation or close indefinitely. There is no implicit timeout or new callback cancellation-context argument.
+
+The SDK exports `AgentError` and `ErrorInfo`. Input/lookup/control errors reject calls; execution failure after admission is task data. Existing error codes remain in use. `RUNNER_CLOSED` and `SESSION_CLOSED` identify closed-owner admission/control attempts; reads and close retries remain available. `cancel` on terminal work is still an inspection even after close. Unknown option/input shapes reject with `INVALID_ARGUMENT`, invalid definitions with `INVALID_DEFINITION`, and invalid access configuration with `INVALID_CONFIG`.
+
+## Contract boundaries
+
+Connected and embedded execution share the session, task, and approval contracts above. Native adapters retain their documented capability limits; the SDK does not add a model loop or native permission system.
+
+No public native recovery, collection watch, automatic mutation retry, public idempotency keys, arbitrary remote endpoints, closure transfer, or restart persistence is promised. Polling, per-task observation, explicit connection failure, and breaking-release migration are the defined behavior. Original tool input and the exclusion of persistent settings changes remain approval limits; applications own the UI layout.
+
+## Hosted delegation
+
+Inline `subagents` declarations are supported. The embedded SDK prepares native custom tools for declared children in the application process, without creating CLI launchers or a coordinator HTTP service. The prepared native definition contains those tools instead of a native-facing `subagents` descriptor; this explicitly avoids CLI shell permission grants. The retained original graph authorizes child selection. Agents without declared children receive no hosted delegation tools. Existing CLI delegation is unchanged.
+
+The following reserved tool names are added only to SDK sessions that declare children. A collision with a custom tool name anywhere in an admitted graph rejects before execution. Tool input schemas reject unknown fields. Optional `cwd` defaults to the calling session directory and must be an existing absolute directory.
+
+The `agent_run` tool description lists each direct child's map key, display name, and description so the native parent can choose a specialist without prior knowledge of the graph. Its `agent` field enumerates those map keys. Child instructions, tools, and credentials are not included in that catalog.
+
+Failed hosted calls expose the safe library error code in the native tool failure, allowing the parent to distinguish invalid lineage, unavailable identifiers, queue limits, and expired approvals. This applies only to SDK-owned delegation errors. Exceptions from application-defined tools retain the generic custom-tool failure behavior and do not expose arbitrary exception details.
+
+| Tool | Input | Output |
+| --- | --- | --- |
+| `agent_run` | `{ agent: string, prompt: string, cwd?: string }` | Admission `{ taskId, sessionId, state }`; `agent` is a direct subagent map key. |
+| `agent_send` | `{ sessionId: string, prompt: string, delivery?: "queue" \| "steer" \| "interrupt" }` | `{ taskId, sessionId, requestedDelivery, effectiveDelivery }`. |
+| `agent_wait` | `{ taskId: string, after?: string }` | Private response/approval_required/terminal observation records; native approval schemas are preserved. |
+| `agent_status` | `{ taskId: string }` | Private task snapshot with native approval request schemas. |
+| `agent_queue` | `{ sessionId: string }` | Private session snapshot. |
+| `agent_cancel` | `{ taskId: string }` | The confirmed Private task snapshot with native approval request schemas. |
+| `agent_respond` | `{ requestId: string, content: ApprovalContent }` | `{ requestId, answered: true }` after schema-valid submission. |
+
+Private binding identifies the active parent task; the model cannot provide parent identities. Run resolves only direct declarations. Existing identifier-based follow-up/observation behavior remains in effect; these tools are not an application-user authorization boundary. Self/ancestor-session follow-ups remain forbidden. `agent_wait` and `agent_cancel` reject the caller's active task or an ancestor with `INVALID_PARENT`: waiting for or stopping that task would wait for the executing callback itself. `agent_status` remains available for immediate inspection. `agent_respond` can answer only strict-descendant requests, preserving managed-parent authority. Native permissions and tool-deny policies remain authoritative.
+
+Child follow-ups belong to the invoking current parent task. Depth is limited to eight and session queue capacity to 100. A terminal child result returned by `agent_wait` through its active parent's managed tool interaction is acknowledged once. Snapshot inspection, including `agent_status`, and UI observation do not acknowledge delivery. Results arriving after a pending parent response continue that same task and native conversation. Parent failure/cancellation retires managed waits and propagates to descendants. Stale tools cannot admit work into a later parent task: their invoking task identity is fixed before asynchronous work and revalidated before mutation. Arbitrary public `runner.createSession` and `session.prompt` calls from an app tool are independent top-level work; they do not imply lineage.