@agent-compose/sdk 0.5.8 → 0.5.9

package/dist/types/runtime.d.ts

@@ -4,6 +4,7 @@
 import type { SandboxProvider } from "./sandbox.js";
 import type { AgentMessage } from "./protocol.js";
 import type { Processor, ProcessorContext, ToolCall } from "../processors/processor.js";
+import type { BoundaryPauseFn } from "../pause/pause-core.js";
 import type { RequestContext } from "../request-context/request-context.js";
 /** Configuration for a single MCP server. */
 export interface McpServerConfig {
@@ -28,6 +29,12 @@ export interface RuntimeOptions {
     /** Agent id and label for processor context / adapter logs. */
     agentId?: string;
     iteration?: number;
+    /** The run's pause boundary, threaded from the agent loop so a runtime-driven
+     *  pre-tool gate (e.g. the ACP `session/request_permission` path through
+     *  `gateToolCall`) can raise a human-approval `ctx.pause`. The runtime binds it
+     *  to the current `{ agentId, iteration }` when it builds a ProcessorContext.
+     *  Absent ⇒ a processor pause throws (no boundary; see `boundProcessorPause`). */
+    pause?: BoundaryPauseFn;
     /** Optional JSON schema for runtimes with native structured-output support. */
     outputFormat?: {
         type: "json_schema";

package/dist/types/sandbox-environment.d.ts

@@ -35,7 +35,7 @@
  */
 import type { SandboxProvider } from "./sandbox.js";
 import type { Workflow } from "../workflow-steps/types.js";
-import type { SnapshotConfig } from "./workflow-metadata.js";
+import type { SandboxResources, SnapshotConfig } from "./workflow-metadata.js";
 export interface SandboxEnvironmentDefinition {
     name: string;
     description?: string;
@@ -45,6 +45,11 @@ export interface SandboxEnvironmentDefinition {
      *  useful — an env with no snapshot can't be referenced as a
      *  `bootFrom` on another workflow). */
     snapshots?: SnapshotConfig;
+    /** Which substrate to build this environment on (and any sizing).
+     *  An env image is provider-specific — a snapshot captured on E2B
+     *  can't boot on Vercel and vice-versa — so building the E2B base/
+     *  agent-env requires `resources: { provider: "e2b" }`. */
+    resources?: SandboxResources;
 }
 /** Sugar over `defineWorkflow` for setup-only workflows that exist to
  *  capture a snapshot. The workflow takes no meaningful input and returns

package/dist/types/sandbox.d.ts

@@ -21,6 +21,36 @@ export interface SandboxCommandResult {
     stdout: string;
     stderr: string;
 }
+/** A spawned long-lived command with a writable stdin and readable stdout,
+ *  exposed as byte web-streams. Unlike `commands.run` (which buffers to
+ *  completion and exposes stdout only via an `onStdout` callback), a duplex
+ *  handle keeps the process alive and lets the caller WRITE to its stdin —
+ *  the half `commands.run` cannot provide. It is the transport the ACP client
+ *  (`AcpClientPeer` over `ndJsonStream`) needs: the agent CLI reads JSON-RPC
+ *  request frames on stdin and answers on stdout.
+ *
+ *  Only `makeLocalSandboxProvider` implements it. The runner runs IN the
+ *  sandbox VM and spawns CLIs via the local provider (a plain `child_process`
+ *  pipe), so a duplex stdin works identically on Vercel/E2B/local. The
+ *  vercel/e2b providers are the SERVER→sandbox view and never spawn the in-VM
+ *  CLI, so they leave `spawnDuplex` undefined and callers fall back cleanly. */
+export interface SandboxDuplexProcess {
+    /** Subprocess stdin. JSON-RPC request frames are written here. */
+    stdin: WritableStream<Uint8Array>;
+    /** Subprocess stdout. JSON-RPC response/notification frames arrive here. */
+    stdout: ReadableStream<Uint8Array>;
+    /** Resolves when the subprocess exits, carrying the captured stderr tail. */
+    exited: Promise<{
+        exitCode: number;
+        stderr: string;
+    }>;
+    /** Force-terminate the subprocess. */
+    kill(): void;
+}
+export interface SandboxSpawnDuplexOptions {
+    cwd?: string;
+    envs?: Record<string, string>;
+}
 /**
  * A sandbox provider implements the RAW provider operations only. It does NOT
  * implement transient-failure retry/backoff: reconnecting and snapshotting both
@@ -43,6 +73,11 @@ export interface SandboxProvider {
     cwd?: string;
     commands: {
         run(cmd: string, opts?: SandboxCommandRunOptions): Promise<SandboxCommandResult>;
+        /** Spawn a long-lived command with a real duplex stdin/stdout. OPTIONAL —
+         *  implemented only by `makeLocalSandboxProvider` (the in-VM `child_process`
+         *  view). The vercel/e2b providers (server→sandbox) leave it undefined; an
+         *  ACP caller that finds it absent falls back to the JSONL transport. */
+        spawnDuplex?(cmd: string, opts?: SandboxSpawnDuplexOptions): SandboxDuplexProcess;
     };
     files: {
         write(path: string, content: string): Promise<void>;
@@ -60,12 +95,12 @@ export interface SandboxProvider {
         snapshotId: string;
         sizeBytes?: number;
     }>;
-    /** Replace the live sandbox's egress policy in place. Vercel implements
-     *  it via `sandbox.update({ networkPolicy })` (2.x) so the server can
-     *  push a freshly resolved policy — with re-minted connector access
-     *  tokens — before each step instead of relying on the policy baked at
-     *  create. Providers whose enforcement lives inside the VM (E2B
-     *  iron-proxy) leave it undefined. */
+    /** Replace the live sandbox's egress policy in place — so the server can
+     *  push a freshly resolved policy (with re-minted connector access tokens)
+     *  before each step instead of relying on the policy baked at create.
+     *  Vercel implements it via `sandbox.update({ networkPolicy })` (2.x); E2B
+     *  via its native `sandbox.updateNetwork(...)`. Providers without a live
+     *  network-update primitive leave it undefined. */
     updateNetworkPolicy?(policy: SandboxNetworkPolicy): Promise<void>;
 }
 /** Stateless provider-level snapshot deletion — no live sandbox needed,

package/dist/types/workflow-metadata.d.ts

@@ -8,8 +8,13 @@
  * Keep this module free of value imports from `types/workflow.ts` or
  * `workflow-steps/workflow.ts` — it is the cycle-break point.
  */
-import type { SandboxNetworkPolicy, SandboxSize } from "../sandbox.js";
+import type { SandboxNetworkPolicy, SandboxSize, SandboxProviderName } from "../sandbox.js";
 import type { Processor } from "../processors/processor.js";
+/** The sandbox providers selectable per-workflow. A narrowing of
+ *  `SandboxProviderName` to the two substrates that execute step workloads —
+ *  `e2b-desktop` (registry-only, never a workflow's runtime) is deliberately
+ *  excluded so a workflow can only ask for a substrate that actually runs steps. */
+export type WorkflowSandboxProvider = Extract<SandboxProviderName, "vercel" | "e2b">;
 /**
  * Workflow-level metadata read by the server at registration. Lives on
  * every `Workflow` as `workflow.metadata`, regardless of which form of
@@ -75,11 +80,14 @@ export interface IOSchema {
 /** Alias kept for backwards source-compatibility with the original
  *  output-only release. New code should prefer `IOSchema`. */
 export type OutputSchema = IOSchema;
-/** Per-connector HTTP request matcher (Tier-2 capability narrowing). The
- *  iron-proxy / firewall consults these when deciding whether to attach the
- *  brokered Authorization header to an outbound request. A request to the
- *  connector host whose method is not in `methods`, or whose path matches no
- *  entry in `pathPrefixes`, is refused (403) and the token is WITHHELD. */
+/** Per-connector HTTP request matcher (Tier-2 capability narrowing). Vercel's
+ *  firewall consults these when deciding whether to attach the brokered
+ *  Authorization header to an outbound request: a request to the connector
+ *  host whose method is not in `methods`, or whose path matches no entry in
+ *  `pathPrefixes`, goes out WITHOUT the token. NOT enforced on E2B — its
+ *  native rules carry only a header transform, no method/path matcher, so the
+ *  token rides every request to an allowed connector host there (the host
+ *  allowlist still confines which hosts are reachable). See `toE2bNetwork`. */
 export interface ConnectorRequestRules {
     /** Allowed HTTP methods (upper-case). Omit = any method (subject to
      *  `access`). */
@@ -138,10 +146,19 @@ export interface InvokePolicy {
  *  today; kept as its own object so finer controls (disk, gpu, …) can be
  *  added later without reshaping `WorkflowMetadata`. */
 export interface SandboxResources {
-    /** Machine size — `small | medium | large`. Maps to provider specs at
-     *  create time (Vercel: 2 / 4 / 8 vCPU, 2048 MB RAM per vCPU). Omit →
-     *  `"small"`. E2B sizing is template-defined and ignores this. */
+    /** Machine hardware SKU — one of the `SandboxSize` vCPU strings
+     *  (`2vcpu-4gb` | `4vcpu-8gb` | `8vcpu-16gb` | `32vcpu-64gb`). Maps to
+     *  provider specs at create time (Vercel: 2 / 4 / 8 / 32 vCPU, 2048 MB RAM
+     *  per vCPU). Omit → the smallest SKU. E2B sizing is template-defined and
+     *  ignores this. */
     size?: SandboxSize;
+    /** Sandbox provider this workflow's runs execute on — `"vercel"` or
+     *  `"e2b"`. Optional and additive: omit and the run resolves to the
+     *  platform default (`vercel`). Set explicitly to pin a workflow to a
+     *  substrate regardless of the deployment default. Snapshot formats are
+     *  provider-specific, so the resolved provider is stamped on the run row
+     *  at first dispatch and reused across pause/resume/replay. */
+    provider?: WorkflowSandboxProvider;
 }
 export interface WorkflowMetadata {
     /** One-line, human-readable description of what the workflow does.
@@ -163,7 +180,8 @@ export interface WorkflowMetadata {
     outputSchema?: IOSchema;
     /** All snapshot config — boot source + capture mode. */
     snapshots?: SnapshotConfig;
-    /** Sandbox machine resources (size). Optional; omit → small. */
+    /** Sandbox machine resources — size + provider. Optional; omit → smallest
+     *  SKU on the platform-default provider (`vercel`). */
     resources?: SandboxResources;
     processors?: readonly Processor[];
     /** Connector requirements — providers whose APIs this workflow calls.
@@ -176,6 +194,18 @@ export interface WorkflowMetadata {
     /** Tier-1 invoke ACL — who may dispatch this connector-brokering workflow.
      *  See `InvokePolicy`. */
     invokePolicy?: InvokePolicy;
+    /** Set by `defineSandboxEnvironment` to mark this workflow as an ENVIRONMENT
+     *  BUILD — a setup-only workflow whose job is to leave its VM configured and
+     *  snapshot it (base-env / agent-env). Environment builds build a platform
+     *  IMAGE and never use the shared factory drive, so the server SKIPS mounting
+     *  /factory for them: a live Archil mount baked into the captured snapshot
+     *  fails the NEXT boot's re-mount ("an older Archil process is still running
+     *  for this mountpoint"), degrading /factory for every workflow booting from
+     *  that snapshot. Absent on ordinary workflows — which mount /factory exactly
+     *  as before. Optional + additive: an ABSENT flag contributes nothing to the
+     *  canonical metadata hash (frozen-metadata rule), so existing workflows are
+     *  not forced to re-register. */
+    environmentBuild?: boolean;
 }
 /**
  * Pull the server-readable declarations off a source object (run-form

package/dist/types/workflow.d.ts

@@ -41,9 +41,16 @@ export interface WorkflowCtx<TInput extends Record<string, unknown> = Record<str
     /** Persist key-value metadata on the run record (e.g. prUrl, planUrl). */
     setMetadata: (data: Record<string, unknown>) => Promise<void>;
     /**
-     * Wrap a named step for observability. Emits step_started / step_completed /
-     * step_failed lifecycle events with duration. Use for long phases you want
+     * Durable named step (ADR-0012). Runs `fn` once and memoises its result to
+     * the sandbox state-dir; on a pause-resume re-entry the recorded value is
+     * returned and `fn` is NOT re-run (a duration-0 "restored" sub-step). Also
+     * emits substep_started / substep_completed / substep_failed lifecycle
+     * events with duration — use for long phases you want both durable and
      * visible on the run's timeline (setup, external API calls, submit).
+     *
+     * Names must be unique within a step body (they key the memoise file).
+     * A body that pauses is never memoised — the resume re-runs it. For
+     * cross-process side effects (DB writes, emails) use `invokeChild`.
      */
     step<T>(name: string, fn: () => Promise<T>): Promise<T>;
     /** Pass to `agent({ events: ctx.agentEvents })` to stream agent lifecycle events. */
@@ -101,10 +108,12 @@ export interface WorkflowDefinition<TOutput = unknown, TInput extends Record<str
      */
     snapshots?: SnapshotConfig;
     /**
-     * Sandbox machine size — `small` (default) | `medium` | `large`. Maps to
-     * provider machine specs at create (Vercel: 2 / 4 / 8 vCPU, 2048 MB RAM
-     * per vCPU). Optional; omit for `small`. E2B sizing is template-defined
-     * and ignores this. Per-invocation `invoke({ size })` overrides it.
+     * Sandbox resources — machine SKU (`size`, a `SandboxSize` vCPU string:
+     * `2vcpu-4gb` | `4vcpu-8gb` | `8vcpu-16gb` | `32vcpu-64gb`) and `provider`
+     * (`vercel` | `e2b`). `size` maps to provider machine specs at create
+     * (Vercel: vCPUs, 2048 MB RAM per vCPU); E2B sizing is template-defined and
+     * ignores it. Optional; omit → smallest SKU on the default provider.
+     * Per-invocation `invoke({ size })` overrides the size.
      */
     resources?: SandboxResources;
     /**
@@ -178,6 +187,13 @@ export interface WorkflowDefinition<TOutput = unknown, TInput extends Record<str
      * invokePolicy: { users: "owner", workflows: ["nightly-orchestrator"] }
      */
     invokePolicy?: InvokePolicy;
+    /**
+     * Internal — set by `defineSandboxEnvironment`, not by workflow authors.
+     * Marks the workflow as an environment build (base-env / agent-env) so the
+     * server skips mounting the shared factory drive for its runs (#13). See
+     * `WorkflowMetadata.environmentBuild`.
+     */
+    environmentBuild?: boolean;
 }
 /**
  * Declare a workflow. Two forms; both return a `Workflow` whose

package/dist/utils/bundler.d.ts

@@ -84,7 +84,8 @@ export interface BundledWorkflow {
     /** Snapshot config from the workflow definition — `bootFrom` (where to
      *  restore at run start), `save`, `retain`. */
     snapshots?: SnapshotConfig;
-    /** Sandbox machine size declared via `defineWorkflow({ resources: { size } })`. */
+    /** Sandbox resources declared via `defineWorkflow({ resources })` — machine
+     *  SKU (`size`) and `provider` (`vercel` | `e2b`). */
     resources?: SandboxResources;
     workflowPlan: WorkflowPlan;
     /** Compact JSON-Schema-shaped description of the workflow's input
@@ -100,6 +101,9 @@ export interface BundledWorkflow {
     /** Tier-1 invoke ACL — who may dispatch this connector-brokering
      *  workflow (`defineWorkflow({ invokePolicy })`). */
     invokePolicy?: InvokePolicy;
+    /** Set by `defineSandboxEnvironment` — marks an environment build so the
+     *  server skips the /factory mount for its runs (#13). */
+    environmentBuild?: boolean;
 }
 /**
  * Parse the bundled source and assert the default export is a CallExpression

package/dist/workflow-steps/observability.d.ts

@@ -31,13 +31,19 @@
 import type { AgentLifecycleEvent } from "../agent/agent-loop.js";
 import type { AgentEventSink } from "../types/workflow.js";
 import type { LiveAgentEventEmitter } from "./run-callback.js";
+import type { ScopedMemoize } from "../pause/checkpoint.js";
 /** One named sub-step (from `ctx.step("name", async () => ...)`).
- *  Becomes a `workflow_substep_*` lifecycle event on the run timeline. */
+ *  Becomes a `workflow_substep_*` lifecycle event on the run timeline.
+ *
+ *  `restored` is the durable-step resume case (ADR-0012): the body did NOT
+ *  re-run — its memoised result was read from the state-dir checkpoint a
+ *  prior subprocess wrote. Always `durationMs: 0` (no work happened this
+ *  pass) and never carries `error`. */
 export interface SubStepEvent {
     name: string;
     startedAt: number;
     durationMs: number;
-    status: "completed" | "failed";
+    status: "completed" | "failed" | "restored";
     /** Present when status="failed" — the user error's message. */
     error?: string;
 }
@@ -64,14 +70,34 @@ export declare class StepObservabilityCollector {
     private events;
     private subSteps;
     private readonly liveEmitter?;
+    /** State-dir memoise bound to this step's `step<idx>` scope. Present in
+     *  the sandbox runner (durable `ctx.step`); absent in-process so unit
+     *  tests record observability without touching disk. */
+    private readonly memoize?;
+    /** Sub-step names already used in THIS step body. A durable `ctx.step`
+     *  memoises by name, so a reused name would alias two distinct bodies
+     *  onto one checkpoint file — guarded by throwing on reuse (ADR-0012). */
+    private readonly usedStepNames;
     /** Seqs of events the server confirmed via the live route. */
     private readonly ackedSeqs;
     /** Promises for in-flight live emits — awaited at snapshot time. */
     private readonly inFlight;
     constructor(opts?: {
         liveEmitter?: LiveAgentEventEmitter;
+        memoize?: ScopedMemoize;
     });
     readonly setMetadata: (data: Record<string, unknown>) => Promise<void>;
+    /**
+     * Durable named sub-step (ADR-0012). The body's result is memoised to the
+     * state-dir checkpoint keyed `step<idx>.<name>`; on a pause-resume re-entry
+     * the value is read from disk and `fn` is NOT re-run (recorded as a
+     * duration-0 `"restored"` sub-step). A body that PAUSES (PauseSignal)
+     * propagates BEFORE any memoise write — partial work is never stored, so
+     * the resume re-runs it.
+     *
+     * When no memoise store is wired (in-process tests), the body always runs
+     * and is recorded as a normal timed `"completed"` / `"failed"` sub-step.
+     */
     readonly step: <T>(name: string, fn: () => Promise<T>) => Promise<T>;
     readonly agentEvents: AgentEventSink;
     /** Wait for in-flight live emits to settle (or timeout) so the

package/dist/workflow-steps/types.d.ts

@@ -36,14 +36,18 @@ export interface StepContext<TInput = unknown> extends BaseExecutionContext {
      */
     setMetadata(data: Record<string, unknown>): Promise<void>;
     /**
-     * Wrap a named sub-step for observability. Emits
-     * `workflow_substep_started` / `workflow_substep_completed` /
-     * `workflow_substep_failed` lifecycle events on the run timeline with
-     * the measured `durationMs`. Use for long sub-phases inside one step
-     * (setup, external API call, submit).
+     * Durable named sub-step (ADR-0012). Runs `fn` once and memoises its
+     * result to the state-dir checkpoint keyed `step<idx>.<name>`; on a
+     * pause-resume re-entry the value is read from disk and `fn` is NOT
+     * re-run. Emits `workflow_substep_started` /
+     * `workflow_substep_completed` / `workflow_substep_failed` lifecycle
+     * events on the run timeline with the measured `durationMs` — a restored
+     * sub-step reports `durationMs: 0` and status `"restored"`.
      *
-     * The block runs even if observability flushing fails — instrumentation
-     * never breaks the workflow.
+     * Names must be unique within one step body — they key the memoise file,
+     * so a reused name throws. A body that pauses (PauseSignal) is never
+     * memoised: the resume re-enters and re-runs it. For cross-process side
+     * effects (DB writes, emails) use `invokeChild`, not `step`.
      */
     step<T>(name: string, fn: () => Promise<T>): Promise<T>;
     /**

package/dist/workflow-steps/workflow.d.ts

@@ -46,8 +46,9 @@ export interface StepWorkflowDefinition<TInput, TOutput> {
     networkPolicy?: SandboxNetworkPolicy;
     placeholders?: Record<string, string>;
     snapshots?: SnapshotConfig;
-    /** Sandbox machine size — small (default) | medium | large. Vercel maps
-     *  it to vCPUs; E2B sizing is template-defined. Omit → small. */
+    /** Sandbox resources — machine SKU (`size`, a `SandboxSize` vCPU string)
+     *  and `provider` (`vercel` | `e2b`). Vercel maps `size` to vCPUs; E2B
+     *  sizing is template-defined. Omit → smallest SKU on the default provider. */
     resources?: SandboxResources;
     processors?: readonly Processor[];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-compose/sdk",
-  "version": "0.5.8",
+  "version": "0.5.9",
   "description": "Client library for agent-compose — define agents, runtimes, and workflows, and invoke them against an agent-compose server.",
   "license": "MIT",
   "repository": {
@@ -60,13 +60,14 @@
     "vitest": "^3.0.0"
   },
   "dependencies": {
+    "@agentclientprotocol/sdk": "0.29.0",
     "@anthropic-ai/claude-agent-sdk": "^0.2.129",
     "@babel/parser": "^7.29.3",
     "@babel/types": "^7.29.0",
     "@e2b/desktop": "^1.1.2",
     "@vercel/sandbox": "^2.2.0",
     "ai": "^6.0.175",
-    "e2b": "^2.3.0",
+    "e2b": "2.30.5",
     "ofetch": "^1.5.1",
     "openai": "^6.33.0",
     "p-retry": "^6.2.0",

package/src/agent/agent-context.ts

@@ -81,11 +81,19 @@ Use \`/ac:generate-workflow\` / \`/ac:generate-agent\` to scaffold, then
 
 ## Pausing to ask the human — \`agentc pause\`
 
-When you can't or shouldn't proceed without a human, run \`agentc pause\`. It
-blocks until they answer on the dashboard, then prints their answer to stdout:
+When you can't or shouldn't proceed without a human, run \`agentc pause\`, then
+**END YOUR TURN**:
 
-    ANSWER=$(agentc pause --reason "Notion returned 401 — connect Notion to continue" \\
-                          --option retry --option skip)
+    agentc pause --reason "Notion returned 401 — connect Notion to continue" \\
+                 --option retry --option skip
+
+\`agentc pause\` does NOT block and does NOT print the answer. It records your
+question and returns immediately. The moment you end your turn, the run pauses
+(your sandbox is snapshotted and compute stops while the human decides) and the
+human's answer is delivered to you as your **next message** — you pick up
+exactly where you left off, with the answer in hand. So: ask, end your turn,
+and wait. Do NOT keep working, do NOT call more tools, and do NOT mark the task
+complete after pausing.
 
 Reach for it the moment you hit — or foresee — any of these:
 - **A wall only a human can clear:** a 401/403, a missing credential, an
@@ -99,8 +107,8 @@ Reach for it the moment you hit — or foresee — any of these:
   several valid paths, a conflict with existing state, missing input only they have.
 
 You compose the \`--reason\` (the ask) yourself; pass \`--option\` choices when
-there are clear ones, omit them for a free-form answer. Read the printed answer
-and act on it. Each agent pauses independently — pausing doesn't stop the others.
+there are clear ones, omit them for a free-form answer. Each agent pauses
+independently — pausing doesn't stop the others.
 
 ## Credentials
 

package/src/agent/agent-loop.ts

@@ -9,11 +9,13 @@ import { AgentStatusSchema, parseAgentResponse } from "./protocol.js";
 import type { AgentStatus, AgentMessage } from "./protocol.js";
 import { randomUUID } from "node:crypto";
 import type { Processor, ProcessorContext } from "../processors/processor.js";
+import { boundProcessorPause, type BoundaryPauseFn } from "../pause/pause-core.js";
 import { runProcessorChain } from "../processors/runner.js";
 import { RequestContext } from "../request-context/request-context.js";
 import { PauseManager } from "../pause/manager.js";
 import { PauseSignal, isPauseSignal } from "../pause/pause-core.js";
 import { SteerDecisionSchema, type SteerDecision, type SteerPayload } from "./steer-control.js";
+import { type LocalPauseRequest } from "./local-pause-request.js";
 
 export const DEFAULT_CLAUDE_MODEL = "claude-fable-5";
 
@@ -55,7 +57,8 @@ export type AgentMessageSummary =
   | { type: "tool_result"; toolUseId: string; output: string; isError: boolean }
   | { type: "usage"; inputTokens: number; outputTokens: number; cacheReadTokens: number; cacheCreationTokens: number; durationMs: number; numTurns: number; model?: string }
   | { type: "done"; sessionId: string }
-  | { type: "error"; text: string };
+  | { type: "error"; text: string }
+  | { type: "plan"; entries: { content: string; priority: "high" | "medium" | "low"; status: "pending" | "in_progress" | "completed" }[] };
 
 function truncate(value: string): string {
   return value.length > MESSAGE_PREVIEW_CHARS ? `${value.slice(0, MESSAGE_PREVIEW_CHARS)}…` : value;
@@ -83,6 +86,11 @@ export function summarizeAgentMessage(msg: AgentMessage): AgentMessageSummary {
     };
     case "done": return { type: "done", sessionId: msg.sessionId };
     case "error": return { type: "error", text: truncate(msg.text) };
+    // ACP `plan` (WS-C / ADR-0020 Q2). Pure observability — forwarded to
+    // onAgentEvent / agent.message; it is NOT an AgentStatus and never feeds
+    // self-pause. Pass the entries straight through (the dashboard renders the
+    // structured plan; no preview truncation needed — entries are short).
+    case "plan": return { type: "plan", entries: msg.entries };
   }
 }
 
@@ -135,19 +143,24 @@ export interface AgentLoopOpts<TResponse = unknown> {
    * streaming input (ignored otherwise — handled at the runtime).
    */
   inbox?: import("./async-queue.js").AsyncQueue<{ text: string; senderName?: string | null }>;
-  /** PR 7 steer-pause: the boundary calls this to pause the workflow for a
-   *  human steer. agent() builds it (a corePause closed over runId/stepIndex);
-   *  the loop supplies the agentScope so the pauseId is stable across resume.
-   *  Absent ⇒ no steer pause (local tests, non-sandbox callers). */
-  pause?: <T = unknown>(
-    req: { reason: string; correlationKey?: string; schema?: z.ZodType<T> },
-    agentScope: { agentId: string; iteration: number },
-  ) => Promise<T>;
+  /** The run's pause boundary. agent() builds it (a corePause closed over
+   *  runId/stepIndex); the loop supplies the agentScope so the pauseId is
+   *  stable across resume. Drives both PR-7 steer-pause AND a processor's
+   *  `ctx.pause` (human-approval gate). Absent ⇒ no pause (local tests,
+   *  non-sandbox callers). */
+  pause?: BoundaryPauseFn;
   /** PR 7: take-once read of this agent's pending steer (set by the control
    *  poller). Returns the steer's payload (reason / correlationKey) or null.
    *  The boundary consumes it once per check, and only when no steer is
    *  already staged. */
   consumeSteerPending?: () => SteerPayload | null;
+  /** Take-once read of a local `agentc pause` request this agent dropped in the
+   *  state dir during its turn (the CLI writes it; see local-pause-request.ts).
+   *  Returns the request (reason + offered options) or null. The loop turns it
+   *  into a staged self-pause the next boundary takes — the same snapshot-release
+   *  path as `needs_input`, but triggered by an explicit `agentc pause` call so
+   *  it is honored regardless of `mode`. */
+  consumeLocalPauseRequest?: () => LocalPauseRequest | null;
   /** PR 7: `auto` (autonomous, default) or `hitl` (can be steer-paused). The
    *  boundary is inert unless `hitl`. */
   mode?: "auto" | "hitl";
@@ -180,6 +193,7 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
     retryCount:  0,
     agentId,
     iteration,
+    pause: boundProcessorPause(opts.pause, { agentId, iteration }),
   });
 
   if (!opts.runtime) throw new Error("agentLoop: opts.runtime is required");
@@ -191,6 +205,10 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
     processors,
     requestContext,
     agentId,
+    // Thread the pause boundary so a runtime-driven pre-tool gate (e.g. the ACP
+    // `session/request_permission` path through CliAgentRunner.gateToolCall) can
+    // raise a human-approval `ctx.pause`, not just on the loop's own hooks.
+    ...(opts.pause ? { pause: opts.pause } : {}),
     ...(opts.responseSchema ? { outputFormat: { type: "json_schema" as const, schema: z.toJSONSchema(opts.responseSchema) as Record<string, unknown> } } : {}),
   });
 
@@ -222,7 +240,7 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
   let resumed = false;
   // PR 7: a pending human steer-pause intent. Persisted in loop state so it
   // survives a resume and the boundary re-issues the pause on re-entry.
-  let pendingSteerPause: { reason: string; correlationKey: string | null; at: number } | null = null;
+  let pendingSteerPause: { reason: string; correlationKey: string | null; at: number; payload?: Record<string, unknown> } | null = null;
 
   const pauseManager = new PauseManager(agentId);
   const restore = await pauseManager.restoreAgentLoop<TResponse>(client);
@@ -342,6 +360,7 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
           {
             reason: pendingSteerPause.reason,
             ...(pendingSteerPause.correlationKey !== null ? { correlationKey: pendingSteerPause.correlationKey } : {}),
+            ...(pendingSteerPause.payload !== undefined ? { payload: pendingSteerPause.payload } : {}),
             schema: SteerDecisionSchema,
           },
           { agentId, iteration },
@@ -403,6 +422,11 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
       // (otherwise it restarts the task in a fresh session and repeats side effects).
       sessionId: lastSessionId ?? undefined,
       iteration: iteration + 1,
+      // Thread the loop's abort signal so a runtime that owns a cancellable
+      // transport (the ACP path's `session/cancel`, ADR-0020) actually unwinds
+      // when the loop aborts — input/output processor `abort`, or any external
+      // cancel. Without this the cancel/session-cancel wiring is dead.
+      signal: loopAbort.signal,
       ...(opts.inbox ? { inboxStream: opts.inbox } : {}),
     })) {
       // processOutput chain — deny drops the message from accumulation;
@@ -437,6 +461,31 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
     lastResponseText = responseText;
 
     let status = parseAgentStatus(responseText);
+
+    // `agentc pause` — the agent shelled out to the CLI during this turn, which
+    // dropped a durable pause-request marker in the state dir. Honor it like a
+    // self-pause: stage the pause the NEXT boundary takes, carrying the agent's
+    // question as the reason and any offered choices as the pause payload (the
+    // dashboard renders them as buttons). Checked BEFORE the settle / needs_input
+    // paths and independent of the <status> block — the common case is an agent
+    // that called the tool and ended its turn with no status at all, which would
+    // otherwise fall through to the empty-output re-prompt below. UNGATED by
+    // `mode`: an explicit `agentc pause` is a deliberate ask, not the `needs_input`
+    // heuristic that only `hitl` agents may trigger.
+    if (opts.pause && pendingSteerPause === null) {
+      const localPause = opts.consumeLocalPauseRequest?.() ?? null;
+      if (localPause) {
+        pendingSteerPause = {
+          reason:         localPause.reason,
+          correlationKey: null,
+          ...(localPause.options && localPause.options.length > 0 ? { payload: { options: localPause.options } } : {}),
+          at:             Date.now(),
+        };
+        blockerStreak = null;   // an explicit ask is not a stuck loop
+        continue;               // pause fires at the next boundary
+      }
+    }
+
     // Inline safeParse (instead of letting parseAgentResponse validate)
     // so a schema failure surfaces via lastResponseValidationError on
     // the next iteration — the model needs that feedback to fix its