@krapht/ork 0.2.0 → 0.3.0

package/dist/{src-DAsOYtoR.mjs → src-CZOVF2yU.mjs}

@@ -1,10 +1,312 @@
-import { S as FEEDBACK_TARGETS, b as FEEDBACK_KINDS, f as parseReport, x as FEEDBACK_SEVERITIES } from "./src-CJ_zF0Zj.mjs";
+import { Ct as FEEDBACK_SEVERITIES, D as parseReport, St as FEEDBACK_KINDS, wt as FEEDBACK_TARGETS } from "./src-Cz1yOUTg.mjs";
 import { z } from "zod";
 import { randomBytes, timingSafeEqual } from "node:crypto";
 import { createInterface } from "node:readline";
 import { spawn } from "node:child_process";
 import { createServer } from "node:http";
 import { createSdkMcpServer, query, tool } from "@anthropic-ai/claude-agent-sdk";
+// ../runtime-claude/src/normalize.ts
+/**
+* @file Both drivers emit the same message JSON (the Agent SDK's messages are
+*   the CLI's `stream-json` lines), so one normalizer serves both.
+*/
+const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const get = (value, key) => isObject(value) ? value[key] : void 0;
+const num = (value) => typeof value === "number" ? value : 0;
+const str = (value) => typeof value === "string" ? value : "";
+const blocks = (message) => {
+	const content = get(get(message, "message"), "content");
+	return Array.isArray(content) ? content.filter((item) => isObject(item)) : [];
+};
+const usageOf = (result) => {
+	const usage = get(result, "usage");
+	return {
+		costUsd: num(result["total_cost_usd"]),
+		inputTokens: num(get(usage, "input_tokens")),
+		outputTokens: num(get(usage, "output_tokens")),
+		cacheReadTokens: num(get(usage, "cache_read_input_tokens")),
+		cacheWriteTokens: num(get(usage, "cache_creation_input_tokens")),
+		turns: num(result["num_turns"]),
+		durationMs: num(result["duration_ms"])
+	};
+};
+/** The outcome a `result` message describes. */
+const outcomeOf = (result) => {
+	const errors = result["errors"];
+	return {
+		subtype: str(result["subtype"]) || "unknown",
+		sessionId: str(result["session_id"]),
+		report: parseReport(result["structured_output"]),
+		text: str(result["result"]),
+		usage: usageOf(result),
+		errors: Array.isArray(errors) ? errors.filter((e) => typeof e === "string") : []
+	};
+};
+/** The year 2286: a reset beyond this is not in seconds. */
+const MAX_RESET_SECONDS = 1e10;
+/**
+* What a subscription's limit said (RFC-007). Only the fields Claude Code
+* documents are read, so `utilization`, often absent, plays no part.
+*/
+const planLimitOf = (info) => {
+	const status = get(info, "status");
+	if (status !== "allowed" && status !== "allowed_warning" && status !== "rejected") return [];
+	const window = get(info, "rateLimitType");
+	const resets = get(info, "resetsAt");
+	const overage = get(info, "overageStatus");
+	return [{
+		type: "plan.limit",
+		status: status === "rejected" && !(status === "rejected" && overage !== "allowed" && overage !== "allowed_warning") ? "allowed_warning" : status,
+		window: typeof window === "string" ? window : "plan",
+		...typeof resets === "number" && resets > 0 && resets < MAX_RESET_SECONDS ? { resetsAt: (/* @__PURE__ */ new Date(resets * 1e3)).toISOString() } : {}
+	}];
+};
+/** Maps one driver message to zero or more normalized events. */
+const normalize = (message) => {
+	if (!isObject(message)) return [];
+	switch (message["type"]) {
+		case "system": {
+			if (message["subtype"] !== "init") return [];
+			const started = {
+				type: "session.started",
+				sessionId: str(message["session_id"]),
+				model: str(message["model"])
+			};
+			if (str(message["cwd"]) !== "") started.cwd = str(message["cwd"]);
+			return [started];
+		}
+		case "assistant": return blocks(message).flatMap((block) => {
+			if (block["type"] === "text" && str(block["text"]).trim() !== "") return [{
+				type: "assistant.text",
+				text: str(block["text"])
+			}];
+			if (block["type"] === "tool_use") {
+				const input = block["input"];
+				return [{
+					type: "tool.called",
+					id: str(block["id"]),
+					name: str(block["name"]),
+					input: isObject(input) ? input : {}
+				}];
+			}
+			return [];
+		});
+		case "user": return blocks(message).filter((block) => block["type"] === "tool_result").map((block) => ({
+			type: "tool.result",
+			id: str(block["tool_use_id"]),
+			isError: block["is_error"] === true
+		}));
+		case "rate_limit_event": return planLimitOf(message["rate_limit_info"]);
+		case "result": return [{
+			type: "session.finished",
+			outcome: outcomeOf(message)
+		}];
+		default: return [];
+	}
+};
+/** Marks a session's start with the driver that runs it. */
+const withDriver = (event, driver) => event.type === "session.started" ? {
+	...event,
+	driver
+} : event;
+/** A finished event for a session the driver could not run. */
+const driverFailure = (message) => ({
+	type: "session.finished",
+	outcome: {
+		subtype: "error_driver",
+		sessionId: "",
+		report: null,
+		text: "",
+		usage: {
+			costUsd: 0,
+			inputTokens: 0,
+			outputTokens: 0,
+			cacheReadTokens: 0,
+			cacheWriteTokens: 0,
+			turns: 0,
+			durationMs: 0
+		},
+		errors: [message]
+	}
+});
+/** How long a hook holds a call before it defers it instead. */
+const HOLD_WINDOW_MS = 54e4;
+/**
+* Waits at a tool call while `hold` is held: "go" once it is released within
+* the window (or at once when it is not held), "defer" after the window.
+*/
+const holdAtTool = async (hold, signal, windowMs = HOLD_WINDOW_MS) => {
+	if (!hold.held()) return "go";
+	const window = new AbortController();
+	const timer = setTimeout(() => {
+		window.abort();
+	}, windowMs);
+	try {
+		await hold.wait("tool", AbortSignal.any([signal, window.signal]));
+	} finally {
+		clearTimeout(timer);
+	}
+	return hold.held() && !signal.aborted ? "defer" : "go";
+};
+/** The hook's answer: nothing to say for "go", the deferral otherwise. */
+const hookOutput = (answer) => answer === "go" ? {} : { hookSpecificOutput: {
+	hookEventName: "PreToolUse",
+	permissionDecision: "defer",
+	permissionDecisionReason: "Ork paused this node; it goes on from this call when it continues."
+} };
+/** Whether a stream-json message is the result of a deferred tool call. */
+const isDeferredResult = (message) => typeof message === "object" && message !== null && "type" in message && message.type === "result" && "stop_reason" in message && message.stop_reason === "tool_deferred";
+/**
+* Two legs of one session, as one: the tokens of both, and the later leg's
+* cost, which is already the session's total (ADR-046).
+*/
+const addUsage = (a, b) => ({
+	costUsd: Math.max(a.costUsd, b.costUsd),
+	inputTokens: a.inputTokens + b.inputTokens,
+	outputTokens: a.outputTokens + b.outputTokens,
+	cacheReadTokens: a.cacheReadTokens + b.cacheReadTokens,
+	cacheWriteTokens: a.cacheWriteTokens + b.cacheWriteTokens,
+	turns: a.turns + b.turns,
+	durationMs: a.durationMs + b.durationMs
+});
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+* The node's `--settings` with Ork's `PreToolUse` HTTP hook added: before every
+* tool call, pre-approved ones included, the session asks whether its node may
+* go on.
+*/
+const withHoldHook = (settings, holdUrl, token) => {
+	const hooks = isRecord(settings?.["hooks"]) ? settings["hooks"] : {};
+	const listed = hooks["PreToolUse"];
+	const before = Array.isArray(listed) ? [...listed] : [];
+	const hook = {
+		type: "http",
+		url: holdUrl,
+		headers: { Authorization: `Bearer ${token}` },
+		timeout: 600
+	};
+	return {
+		...settings,
+		hooks: {
+			...hooks,
+			PreToolUse: [...before, {
+				matcher: "*",
+				hooks: [hook]
+			}]
+		}
+	};
+};
+/**
+* What one stream-json message of a leg yields, and how the leg ends if it
+* does: a result is the session's end, unless the hold hook deferred a call in
+* this leg; a resumed leg's start is not news, and its end carries what the
+* legs before it spent.
+*/
+const legStep = (message, input) => {
+	const deferred = input.deferred && isDeferredResult(message);
+	const events = [];
+	let ended;
+	for (const event of normalize(message)) {
+		if (event.type === "session.started" && input.carried !== void 0) continue;
+		if (event.type !== "session.finished") events.push(withDriver(event, input.driver));
+		else if (deferred) ended = {
+			kind: "deferred",
+			sessionId: event.outcome.sessionId,
+			usage: event.outcome.usage,
+			last: withDriver(event, input.driver)
+		};
+		else {
+			const usage = input.carried === void 0 ? event.outcome.usage : addUsage(input.carried, event.outcome.usage);
+			events.push(withDriver({
+				...event,
+				outcome: {
+					...event.outcome,
+					usage
+				}
+			}, input.driver));
+			ended = { kind: "finished" };
+		}
+	}
+	return ended === void 0 ? { events } : {
+		events,
+		ended
+	};
+};
+// ../runtime-claude/src/cli-leg.ts
+/**
+* @file One `claude -p` process of a CLI-driven session: it writes the queued
+*   stream-json lines, yields the normalized events, and says how it ended. A
+*   session is one leg, or several when a paused node's tool call was deferred
+*   and the session resumed (ADR-041); a resumed leg carries what the legs
+*   before it spent, and its start is not news.
+*/
+const STDERR_LINES = 20;
+const parseLine = (line) => {
+	try {
+		return JSON.parse(line);
+	} catch {
+		return;
+	}
+};
+/** Runs one `claude` process, yielding its events; returns how it ended. */
+const runLeg = async function* (input) {
+	const child = spawn(input.bin, input.args, {
+		cwd: input.cwd,
+		env: { ...input.env },
+		stdio: [
+			"pipe",
+			"pipe",
+			"pipe"
+		]
+	});
+	const exited = new Promise((resolve) => {
+		child.on("close", (code) => {
+			resolve(code);
+		});
+	});
+	const spawnError = new Promise((resolve) => {
+		child.on("error", resolve);
+	});
+	const stderr = [];
+	child.stderr.setEncoding("utf8");
+	child.stderr.on("data", (chunk) => {
+		stderr.push(...chunk.split("\n").filter((l) => l.trim() !== ""));
+		stderr.splice(0, Math.max(0, stderr.length - STDERR_LINES));
+	});
+	const write = (line) => {
+		if (child.stdin.writable) child.stdin.write(line);
+	};
+	input.attach({
+		write,
+		stop: () => {
+			child.kill("SIGINT");
+		}
+	});
+	for (const line of input.pending.splice(0)) write(line);
+	let outcome;
+	try {
+		for await (const line of createInterface({ input: child.stdout })) {
+			const { events, ended } = legStep(parseLine(line), {
+				carried: input.carried,
+				deferred: input.deferred(),
+				driver: "cli"
+			});
+			yield* events;
+			if (ended !== void 0) {
+				child.stdin.end();
+				outcome = ended;
+			}
+		}
+		const code = await Promise.race([exited, spawnError.then((error) => error)]);
+		return outcome ?? {
+			kind: "failed",
+			reason: code instanceof Error ? `could not start ${input.bin}: ${code.message}` : stderr.at(-1) ?? `claude exited with code ${String(code)}`
+		};
+	} finally {
+		input.attach();
+		if (child.exitCode === null) child.kill();
+	}
+};
 /** The name Claude Code gives an Ork tool: `mcp__ork__<name>`. */
 const toolId = (name) => `mcp__ork__${name}`;
 const text = (value) => ({ content: [{
@@ -30,9 +332,11 @@ const defineTool = (definition) => {
 * @file A minimal MCP server over the streamable HTTP transport, for the
 *   `claude` CLI driver. It answers with plain JSON (no SSE stream), which the
 *   transport allows, and implements only what Ork needs: `initialize`, `ping`,
-*   `tools/list` and `tools/call`.
+*   `tools/list` and `tools/call`. Beside it, `/hold` answers the session's
+*   `PreToolUse` HTTP hook, which waits while the node is paused (ADR-041).
 */
 const PATH = "/mcp";
+const HOLD_PATH = "/hold";
 const MAX_BODY = 1048576;
 const MCP_PROTOCOL_FALLBACK = "2025-06-18";
 const JsonRpcSchema = z.object({
@@ -115,11 +419,32 @@ const respond = (res, status, body) => {
 	}
 	res.writeHead(status, { "content-type": "application/json" }).end(JSON.stringify(body));
 };
-const serve = async (req, res, tools, token) => {
+/** The hook's POST: waits for `hold`; a closed connection gives up. */
+const serveHold = async (req, res, hold) => {
+	if (req.method !== "POST") {
+		respond(res, 405);
+		return;
+	}
+	if (await readBody(req) === null) {
+		respond(res, 413);
+		return;
+	}
+	const gone = new AbortController();
+	res.once("close", () => {
+		gone.abort();
+	});
+	const output = await hold(gone.signal);
+	if (!gone.signal.aborted) respond(res, 200, output);
+};
+const serve = async (req, res, tools, token, hold) => {
 	if (!authorized(req, token)) {
 		respond(res, 401);
 		return;
 	}
+	if (req.url === HOLD_PATH && hold !== void 0) {
+		await serveHold(req, res, hold);
+		return;
+	}
 	if (req.url !== PATH) {
 		respond(res, 404);
 		return;
@@ -156,10 +481,10 @@ const serve = async (req, res, tools, token) => {
 * Serves Ork's tools to one `claude` CLI session: on 127.0.0.1 only, on a
 * random port, behind a per-session bearer token.
 */
-const startOrkMcpHttp = async (tools) => {
+const startOrkMcpHttp = async (tools, hold) => {
 	const token = randomBytes(24).toString("hex");
 	const http = createServer((req, res) => {
-		serve(req, res, tools, token).catch(() => {
+		serve(req, res, tools, token, hold).catch(() => {
 			if (!res.headersSent) respond(res, 500);
 		});
 	});
@@ -167,8 +492,10 @@ const startOrkMcpHttp = async (tools) => {
 		http.listen(0, "127.0.0.1", resolve);
 	});
 	const address = http.address();
+	const port = typeof address === "object" && address !== null ? address.port : 0;
 	return {
-		url: `http://127.0.0.1:${typeof address === "object" && address !== null ? address.port : 0}${PATH}`,
+		url: `http://127.0.0.1:${port}${PATH}`,
+		holdUrl: `http://127.0.0.1:${port}${HOLD_PATH}`,
 		token,
 		close: () => new Promise((resolve) => {
 			http.closeAllConnections();
@@ -178,110 +505,6 @@ const startOrkMcpHttp = async (tools) => {
 		})
 	};
 };
-// ../runtime-claude/src/normalize.ts
-/**
-* @file Both drivers emit the same message JSON (the Agent SDK's messages are
-*   the CLI's `stream-json` lines), so one normalizer serves both.
-*/
-const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
-const get = (value, key) => isObject(value) ? value[key] : void 0;
-const num = (value) => typeof value === "number" ? value : 0;
-const str = (value) => typeof value === "string" ? value : "";
-const blocks = (message) => {
-	const content = get(get(message, "message"), "content");
-	return Array.isArray(content) ? content.filter((item) => isObject(item)) : [];
-};
-const usageOf = (result) => {
-	const usage = get(result, "usage");
-	return {
-		costUsd: num(result["total_cost_usd"]),
-		inputTokens: num(get(usage, "input_tokens")),
-		outputTokens: num(get(usage, "output_tokens")),
-		cacheReadTokens: num(get(usage, "cache_read_input_tokens")),
-		cacheWriteTokens: num(get(usage, "cache_creation_input_tokens")),
-		turns: num(result["num_turns"]),
-		durationMs: num(result["duration_ms"])
-	};
-};
-/** The outcome a `result` message describes. */
-const outcomeOf = (result) => {
-	const errors = result["errors"];
-	return {
-		subtype: str(result["subtype"]) || "unknown",
-		sessionId: str(result["session_id"]),
-		report: parseReport(result["structured_output"]),
-		text: str(result["result"]),
-		usage: usageOf(result),
-		errors: Array.isArray(errors) ? errors.filter((e) => typeof e === "string") : []
-	};
-};
-/** Maps one driver message to zero or more normalized events. */
-const normalize = (message) => {
-	if (!isObject(message)) return [];
-	switch (message["type"]) {
-		case "system": {
-			if (message["subtype"] !== "init") return [];
-			const started = {
-				type: "session.started",
-				sessionId: str(message["session_id"]),
-				model: str(message["model"])
-			};
-			if (str(message["cwd"]) !== "") started.cwd = str(message["cwd"]);
-			return [started];
-		}
-		case "assistant": return blocks(message).flatMap((block) => {
-			if (block["type"] === "text" && str(block["text"]).trim() !== "") return [{
-				type: "assistant.text",
-				text: str(block["text"])
-			}];
-			if (block["type"] === "tool_use") {
-				const input = block["input"];
-				return [{
-					type: "tool.called",
-					id: str(block["id"]),
-					name: str(block["name"]),
-					input: isObject(input) ? input : {}
-				}];
-			}
-			return [];
-		});
-		case "user": return blocks(message).filter((block) => block["type"] === "tool_result").map((block) => ({
-			type: "tool.result",
-			id: str(block["tool_use_id"]),
-			isError: block["is_error"] === true
-		}));
-		case "result": return [{
-			type: "session.finished",
-			outcome: outcomeOf(message)
-		}];
-		default: return [];
-	}
-};
-/** Marks a session's start with the driver that runs it. */
-const withDriver = (event, driver) => event.type === "session.started" ? {
-	...event,
-	driver
-} : event;
-/** A finished event for a session the driver could not run. */
-const driverFailure = (message) => ({
-	type: "session.finished",
-	outcome: {
-		subtype: "error_driver",
-		sessionId: "",
-		report: null,
-		text: "",
-		usage: {
-			costUsd: 0,
-			inputTokens: 0,
-			outputTokens: 0,
-			cacheReadTokens: 0,
-			cacheWriteTokens: 0,
-			turns: 0,
-			durationMs: 0
-		},
-		errors: [message]
-	}
-});
 // ../runtime-claude/src/tools/ask-user.ts
 const askUserTool = defineTool({
 	name: "ask_user",
@@ -428,13 +651,25 @@ const feedbackTool = defineTool({
 *   session gets a one-line notice; `answer` replies to a question Ork asked an
 *   owner about a node it owns. Only sessions inside a run get them.
 */
-/** Peers are mutual: a node no one may write to has no inbox to read. */
-const hasPeers = ({ ports }) => (ports.mailbox?.peers().length ?? 0) > 0;
+/**
+* Peers are mutual: a node no one may write to has no inbox to read, unless it
+* may be linked later, since a session's tools are set when it starts.
+*/
+const hasPeers = ({ ports }) => (ports.mailbox?.peers().length ?? 0) > 0 || ports.mailbox?.linkable() === true;
+/** A program or a rule may write to a node with no one to write to itself. */
+const hasInbox = (context) => hasPeers(context) || context.ports.mailbox?.hears() === true;
+const MAX_WAIT_SECONDS = 3600;
+const DEFAULT_WAIT_SECONDS = 300;
+const inboxText = (unread) => JSON.stringify({ messages: unread.map((m) => ({
+	from: m.from,
+	...m.via === void 0 ? {} : { via: m.via },
+	body: m.body
+})) });
 const sendMessageTool = defineTool({
 	name: "send_message",
-	description: "Send a short message to another node in this run: your owner, a node you own, or one you share a declared channel with. It sees a notice and reads the message with read_inbox. Use it for what they need to know now; your report still goes to your owner at the end.",
+	description: "Send a short message to a node you can reach: your owner, a node you own, one you share a declared channel with, or a node of another run the user linked you to. It sees a notice and reads the message with read_inbox. Use it for what they need to know now; your report still goes to your owner at the end.",
 	shape: {
-		to: z.string().describe("The node's id."),
+		to: z.string().describe("The node's id, or <run>/<node> for a linked node."),
 		body: z.string().min(1).describe("Self-contained: the recipient does not see your work.")
 	},
 	available: hasPeers,
@@ -442,20 +677,29 @@ const sendMessageTool = defineTool({
 		const sent = ports.mailbox?.send(args.to, args.body);
 		if (sent === void 0) return Promise.resolve(text("No message bus."));
 		if (!sent.ok) return Promise.resolve(text(`Not sent: ${sent.error}.`));
-		return Promise.resolve(text(sent.delivered === "now" ? `Sent to ${args.to}; it sees a notice at its next step.` : `Sent to ${args.to}; it is not running now and sees the message when it next starts.`));
+		return Promise.resolve(text(sent.delivered === "now" ? `Sent to ${args.to}; it sees a notice at its next step.` : `Sent to ${args.to}; it is not running now and sees the message if it starts again.`));
 	}
 });
 const readInboxTool = defineTool({
 	name: "read_inbox",
-	description: "Read your unread messages from other nodes in this run, oldest first. Ork tells you when one arrives.",
+	description: "Read your unread messages from other nodes, oldest first. Ork tells you when one arrives.",
 	shape: {},
-	available: hasPeers,
+	available: hasInbox,
 	run: ({ ports }) => {
 		const unread = ports.mailbox?.read() ?? [];
-		return Promise.resolve(text(unread.length === 0 ? "No unread messages." : JSON.stringify({ messages: unread.map((m) => ({
-			from: m.from,
-			body: m.body
-		})) })));
+		return Promise.resolve(text(unread.length === 0 ? "No unread messages." : inboxText(unread)));
+	}
+});
+const waitForMessagesTool = defineTool({
+	name: "wait_for_messages",
+	description: "Wait for a message from another node when you cannot go on without its reply, instead of ending your session. Returns what arrived, or says none did in time. You hold no session slot while you wait.",
+	shape: { timeoutSeconds: z.number().int().positive().max(MAX_WAIT_SECONDS).optional().describe(`How long to wait. Default: ${String(DEFAULT_WAIT_SECONDS)}.`) },
+	available: hasInbox,
+	run: async ({ ports }, args) => {
+		const seconds = args.timeoutSeconds ?? DEFAULT_WAIT_SECONDS;
+		await ports.mailbox?.wait(seconds * 1e3);
+		const unread = ports.mailbox?.read() ?? [];
+		return text(unread.length === 0 ? `No message yet, after waiting up to ${String(seconds)} seconds. Ork may have told you something; if not, wait again or go on.` : inboxText(unread));
 	}
 });
 const answerTool = defineTool({
@@ -508,6 +752,7 @@ const ORK_TOOLS = [
 	spawnWorkerTool,
 	sendMessageTool,
 	readInboxTool,
+	waitForMessagesTool,
 	answerTool,
 	claimTool,
 	releaseTool,
@@ -519,11 +764,6 @@ const orkTools = (context) => ORK_TOOLS.flatMap((tool) => tool.bind(context) ??
 const preapprovedTools = (tools) => tools.filter((t) => t.preapproved).map((t) => toolId(t.name));
 // ../runtime-claude/src/cli.ts
 /**
-* @file The CLI driver: runs a session through the user's own `claude -p` in
-*   stream-json mode, with Ork's tools served by a local MCP server.
-*/
-const STDERR_LINES = 20;
-/**
 * Per-request timeout for Ork's MCP server, in ms. The CLI otherwise gives an
 * HTTP server's request 60 seconds and drops a call silent for 5 minutes, and
 * `delegate` waits for whole child sessions (the per-server `timeout` raises
@@ -582,16 +822,10 @@ const buildCliArgs = (spec, mcp, allowed) => {
 	if (spec.budgetUsd !== void 0) args.push("--max-budget-usd", String(spec.budgetUsd));
 	if (spec.resume !== void 0) args.push("--resume", spec.resume);
 	for (const dir of spec.plugins ?? []) args.push("--plugin-dir", dir);
-	if (spec.settings !== void 0) args.push("--settings", JSON.stringify(spec.settings));
+	const settings = mcp.holdUrl === void 0 ? spec.settings : withHoldHook(spec.settings, mcp.holdUrl, mcp.token);
+	if (settings !== void 0) args.push("--settings", JSON.stringify(settings));
 	return args;
 };
-const parseLine = (line) => {
-	try {
-		return JSON.parse(line);
-	} catch {
-		return;
-	}
-};
 /**
 * Drives a session with the user's own `claude` CLI in print mode, logged in by
 * the user. Ork never reads or passes its credentials.
@@ -600,63 +834,62 @@ const createCliRuntime = (options = {}) => ({
 	driver: "cli",
 	start: (spec, ports) => {
 		const pending = [userLine(spec.prompt)];
-		let write;
-		let stop;
+		let io;
+		const ended = new AbortController();
+		/** The hold hook deferred a call in the running process. */
+		let deferring = false;
+		const { hold } = ports;
 		const events = async function* () {
 			const tools = orkTools({
 				nodeId: spec.nodeId,
 				driver: "cli",
 				ports
 			});
-			const mcp = await startOrkMcpHttp(tools);
-			const args = buildCliArgs(spec, mcp, preapprovedTools(tools));
-			const child = spawn(options.bin ?? "claude", args, {
-				cwd: spec.cwd,
-				env: { ...options.env ?? process.env },
-				stdio: [
-					"pipe",
-					"pipe",
-					"pipe"
-				]
-			});
-			const exited = new Promise((resolve) => {
-				child.on("close", (code) => {
-					resolve(code);
-				});
-			});
-			const spawnError = new Promise((resolve) => {
-				child.on("error", resolve);
+			const mcp = await startOrkMcpHttp(tools, hold === void 0 ? void 0 : async (gone) => {
+				const answer = await holdAtTool(hold, AbortSignal.any([gone, ended.signal]), options.holdWindowMs);
+				if (answer === "defer") deferring = true;
+				return hookOutput(answer);
 			});
-			const stderr = [];
-			child.stderr.setEncoding("utf8");
-			child.stderr.on("data", (chunk) => {
-				stderr.push(...chunk.split("\n").filter((l) => l.trim() !== ""));
-				stderr.splice(0, Math.max(0, stderr.length - STDERR_LINES));
+			const allowed = preapprovedTools(tools);
+			const endpoint = hold === void 0 ? {
+				url: mcp.url,
+				token: mcp.token
+			} : mcp;
+			const legOf = (args, carried) => runLeg({
+				bin: options.bin ?? "claude",
+				env: options.env ?? process.env,
+				cwd: spec.cwd,
+				args,
+				carried,
+				pending,
+				deferred: () => deferring,
+				attach: (attached) => {
+					io = attached;
+				}
 			});
-			write = (line) => {
-				if (child.stdin.writable) child.stdin.write(line);
-			};
-			stop = () => {
-				child.kill("SIGINT");
-			};
-			for (const line of pending.splice(0)) write(line);
-			let finished = false;
+			let args = buildCliArgs(spec, endpoint, allowed);
+			let spent;
 			try {
-				const lines = createInterface({ input: child.stdout });
-				for await (const line of lines) for (const event of normalize(parseLine(line))) {
-					if (event.type === "session.finished") {
-						finished = true;
-						child.stdin.end();
+				for (;;) {
+					const leg = yield* legOf(args, spent);
+					if (leg.kind === "failed") {
+						yield driverFailure(leg.reason);
+						return;
 					}
-					yield withDriver(event, "cli");
-				}
-				const code = await Promise.race([exited, spawnError.then((error) => error)]);
-				if (!finished) {
-					const reason = code instanceof Error ? `could not start ${options.bin ?? "claude"}: ${code.message}` : stderr.at(-1) ?? `claude exited with code ${String(code)}`;
-					yield driverFailure(reason);
+					if (leg.kind === "finished") return;
+					deferring = false;
+					spent = spent === void 0 ? leg.usage : addUsage(spent, leg.usage);
+					await hold?.wait("tool", ended.signal);
+					if (ended.signal.aborted) {
+						yield leg.last;
+						return;
+					}
+					args = buildCliArgs({
+						...spec,
+						resume: leg.sessionId
+					}, endpoint, allowed);
 				}
 			} finally {
-				if (child.exitCode === null) child.kill();
 				await mcp.close();
 			}
 		};
@@ -664,11 +897,12 @@ const createCliRuntime = (options = {}) => ({
 			events: events(),
 			send: (text) => {
 				const line = userLine(text, true);
-				if (write === void 0) pending.push(line);
-				else write(line);
+				if (io === void 0) pending.push(line);
+				else io.write(line);
 			},
 			interrupt: () => {
-				stop?.();
+				ended.abort();
+				io?.stop();
 				return Promise.resolve();
 			}
 		};
@@ -721,7 +955,10 @@ const createQueue = () => {
 // ../runtime-claude/src/sdk.ts
 /**
 * @file The SDK driver: runs a session in-process with the Claude Agent SDK,
-*   only with an API key or a cloud provider, never a claude.ai login.
+*   only with an API key or a cloud provider, never a claude.ai login. A node
+*   that can be paused gets a `PreToolUse` callback hook: a short pause holds
+*   the call, a long one defers it and resumes the session when the node
+*   continues (ADR-041).
 */
 /**
 * The SDK driver runs only with an API key or a cloud provider. It must never
@@ -747,8 +984,24 @@ const userMessage = (text, later = false) => ({
 	...later ? { priority: "next" } : {}
 });
 const definedEnv = (env) => Object.fromEntries(Object.entries(env).filter((entry) => entry[1] !== void 0));
+/**
+* The hold hook: waits before each tool call while the node is paused, and
+* defers the call (`onDefer`) when the pause outlasts the window.
+*/
+const holdHook = (hold, onDefer, windowMs) => ({
+	timeout: 600,
+	hooks: [async (_input, _toolUseId, { signal }) => {
+		if (await holdAtTool(hold, signal, windowMs) === "go") return {};
+		onDefer();
+		return { hookSpecificOutput: {
+			hookEventName: "PreToolUse",
+			permissionDecision: "defer",
+			permissionDecisionReason: "Ork paused this node; it goes on from this call when it continues."
+		} };
+	}]
+});
 /** The Agent SDK options for a session spec. */
-const buildSdkOptions = (spec, ports, env) => {
+const buildSdkOptions = (spec, ports, env, held) => {
 	const { human } = ports;
 	const tools = orkTools({
 		nodeId: spec.nodeId,
@@ -804,28 +1057,77 @@ const buildSdkOptions = (spec, ports, env) => {
 		path: dir
 	}));
 	if (spec.settings !== void 0) options.settings = spec.settings;
+	if (ports.hold !== void 0 && held !== void 0) options.hooks = { PreToolUse: [holdHook(ports.hold, held.onDefer, held.windowMs)] };
 	return options;
 };
 /** Drives a session with the Claude Agent SDK, in this process. */
-const createSdkRuntime = (env = process.env) => ({
+const createSdkRuntime = (env = process.env, holdWindowMs) => ({
 	driver: "sdk",
 	start: (spec, ports) => {
-		const input = createQueue();
+		let input = createQueue();
 		input.push(userMessage(spec.prompt));
 		let current;
+		const ended = new AbortController();
+		/** The hold hook deferred a call in the current query. */
+		let deferring = false;
+		const held = {
+			onDefer: () => {
+				deferring = true;
+			},
+			...holdWindowMs === void 0 ? {} : { windowMs: holdWindowMs }
+		};
+		/** One query: a leg of the session, until its result. */
+		const leg = async function* (resume, carried) {
+			deferring = false;
+			const legSpec = resume === void 0 ? spec : {
+				...spec,
+				resume
+			};
+			current = query({
+				prompt: input,
+				options: buildSdkOptions(legSpec, ports, env, held)
+			});
+			let outcome = {
+				kind: "failed",
+				reason: "the session ended early"
+			};
+			for await (const message of current) {
+				const { events, ended: end } = legStep(message, {
+					carried,
+					deferred: deferring,
+					driver: "sdk"
+				});
+				yield* events;
+				if (end !== void 0) {
+					input.close();
+					outcome = end;
+				}
+			}
+			return outcome;
+		};
 		const events = async function* () {
 			if (sdkCredentials(env) === null) {
 				yield driverFailure(NO_SDK_CREDENTIALS);
 				return;
 			}
+			let resume = spec.resume;
+			let spent;
 			try {
-				current = query({
-					prompt: input,
-					options: buildSdkOptions(spec, ports, env)
-				});
-				for await (const message of current) for (const event of normalize(message)) {
-					if (event.type === "session.finished") input.close();
-					yield withDriver(event, "sdk");
+				for (;;) {
+					const result = yield* leg(resume, spent);
+					if (result.kind === "failed") {
+						yield driverFailure(result.reason);
+						return;
+					}
+					if (result.kind === "finished") return;
+					input = createQueue();
+					spent = spent === void 0 ? result.usage : addUsage(spent, result.usage);
+					await ports.hold?.wait("tool", ended.signal);
+					if (ended.signal.aborted) {
+						yield result.last;
+						return;
+					}
+					resume = result.sessionId;
 				}
 			} catch (error) {
 				input.close();
@@ -838,6 +1140,7 @@ const createSdkRuntime = (env = process.env) => ({
 				input.push(userMessage(text, true));
 			},
 			interrupt: async () => {
+				ended.abort();
 				await current?.interrupt();
 			}
 		};