@agent-compose/sdk 0.5.8 → 0.6.0

package/src/agent/pause-client.ts

@@ -0,0 +1,108 @@
+/**
+ * In-sandbox pause client (ADR-0028). The single way an agent pauses its OWN
+ * run: `agentc pause` and the gate-pause processor both call
+ * `requestPauseAndAwait`, which drives the server pause API and blocks until a
+ * human resolves it.
+ *
+ * Create-then-poll, NOT a held connection:
+ *   1. POST /pauses creates the pending row. The server wakes the step
+ *      activity, which freezes the live VM in place (E2B native suspend). The
+ *      poll loop below is part of that frozen process — between polls it costs
+ *      ZERO compute while the run is parked.
+ *   2. GET /pauses/:id long-polls (each request a bounded ~5s server-side
+ *      LISTEN race) until the row is terminal, then returns the human's answer.
+ *
+ * There is no marker file and no exception threaded through workflow code — the
+ * pause is a server operation, so nothing a `try/catch` can swallow.
+ */
+
+export interface PauseDecision {
+  status:   "resolved" | "expired" | "cancelled";
+  /** The human's answer (present on `resolved`). Caller-defined shape; the
+   *  dashboard sends `{ decision: string }`. Null on expiry/cancel. */
+  decision: unknown;
+}
+
+export interface RequestPauseOptions {
+  /** `AGENT_COMPOSE_URL` — the server base URL injected into the sandbox. */
+  baseUrl: string;
+  /** `AGENT_COMPOSE_RUN_TOKEN` — the run credential the agent already carries. */
+  token:   string;
+  /** `RUN_ID`. */
+  runId:   string;
+  /** Human-readable reason shown on the pause feed / approval UI. */
+  reason:  string;
+  /** Optional pause TTL; the workflow auto-expires the pause after this. */
+  ttlMs?:  number;
+  /** Optional decision options the human picks from (e.g. approve / deny). */
+  options?: Array<{ id: string; label: string }>;
+  /** The action under review (e.g. the tool call), surfaced to the human. */
+  action?: Record<string, unknown>;
+  /** Optional second-key resume route. */
+  correlationKey?: string;
+  /** Abort the wait (the agent loop's signal). */
+  signal?: AbortSignal;
+}
+
+/** Inject a custom fetch (tests). Defaults to global fetch. */
+type FetchFn = typeof fetch;
+
+const isAbort = (signal: AbortSignal | undefined) => Boolean(signal?.aborted);
+
+export async function requestPauseAndAwait(
+  opts: RequestPauseOptions,
+  fetchImpl: FetchFn = fetch,
+): Promise<PauseDecision> {
+  const base = opts.baseUrl.replace(/\/+$/, "");
+  const headers = {
+    authorization:  `Bearer ${opts.token}`,
+    "content-type": "application/json",
+    accept:         "application/json",
+  } as const;
+
+  // 1. Create the pending pause. The server wakes the step activity → the live
+  //    VM suspends in place. 202 → { pauseId }.
+  const createRes = await fetchImpl(`${base}/api/v1/runs/${opts.runId}/pauses`, {
+    method:  "POST",
+    headers,
+    body: JSON.stringify({
+      reason: opts.reason,
+      ...(opts.ttlMs !== undefined  ? { ttlMs:          opts.ttlMs }          : {}),
+      ...(opts.options              ? { options:        opts.options }        : {}),
+      ...(opts.action               ? { action:         opts.action }         : {}),
+      ...(opts.correlationKey       ? { correlationKey: opts.correlationKey } : {}),
+    }),
+    ...(opts.signal ? { signal: opts.signal } : {}),
+  });
+  if (!createRes.ok) {
+    const text = await createRes.text().catch(() => "");
+    throw new Error(`pause create failed (${createRes.status}): ${text.slice(0, 300)}`);
+  }
+  const { pauseId } = await createRes.json() as { pauseId: string };
+
+  // 2. Poll until terminal. Each GET is a bounded server long-poll; the loop
+  //    reissues. A transient error backs off and retries — the durable row is
+  //    the source of truth, so a dropped poll never loses the decision.
+  const pollUrl = `${base}/api/v1/runs/${opts.runId}/pauses/${pauseId}`;
+  let backoffMs = 0;
+  for (;;) {
+    if (isAbort(opts.signal)) throw new Error("pause wait aborted");
+    if (backoffMs > 0) await new Promise((r) => setTimeout(r, backoffMs));
+    let res: Awaited<ReturnType<FetchFn>>;
+    try {
+      res = await fetchImpl(pollUrl, { method: "GET", headers, ...(opts.signal ? { signal: opts.signal } : {}) });
+    } catch (err) {
+      if (isAbort(opts.signal)) throw err;
+      backoffMs = Math.min(8_000, (backoffMs || 500) * 2);
+      continue;
+    }
+    if (!res.ok) {
+      backoffMs = Math.min(8_000, (backoffMs || 500) * 2);
+      continue;
+    }
+    backoffMs = 0;
+    const body = await res.json() as { status: string; resumePayload?: unknown };
+    if (body.status === "pending") continue;
+    return { status: body.status as PauseDecision["status"], decision: body.resumePayload ?? null };
+  }
+}

