Skip to content

Human in the loop

Some tool calls are too consequential to let the model run unattended — issuing a refund, sending an email, deleting a record. ai.human.* pauses before a specific tool call, routes it to a human, and applies their ruling. Two shapes share one API: an in-process await (a reviewer rules while the run is blocked) and a durable suspend-and-resume (the run unwinds, the request is persisted, a reviewer rules out of process hours later).

  • Approval gate — a tool’s side-effect is irreversible or sensitive, and a human should sign off per call. Wire ai.human.approval(...) as agent middleware.
  • In-process — the reviewer is reachable synchronously (a CLI prompt, a blocking UI). The handler resolves a decision and the run continues.
  • Durable — the reviewer is in another process / another hour (a Slack button, a webhook). The handler persists the request and suspends; ai.human.resume(...) re-drives the turn once the decision lands.

It is middleware on the agent, so it composes with everything else — guardrails, budget, semantic cache. See Attach middleware.

SurfaceRole
ai.human.approval(options)The tool.before gate. Evaluates a policy; gated calls go to a handler; the decision is applied.
ai.human.resume(id, decision, options)Out-of-process, idempotent resume. Loads the persisted interrupt, applies the ruling, optionally re-runs the turn.
ai.human.interrupt.{memory,pg,redis}()InterruptStore factories — where a suspended request is persisted for durable resume.

Returns an AgentMiddleware declaring a single tool.before hook. On each tool dispatch it evaluates the policy; an ungated call runs the real tool untouched; a gated call is routed to the handler and the returned decision is applied.

import { ai } from "@warlock.js/ai";
const support = ai.agent({
model,
tools: [refundCustomer, lookupOrder],
middleware: [
ai.human.approval({
policy: { type: "allowlist", tools: ["refundCustomer"], tags: () => ["money"] },
handler: async (request) => ui.prompt(request), // resolves an ApprovalDecision
}),
],
});
interface HumanApprovalOptions {
name?: string; // middleware name — must be unique per agent (default "human-approval")
policy?: InterruptPolicy; // which tool calls require a human
tools?: Record<string, "allow" | "deny" | "ask">; // per-tool mode, beats the policy
defaultMode?: "allow" | "deny" | "ask"; // for tools nothing else covers
denyReason?: string; // what the model is told when a call is denied
remember?: true | { memory?: ApprovalMemory }; // remember approvals per session
handler: ApprovalHandler; // how a gated call reaches a human and yields a decision
store?: InterruptStore; // durable persistence (only used in suspend-and-resume mode)
}

lookupOrder above is never gated — only refundCustomer matches the allowlist, so every other tool runs untouched with zero overhead.

policy is a discriminated union keyed on type:

// (a) allowlist — gate ONLY the listed tools
{ type: "allowlist", tools: ["refundCustomer"], tags: (name) => ["money"] }
// (b) denylist — gate EVERY tool EXCEPT the listed ones
{ type: "denylist", tools: ["lookupOrder", "search"] }
// (c) predicate — gate when requiresApproval returns truthy
{
type: "predicate",
requiresApproval: (ctx) => {
const args = ctx.args as { amount?: number };
if ((args.amount ?? 0) > 1_000) return ["money", "high-value"]; // gate + tags
return false; // let it through
},
}

For the predicate form, the callback receives a read-only PolicyContext (toolName, toolDescription, args, agentName, tripIndex, sessionId). Its return value is overloaded:

  • false (or an empty string[] — “no rule matched”) → the call passes through.
  • true → gate the call with no tags.
  • a non-empty string[] → gate the call and use the array as context.tags.

For the list variants, the optional tags(toolName) callback derives the tags surfaced on request.context.tags — a reviewer surface can group or prioritize on them.

When you would rather say it per tool than write a policy, pass tools:

humanApproval({
tools: {
read_file: "allow", // always runs, never asks
delete_file: "deny", // never runs; the model is told why (denyReason)
run_shell: "ask", // goes to the handler
},
defaultMode: "ask", // everything else (default when there is no policy)
handler,
});

A tools entry beats policy; for tools it does not list, policy decides when there is one, otherwise defaultMode (default "ask"). A denied call comes back to the model as an ApprovalRejectedError, like a rejection.

Without remember, the same tool asks again on every call. Turn it on and let the reviewer say how far an approval goes:

const approvals = ai.human.approvalMemory(); // optional: keep it to clear a session later
const agent = ai.agent({
model,
tools,
middleware: [
ai.human.approval({
tools: { run_shell: "ask" },
remember: { memory: approvals }, // or `remember: true`
handler: async (request) => {
const answer = await ui.prompt(request); // "once" | "tool" | "args" | "no"
if (answer === "no") return { type: "reject", reason: "declined" };
return answer === "once" ? { type: "approve" } : { type: "approve", remember: answer };
},
}),
],
});
await agent.execute("clean up the build folder", { sessionId });
approvals.clear(sessionId); // when the session ends
  • remember: "tool" approves every later call to that tool in the session.
  • remember: "args" approves only calls to that tool with identical arguments (key order does not matter).
  • Approvals are scoped to the run’s sessionId; a run without one is always asked.
  • Only approve decisions are remembered. A rejection or an edit is asked again next time.
  • The default memory lives in the process. Implement ApprovalMemory (has, add, clear) to keep approvals in your database; the handler is not called for a remembered approval.
  • Remembered approvals also apply to calls resumed through ai.human.resume.

