@krapht/ork 1.0.0-alpha.4 → 1.0.0-alpha.6

package/dist/{format-Creyq4U3.mjs → format-OL0E1AjA.mjs}

@@ -1,6 +1,211 @@
-import { ht as liveStatus } from "./src-BRB5EQyC.mjs";
-import { i as style, n as cost } from "./output-CuivUcDa.mjs";
+import { cn as maskSecrets, ht as liveStatus } from "./src-DG4dyBqm.mjs";
+import { i as style, n as cost } from "./output-CjOPL8W0.mjs";
 import { createInterface } from "node:readline/promises";
+// ../core/src/control/queue.ts
+const PERMISSION_OPTIONS = [{
+	id: "allow",
+	label: "Allow"
+}, {
+	id: "deny",
+	label: "Deny"
+}];
+const DENIED = "The user did not allow this tool.";
+/** The deny message a session gets, with the person's words when given. */
+const deniedMessage = (note) => note === void 0 ? DENIED : `${DENIED} They said: ${note}`;
+/** The input fields that say what a tool will do, the first one present. */
+const TOOL_INPUT_KEYS = [
+	"command",
+	"file_path",
+	"path",
+	"url",
+	"pattern"
+];
+/** A tool's input for the decision's context: as written, cut at `max`. */
+const inputContext = (input, max = 4e3) => {
+	const key = TOOL_INPUT_KEYS.find((k) => typeof input[k] === "string");
+	const text = key === void 0 ? JSON.stringify(input, void 0, 2) : String(input[key]);
+	return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+};
+const createDecisionQueue = (options) => {
+	const { store, runId, emit } = options;
+	let count = 0;
+	/** Opens a decision and settles it with the first answer. */
+	const decide = (open, local, withdrawn) => {
+		count += 1;
+		const id = `${runId}-${String(count)}`;
+		const record = store.openDecision({
+			...open,
+			id,
+			runId
+		});
+		const event = {
+			type: "decision.opened",
+			node: record.node,
+			decision: id,
+			kind: record.kind,
+			question: record.question,
+			options: record.options
+		};
+		if (record.recommended !== void 0) event.recommended = record.recommended;
+		if (record.owner !== void 0) event.owner = record.owner;
+		emit(event);
+		const { promise, resolve, reject } = Promise.withResolvers();
+		const settled = new AbortController();
+		/** `note` is the stored one: masked, and absent when blank. */
+		const finish = (answer, by, note) => {
+			if (settled.signal.aborted) return;
+			settled.abort();
+			const answered = {
+				type: "decision.answered",
+				node: open.node,
+				decision: id,
+				answer,
+				by
+			};
+			if (note !== void 0) answered.note = note;
+			emit(answered);
+			resolve(note === void 0 ? {
+				answer,
+				by
+			} : {
+				answer,
+				by,
+				note
+			});
+		};
+		const withdraw = () => {
+			if (settled.signal.aborted) return;
+			settled.abort();
+			store.withdrawDecision(id);
+			emit({
+				type: "decision.withdrawn",
+				node: open.node,
+				decision: id
+			});
+			reject(/* @__PURE__ */ new Error("the question was withdrawn"));
+		};
+		if (withdrawn?.aborted === true) withdraw();
+		withdrawn?.addEventListener("abort", withdraw, { once: true });
+		const fromStore = async () => {
+			try {
+				const closed = await options.waitFor(id, settled.signal);
+				if (closed.status === "answered" && closed.answer !== void 0) finish(closed.answer, closed.answeredBy ?? "decide", closed.note);
+			} catch {}
+		};
+		const fromTerminal = async (ask) => {
+			try {
+				const { answer, note } = await ask(settled.signal);
+				if (store.answerDecision(id, answer, "terminal", note)) finish(answer, "terminal", store.decision(id)?.note);
+			} catch {}
+		};
+		fromStore();
+		if (local !== void 0) fromTerminal(local);
+		return promise;
+	};
+	return {
+		ask: (question) => {
+			const open = {
+				node: question.nodeId,
+				kind: "question",
+				question: question.question,
+				options: question.options
+			};
+			if (question.recommended !== void 0) open.recommended = question.recommended;
+			if (question.context !== void 0) open.context = question.context;
+			if (question.document !== void 0) open.document = question.document;
+			if (question.owner !== void 0) open.owner = question.owner;
+			const { local } = options;
+			return decide(open, local === void 0 ? void 0 : (signal) => {
+				let note;
+				return local.ask({
+					...question,
+					question: maskSecrets(question.question),
+					...question.context === void 0 ? {} : { context: maskSecrets(question.context) },
+					...question.document === void 0 ? {} : { document: maskSecrets(question.document) },
+					signal,
+					onNote: (given) => {
+						note = given;
+					}
+				}).then((answer) => note === void 0 ? { answer } : {
+					answer,
+					note
+				});
+			}, question.signal).then(({ answer, note }) => {
+				if (note !== void 0) question.onNote?.(note);
+				return answer;
+			});
+		},
+		settled: (question) => {
+			count += 1;
+			const id = `${runId}-${String(count)}`;
+			const { owner } = question;
+			const record = store.openDecision({
+				id,
+				runId,
+				node: question.nodeId,
+				kind: "question",
+				question: question.question,
+				options: question.options,
+				owner,
+				...question.recommended === void 0 ? {} : { recommended: question.recommended },
+				...question.context === void 0 ? {} : { context: question.context }
+			});
+			emit({
+				type: "decision.opened",
+				node: record.node,
+				decision: id,
+				kind: "question",
+				question: record.question,
+				options: record.options,
+				owner,
+				...record.recommended === void 0 ? {} : { recommended: record.recommended }
+			});
+			store.answerDecision(id, question.answer, "owner", question.note);
+			const note = store.decision(id)?.note;
+			emit({
+				type: "decision.answered",
+				node: record.node,
+				decision: id,
+				answer: question.answer,
+				by: "owner",
+				owner,
+				...note === void 0 ? {} : { note }
+			});
+		},
+		permit: async (request) => {
+			const { local } = options;
+			let localMessage = DENIED;
+			const { answer, note } = await decide({
+				node: request.nodeId,
+				kind: "permission",
+				question: `Allow ${request.toolName}?`,
+				options: PERMISSION_OPTIONS,
+				context: inputContext(request.input)
+			}, local === void 0 ? void 0 : (signal) => {
+				let said;
+				return local.permit({
+					...request,
+					signal,
+					onNote: (given) => {
+						said = given;
+					}
+				}).then((result) => {
+					if (!result.allow) localMessage = result.message;
+					const choice = result.allow ? "allow" : "deny";
+					return said === void 0 ? { answer: choice } : {
+						answer: choice,
+						note: said
+					};
+				});
+			});
+			if (note !== void 0) request.onNote?.(note);
+			return answer === "allow" ? { allow: true } : {
+				allow: false,
+				message: note === void 0 ? localMessage : deniedMessage(note)
+			};
+		}
+	};
+};
 // src/human.ts
 /**
 * @file The terminal `HumanChannel`: answers `ask_user` questions, gates and
@@ -10,18 +215,14 @@ import { createInterface } from "node:readline/promises";
 *   answerer, racing `ork decide`.
 */
 const PREVIEW = 160;
