@sgtbeatdown/wolfpack-tasks 0.0.0-stage → 0.2.0

package/src/claude/server.ts

@@ -0,0 +1,37 @@
+import { execFile } from "node:child_process";
+import { createInterface } from "node:readline";
+
+import { createClaudeTaskServer } from "./mcp-server";
+import type { CommandRunner } from "./wake";
+
+/** Runs an argv array without a shell. A non-zero exit is a result, not an error: callers read stdout either way. */
+const runCommand: CommandRunner = (argv, options) => new Promise((resolve, reject) => {
+	const [file, ...args] = argv;
+	if (!file) { reject(new Error("empty command")); return; }
+	execFile(file, args, { timeout: options.timeoutMs, maxBuffer: 1024 * 1024, encoding: "utf8", windowsHide: true }, (error, stdout, stderr) => {
+		if (error && typeof error.code !== "number") { reject(error); return; }
+		resolve({ exitCode: error ? Number(error.code) : 0, stdout, stderr });
+	});
+});
+
+// Stdout carries only JSON-RPC. Route stray console output from any bundled code to stderr.
+console.log = console.info = console.debug = (...values: unknown[]) => console.error(...values);
+
+const server = createClaudeTaskServer({
+	env: process.env,
+	send: (message) => { process.stdout.write(`${JSON.stringify(message)}\n`); },
+	runCommand,
+	log: (message) => { process.stderr.write(`${message}\n`); },
+});
+
+let stopping: Promise<void> | undefined;
+const stop = (): Promise<void> => {
+	stopping ??= server.shutdown().catch(() => undefined).finally(() => process.exit(0));
+	return stopping;
+};
+
+// Requests run concurrently: a long agent_task_wait must not block pings, cancellations or other tools.
+createInterface({ input: process.stdin, crlfDelay: Number.POSITIVE_INFINITY })
+	.on("line", (line) => { void server.handleLine(line); })
+	.on("close", () => { void stop(); });
+for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"] as const) process.on(signal, () => { void stop(); });

package/src/claude/status-file.ts