The handler returns (sync or as a promise) an ApprovalDecision, a union keyed on type:

type ApprovalDecision =
| { type: "approve"; remember?: "tool" | "args" } // run the real tool, args unchanged
| { type: "reject"; reason: string } // short-circuit; model sees a typed error
| { type: "edit"; args: unknown; reason?: string }; // run the tool with replaced args
  • approve — the gate returns and the real tool runs with the model’s original arguments.
  • reject — the gate short-circuits an ApprovalRejectedError onto the failed tool result. The reviewer’s reason reaches the model on the next trip as a role: "tool" message, so the model can self-correct — exactly the existing tool-error feedback path.
  • edit — the gate rewrites the pending arguments to decision.args, then lets the real tool run with the edited args. The tool’s own schema validation still applies, so a bad edit surfaces as an ordinary tool error.
interface ApprovalRequest {
interruptId: string; // stable id; durable mode keys the store on it
toolName: string;
toolDescription?: string;
args: unknown; // the exact args the model produced
context: {
agentName: string;
tripIndex: number; // which model round-trip produced the call
sessionId?: string;
originalInput?: string; // the run's original prompt — re-used on resume
tags?: string[]; // from the policy match
};
requestedAt: string; // ISO-8601
}

The middleware never throws out of the pipeline

Section titled “The middleware never throws out of the pipeline”

Every outcome — skip, approve, reject, edit, suspend — returns normally. reject and durable-suspend short-circuit a failed ToolInvokeResult carrying a typed AIError, which the agent dispatch funnels onto result.error. So agent.execute() still never throws; you branch on result.error:

const result = await support.execute("Refund my last order");
if (result.error instanceof ApprovalRejectedError) {
console.log(`${result.error.toolName} rejected: ${result.error.reason}`);
}

Only a handler bug (a non-sentinel throw) propagates, and even then it lands on result.error.

In-process await only works while the run is blocked. For a reviewer who rules minutes or hours later in another process, the run must unwind and the request must be persisted.

Step 1 — the handler persists and suspends

Section titled “Step 1 — the handler persists and suspends”

Configure a store, then have the handler write the request to it and throw InterruptSuspendedError:

import { ai, InterruptSuspendedError } from "@warlock.js/ai";
const store = ai.human.interrupt.memory();
const support = ai.agent({
model,
tools: [refundCustomer],
middleware: [
ai.human.approval({
policy: { type: "allowlist", tools: ["refundCustomer"] },
store,
handler: async (request) => {
// Persist the pending interrupt out-of-band…
await store.save({
interruptId: request.interruptId,
request,
status: "pending",
savedAt: new Date().toISOString(),
});
await notifyReviewer(request); // Slack message, email, queue, …
// …then suspend the run. The middleware recognizes its OWN sentinel.
throw new InterruptSuspendedError("Awaiting human approval", {
interruptId: request.interruptId,
});
},
}),
],
});

The middleware catches its own InterruptSuspendedError, short-circuits a failed result carrying it, and the run ends. The caller reads the id off result.error:

const result = await support.execute("Refund order #4821", { sessionId: "sess_42" });
if (result.error instanceof InterruptSuspendedError) {
return { status: "awaiting-approval", interruptId: result.error.interruptId };
}

Hours later, in a webhook handler, apply the reviewer’s decision with ai.human.resume(interruptId, decision, options):

// Re-run the turn with the decision pre-seeded:
const outcome = await ai.human.resume(
interruptId,
{ type: "edit", args: { amount: 5 } },
{ store, agent: support },
);
if (outcome.type === "applied" && outcome.result) {
console.log(outcome.result.text); // the completed re-run
}

resume validates the decision, claims the PendingInterrupt (removes and returns it in one atomic step), then (when an agent is supplied) re-executes the original turn with the decision pre-seeded — so the gated tool call this time resolves to the ruling instead of pausing again. The original prompt is recovered from request.context.originalInput unless you pass input to override.

Durable v1 model — re-run, not mid-flight suspend. Resume re-executes the turn from the top with the decision seeded; it does not rehydrate an in-flight supervisor at the exact suspended step. Keep the gated tool deterministic up to the gate, or pass a fresh input that reflects what already happened.

interface ResumeOptions<TOutput = unknown> {
store: InterruptStore; // required — where the interrupt lives
agent?: AgentContract<TOutput>; // omit for apply-only (no re-run)
input?: string; // override the re-run prompt
executeOptions?: AgentExecuteOptions<TOutput>; // forwarded to agent.execute on re-run
}
type ResumeResult<TOutput = unknown> =
| {
type: "applied";
interruptId: string;
decision: ApprovalDecision;
result?: AgentResult<TOutput>;
}
| { type: "already-resolved"; interruptId: string };