+/** A document longer than this is offered (`d`) rather than printed. */
+const SHORT_DOCUMENT_LINES = 40;
 const NO_ONE_TO_PERMIT = "No one is at the terminal to approve this tool, so it is not allowed in this run.";
 const NOTE_PROMPT = "  Note for the run (optional, Enter to skip): ";
 const NO_ONE_TO_ASK = "no one (nobody is at the terminal; use your best judgment and say so in your report)";
 /** One line that shows what a tool is about to do. */
 const previewInput = (toolName, input) => {
-	const key = [
-		"command",
-		"file_path",
-		"path",
-		"url",
-		"pattern"
-	].find((k) => typeof input[k] === "string");
+	const key = TOOL_INPUT_KEYS.find((k) => typeof input[k] === "string");
 	const line = (key === void 0 ? JSON.stringify(input) : `${key}: ${String(input[key])}`).replaceAll(/\s+/gu, " ").trim();
 	return line.length > PREVIEW ? `${toolName} ${line.slice(0, 159)}…` : `${toolName} ${line}`;
 };
@@ -63,11 +264,13 @@ const createTerminalHuman = (io) => {
 		const note = (await prompt(NOTE_PROMPT, signal)).trim();
 		if (note !== "") onNote(note);
 	};
-	const choose = async (hint, options, recommended, signal) => {
-		const picked = pickOption(await prompt(`  Choose${hint}: `, signal), options, recommended);
+	const choose = async (hint, options, recommended, signal, document) => {
+		const answer = await prompt(`  Choose${hint}: `, signal);
+		const picked = pickOption(answer, options, recommended);
 		if (picked !== void 0) return picked;
-		say(style("dim", "  Type an option's number or id."));
-		return choose(hint, options, recommended, signal);
+		if (document !== void 0 && answer.trim() === "d") say(document);
+		else say(style("dim", "  Type an option's number or id."));
+		return choose(hint, options, recommended, signal, document);
 	};
 	const oneAtATime = (work) => {
 		const result = turn.then(work);
@@ -93,10 +296,12 @@ const createTerminalHuman = (io) => {
 				message: "The user did not allow this tool."
 			};
 		}),
