@agent-compose/sdk 0.5.7 → 0.5.9

package/src/client.ts

@@ -14,10 +14,10 @@
 import { ofetch } from "ofetch";
 import { AgentComposeError } from "./errors.js";
 import { parseSseStream } from "./sse.js";
-import type { SandboxNetworkPolicy } from "./sandbox.js";
+import type { SandboxNetworkPolicy, SandboxSize } from "./sandbox.js";
 import type { RunEvent } from "./types/events.js";
 import type { WorkflowPlan } from "./types/workflow-plan.js";
-import type { SnapshotConfig, IOSchema, ConnectorRequirements, ConnectorOperationTag, InvokePolicy } from "./types/workflow-metadata.js";
+import type { SnapshotConfig, IOSchema, ConnectorRequirements, ConnectorOperationTag, InvokePolicy, SandboxResources } from "./types/workflow-metadata.js";
 import type { WorkflowManifest } from "./utils/bundler.js";
 
 /** UUID-v4-ish — matches the server-side predicate. Used to auto-detect
@@ -103,6 +103,9 @@ export interface RegisterWorkflowInput {
   /** All snapshot config — `bootFrom` (where to restore at run start),
    *  `save`, `retain`. See `WorkflowMetadata.snapshots`. */
   snapshots?: SnapshotConfig;
+  /** Sandbox machine resources — size + provider (template defaults).
+   *  See `WorkflowMetadata.resources`. */
+  resources?: SandboxResources;
   /** Provider-neutral execution plan detected by the CLI bundler. */
   workflowPlan?: WorkflowPlan;
   /** Connector requirements declared via `defineWorkflow({ connectors })`
@@ -119,6 +122,10 @@ export interface RegisterWorkflowInput {
   inputSchema?: IOSchema;
   /** Output schema extracted from the workflow's `output` zod schema. */
   outputSchema?: IOSchema;
+  /** Set by `defineSandboxEnvironment` — marks an environment build so the
+   *  server skips the /factory mount for its runs (#13). See
+   *  `WorkflowMetadata.environmentBuild`. */
+  environmentBuild?: boolean;
   /** Factory slug. Defaults to `"default"`. */
   factorySlug?: string;
 }