Two shapes:

  • apply-only — omit agent. resume loads, validates, deletes, and returns { type: "applied", decision } for a caller-owned re-drive (e.g. a custom transport). No turn is re-run.
  • re-run — pass agent. resume additionally re-executes the turn; the AgentResult rides outcome.result.

Idempotent and exactly-once. A second resume of an already-resolved (deleted) or never-raised interrupt is a no-op — it returns { type: "already-resolved" } without re-applying the decision or re-running the turn. The claim is atomic in every built-in store, so when two resumes of one interrupt race (a double-clicked “Approve”, two reviewers at once) exactly one applies the decision and the other returns already-resolved. The record is claimed before the re-run, so even a re-run that itself raises a fresh interrupt cannot collide with the one being resolved. Webhook retries are safe.

The pre-seeded decision is bound to that re-run: only the gated call made inside the resumed agent.execute(...) can take it. Another execution of the same agent with the same session and arguments running at the same moment reaches its own handler, never the reviewer’s ruling.

resume also validates the decision payload (a webhook can hand it anything): a reject without a string reason, an edit without args, or an unknown type throws a TypeError loudly rather than mis-driving the re-run.

Interrupt stores — ai.human.interrupt.{memory,pg,redis}()

Section titled “Interrupt stores — ai.human.interrupt.{memory,pg,redis}()”

All three implement the same InterruptStore contract (save / load / delete / claim / optional list / schema), shaped like the orchestrator’s SnapshotStore so a single pg.Pool or redis client can back both.

interface InterruptStore {
save(record: PendingInterrupt): Promise<void>;
load(interruptId: string): Promise<PendingInterrupt | undefined>;
delete(interruptId: string): Promise<void>;
list?(prefix?: string): Promise<string[]>;
// Remove and return a pending record in one atomic step; undefined when
// it is unknown, not pending, or already claimed by a concurrent caller.
claim?(interruptId: string): Promise<PendingInterrupt | undefined>;
schema(): string; // DDL string for stores with a table; "" otherwise
}

claim is optional so existing custom stores keep working: without it, resume falls back to load + delete and logs a one-time warning, because two concurrent resumes can then both apply the decision. Add claim to a custom store — for SQL, DELETE ... WHERE interrupt_id = $1 AND status = 'pending' RETURNING ...; for a key-value store, a delete that reports whether it removed the key.

Pure in-process Map, zero dependencies. Good for tests and single-process apps where the reviewer rules within the process lifetime.

const store = ai.human.interrupt.memory();
import { Pool } from "pg";
const pool = new Pool({ connectionString: process.env.DATABASE_URL });
const store = ai.human.interrupt.pg({ client: pool });
// Once, via your migration tooling — the store NEVER auto-migrates:
await pool.query(store.schema());

Pass { client } (a pg.Pool / pg.Client — @warlock.js/ai never imports pg in that case) or { connectionString } and let the store lazily import("pg") to build its own pool. table defaults to warlock_ai_human_interrupts and must be a safe SQL identifier ([A-Za-z_][A-Za-z0-9_]*). When pg is absent, a curated install string surfaces on first use, never at import.

import { createClient } from "redis";
const client = createClient({ url: process.env.REDIS_URL });
await client.connect();
const store = ai.human.interrupt.redis({ client });

Pass { client } (a connected redis client) or { url } to let the store lazily import("redis"), build, and connect its own. prefix defaults to warlock:ai-human:interrupt:. schema() returns an empty string (Redis needs no migration); list() is backed by a self-maintained id index since the structural client surface exposes no SCAN: a Redis set when the client has the set commands (sAdd/sRem/sMembers or sadd/srem/smembers), so parallel interrupts never drop an id, otherwise a JSON array. An index written by an earlier release is copied into the set on first use. claim() reads the record and deletes it; only the caller whose DEL removed the key receives it.

Optional peers. pg and redis are not hard dependencies. A memory-only app never installs either, and importing @warlock.js/ai never forces them to resolve. The driver loads only the first time a pg/redis store actually does IO.

  1. Model produces a tool call.
  2. tool.before runs the policy. Not gated → the real tool runs.
  3. Gated → build an ApprovalRequest, call the handler.
  4. In-process: handler resolves a decision → approve / reject / edit applied immediately.
  5. Durable: handler persists the request and throws InterruptSuspendedError → run unwinds, caller reads result.error.interruptId.
  6. Reviewer rules later → ai.human.resume(id, decision, { store, agent }) re-runs the turn with the decision pre-seeded; the gate resolves to the ruling.

Both surface via result.error like every other AIError — they never escape execute():

  • ApprovalRejectedError (code: "APPROVAL_REJECTED") — carries reason and toolName. The model also sees reason on the next trip and can self-correct.
  • InterruptSuspendedError (code: "INTERRUPT_SUSPENDED") — carries interruptId, the key a later resume uses.
import { ApprovalRejectedError, InterruptSuspendedError } from "@warlock.js/ai";
  • Attach middleware — how approval composes with budget, guardrail, cache; ordering invariants.
  • Guardrails — automated content gating (escalation.onBlock can hand off to a human-review hook).
  • Run agent — the agent the gate wraps; result.error handling.
  • Define tools — the tools a policy gates.