-		ask: ({ nodeId, question, options, recommended, context, signal, onNote }) => oneAtATime(async () => {
+		ask: ({ nodeId, question, options, recommended, context, document, signal, onNote }) => oneAtATime(async () => {
 			if (signal?.aborted === true) throw new Error("the question was withdrawn");
+			const documentLines = document?.trimEnd().split("\n").length ?? 0;
+			if (document !== void 0 && documentLines <= SHORT_DOCUMENT_LINES) say(document);
 			say(`${style(["yellow", "bold"], "?")} ${style("bold", nodeId)} asks: ${question}`);
-			if (context !== void 0) say(style("dim", `  ${context}`));
+			if (context !== void 0) say(style("dim", `  ${context.replaceAll("\n", "\n  ")}`));
 			for (const [index, option] of options.entries()) say(optionLine(option, index, recommended));
 			if (!io.interactive) {
 				const answer = recommended ?? NO_ONE_TO_ASK;
@@ -105,7 +310,8 @@ const createTerminalHuman = (io) => {
 			}
 			const fallback = options.findIndex((o) => o.id === recommended);
 			const hint = fallback === -1 ? "" : ` [${String(fallback + 1)}]`;
-			const picked = await choose(hint, options, recommended, signal);
+			if (documentLines > SHORT_DOCUMENT_LINES) say(`  Document: ${String(documentLines)} lines. Type d to read it.`);
+			const picked = await choose(hint, options, recommended, signal, document);
 			await takeNote(onNote, signal);
 			return picked;
 		}),
@@ -424,4 +630,4 @@ const formatTree = (roots) => {
 		return `${text.padEnd(label)}  ${style("dim", node.type.padEnd(type))}  ${state}${usage}`;
 	});
 };
-export { formatRunEvent as a, formatEvent as i, formatRuns as n, createTerminalHuman as o, formatTree as r, ago as t };
+export { formatRunEvent as a, formatEvent as i, formatRuns as n, createTerminalHuman as o, formatTree as r, createDecisionQueue as s, ago as t };

package/dist/{in-a-run-CsSBQQ2q.mjs → in-a-run-emTc-kZI.mjs}

@@ -1,4 +1,4 @@
-import { p as runMarkerIn } from "./src-Bc9yaAiZ.mjs";
+import { p as runMarkerIn } from "./src-8nec4uoe.mjs";
 // src/commands/in-a-run.ts
 /**
 * @file The commands that act as the user refuse a program or an agent in a run

package/dist/{limits-D_HxH0CK.mjs → limits-TxTnWxix.mjs}

@@ -1,4 +1,4 @@
-import { a as limitsNow, i as NOT_STARTED, o as limitsReport, r as capsHere } from "./src-BRB5EQyC.mjs";
+import { a as limitsNow, i as NOT_STARTED, o as limitsReport, r as capsHere } from "./src-DG4dyBqm.mjs";
 // src/run/limits.ts
 /**
 * @file The limits across runs that apply here (RFC-007): the user's settings

package/dist/{list-CzzpVEpM.mjs → list-P5CfcoWx.mjs}

@@ -1,4 +1,4 @@
-import { A as gitOk, j as lines, k as git } from "./src-BRB5EQyC.mjs";
+import { A as gitOk, j as lines, k as git } from "./src-DG4dyBqm.mjs";
 import { existsSync } from "node:fs";
 // ../core/src/worktree/list.ts
 /**

package/dist/{mcp-DYmQt372.mjs → mcp-qUwFT9yi.mjs}

@@ -1,8 +1,8 @@
-import { h as isNewer } from "./src-BRB5EQyC.mjs";
-import { n as ORK_VERSION } from "./__build_info__-1i1IwLg7.mjs";
-import { a as openMcp, c as refused, o as tool, s as answer } from "./src-CsjumY1t.mjs";
-import { p as runMarkerIn } from "./src-Bc9yaAiZ.mjs";
-import { n as explainNode } from "./context-CD5TCD1D.mjs";
+import { h as isNewer } from "./src-DG4dyBqm.mjs";
+import { n as ORK_VERSION } from "./__build_info__-CxH89h1r.mjs";
+import { a as openMcp, c as refused, o as tool, s as answer } from "./src-jyCJE1kd.mjs";
+import { p as runMarkerIn } from "./src-8nec4uoe.mjs";
+import { n as explainNode } from "./context-CHV6aTs7.mjs";
 import { z } from "zod";
 import { defineCommand } from "citty";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -43,7 +43,7 @@ const orkMcpServer = (options = {}) => {
 		...options.script === void 0 ? {} : { script: options.script }
 	});
 	const all = [...opened.tools, explainTool(opened, options.home)];
-	const tools = options.expects !== void 0 && isNewer(options.expects, "1.0.0-alpha.4") ? tooOld(all, options.expects) : all;
+	const tools = options.expects !== void 0 && isNewer(options.expects, "1.0.0-alpha.6") ? tooOld(all, options.expects) : all;
 	const server = new McpServer({
 		name: "ork",
 		version: ORK_VERSION

package/dist/{output-CuivUcDa.mjs → output-CjOPL8W0.mjs}

@@ -1,4 +1,4 @@
-import { $ as text, $t as maskReplacer, Ht as FEEDBACK_SEVERITIES, Q as inTransaction, Ut as FEEDBACK_TARGETS, Vt as FEEDBACK_KINDS, X as usageQueries, Y as backfillUsage, Z as eventOf, en as maskSecrets, yn as PROJECT_MODES, yt as ownProcessStart } from "./src-BRB5EQyC.mjs";
+import { $ as text, Ht as FEEDBACK_SEVERITIES, Q as inTransaction, Ut as FEEDBACK_TARGETS, Vt as FEEDBACK_KINDS, X as usageQueries, Y as backfillUsage, Z as eventOf, cn as maskSecrets, sn as maskReplacer, yn as PROJECT_MODES, yt as ownProcessStart } from "./src-DG4dyBqm.mjs";
 import path from "node:path";
 import { mkdirSync } from "node:fs";
 import { homedir } from "node:os";
@@ -70,6 +70,7 @@ const decisionOf = (row) => {
 	const optional = {
 		recommended: text(row, "recommended"),
 		context: text(row, "context"),
+		document: text(row, "document"),
 		answer: text(row, "answer"),
 		answeredAt: text(row, "answered_at"),
 		note: text(row, "note"),
@@ -81,8 +82,8 @@ const decisionOf = (row) => {
 	return record;
 };
 const decisionQueries = (db) => {
-	const insert = db.prepare(`INSERT INTO decisions (id, run_id, node, kind, question, options, recommended, context, owner, opened_at, status)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'open')`);
+	const insert = db.prepare(`INSERT INTO decisions (id, run_id, node, kind, question, options, recommended, context, document, owner, opened_at, status)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'open')`);
 	const answer = db.prepare(`UPDATE decisions SET status = 'answered', answer = ?, answered_by = ?, answered_at = ?, note = ?
      WHERE id = ? AND status = 'open'`);
 	const withdraw = db.prepare("UPDATE decisions SET status = 'withdrawn', answered_at = ? WHERE id = ? AND status = 'open'");
@@ -102,9 +103,10 @@ const decisionQueries = (db) => {
 			const masked = {
 				...decision,
 				question: maskSecrets(decision.question),
-				...decision.context === void 0 ? {} : { context: maskSecrets(decision.context) }
+				...decision.context === void 0 ? {} : { context: maskSecrets(decision.context) },
+				...decision.document === void 0 ? {} : { document: maskSecrets(decision.document) }
 			};
-			insert.run(masked.id, masked.runId, masked.node, masked.kind, masked.question, JSON.stringify(masked.options), masked.recommended ?? null, masked.context ?? null, masked.owner ?? null, openedAt);
+			insert.run(masked.id, masked.runId, masked.node, masked.kind, masked.question, JSON.stringify(masked.options), masked.recommended ?? null, masked.context ?? null, masked.document ?? null, masked.owner ?? null, openedAt);
 			return {
 				...masked,
 				openedAt,
@@ -731,7 +733,8 @@ const MIGRATIONS = [
 	`ALTER TABLE runs ADD COLUMN skipped INTEGER;
    ALTER TABLE runs ADD COLUMN failures_handled INTEGER;`,
 	`ALTER TABLE decisions ADD COLUMN note TEXT;`,
-	`ALTER TABLE decisions ADD COLUMN owner TEXT;`
+	`ALTER TABLE decisions ADD COLUMN owner TEXT;`,
+	`ALTER TABLE decisions ADD COLUMN document TEXT;`
 ];
 const versionOf = (db) => Number(db.prepare("PRAGMA user_version").get()?.["user_version"] ?? 0);
 /**

package/dist/{pause-W6MzQqg8.mjs → pause-CBSAxtTp.mjs}

@@ -1,7 +1,7 @@
-import { G as requestContinue, K as requestPause } from "./src-BRB5EQyC.mjs";
-import { t as findRun } from "./find-BgZjVKhv.mjs";
-import { a as write, c as openStore, i as style, o as writeErr } from "./output-CuivUcDa.mjs";
-import { r as continueRefusal } from "./in-a-run-CsSBQQ2q.mjs";
+import { G as requestContinue, K as requestPause } from "./src-DG4dyBqm.mjs";
+import { t as findRun } from "./find-Dy2H5IvT.mjs";
+import { a as write, c as openStore, i as style, o as writeErr } from "./output-CjOPL8W0.mjs";
+import { r as continueRefusal } from "./in-a-run-emTc-kZI.mjs";
 import { defineCommand } from "citty";
 // src/commands/pause.ts
 /**

package/dist/{relay-CsdoZUXJ.mjs → relay-UgK1Cp9a.mjs}

@@ -1,5 +1,5 @@
-import { B as linkNodes, L as addressOf, U as unlinkNodes } from "./src-BRB5EQyC.mjs";
-import { a as write, c as openStore, i as style, o as writeErr } from "./output-CuivUcDa.mjs";
+import { B as linkNodes, L as addressOf, U as unlinkNodes } from "./src-DG4dyBqm.mjs";
+import { a as write, c as openStore, i as style, o as writeErr } from "./output-CjOPL8W0.mjs";
 import { defineCommand } from "citty";
 // src/commands/relay.ts
 /**

package/dist/{remove-DLfDjBdF.mjs → remove-ccycC3vI.mjs}

@@ -1,6 +1,6 @@
-import { ht as liveStatus, j as lines, k as git } from "./src-BRB5EQyC.mjs";
-import { n as listOrkWorktrees, t as createdWorktrees } from "./list-CzzpVEpM.mjs";
-import { i as keyOf, n as applyStep, r as cleanStep, s as stepPrunes } from "./clean-B1zPxq6A.mjs";
+import { ht as liveStatus, j as lines, k as git } from "./src-DG4dyBqm.mjs";
+import { n as listOrkWorktrees, t as createdWorktrees } from "./list-P5CfcoWx.mjs";
+import { i as keyOf, n as applyStep, r as cleanStep, s as stepPrunes } from "./clean-BbrkMQQi.mjs";
 // ../core/src/worktree/words.ts
 /**
 * @file The plain words for what `ork worktrees` shows, in one place, so the

package/dist/{send-Bw2FI_Sv.mjs → send-B39-Xeo7.mjs}

@@ -1,6 +1,6 @@
-import { cn as wakeRun, ht as liveStatus, kt as scriptContactsOf, on as socketPath } from "./src-BRB5EQyC.mjs";
-import { c as openStore, o as writeErr } from "./output-CuivUcDa.mjs";
-import { u as inheritedScrubber } from "./src-Bc9yaAiZ.mjs";
+import { ht as liveStatus, in as socketPath, kt as scriptContactsOf, on as wakeRun } from "./src-DG4dyBqm.mjs";
+import { c as openStore, o as writeErr } from "./output-CjOPL8W0.mjs";
+import { u as inheritedScrubber } from "./src-8nec4uoe.mjs";
 import { defineCommand } from "citty";
 // ../core/src/remote/send.ts
 /**

package/dist/{src-CrYCkU9J.mjs → src-5-sCA7cY.mjs}

@@ -1,4 +1,4 @@
-import { Ht as FEEDBACK_SEVERITIES, Ut as FEEDBACK_TARGETS, Vt as FEEDBACK_KINDS, pt as parseReport } from "./src-BRB5EQyC.mjs";
+import { Ht as FEEDBACK_SEVERITIES, Ut as FEEDBACK_TARGETS, Vt as FEEDBACK_KINDS, pt as parseReport } from "./src-DG4dyBqm.mjs";
 import { z } from "zod";
 import { randomBytes, timingSafeEqual } from "node:crypto";
 import { createInterface } from "node:readline";
@@ -336,20 +336,45 @@ const text = (value) => ({ content: [{
 	type: "text",
 	text: value
 }] });
-const defineTool = (definition) => {
-	const schema = z.object(definition.shape);
-	return {
-		name: definition.name,
-		bind: (context) => definition.available?.(context) ?? true ? {
+const issueAt = (issue) => {
+	const where = z.core.toDotPath(issue.path);
+	return where === "" ? "" : `${where}: `;
+};
+/** Whether `issue` is about a field of the object `parent` is about. */
+const isFieldOf = (issue, parent) => issue.path.length === parent.path.length + 1 && parent.path.every((key, index) => key === issue.path[index]);
+const expectedField = (issue) => `; the field is \`${String(issue.path.at(-1))}\`${issue.code === "invalid_value" ? `, one of: ${issue.values.join(", ")}` : ""}`;
+/**
+* A failed parse as text a model can act on. A stray key is reported with the
+* fields its object lacks, read from the schema's own issues: a wrong name is
+* otherwise only a "missing" error that hides what was sent.
+*/
+const readableIssues = (issues) => {
+	const strays = issues.filter((issue) => issue.code === "unrecognized_keys");
+	const lacking = issues.filter((issue) => issue.input === void 0 && strays.some((stray) => isFieldOf(issue, stray)));
+	return [...strays.map((stray) => `${issueAt(stray)}unknown field ${stray.keys.map((key) => `\`${key}\``).join(", ")}${lacking.filter((issue) => isFieldOf(issue, stray)).map((issue) => expectedField(issue)).join("")}`), ...issues.filter((issue) => issue.code !== "unrecognized_keys" && !lacking.includes(issue)).map((issue) => `${issueAt(issue)}${issue.message}`)].join("\n");
+};
+const defineTool = (definition) => ({
+	name: definition.name,
+	bind: (context) => {
+		if (!(definition.available?.(context) ?? true)) return null;
+		const shape = typeof definition.shape === "function" ? definition.shape(context) : definition.shape;
+		const schema = z.object(shape);
+		return {
 			name: definition.name,
 			description: definition.description,
-			shape: definition.shape,
+			shape,
 			schema,
 			preapproved: definition.preapproved ?? true,
-			call: (args) => definition.run(context, schema.parse(args))
-		} : null
-	};
-};
+			call: (args) => {
+				const parsed = schema.safeParse(args, { reportInput: true });
+				return parsed.success ? definition.run(context, parsed.data) : Promise.resolve({
+					...text(readableIssues(parsed.error.issues)),
+					isError: true
+				});
+			}
+		};
+	}
+});
 // ../runtime-claude/src/mcp-http.ts
 /**
 * @file A minimal MCP server over the streamable HTTP transport, for the
@@ -621,10 +646,13 @@ const delegationText = (delegation) => text(JSON.stringify({
 const delegateTool = defineTool({
 	name: "delegate",
 	description: "Hand tasks to nodes you own. Tasks in one call run in parallel; the call returns every child's report when all are done. Ork merges a passing child's branch into yours.",
-	shape: { tasks: z.array(z.object({
-		child: z.string().describe("The id of a node you own."),
-		brief: BRIEF
-	})).min(1) },
+	shape: ({ ports }) => {
+		const ids = ports.ownership?.children.map((child) => child.id) ?? [];
+		return { tasks: z.array(z.strictObject({
+			child: z.enum(ids).describe(`The id of a node you own: ${ids.join(", ")}.`),
+			brief: BRIEF
+		})).min(1) };
+	},
 	available: ({ ports }) => (ports.ownership?.children.length ?? 0) > 0,
 	run: async ({ ports }, args) => {
 		if (ports.ownership === void 0) return text("You own no nodes.");
@@ -634,10 +662,13 @@ const delegateTool = defineTool({
 const spawnWorkerTool = defineTool({
 	name: "spawn_worker",
 	description: "Start new instances of a child worker for work that splits into independent parts. Each runs in its own worktree; the call returns their reports when all are done.",
-	shape: { tasks: z.array(z.object({
-		template: z.string().describe("The id of a child worker you own."),
-		brief: BRIEF
-	})).min(1) },
+	shape: ({ ports }) => {
+		const ids = ports.ownership?.templates ?? [];
+		return { tasks: z.array(z.strictObject({
+			template: z.enum(ids).describe(`The id of a child worker you own: ${ids.join(", ")}.`),
+			brief: BRIEF
+		})).min(1) };
+	},
 	available: ({ ports }) => ports.ownership !== void 0 && ports.ownership.templates.length > 0 && ports.ownership.workersLeft() > 0,
 	run: async ({ ports }, args) => {
 		if (ports.ownership === void 0) return text("You own no workers.");

package/dist/{src-Bc9yaAiZ.mjs → src-8nec4uoe.mjs}

@@ -1,4 +1,4 @@
-import { $n as isToolNode, At as runScope, Bt as serversIn, F as declaredProblem, Mt as envReadsOf, Ot as heldTimeout, Pt as declaredOutputOf, Rt as MCP_FILE, Wn as markValue, Zn as beforeOf, ar as integrationFor, er as programsRunBy, ft as sessionDriver, ir as TOOL_PREFIX, jt as calledWorkflows, mt as reportSchemaFor, nn as parseTemplate, nr as timeoutMs, rn as renderTemplate, rr as INTEGRATIONS, s as planReason, tn as evaluate, ut as planNodeSession, zt as mcpNotText } from "./src-BRB5EQyC.mjs";
+import { $n as isToolNode, $t as evaluate, At as runScope, Bt as serversIn, F as declaredProblem, Mt as envReadsOf, Ot as heldTimeout, Pt as declaredOutputOf, Rt as MCP_FILE, Wn as markValue, Zn as beforeOf, ar as integrationFor, en as parseTemplate, er as programsRunBy, ft as sessionDriver, ir as TOOL_PREFIX, jt as calledWorkflows, mt as reportSchemaFor, nr as timeoutMs, rr as INTEGRATIONS, s as planReason, tn as renderTemplate, ut as planNodeSession, zt as mcpNotText } from "./src-DG4dyBqm.mjs";
 import path from "node:path";
 import { accessSync, constants, lstatSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { spawn } from "node:child_process";
@@ -1689,10 +1689,11 @@ const claudeExecutor = (options) => async (context) => {
 };
 // ../nodes/src/gate.ts
 /**
-* @file The `human.gate` node type: asks the human the rendered question,
-*   outputs their choice with the note they gave, and answers with the
-*   `default` when the `timeout` passes. The timeout counts only while the run
-*   and the gate are not paused (ADR-041).
+* @file The `human.gate` node type: asks the human the rendered question, with
+*   its document if it has one, both in readable text (no raw JSON), outputs
+*   their choice with the note they gave, and answers with the `default` when
+*   the `timeout` passes. The timeout counts only while the run and the gate
+*   are not paused (ADR-041).
 */
 /** A promise that never settles: the losing side of a race. */
 const NEVER = new Promise(() => {});
@@ -1714,8 +1715,13 @@ const gateExecutor = async (context) => {
 		output: {},
 		error: `${context.id} is not a gate`
 	};
-	const template = parseTemplate(node.question);
-	const question = template.ok ? renderTemplate(template.parts, runScope(context.inputs, context.outputs, context.runId)) : node.question;
+	const scope = runScope(context.inputs, context.outputs, context.runId);
+	const render = (text) => {
+		const template = parseTemplate(text);
+		return template.ok ? renderTemplate(template.parts, scope, { readable: true }) : text;
+	};
+	const question = render(node.question);
+	const document = render(node.document ?? "");
 	const options = node.options.map((o) => choiceOf(o));
 	const withdraw = new AbortController();
 	context.signal.addEventListener("abort", () => {
@@ -1732,6 +1738,7 @@ const gateExecutor = async (context) => {
 		}
 	};
 	if (node.recommended !== void 0) asked.recommended = node.recommended;
+	if (document.trim() !== "") asked.document = document;
 	const answer = context.human.ask(asked).then((choice) => ({
 		choice,
 		answeredBy: "user",