@@ -0,0 +1,66 @@
+import { chmodSync, mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+import type { WakeMode } from "./wake";
+
+export const STATUS_FILE_VERSION = 1;
+
+export interface ClaudeStatus {
+	readonly version: typeof STATUS_FILE_VERSION;
+	readonly sessionId: string;
+	readonly sessionName: string;
+	readonly pid: number;
+	readonly wake: WakeMode;
+	/** The MCP protocol version this server answered. */
+	readonly protocolVersion: string;
+	/** The version the client proposed, when it was a string. */
+	readonly clientProtocolVersion: string | null;
+	readonly startedAt: number;
+	readonly updatedAt: number;
+	readonly lastPointerAt: number | null;
+	readonly lastInboxAt: number | null;
+	readonly lastNudgeAt: number | null;
+	readonly fallbackAt: number | null;
+	readonly lastNudgeError: string | null;
+	/** Failed wolfpack status checks for the current pointer; a positive value means the fallback is retrying. */
+	readonly statusFailures: number;
+	/** When a pointer's fallback was given up after its status retries; null after the next inbox call. */
+	readonly wakeStalledAt: number | null;
+	/** The runtime's last status-line text; null when clear. */
+	readonly lastStatus: string | null;
+}
+
+export type ClaudeStatusPatch = Partial<Omit<ClaudeStatus, "version" | "sessionId" | "sessionName" | "pid" | "startedAt" | "updatedAt">>;
+
+export interface ClaudeStatusFile {
+	readonly path: string;
+	update(patch: ClaudeStatusPatch): void;
+}
+
+/** Diagnostic status for operators and tests, rewritten atomically on change; never read back as task state. */
+export function createStatusFile(path: string, initial: Omit<ClaudeStatus, "version" | "updatedAt">, now: () => number, log: (message: string) => void): ClaudeStatusFile {
+	let status: ClaudeStatus = { version: STATUS_FILE_VERSION, ...initial, updatedAt: now() };
+	let failed = false;
+	const write = (): void => {
+		try {
+			mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+			const temporary = `${path}.${process.pid}.tmp`;
+			writeFileSync(temporary, `${JSON.stringify(status, null, 2)}\n`, { mode: 0o600 });
+			chmodSync(temporary, 0o600);
+			renameSync(temporary, path);
+			failed = false;
+		} catch (error) {
+			// Best effort: report the first failure of a streak, never fail task work over diagnostics.
+			if (!failed) log(`wolfpack-tasks: status file write failed: ${error instanceof Error ? error.message : String(error)}`);
+			failed = true;
+		}
+	};
+	write();
+	return {
+		path,
+		update(patch) {
+			status = { ...status, ...patch, updatedAt: now() };
+			write();
+		},
+	};
+}

package/src/claude/validation.ts

@@ -0,0 +1,28 @@
+import { Compile } from "typebox/compile";
+import type { TSchema } from "typebox";
+import { Value } from "typebox/value";
+
+const validators = new WeakMap<TSchema, ReturnType<typeof Compile>>();
+
+/**
+ * Mirrors Pi's tool argument validation (pi-ai `validateToolArguments` for TypeBox schemas): clone, convert, check,
+ * and the same error text, so a Claude model sees the same feedback for the same invalid call.
+ */
+export function validateToolArguments(name: string, schema: TSchema, input: unknown): unknown {
+	const args = structuredClone(input);
+	Value.Convert(schema, args);
+	let validator = validators.get(schema);
+	if (!validator) { validator = Compile(schema); validators.set(schema, validator); }
+	if (validator.Check(args)) return args;
+	const errors = validator.Errors(args).map((error) => `  - ${validationPath(error)}: ${error.message}`).join("\n") || "Unknown validation error";
+	throw new Error(`Validation failed for tool "${name}":\n${errors}\n\nReceived arguments:\n${JSON.stringify(input, null, 2)}`);
+}
+
+function validationPath(error: { readonly keyword: string; readonly instancePath: string; readonly params: unknown }): string {
+	const base = error.instancePath.replace(/^\//, "").replace(/\//g, ".");
+	if (error.keyword === "required") {
+		const property = (error.params as { readonly requiredProperties?: readonly string[] }).requiredProperties?.[0];
+		if (property) return base ? `${base}.${property}` : property;
+	}
+	return base || "root";
+}

package/src/claude/wake.ts

@@ -0,0 +1,215 @@
+import { CLAUDE_PLUGIN } from "./constants";
+
+/** Relay-side bound for a held delivery to reach its receiver's model; the fallback must finish well inside it. */
+export const RELAY_WAKE_DEADLINE_MS = 120_000;
+
+export interface WakeTiming {
+	/** Channel mode: how long a pointer may stay unanswered before the fallback is considered. */
+	readonly channelGraceMs: number;
+	/** Fallback mode: the same delay once the channel was found not to wake the model. */
+	readonly fallbackGraceMs: number;
+	/** After a Stop hook, the quiet period before an idle session is nudged. */
+	readonly settleMs: number;
+	/** Per wolfpack CLI command. */
+	readonly commandTimeoutMs: number;
+	/** Spacing between status checks for the same pointer after a failed or unreadable status. */
+	readonly statusRetryMs: number;
+	/** Status checks per pointer before its fallback is given up and the pointer is released. */
+	readonly statusAttempts: number;
+}
+
+export const DEFAULT_WAKE_TIMING: WakeTiming = Object.freeze({ channelGraceMs: 15_000, fallbackGraceMs: 2_000, settleMs: 3_000, commandTimeoutMs: 10_000, statusRetryMs: 5_000, statusAttempts: 3 });
+
+/**
+ * A nudged pointer that is still unanswered this long after its nudge is replaced by the next pointer request, so an
+ * uncertain or ignored nudge cannot hold later mail forever. It also bounds a repeated paste to one per period.
+ */
+export const NUDGED_POINTER_EXPIRY_MS = RELAY_WAKE_DEADLINE_MS;
+
+export type WakeMode = "channel" | "fallback";
+export type SessionActivity = "busy" | "idle";
+
+export interface WakeTimers {
+	now(): number;
+	/** Returns a cancel function. */
+	setTimeout(fire: () => void, ms: number): () => void;
+}
+
+export interface CommandResult {
+	readonly exitCode: number;
+	readonly stdout: string;
+	readonly stderr: string;
+}
+
+/** Runs an argv array without a shell. */
+export type CommandRunner = (argv: readonly string[], options: { readonly timeoutMs: number }) => Promise<CommandResult>;
+
+export interface WakeStatusPatch {
+	readonly wake?: WakeMode;
+	readonly lastPointerAt?: number;
+	readonly lastInboxAt?: number;
+	readonly lastNudgeAt?: number;
+	readonly fallbackAt?: number;
+	readonly lastNudgeError?: string;
+	/** Failed status checks for the current pointer. */
+	readonly statusFailures?: number;
+	/** Set when a pointer's fallback was given up after its status retries; cleared by the next inbox call. */
+	readonly wakeStalledAt?: number | null;
+}
+
+export interface WakeControllerOptions {
+	readonly sessionId: string;
+	sendChannel(meta: Readonly<Record<string, string>>): void;
+	readonly runCommand: CommandRunner;
+	readonly timers: WakeTimers;
+	readonly timing?: WakeTiming;
+	onChange(patch: WakeStatusPatch): void;
+}
+
+export interface WakeController {
+	readonly mode: WakeMode;
+	/** True from a pointer request until `inboxCalled`. */
+	readonly pointerOutstanding: boolean;
+	/** Coalesced: at most one pointer is outstanding until `inboxCalled`. */
+	requestPointer(meta: Readonly<Record<string, string>>): void;
+	inboxCalled(): void;
+	activity(state: SessionActivity): void;
+	close(): void;
+}
+
+interface Outstanding {
+	readonly at: number;
+	/** The once-per-pointer nudge started its terminal sends (successfully or not). */
+	nudged: boolean;
+	nudgedAt?: number;
+	nudging: boolean;
+	statusFailures: number;
+}
+
+/**
+ * Channel pointer plus the D6 fallback. Activity comes from Claude Code hooks: UserPromptSubmit and PreToolUse mean
+ * busy, Stop means idle. A fresh session starts idle because no turn has begun. The fallback never runs while busy.
+ *
+ * Failure policy: a status check has no terminal side effect, so a failed, unreadable or not-ready status (or a runner
+ * error such as ENOENT) is retried for the same idle pointer up to `statusAttempts`; then the pointer is released and
+ * the next pointer request starts over. A paste or submit that fails, times out or throws is uncertain: the text may
+ * already be in the prompt input. It is never repeated and never followed by a submit for that pointer; the pointer
+ * expires `NUDGED_POINTER_EXPIRY_MS` after the nudge.
+ */
+export function createWakeController(options: WakeControllerOptions): WakeController {
+	const timing = options.timing ?? DEFAULT_WAKE_TIMING;
+	let mode: WakeMode = "channel";
+	let activity: SessionActivity = "idle";
+	let outstanding: Outstanding | undefined;
+	let cancelTimer: (() => void) | undefined;
+	let closed = false;
+
+	const grace = (): number => mode === "channel" ? timing.channelGraceMs : timing.fallbackGraceMs;
+	const schedule = (delayMs: number): void => {
+		cancelTimer?.();
+		cancelTimer = options.timers.setTimeout(() => { cancelTimer = undefined; check(); }, Math.max(0, delayMs));
+	};
+	const check = (): void => {
+		const pending = outstanding;
+		if (closed || !pending || pending.nudged || pending.nudging || activity === "busy") return;
+		const remaining = pending.at + grace() - options.timers.now();
+		if (remaining > 0) { schedule(remaining); return; }
+		void nudge(pending);
+	};
+	/** Why a nudge for `pending` must not take its next terminal step, or undefined when it may. */
+	const fenced = (pending: Outstanding): string | undefined => {
+		if (closed) return "controller closed";
+		if (outstanding !== pending) return "pointer acknowledged";
+		return activity === "busy" ? "session busy" : undefined;
+	};
+	/** Status patches after an await: a closed controller writes nothing more. */
+	const report = (patch: WakeStatusPatch): void => { if (!closed) options.onChange(patch); };
+	const command = async (argv: readonly string[]): Promise<CommandResult> => options.runCommand(argv, { timeoutMs: timing.commandTimeoutMs });
+	const statusFailed = (pending: Outstanding, reason: string): void => {
+		pending.statusFailures++;
+		if (closed || outstanding !== pending) return;
+		if (pending.statusFailures < timing.statusAttempts) {
+			report({ lastNudgeError: reason, statusFailures: pending.statusFailures });
+			if (activity === "idle") schedule(timing.statusRetryMs);
+			return;
+		}
+		outstanding = undefined;
+		report({ lastNudgeError: `${reason}; fallback given up after ${pending.statusFailures} status checks`, statusFailures: pending.statusFailures, wakeStalledAt: options.timers.now() });
+	};
+	const nudge = async (pending: Outstanding): Promise<void> => {
+		pending.nudging = true;
+		try {
+			let reason: string | undefined;
+			try {
+				reason = readyFailure(await command(["wolfpack", "session", "status", options.sessionId, "--json"]), options.sessionId);
+			} catch (error) {
+				reason = error instanceof Error ? error.message : String(error);
+			}
+			if (reason !== undefined) { statusFailed(pending, reason); return; }
+			// Busy or acknowledged meanwhile: the next Stop hook re-arms the check.
+			if (fenced(pending) !== undefined) return;
+			const at = options.timers.now();
+			pending.nudged = true;
+			pending.nudgedAt = at;
+			const paste = await command(["wolfpack", "session", "send", options.sessionId, CLAUDE_PLUGIN.pointer, "--json"]);
+			if (paste.exitCode !== 0) { report({ lastNudgeAt: at, lastNudgeError: `session send exited ${paste.exitCode}` }); return; }
+			// The paste is out; the submit is a second terminal side effect and must not reach a session that changed meanwhile.
+			// The pointer text stays unsubmitted in the prompt input, the same best-effort residue as any appended nudge.
+			const fence = fenced(pending);
+			if (fence !== undefined) { report({ lastNudgeAt: at, lastNudgeError: `submit skipped: ${fence} during paste` }); return; }
+			if (mode === "channel") { mode = "fallback"; report({ wake: mode, fallbackAt: at }); }
+			const submit = await command(["wolfpack", "session", "send", options.sessionId, "\r", "--no-enter", "--json"]);
+			report(submit.exitCode === 0 ? { lastNudgeAt: at } : { lastNudgeAt: at, lastNudgeError: `session submit exited ${submit.exitCode}` });
+		} catch (error) {
+			report({ lastNudgeError: error instanceof Error ? error.message : String(error) });
+		} finally {
+			pending.nudging = false;
+		}
+	};
+
+	return {
+		get mode() { return mode; },
+		get pointerOutstanding() { return outstanding !== undefined; },
+		requestPointer(meta) {
+			if (closed) return;
+			const at = options.timers.now();
+			if (outstanding && !(outstanding.nudgedAt !== undefined && at - outstanding.nudgedAt >= NUDGED_POINTER_EXPIRY_MS)) return;
+			outstanding = { at, nudged: false, nudging: false, statusFailures: 0 };
+			if (mode === "channel") options.sendChannel(meta);
+			options.onChange({ lastPointerAt: at, statusFailures: 0 });
+			schedule(grace());
+		},
+		inboxCalled() {
+			outstanding = undefined;
+			cancelTimer?.();
+			cancelTimer = undefined;
+			if (!closed) options.onChange({ lastInboxAt: options.timers.now(), wakeStalledAt: null });
+		},
+		activity(state) {
+			activity = state;
+			if (state === "busy") { cancelTimer?.(); cancelTimer = undefined; return; }
+			const pending = outstanding;
+			if (closed || !pending || pending.nudged) return;
+			schedule(Math.max(timing.settleMs, pending.at + grace() - options.timers.now()));
+		},
+		close() {
+			closed = true;
+			cancelTimer?.();
+			cancelTimer = undefined;
+		},
+	};
+}
+
+/** Undefined when `wolfpack session status --json` shows this live, ready terminal; otherwise the reason. */
+function readyFailure(result: CommandResult, sessionId: string): string | undefined {
+	let status: unknown;
+	try { status = JSON.parse(result.stdout); } catch { return `session status unreadable (exit ${result.exitCode})`; }
+	if (!isRecord(status) || status.ok !== true || status.sessionId !== sessionId) return "session status does not match this session";
+	const terminal = status.terminal;
+	if (status.state !== "active" || !isRecord(terminal) || terminal.exists !== true || terminal.alive !== true || terminal.status !== "ready") return "session terminal is not live and ready";
+	return undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}

package/src/claude/worker-gate-hook.ts

@@ -0,0 +1,26 @@
+import { readFileSync } from "node:fs";
+
+import { WORKER_GATE_DENIAL_CODE } from "../task-worker-mode";
+import { decideWorkerGateHook } from "./worker-gate";
+
+// Entry point of the plugin's fail-closed PreToolUse command hook (dist/worker-gate.mjs). Exit 2 blocks the tool call.
+let stdinRead = false;
+let result;
+try {
+	result = await decideWorkerGateHook({
+		env: process.env,
+		readStdin: () => {
+			stdinRead = true;
+			return readFileSync(0, "utf8");
+		},
+	});
+} catch (error) {
+	// Unreachable by design; any other exit code would also block under onFailure: "block".
+	result = { exitCode: 2 as const, stderr: `${WORKER_GATE_DENIAL_CODE}: native tools are blocked: worker gate failed: ${error instanceof Error ? error.message : String(error)}` };
+}
+// Claude Code fails a hook that exits before its input is written (EPIPE), and onFailure: "block" turns that into a block.
+if (!stdinRead) {
+	try { readFileSync(0); } catch { /* stdin is already closed: nothing to drain */ }
+}
+if (result.stderr) process.stderr.write(`${result.stderr}\n`);
+process.exitCode = result.exitCode;

package/src/claude/worker-gate.ts

@@ -0,0 +1,260 @@
+import { randomBytes } from "node:crypto";
+import { chmodSync, lstatSync, mkdirSync, renameSync, rmSync, unlinkSync } from "node:fs";
+import { createConnection, createServer } from "node:net";
+import type { Socket } from "node:net";
+import { dirname, join } from "node:path";
+
+import { taskWorkerModeEnabled, WORKER_GATE_DENIAL_CODE } from "../task-worker-mode";
+import { CLAUDE_PLUGIN, HARNESS_PRE_ASSIGNMENT_TOOLS } from "./constants";
+import { readClaudeEnvironment } from "./environment";
+
+/**
+ * Fail-closed worker gate for Claude Code native tools.
+ *
+ * The `mcp_tool` `PreToolUse` hook fails open when the MCP server is disconnected, errors or times out. A `command`
+ * hook with `onFailure: "block"` does not: Claude Code counts a hook that cannot start, times out, or exits with a code
+ * other than 0 or 2 as exit code 2, which blocks the tool call. That hook runs `decideWorkerGateHook`, which asks the
+ * running MCP server over a unix-domain socket and denies unless the server answers now with an authorization for this
+ * session. Only a listening server can answer, so a stopped, killed or hung server denies: there is no stored
+ * authorization to outlive it. This module and its script import no task runtime, so the script starts quickly.
+ *
+ * Protocol (one line each way, JSON, newline-terminated):
+ *   request `{"v":1,"session":<WOLFPACK_SESSION_ID>,"tool":<tool name>}`
+ *   reply   `{"v":1,"session":<server session id>,"authorized":<boolean>,"reason":<string|null>}`
+ */
+
+export const WORKER_GATE_PROTOCOL_VERSION = 1;
+/** The hook denies when the server has not answered within this time; the hook itself has a 10 s Claude Code timeout. */
+export const WORKER_GATE_TIMEOUT_MS = 3_000;
+/** The server waits at most this long for a fresh evaluation, then answers from the latest one. */
+export const WORKER_GATE_ANSWER_WAIT_MS = 1_000;
+/** The server closes a connection this long after accept, answered or not; below the hook's timeout. */
+export const WORKER_GATE_REQUEST_DEADLINE_MS = 2_000;
+/** Connections the server holds at once; it closes more at accept, so slow clients cannot take every descriptor. */
+export const WORKER_GATE_MAX_CONNECTIONS = 16;
+export const WORKER_GATE_REQUEST_MAX_BYTES = 4_096;
+export const WORKER_GATE_REPLY_MAX_BYTES = 16_384;
+/** Bound on the denial text the hook prints; Claude Code shows it to the model. */
+export const WORKER_GATE_REASON_MAX_CHARS = 8_192;
+/** macOS `sun_path` holds 104 bytes including the terminating NUL; Linux holds 108. The smaller limit applies. */
+export const UNIX_SOCKET_PATH_MAX_BYTES = 103;
+const TOOL_NAME_MAX_CHARS = 256;
+
+export const socketPathFits = (path: string): boolean => Buffer.byteLength(path) <= UNIX_SOCKET_PATH_MAX_BYTES;
+
+export interface WorkerGateAnswer {
+	readonly authorized: boolean;
+	/** The runtime's denial reason when unauthorized; null when authorized or when the runtime gave none. */
+	readonly reason: string | null;
+}
+
+export type WorkerGateQueryResult = ({ readonly ok: true } & WorkerGateAnswer) | { readonly ok: false; readonly detail: string };
+
+export interface WorkerGateHookInput {
+	readonly env: Readonly<Record<string, string | undefined>>;
+	/** Read only in a Wolfpack worker session. */
+	readStdin(): string;
+	readonly timeoutMs?: number;
+}
+
+export interface WorkerGateHookResult {
+	/** 0 allows; 2 blocks the tool call and shows `stderr` to the model. */
+	readonly exitCode: 0 | 2;
+	readonly stderr: string;
+}
+
+const ALLOW: WorkerGateHookResult = Object.freeze({ exitCode: 0, stderr: "" });
+
+function bound(text: string, max: number): string {
+	return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+
+function deny(reason: string): WorkerGateHookResult {
+	const text = reason.startsWith(WORKER_GATE_DENIAL_CODE) ? reason : `${WORKER_GATE_DENIAL_CODE}: ${reason}`;
+	return { exitCode: 2, stderr: bound(text, WORKER_GATE_REASON_MAX_CHARS) };
+}
+
+const blocked = (detail: string): WorkerGateHookResult => deny(`native tools are blocked: ${detail}; call agent_task_inbox for an assignment, or check that the wolfpack-tasks MCP server is running`);
+
+/** Decides one `PreToolUse` call. Outside a Wolfpack worker session it allows without reading input or contacting a server. */
+export async function decideWorkerGateHook(input: WorkerGateHookInput): Promise<WorkerGateHookResult> {
+	if (!taskWorkerModeEnabled(input.env)) return ALLOW;
+	const environment = readClaudeEnvironment(input.env);
+	if (environment.kind === "inactive") return ALLOW;
+	if (environment.kind === "misconfigured") return blocked(`wolfpack tasks misconfigured: ${environment.variable} ${environment.reason}`);
+
+	let toolName: unknown;
+	try { toolName = (JSON.parse(input.readStdin()) as { tool_name?: unknown } | null)?.tool_name; } catch { /* handled below */ }
+	if (typeof toolName !== "string" || toolName === "") return blocked("hook input is unreadable");
+	// Own tools are gated inside the MCP server with their validated input.
+	if (toolName.startsWith(CLAUDE_PLUGIN.toolPrefix) || HARNESS_PRE_ASSIGNMENT_TOOLS.has(toolName)) return ALLOW;
+
+	const path = environment.gateSocketPath;
+	if (!socketPathFits(path)) return blocked(`task server socket path is longer than ${UNIX_SOCKET_PATH_MAX_BYTES} bytes: ${path}`);
+	const answer = await queryWorkerGate(path, { sessionId: environment.sessionId, toolName }, input.timeoutMs ?? WORKER_GATE_TIMEOUT_MS);
+	if (!answer.ok) return blocked(answer.detail);
+	if (!answer.authorized) return deny(answer.reason ?? WORKER_GATE_DENIAL_CODE);
+	return ALLOW;
+}
+
+/** Asks the server at `path` once. Every failure, including no answer within `timeoutMs`, is a result, never a throw. */
+export function queryWorkerGate(path: string, request: { readonly sessionId: string; readonly toolName: string }, timeoutMs = WORKER_GATE_TIMEOUT_MS): Promise<WorkerGateQueryResult> {
+	return new Promise((resolve) => {
+		let settled = false;
+		let received = Buffer.alloc(0);
+		const socket = createConnection(path);
+		const finish = (result: WorkerGateQueryResult): void => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			socket.destroy();
+			resolve(result);
+		};
+		const failed = (detail: string): void => finish({ ok: false, detail });
+		const timer = setTimeout(() => failed(`task server did not answer within ${timeoutMs} ms`), timeoutMs);
+		socket.on("connect", () => {
+			socket.write(`${JSON.stringify({ v: WORKER_GATE_PROTOCOL_VERSION, session: request.sessionId, tool: request.toolName.slice(0, TOOL_NAME_MAX_CHARS) })}\n`);
+		});
+		socket.on("data", (chunk: Buffer) => {
+			received = Buffer.concat([received, chunk]);
+			const end = received.indexOf(0x0a);
+			if (end > WORKER_GATE_REPLY_MAX_BYTES || (end < 0 && received.length > WORKER_GATE_REPLY_MAX_BYTES)) { failed(`task server sent an oversized answer (more than ${WORKER_GATE_REPLY_MAX_BYTES} bytes)`); return; }
+			if (end >= 0) finish(parseReply(received.subarray(0, end).toString("utf8"), request.sessionId));
+		});
+		socket.on("end", () => failed("task server closed the connection without an answer"));
+		socket.on("close", () => failed("task server closed the connection without an answer"));
+		socket.on("error", (error: NodeJS.ErrnoException) => failed(connectionFailure(error)));
+	});
+}
+
+function connectionFailure(error: NodeJS.ErrnoException): string {
+	if (error.code === "ENOENT") return "task server socket is missing (the server is not running)";
+	if (error.code === "ECONNREFUSED") return "task server is not running (connection refused)";
+	return `cannot reach the task server (${error.code ?? error.message})`;
+}
+
+function parseReply(line: string, sessionId: string): WorkerGateQueryResult {
+	let reply: unknown;
+	try { reply = JSON.parse(line); } catch { return { ok: false, detail: "task server sent a malformed answer" }; }
+	if (typeof reply !== "object" || reply === null) return { ok: false, detail: "task server sent a malformed answer" };
+	const fields = reply as Record<string, unknown>;
+	if (fields.v !== WORKER_GATE_PROTOCOL_VERSION) return { ok: false, detail: `task server speaks protocol version ${bound(JSON.stringify(fields.v) ?? "none", 32)}, expected ${WORKER_GATE_PROTOCOL_VERSION}` };
+	if (fields.session !== sessionId) return { ok: false, detail: "task server answered for another session" };
+	if (typeof fields.authorized !== "boolean" || !(fields.reason === null || typeof fields.reason === "string")) return { ok: false, detail: "task server sent a malformed answer" };
+	return { ok: true, authorized: fields.authorized, reason: fields.reason };
+}
+
+export interface WorkerGateListener {
+	/** Stops answering, ends open connections, and unlinks the socket unless a newer listener replaced it. */
+	close(): Promise<void>;
+}
+
+export interface WorkerGateListenOptions {
+	readonly path: string;
+	readonly sessionId: string;
+	/** The server's current gate decision; a rejection answers with a denial carrying its message. */
+	answer(): Promise<WorkerGateAnswer>;
+	log(message: string): void;
+	/** Defaults to `WORKER_GATE_MAX_CONNECTIONS`. */
+	readonly maxConnections?: number;
+	/** Defaults to `WORKER_GATE_REQUEST_DEADLINE_MS`. */
+	readonly requestDeadlineMs?: number;
+}
+
+/**
+ * Listens for gate requests at `path` in a mode-0700 directory. Returns undefined, after logging why, when it cannot
+ * listen; the hook then denies. The socket is bound at a temporary name and renamed into place: the rename replaces a
+ * stale socket atomically, and closing unlinks only the temporary name (Node and Bun unlink a unix socket's bound path
+ * on close), so a closing listener cannot remove a newer listener's socket.
+ */
+export async function listenWorkerGate(options: WorkerGateListenOptions): Promise<WorkerGateListener | undefined> {
+	const { path, sessionId, log } = options;
+	const failed = (reason: string): undefined => { log(`wolfpack-tasks: worker gate is not listening, native tools stay blocked: ${reason}`); return undefined; };
+	if (!socketPathFits(path)) return failed(`socket path is longer than ${UNIX_SOCKET_PATH_MAX_BYTES} bytes: ${path}`);
+	const directory = dirname(path);
+	try {
+		mkdirSync(directory, { recursive: true, mode: 0o700 });
+		chmodSync(directory, 0o700);
+	} catch (error) {
+		return failed(`cannot prepare ${directory}: ${message(error)}`);
+	}
+	try {
+		if (!lstatSync(path).isSocket()) return failed(`${path} exists and is not a socket`);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") return failed(`cannot inspect ${path}: ${message(error)}`);
+	}
+
+	const maxConnections = options.maxConnections ?? WORKER_GATE_MAX_CONNECTIONS;
+	const requestDeadlineMs = options.requestDeadlineMs ?? WORKER_GATE_REQUEST_DEADLINE_MS;
+	const sockets = new Set<Socket>();
+	const server = createServer((socket) => {
+		socket.on("error", () => undefined);
+		// Admission: a slow or hostile client cannot hold more than the cap; the hook denies a rejected query.
+		if (sockets.size >= maxConnections) { socket.destroy(); return; }
+		sockets.add(socket);
+		// Absolute from accept, unlike an idle timeout, so trickling bytes cannot extend it.
+		const deadline = setTimeout(() => socket.destroy(), requestDeadlineMs);
+		socket.on("close", () => { clearTimeout(deadline); sockets.delete(socket); });
+		let received = Buffer.alloc(0);
+		let handled = false;
+		socket.on("data", (chunk: Buffer) => {
+			if (handled) return;
+			received = Buffer.concat([received, chunk]);
+			const end = received.indexOf(0x0a);
+			if (end > WORKER_GATE_REQUEST_MAX_BYTES || (end < 0 && received.length > WORKER_GATE_REQUEST_MAX_BYTES)) { handled = true; socket.destroy(); return; }
+			if (end < 0) return;
+			handled = true;
+			void respond(received.subarray(0, end).toString("utf8")).then((answer) => {
+				if (socket.destroyed) return;
+				const reason = answer.reason === null ? null : bound(answer.reason, WORKER_GATE_REASON_MAX_CHARS);
+				socket.end(`${JSON.stringify({ v: WORKER_GATE_PROTOCOL_VERSION, session: sessionId, authorized: answer.authorized, reason })}\n`);
+			});
+		});
+	});
+	const respond = async (line: string): Promise<WorkerGateAnswer> => {
+		let request: unknown;
+		try { request = JSON.parse(line); } catch { return refuse("malformed request"); }
+		if (typeof request !== "object" || request === null) return refuse("malformed request");
+		const fields = request as Record<string, unknown>;
+		if (fields.v !== WORKER_GATE_PROTOCOL_VERSION) return refuse(`unsupported protocol version ${bound(JSON.stringify(fields.v) ?? "none", 32)}`);
+		if (fields.session !== sessionId) return refuse("request for another session");
+		if (typeof fields.tool !== "string") return refuse("malformed request");
+		try { return await options.answer(); } catch (error) { return refuse(`evaluation failed: ${message(error)}`); }
+	};
+
+	const temporary = join(directory, `${randomBytes(8).toString("hex")}.tmp`);
+	try {
+		await new Promise<void>((resolve, reject) => { server.once("error", reject); server.listen(temporary, () => { server.off("error", reject); resolve(); }); });
+		chmodSync(temporary, 0o600);
+		renameSync(temporary, path);
+	} catch (error) {
+		await closeServer(server, sockets);
+		try { rmSync(temporary, { force: true }); } catch { /* best effort */ }
+		return failed(`cannot listen at ${path}: ${message(error)}`);
+	}
+	const inode = lstatSync(path).ino;
+	server.on("error", (error) => log(`wolfpack-tasks: worker gate socket error: ${message(error)}`));
+
+	let closing: Promise<void> | undefined;
+	return {
+		close() {
+			closing ??= (async () => {
+				// Unlink first so new hooks see a missing socket, but only our own: a newer listener may have replaced it.
+				try { if (lstatSync(path).ino === inode) unlinkSync(path); } catch { /* already gone */ }
+				await closeServer(server, sockets);
+			})();
+			return closing;
+		},
+	};
+}
+
+function closeServer(server: ReturnType<typeof createServer>, sockets: Set<Socket>): Promise<void> {
+	return new Promise((resolve) => {
+		for (const socket of sockets) socket.destroy();
+		if (!server.listening) { resolve(); return; }
+		server.close(() => resolve());
+	});
+}
+
+const refuse = (reason: string): WorkerGateAnswer => ({ authorized: false, reason: `${WORKER_GATE_DENIAL_CODE}: worker gate ${reason}` });
+const message = (error: unknown): string => error instanceof Error ? error.message : String(error);