@@ -139,6 +146,10 @@ export interface InvokeWorkflowOptions {
    *  vars after brokering. Replaces the template-level placeholders for
    *  this run only — registered metadata is not mutated. */
   placeholders?: Record<string, string>;
+  /** Per-invocation machine-size override of the template's `resources.size`.
+   *  `small` (default) | `medium` | `large`; omit → the template default,
+   *  else `small`. Honoured on Vercel (→ vCPUs); E2B ignores it. */
+  size?: SandboxSize;
   /** Explicit parent run id. Pass `null` to suppress ambient RUN_ID auto-detection. */
   parentRunId?:  string | null;
   /** Agent loop inside the parent run that caused this invoke, when applicable. */
@@ -179,6 +190,56 @@ export interface ListTemplatesOptions {
   factorySlug?: string;
 }
 
+/** A human member of your team — the people an agent (or you) can @-flag. */
+export interface TeamMember {
+  /** Membership row id. */
+  id: string;
+  /** The user id — what you pass to `createMentions({ mentionedUserIds })`. */
+  userId: string;
+  role: string;
+  email: string;
+  name: string;
+  joinedAt: string;
+}
+
+/** A "you were flagged" ping, persisted server-side so it reaches the
+ *  mentioned teammate in their Workbench. */
+export interface Mention {
+  id: string;
+  factoryId: string;
+  mentionedUserId: string;
+  /** Who flagged: 'user' | 'api_key' | 'run' | 'system'. */
+  actorKind: string;
+  actorId: string | null;
+  actorLabel: string | null;
+  /** Where it lives: 'doc' | 'comment' | 'plan' | 'run'. */
+  contextKind: string;
+  contextPath: string | null;
+  /** Ready-made relative dashboard URL the Workbench card links to. */
+  contextUrl: string | null;
+  text: string;
+  runId: string | null;
+  seenAt: string | null;
+  resolvedAt: string | null;
+  createdAt: string;
+}
+
+export interface CreateMentionsInput {
+  /** Team-member user ids to flag (1–20). Discover them via `listMembers()`.
+   *  Non-members are dropped server-side. */
+  mentionedUserIds: string[];
+  /** The flag message shown in the teammate's Workbench. */
+  text: string;
+  contextKind: "doc" | "comment" | "plan" | "run";
+  /** Factory-relative file path or comment thread id, when applicable. */
+  contextPath?: string;
+  /** Ready-made relative dashboard URL the Workbench card links to (e.g.
+   *  `/factories/<slug>/files/view?path=<plan>`). */
+  contextUrl?: string;
+  runId?: string;
+  factorySlug?: string;
+}
+
 export interface CreateFactoryInput {
   slug: string;
   name: string;
@@ -661,6 +722,7 @@ export class AgentComposeClient {
         ...(opts?.snapshots     !== undefined ? { snapshots:     opts.snapshots }     : {}),
         ...(opts?.networkPolicy !== undefined ? { networkPolicy: opts.networkPolicy } : {}),
         ...(opts?.placeholders  !== undefined ? { placeholders:  opts.placeholders }  : {}),
+        ...(opts?.size          !== undefined ? { size:          opts.size }          : {}),
         ...(parentRunId                       ? { parentRunId }                       : {}),
         ...(opts?.agentId                     ? { agentId: opts.agentId }             : {}),
       },
@@ -1014,6 +1076,36 @@ export class AgentComposeClient {
     );
   }
 
+  /** List the human members of your team — the people you (or an agent) can
+   *  @-flag with `createMentions`. Each row's `userId` is what
+   *  `mentionedUserIds` expects. */
+  async listMembers(): Promise<TeamMember[]> {
+    const body = await this.fetch<{ members: TeamMember[] }>("/api/v1/team/members");
+    return body.members;
+  }
+
+  /** Flag one or more teammates — a durable ping that lands in their factory
+   *  Workbench. Use from an agent (e.g. a remediation plan that needs a human
+   *  to rotate a secret) or any team automation. Resolve `mentionedUserIds`
+   *  via `listMembers()`. When run inside a sandbox the run-callback token is
+   *  forwarded so the ping is attributed to the run ("flagged by <workflow>"). */
+  async createMentions(input: CreateMentionsInput): Promise<Mention[]> {
+    const factorySlug = input.factorySlug
+      ?? (typeof process !== "undefined" ? process.env?.AGENT_COMPOSE_FACTORY : undefined)
+      ?? DEFAULT_FACTORY;
+    const runToken = typeof process !== "undefined" ? process.env?.AGENT_COMPOSE_RUN_TOKEN : undefined;
+    const { factorySlug: _omit, ...payload } = input;
+    const body = await this.fetch<{ mentions: Mention[] }>(
+      `/api/v1/factories/${encodeURIComponent(factorySlug)}/mentions`,
+      {
+        method: "POST",
+        body: payload,
+        ...(runToken ? { headers: { "x-run-token": runToken } } : {}),
+      },
+    );
+    return body.mentions;
+  }
+
   /** List events ingested into a factory, newest first. Supports
    *  case-insensitive substring filter (`name`) and timestamp-cursor
    *  pagination (`before`). Returns `{ events, has_more }` — the
@@ -1153,6 +1245,35 @@ export class AgentComposeClient {
     return this.fetch(templatePath(factorySlug, workflowName, "secrets", key), { method: "DELETE" });
   }
 
+  // ── Factory-level secrets (ADR-0014) ────────────────────────────────────────
+  // The inherited tier: a factory secret is visible to EVERY workflow in the
+  // factory; a workflow secret of the same key overrides it. Values are stored
+  // in GCP Secret Manager; never returned by reads.
+
+  /** Create or update a factory-level secret. */
+  setFactorySecret(key: string, value: string, opts?: SecretOptions): Promise<SetSecretResult> {
+    const factorySlug = opts?.factorySlug ?? DEFAULT_FACTORY;
+    return this.fetch(`/api/v1/factories/${encodeURIComponent(factorySlug)}/secrets`, {
+      method: "POST",
+      body: { key, value },
+    });
+  }
+
+  /** List factory-level secret keys (metadata only — values are never returned). */
+  async listFactorySecrets(opts?: SecretOptions): Promise<SecretListEntry[]> {
+    const factorySlug = opts?.factorySlug ?? DEFAULT_FACTORY;
+    const body = await this.fetch<{ secrets: Array<{ secretKey: string; createdAt: string; updatedAt: string }> }>(
+      `/api/v1/factories/${encodeURIComponent(factorySlug)}/secrets`,
+    );
+    return body.secrets.map(s => ({ key: s.secretKey, createdAt: s.createdAt, updatedAt: s.updatedAt }));
+  }
+
+  /** Delete a factory-level secret. */
+  deleteFactorySecret(key: string, opts?: SecretOptions): Promise<void> {
+    const factorySlug = opts?.factorySlug ?? DEFAULT_FACTORY;
+    return this.fetch(`/api/v1/factories/${encodeURIComponent(factorySlug)}/secrets/${encodeURIComponent(key)}`, { method: "DELETE" });
+  }
+
   // ── API keys ───────────────────────────────────────────────────────────────
   // Both endpoints require an admin-scoped key as the bearer token.
 

package/src/index.ts

@@ -73,6 +73,7 @@ export {
   Verdict,
   runProcessorChain,
   denyTools,
+  humanApproval,
   requireScope,
   redactPattern,
 } from "./processors/index.js";
@@ -112,6 +113,7 @@ export type {
   CreateFactoryInput, UpdateFactoryInput,
   SecretOptions, SetSecretResult, SecretListEntry,
   CreateApiKeyInput, StreamRunLogsOptions,
+  TeamMember, Mention, CreateMentionsInput,
   EventSubjectType, EventRow, ReportEventInput, ListEventsOptions, ListEventsResult,
   RunLogLine, ListRunLogsOptions,
   RegisteredRuntime, RunState, RunStatus, FactoryRow, SnapshotListEntry, SnapshotListResponse,
@@ -178,16 +180,20 @@ export type { RunEvent } from "./types/events.js";
 
 // Sandbox providers
 export { createSandbox, reconnectSandbox, killAllSandboxes, killSandboxById,
-  getSandboxQuotas, listOwnedSandboxes, deleteSandboxSnapshot,
+  getSandboxQuotas, listOwnedSandboxes, deleteSandboxSnapshot, snapshotResolves,
   makeSandboxProvider, makeDesktopSandboxProvider,
-  parseSseExecStream, AGENT_COMPOSE_TAG } from "./sandbox.js";
+  parseSseExecStream, AGENT_COMPOSE_TAG,
+  SANDBOX_VCPUS, DEFAULT_SANDBOX_SIZE, E2B_TEMPLATE_SIZES,
+  isE2bSupportedSize, e2bMachineSpec, e2bBaseTemplate, e2bAgentEnvTemplate,
+  isPlatformE2bTemplateAlias } from "./sandbox.js";
 export { SandboxUnavailableError, SANDBOX_UNAVAILABLE_PREFIX } from "./sandbox-errors.js";
 export type {
   SandboxCreateOpts, SandboxNetworkPolicy, SandboxNetworkHeaderTransform,
   SandboxNetworkAllowRule, SandboxNetworkSubnetPolicy, SandboxProviderName,
-  SandboxQuotaResult, OwnedSandboxResult, OwnedSandbox,
+  SandboxQuotaResult, OwnedSandboxResult, OwnedSandbox, SandboxSize,
   ParseSseExecStreamOptions, SandboxCommandRunOptions, SandboxCommandResult,
 } from "./sandbox.js";
+export type { SandboxResources } from "./types/workflow-metadata.js";
 
 // Workflow engine
 export { runWorkflow, WorkflowError, EngineError, classifyError, parseNameVersion } from "./workflows/engine.js";
@@ -249,7 +255,11 @@ export {
 } from "./pause/errors.js";
 export type { PauseErrorCode } from "./pause/errors.js";
 export type { PauseRequest } from "./pause/pause-core.js";
-export type { RequestDecisionRequest, WaitForEventRequest } from "./pause/wrappers.js";
+export type { WaitForEventRequest } from "./pause/wrappers.js";
+// `agentc pause` writes a local pause-request marker the agent loop consumes
+// (the snapshot-release bridge); the CLI imports the writer.
+export { writeLocalPauseRequest, consumeLocalPauseRequest } from "./agent/local-pause-request.js";
+export type { LocalPauseRequest, PauseOption } from "./agent/local-pause-request.js";
 export type {
   StepRequest,
   StepResult,
@@ -265,5 +275,7 @@ export { agentLoop, parseAgentStatus, DEFAULT_CLAUDE_MODEL } from "./agent/agent
 export type { AgentLifecycleEvent, AgentLoopOpts, AgentLoopResult } from "./agent/agent-loop.js";
 export { agent } from "./agent/run-agent.js";
 export type { AgentOpts } from "./agent/run-agent.js";
+export { AGENT_COMPOSE_MANUAL, buildAgentContextDoc, writeAgentContext } from "./agent/agent-context.js";
+export type { AgentConnectorInfo } from "./agent/agent-context.js";
 export { AgentMessageSchema, parseAgentResponse } from "./agent/protocol.js";
 export { importSourceModule, TMP_DIR, LATEST_VERSION } from "./utils/source-loader.js";

package/src/pause/checkpoint.ts

@@ -1,5 +1,6 @@
 /**
- * `ctx.checkpoint(name, fn)` — disk-backed memoise across pause-resume.
+ * Disk-backed memoise across pause-resume — the engine behind durable
+ * `ctx.step(name, fn)` (ADR-0012).
  *
  * First call: `fn()` runs, the result is atomically written to
  * `/tmp/wf/state/checkpoints/<name>.json`. On any subsequent invocation
@@ -16,29 +17,47 @@
  * memoisation is in-sandbox only and would silently retry on a sandbox
  * recreation that lost the checkpoint file.
  *
- * See ADR-0006 §"`ctx.checkpoint(name, fn)` — disk-backed memoisation".
+ * INTERNAL only — there is no public `ctx.checkpoint`. The durable
+ * `ctx.step` wires `scopedMemoize("step<idx>")` and reports a "restored"
+ * sub-step on a cache hit. See ADR-0012.
  */
 
 import { assertSafeCheckpointName, readCheckpoint, writeCheckpoint } from "./state-dir.js";
 
-/** Read-or-run-and-write helper. `name` is validated by the state-dir
- *  layer (rejects path-escape attempts); `fn` is awaited if it returns
- *  a Promise so sync and async callers compose identically. */
-export async function checkpoint<T>(name: string, fn: () => Promise<T> | T): Promise<T> {
+/** Result of a memoise call — `restored` distinguishes a disk hit (fn was
+ *  NOT run, value read from a prior subprocess) from a fresh run (fn ran,
+ *  value just written). The durable `ctx.step` maps `restored` onto the
+ *  duration-0 "restored" sub-step status. */
+export interface MemoizeResult<T> {
+  value:    T;
+  restored: boolean;
+}
+
+/** Read-or-run-and-write helper reporting whether the value was restored
+ *  from disk. `name` is validated by the state-dir layer (rejects
+ *  path-escape attempts); `fn` is awaited if it returns a Promise so sync
+ *  and async callers compose identically.
+ *
+ *  A pause inside `fn` (PauseSignal) propagates BEFORE any write — a
+ *  partially-completed body is never memoised, so the resume re-runs it. */
+export async function memoize<T>(name: string, fn: () => Promise<T> | T): Promise<MemoizeResult<T>> {
   const existing = await readCheckpoint<T>(name);
-  if (existing.found) return existing.value;
+  if (existing.found) return { value: existing.value, restored: true };
   const value = await fn();
   await writeCheckpoint(name, value);
-  return value;
+  return { value, restored: false };
 }
 
-/** Bind user checkpoint names to a runner-owned namespace. The user's
- *  `name` is still validated independently so a scope prefix cannot turn
- *  an empty or path-escaping name into a valid filename. */
-export function scopedCheckpoint(scope: string): typeof checkpoint {
+/** A memoise function bound to a runner-owned scope. */
+export type ScopedMemoize = <T>(name: string, fn: () => Promise<T> | T) => Promise<MemoizeResult<T>>;
+
+/** Bind memoise names to a runner-owned namespace (e.g. `step<idx>`). The
+ *  caller's `name` is still validated independently so a scope prefix
+ *  cannot turn an empty or path-escaping name into a valid filename. */
+export function scopedMemoize(scope: string): ScopedMemoize {
   assertSafeCheckpointName(scope);
-  return async <T>(name: string, fn: () => Promise<T> | T): Promise<T> => {
+  return async <T>(name: string, fn: () => Promise<T> | T): Promise<MemoizeResult<T>> => {
     assertSafeCheckpointName(name);
-    return checkpoint(`${scope}.${name}`, fn);
+    return memoize(`${scope}.${name}`, fn);
   };
 }

package/src/pause/manager.ts

@@ -44,7 +44,7 @@ const RunningAgentLoopStateSchema = z.object({
   blockerStreak:               z.object({ key: z.string(), count: z.number().int().nonnegative() }).nullable(),
   // PR 7: a human-requested steer-pause intent, persisted so it survives a
   // resume and the loop re-issues the boundary pause on re-entry.
-  pendingSteerPause:            z.object({ reason: z.string(), correlationKey: z.string().nullable(), at: z.number().int() }).nullable().default(null),
+  pendingSteerPause:            z.object({ reason: z.string(), correlationKey: z.string().nullable(), at: z.number().int(), payload: z.record(z.string(), z.unknown()).optional() }).nullable().default(null),
 });
 
 const SettledAgentLoopStateSchema = z.object({
@@ -76,7 +76,7 @@ export interface AgentLoopProgressState {
   blockerStreak:               { key: string; count: number } | null;
   /** PR 7 steer-pause intent — see RunningAgentLoopStateSchema. Optional so the
    *  loop can omit it until it wires steer (the schema defaults it to null). */
-  pendingSteerPause?:           { reason: string; correlationKey: string | null; at: number } | null;
+  pendingSteerPause?:           { reason: string; correlationKey: string | null; at: number; payload?: Record<string, unknown> } | null;
 }
 
 export interface SettledAgentLoopResult<TResponse = unknown> {

package/src/pause/pause-core.ts

@@ -94,6 +94,41 @@ export function isPauseSignal(err: unknown): err is PauseSignal {
   return typeof err === "object" && err !== null && (err as Record<symbol, unknown>)[PAUSE_SIGNAL_BRAND] === true;
 }
 
+/**
+ * The run's pause boundary. The runner (`run-agent` `steerPause`) closes a
+ * `corePause` over the ambient `runId`/`stepIndex`; the agent loop / runtime
+ * supplies the per-iteration `agentScope` so the pauseId stays stable across
+ * the loop's iteration-skipping on resume. Absent outside a workflow step
+ * (local / non-sandbox callers) — see `boundProcessorPause`.
+ */
+export type BoundaryPauseFn = <T = unknown>(
+  req: PauseRequest<T>,
+  agentScope: { agentId: string; iteration: number },
+) => Promise<T>;
+
+/**
+ * Build the `ProcessorContext.pause` callable for a given hook scope: binds the
+ * boundary to this hook's `{ agentId, iteration }` so a processor calling
+ * `ctx.pause(req)` gets a deterministic, resume-stable pauseId. When no boundary
+ * is wired (local tests, non-sandbox callers), the returned fn rejects loudly
+ * rather than silently no-op'ing — pause genuinely cannot work without the
+ * runner's snapshot/Temporal machinery.
+ */
+export function boundProcessorPause(
+  boundary: BoundaryPauseFn | undefined,
+  scope: { agentId: string; iteration: number },
+): <T = unknown>(req: PauseRequest<T>) => Promise<T> {
+  return <T = unknown>(req: PauseRequest<T>): Promise<T> => {
+    if (!boundary) {
+      return Promise.reject(new PauseRequestError(
+        "ctx.pause is unavailable here: no pause boundary is wired (a processor can " +
+        "only pause inside a sandboxed workflow step, not in a local/unit-test run)",
+      ));
+    }
+    return boundary(req, scope);
+  };
+}
+
 // ── Deterministic pauseId ───────────────────────────────────────────────────
 
 /** Fixed namespace for agent-compose pause ids (UUIDv5). Constant — must

package/src/pause/state-dir.ts

@@ -6,7 +6,7 @@
  *
  *   agent-<agentInstanceId>.json     ← agent loop state (iteration, messages, processor cursor)
  *   runtime-<agentInstanceId>.json   ← runtime-private blob (opaque to the loop)
- *   checkpoints/<name>.json          ← user `ctx.checkpoint(name, fn)` memoised values
+ *   checkpoints/<name>.json          ← durable `ctx.step(name, fn)` memoised values (keyed `step<idx>.<name>`)
  *   pauses/<pauseId>.json            ← pause records (request + resume payload once available)
  *
  * Atomic writes (write-tmp → fsync → rename) so a mid-write `sandbox.snapshot()`
@@ -50,7 +50,7 @@ const pausePath        = (pauseId: string)         => join(pausesDir(), `${pause
 
 /** `name` is interpolated into a filename; reject anything outside a
  *  conservative slug. Prevents a workflow author from writing
- *  `ctx.checkpoint("../../etc/passwd", fn)` and escaping the dir.
+ *  `ctx.step("../../etc/passwd", fn)` and escaping the dir.
  *
  *  First character must be alphanumeric or `_` so dotfile names (`.foo`)
  *  and parent-directory tokens (`.`, `..`) are rejected regardless of

package/src/pause/wrappers.ts

@@ -1,12 +1,16 @@
 /**
- * The three opinionated pause wrappers (ADR-0006 §"SDK surface"), each a thin
+ * The two opinionated pause wrappers (ADR-0006 §"SDK surface"), each a thin
  * closure over `ctx.pause`:
  *
- *   - `requestDecision` — pause for a typed human/agent decision (schema required).
  *   - `sleep`           — a lightweight timed pause; resolves on its own TTL,
  *                         skips the snapshot, returns void.
  *   - `waitForEvent`    — pause until an event resumes by correlation key.
  *
+ * A typed human/agent decision is NOT a wrapper — it's a plain `ctx.pause`
+ * with a `schema` (and `payload.options` for the dashboard's answer UI). The
+ * pause primitive carries the reason (the ask) and the resume value (the
+ * resolution); there is no separate `requestDecision`.
+ *
  * Built from a `PauseFn` so the wrapper logic lives in one place and the step
  * runner just spreads them onto the context next to `pause`.
  */
@@ -19,18 +23,10 @@ import type { PauseRequest } from "./pause-core.js";
 export type PauseFn = <T = unknown>(req: PauseRequest<T>) => Promise<T>;
 
 /** Internal: pause with an explicit wire `kind`. The wrappers stamp
- *  `decision`/`sleep`/`event` through this; the public `ctx.pause` is always
+ *  `sleep`/`event` through this; the public `ctx.pause` is always
  *  `custom` and never exposes it. */
 export type KindedPauseFn = <T = unknown>(req: PauseRequest<T>, kind: StepPauseRequest["kind"]) => Promise<T>;
 
-export interface RequestDecisionRequest<T> {
-  reason:   string;
-  payload?: Record<string, unknown>;
-  /** Required — a decision is always validated against a shape. */
-  schema:   z.ZodType<T>;
-  ttlMs?:   number;
-}
-
 export interface WaitForEventRequest<T> {
   reason:         string;
   /** Required — the by-key resume route targets this. */
@@ -40,22 +36,12 @@ export interface WaitForEventRequest<T> {
 }
 
 export interface PauseWrappers {
-  requestDecision<T>(req: RequestDecisionRequest<T>): Promise<T>;
   sleep(durationMs: number): Promise<void>;
   waitForEvent<T = unknown>(req: WaitForEventRequest<T>): Promise<T>;
 }
 
 export function buildPauseWrappers(pause: KindedPauseFn): PauseWrappers {
   return {
-    requestDecision<T>(req: RequestDecisionRequest<T>): Promise<T> {
-      return pause<T>({
-        reason: req.reason,
-        schema: req.schema,
-        ...(req.payload !== undefined ? { payload: req.payload } : {}),
-        ...(req.ttlMs !== undefined ? { ttlMs: req.ttlMs } : {}),
-      }, "decision");
-    },
-
     // Resolves on its OWN ttl — there is no external resumer for a sleep, so
     // onExpiry resolves (not throws) with void. snapshot:false keeps it cheap.
     sleep(durationMs: number): Promise<void> {

package/src/processors/builtins.ts

@@ -4,7 +4,8 @@
  * exist as load-bearing examples and as defaults for common policies.
  */
 
-import type { Processor } from "./processor.js";
+import { z } from "zod";
+import type { Processor, ToolCall } from "./processor.js";
 import { Verdict } from "./processor.js";
 
 /**
@@ -27,6 +28,48 @@ export function denyTools(names: readonly string[]): Processor {
   };
 }
 
+/** Resume payload a reviewer sends back to a `humanApproval` pause. */
+const ApprovalDecision = z.object({
+  approved: z.boolean(),
+  reason:   z.string().optional(),
+});
+
+/**
+ * Pause the run for HUMAN APPROVAL before a matching tool executes — the
+ * human-in-the-loop pre-tool gate (ADR-0006 `ctx.pause`). Over an ACP runtime
+ * this is exactly the `session/request_permission` path: the CLI asks to run a
+ * tool, the gate runs here, and `ctx.pause` snapshots the workflow and waits
+ * durably until a reviewer resolves the pause with `{ approved, reason? }`.
+ * Approve → the tool runs; deny → the reason is returned to the model as the
+ * tool result and the loop continues.
+ *
+ *   tools?  — only these tool names require approval (default: EVERY tool call).
+ *   reason? — build the human-facing prompt from the call (default names the tool).
+ *
+ * Dormant on runtimes without pre-tool gating; active on those that wire
+ * `processToolCall` (the ACP CLI runtimes, the Claude pre-tool hook, Vercel).
+ */
+export function humanApproval(opts?: {
+  tools?:  readonly string[];
+  reason?: (call: ToolCall) => string;
+}): Processor {
+  const gated = opts?.tools ? new Set(opts.tools) : null;
+  return {
+    name: "humanApproval",
+    async processToolCall(call, ctx) {
+      if (gated && !gated.has(call.toolName)) return Verdict.continue(call);
+      const decision = await ctx.pause({
+        reason:  opts?.reason?.(call) ?? `Approve tool call: ${call.toolName}`,
+        payload: { tool: call.toolName, input: call.toolInput, toolUseId: call.toolUseId },
+        schema:  ApprovalDecision,
+      });
+      return decision.approved
+        ? Verdict.continue(call)
+        : Verdict.deny(decision.reason ?? `tool "${call.toolName}" denied by human reviewer`);
+    },
+  };
+}
+
 /**
  * Require the calling API key to carry every scope in `required`. Aborts the
  * agent loop with a clear reason if any are missing — defence-in-depth on

package/src/processors/index.ts

@@ -10,6 +10,7 @@ export { runProcessorChain } from "./runner.js";
 
 export {
   denyTools,
+  humanApproval,
   requireScope,
   redactPattern,
 } from "./builtins.js";

package/src/processors/processor.ts

@@ -30,6 +30,7 @@
 
 import type { AgentMessage } from "../types/protocol.js";
 import type { RequestContext } from "../request-context/request-context.js";
+import type { PauseRequest } from "../pause/pause-core.js";
 
 /** Proposed tool call. Mirrors the relevant fields of AgentMessageToolUse but
  *  lives as its own type so runtime adapters (candidate #1) can populate it
@@ -53,6 +54,18 @@ export interface ProcessorContext {
   agentId:        string;
   /** Iteration of the agent loop (1-based). */
   iteration:      number;
+  /**
+   * Pause the run from inside a processor — the human-approval primitive for a
+   * pre-tool-use gate (ADR-0006 §"reachable from every user code path";
+   * ADR-0020 the ACP `session/request_permission` path). On the fresh pass it
+   * throws `PauseSignal` (internal control flow) so the workflow snapshots and
+   * waits durably; on step re-entry after resolution it returns the resume
+   * payload (validated against `req.schema` if given). The agent loop / runtime
+   * wires it to the run's pause boundary with a deterministic, resume-stable
+   * pauseId (keyed on this hook's agentId + iteration). Calling it outside a
+   * sandboxed workflow step throws — pause requires the runner's pause boundary.
+   */
+  pause<T = unknown>(req: PauseRequest<T>): Promise<T>;
 }
 
 /**