package/src/agent/run-agent.ts

@@ -13,7 +13,7 @@
 import { z } from "zod";
 import { randomUUID } from "node:crypto";
 import { getActiveStep, nextAgentCallInActiveStep } from "../active-step.js";
-import { corePause } from "../pause/pause-core.js";
+import { corePause, type PauseRequest } from "../pause/pause-core.js";
 import { agentLoop } from "./agent-loop.js";
 import { consumeSteerPending, runControlPoller } from "./steer-control.js";
 import type { AgentLifecycleEvent, AgentLoopResult } from "./agent-loop.js";
@@ -21,7 +21,7 @@ import { AsyncQueue } from "./async-queue.js";
 import type { AgentMessage, AgentStatus } from "../types/protocol.js";
 import type { AgentRuntime, RuntimeOptions } from "../types/runtime.js";
 import type { SandboxProvider } from "../types/sandbox.js";
-import { writeAgentContext } from "./agent-context.js";
+import { writeAgentContext, buildAgentContextDoc } from "./agent-context.js";
 import type { AgentBudget } from "../types/workflow.js";
 import type { Processor } from "../processors/processor.js";
 import { RequestContext } from "../request-context/request-context.js";
@@ -315,7 +315,7 @@ export async function agent<T = unknown>(opts: AgentOpts<T>): Promise<AgentLoopR
   const activeStepForPause = getActiveStep();
   const steerPause = activeStepForPause && runId
     ? function steerPauseFn<T>(
-        req: { reason: string; correlationKey?: string; schema?: z.ZodType<T> },
+        req: PauseRequest<T>,
         agentScope: { agentId: string; iteration: number },
       ): Promise<T> {
         return corePause<T>(req, {
@@ -333,7 +333,12 @@ export async function agent<T = unknown>(opts: AgentOpts<T>): Promise<AgentLoopR
 
   try {
   return await agentLoop({
-    runtime: (runtimeOpts: RuntimeOptions) => opts.runtime.create(opts.sandbox, runtimeOpts),
+    // Inject the platform manual into every runtime create() so a runtime that
+    // supports a system-prompt append (claude) carries it IN CONTEXT — not
+    // dependent on the agent choosing to `cat` AGENTS.md (which the SDK doesn't
+    // auto-load) or on writeAgentContext succeeding (it EACCES's on a read-only
+    // /workspace). buildAgentContextDoc is the same content writeAgentContext writes.
+    runtime: (runtimeOpts: RuntimeOptions) => opts.runtime.create(opts.sandbox, { ...runtimeOpts, agentManual: buildAgentContextDoc(process.env) }),
     agentId,
     ...(opts.label !== undefined ? { label: opts.label } : {}),
     ...(opts.budget?.turnsPerIteration !== undefined ? { turnsPerIteration: opts.budget.turnsPerIteration } : {}),

package/src/agent/steer-control.ts

@@ -17,13 +17,27 @@
 import { z } from "zod";
 
 /** What a steer/resume answer carries. Used as the boundary pause's `schema`
- *  so it is validated client-side in the re-spawned runner — a null/empty
- *  message is rejected (PauseSchemaError) so an agent never resumes on an
- *  empty steer. `message` becomes the agent's next user turn. */
-export const SteerDecisionSchema = z.object({
-  message: z.string().min(1),
-  actor:   z.string().nullish(),
-});
+ *  so it is validated client-side in the re-spawned runner — an empty answer
+ *  is rejected (PauseSchemaError) so an agent never resumes on nothing. The
+ *  normalised `message` becomes the agent's next user turn.
+ *
+ *  Accepts BOTH resume-payload conventions and normalises to `{ message }`:
+ *    - `{ message }` — the SDK / API steer convention (`answerSteer`).
+ *    - `{ decision }` — what the dashboard's RunPausePanel universally sends
+ *      for every pause (option click or free text). Without this, resuming an
+ *      agent steer / `needs_input` / `agentc pause` pause from the dashboard
+ *      failed schema validation in the re-spawned runner and the agent never
+ *      got the answer — the resume looked like it did nothing. */
+export const SteerDecisionSchema = z
+  .object({
+    message:  z.string().min(1).optional(),
+    decision: z.string().min(1).optional(),
+    actor:    z.string().nullish(),
+  })
+  .transform((d) => ({ message: (d.message ?? d.decision ?? "").trim(), actor: d.actor ?? null }))
+  .refine((d) => d.message.length > 0, {
+    message: "a steer/resume answer needs a non-empty `message` or `decision`",
+  });
 export type SteerDecision = z.infer<typeof SteerDecisionSchema>;
 
 /** Metadata a pending steer carries from the control message to the boundary

package/src/client.ts

@@ -103,7 +103,8 @@ export interface RegisterWorkflowInput {
   /** All snapshot config — `bootFrom` (where to restore at run start),
    *  `save`, `retain`. See `WorkflowMetadata.snapshots`. */
   snapshots?: SnapshotConfig;
-  /** Sandbox machine size (template default). See `WorkflowMetadata.resources`. */
+  /** Sandbox machine resources — size + provider (template defaults).
+   *  See `WorkflowMetadata.resources`. */
   resources?: SandboxResources;
   /** Provider-neutral execution plan detected by the CLI bundler. */
   workflowPlan?: WorkflowPlan;
@@ -121,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;
 }
@@ -1240,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,14 +73,19 @@ export {
   Verdict,
   runProcessorChain,
   denyTools,
+  humanApproval,
   requireScope,
   redactPattern,
+  createGatePauseProcessor,
 } from "./processors/index.js";
 export type {
   Processor,
   ProcessorContext,
   ProcessorVerdict,
   ToolCall,
+  GatePausePolicy,
+  GatePauseApproval,
+  GatePauseConnection,
 } from "./processors/index.js";
 
 // Protocol types (agent-loop input/output shapes)
@@ -179,9 +184,12 @@ 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,
@@ -228,6 +236,8 @@ export type {
 // `invokeStep` (server) and `serveStep` (runner).
 export {
   invokeStep,
+  launchStep,
+  reconnectStep,
   serveStep,
   parseStepResult,
   buildStepEnvs,
@@ -252,6 +262,12 @@ export {
 export type { PauseErrorCode } from "./pause/errors.js";
 export type { PauseRequest } from "./pause/pause-core.js";
 export type { WaitForEventRequest } from "./pause/wrappers.js";
+// ADR-0028 — the in-sandbox pause client. `agentc pause` and the gate-pause
+// processor both pause their OWN run through the server pause API and block
+// until a human answers (create-then-poll; the VM suspends in place while
+// parked). No marker, no exception threaded through workflow code.
+export { requestPauseAndAwait } from "./agent/pause-client.js";
+export type { PauseDecision, RequestPauseOptions } from "./agent/pause-client.js";
 export type {
   StepRequest,
   StepResult,
@@ -260,6 +276,8 @@ export type {
   StepHandler,
   StepHandlerResult,
   ServeStepRequest,
+  RunningStep,
+  InvokeStepOptions,
 } from "./step-invocation/index.js";
 
 // Agent loop — for workflows that embed an LLM agent in their run() body.

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/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/gate-pause.ts

@@ -0,0 +1,94 @@
+/**
+ * Gate-pause processor (ADR-0028).
+ *
+ * A pre-tool gate that, when its `policy` flags a tool call as needing human
+ * approval, pauses the run as a SERVER operation (`requestPauseAndAwait`) and
+ * blocks until a human answers — then allows or denies the tool.
+ *
+ * It pauses through the server pause API (`requestPauseAndAwait`), so the pause
+ * is a server operation no `try/catch` can swallow. It does NOT use today's
+ * `ctx.pause`, which still throws `PauseSignal` — exactly the swallowable path
+ * ADR-0028 supersedes for agents. (Routing `ctx.pause` itself through this same
+ * server pause is the natural unification — ADR-0028 open question — at which
+ * point "the pause API" and "ctx.pause" become one thing.) Because it lives in
+ * the shared `gateToolCall` chain, one implementation covers every runtime — the
+ * Claude Agent SDK `PreToolUse` hook and the ACP `session/request_permission`
+ * path both route through it.
+ *
+ * Opt-in: the workflow/agent supplies the `policy` (which may be a heuristic or
+ * an async classifier agent). The connection defaults to the run credential in
+ * the sandbox env; absent it (local / non-sandbox), the gate is a no-op and
+ * tool calls pass through untouched.
+ */
+
+import type { Processor, ProcessorContext, ToolCall } from "./processor.js";
+import { Verdict } from "./processor.js";
+import { requestPauseAndAwait } from "../agent/pause-client.js";
+
+export interface GatePauseApproval {
+  /** Human-readable question shown on the approval UI. */
+  reason:   string;
+  /** Decision options the human picks from. Defaults to Approve / Deny. */
+  options?: Array<{ id: string; label: string }>;
+}
+
+/** Decide whether a tool call needs human approval. Return `false` to let it
+ *  through untouched, or an approval request to pause the run until a human
+ *  answers. May be async (e.g. a small classifier agent). */
+export type GatePausePolicy = (
+  call: ToolCall,
+  ctx:  ProcessorContext,
+) => (false | GatePauseApproval) | Promise<false | GatePauseApproval>;
+
+export interface GatePauseConnection { baseUrl: string; token: string; runId: string }
+
+const DENY_ANSWERS = new Set(["deny", "no", "reject", "decline", "block"]);
+
+/** Unwrap the dashboard's `{ decision }` resume payload to the raw answer text. */
+function answerText(decision: unknown): string {
+  const raw = decision !== null && typeof decision === "object" && "decision" in decision
+    ? (decision as { decision: unknown }).decision
+    : decision;
+  return typeof raw === "string" ? raw.trim() : raw == null ? "" : JSON.stringify(raw);
+}
+
+export function createGatePauseProcessor(opts: {
+  policy:      GatePausePolicy;
+  /** Override the server connection (defaults to the sandbox run-credential env). */
+  connection?: GatePauseConnection;
+}): Processor {
+  return {
+    name: "gate-pause",
+    async processToolCall(call: ToolCall, ctx: ProcessorContext) {
+      const approval = await opts.policy(call, ctx);
+      if (!approval) return Verdict.continue(call);
+
+      const conn = opts.connection ?? {
+        baseUrl: process.env.AGENT_COMPOSE_URL ?? "",
+        token:   process.env.AGENT_COMPOSE_RUN_TOKEN ?? "",
+        runId:   process.env.RUN_ID ?? "",
+      };
+      // No run credential (local / non-sandbox) — can't pause; let it through
+      // rather than hard-failing a dev invocation.
+      if (!conn.baseUrl || !conn.token || !conn.runId) return Verdict.continue(call);
+
+      const decision = await requestPauseAndAwait({
+        baseUrl: conn.baseUrl, token: conn.token, runId: conn.runId,
+        reason:  approval.reason,
+        action:  { tool: call.toolName, input: call.toolInput },
+        options: approval.options ?? [{ id: "approve", label: "Approve" }, { id: "deny", label: "Deny" }],
+        signal:  ctx.abortSignal,
+      });
+
+      const answer = answerText(decision.decision);
+      // Approve unless the human explicitly denied (or no answer came back on
+      // expiry/cancel). A free-form answer that isn't a deny word lets the tool
+      // run, with the human's guidance available to the model on the next turn.
+      if (decision.status === "resolved" && !DENY_ANSWERS.has(answer.toLowerCase())) {
+        return Verdict.continue(call);
+      }
+      const why = decision.status === "resolved" ? `denied: ${answer}` : `${decision.status} with no approval`;
+      return Verdict.deny(`Human ${why}. Tool "${call.toolName}" was not run — adjust course or ask again.`);
+    },
+  };
+}

package/src/processors/index.ts

@@ -10,6 +10,13 @@ export { runProcessorChain } from "./runner.js";
 
 export {
   denyTools,
+  humanApproval,
   requireScope,
   redactPattern,
 } from "./builtins.js";
+
+// ADR-0028 — server-driven human-approval gate. Pauses the run through the
+// server pause API and blocks until a human answers; covers every runtime
+// through the shared gateToolCall chain.
+export { createGatePauseProcessor } from "./gate-pause.js";
+export type { GatePausePolicy, GatePauseApproval, GatePauseConnection } from "./gate-pause.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>;
 }
 
 /**