@sgtbeatdown/wolfpack-tasks 0.0.0-stage → 0.2.0

package/src/agent-task-tool-schemas.ts

@@ -0,0 +1,30 @@
+import { Type } from "typebox";
+
+/** Same JSON as `StringEnum` from pi-ai without options; kept local so non-pi hosts need no pi packages. */
+function stringEnum<const T extends readonly string[]>(values: T) {
+	return Type.Unsafe<T[number]>({ type: "string", enum: values });
+}
+
+export const MIN_TASK_TIMEOUT_MS = 1_000;
+export const MAX_TASK_TIMEOUT_MS = 86_400_000;
+export const SUMMARY_MAX_CHARS = 1_200;
+
+const EndpointParams = Type.Object({
+	relay: Type.String({ minLength: 1, description: "relay identifier" }),
+	id: Type.String({ minLength: 1, description: "opaque endpoint identifier" }),
+});
+export const SendParams = Type.Object({
+	to: EndpointParams,
+	task: Type.String({ minLength: 1, maxLength: 16 * 1024 }),
+	timeoutMs: Type.Optional(Type.Integer({ minimum: MIN_TASK_TIMEOUT_MS, maximum: MAX_TASK_TIMEOUT_MS })),
+});
+export const TaskIdParams = Type.Object({ taskId: Type.String({ minLength: 1 }) });
+export const WaitParams = Type.Object({ taskId: Type.String({ minLength: 1 }), timeoutMs: Type.Optional(Type.Integer({ minimum: MIN_TASK_TIMEOUT_MS, maximum: MAX_TASK_TIMEOUT_MS })) });
+export const InboxParams = Type.Object({});
+export const MessageParams = Type.Object({ taskId: Type.String({ minLength: 1 }), type: stringEnum(["question", "answer", "information"] as const), message: Type.String({ minLength: 1, maxLength: 16 * 1024 }) });
+export const DoneParams = Type.Object({
+	taskId: Type.String({ minLength: 1 }), status: stringEnum(["completed", "failed", "cancelled"] as const), summary: Type.String({ minLength: 1, maxLength: SUMMARY_MAX_CHARS }),
+	result: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+	error: Type.Optional(Type.Object({ code: Type.String(), message: Type.String(), retryable: Type.Boolean() })),
+	artifacts: Type.Optional(Type.Array(Type.Object({ path: Type.String({ minLength: 1, description: "artifact paths are receiver-project-relative regular files" }), mimeType: Type.Optional(Type.String()), description: Type.Optional(Type.String()) }))),
+});

package/src/claude/adapter.ts

@@ -0,0 +1,336 @@
+import { createAgentTaskRuntime, WORKER_GATE_DENIAL_CODE } from "../agent-task-runtime";
+import type { AgentTaskHost, AgentTaskRuntime, AgentTaskRuntimeContext, AgentTaskToolDefinition, AgentTaskToolResult, ConfiguredCoreFactory } from "../agent-task-runtime";
+import { createConfiguredTaskCore } from "../configured-task-core";
+import type { TaskCore } from "../task-core";
+import { TaskEnvelopeKind, TaskProtocolError } from "../task-protocol";
+import type { TaskInboxItem } from "../task-core";
+import { CLAUDE_PLUGIN, HARNESS_PRE_ASSIGNMENT_TOOLS } from "./constants";
+import type { ClaudeEnvironment } from "./environment";
+import { isRecord } from "./json-rpc";
+import { createStatusFile } from "./status-file";
+import type { ClaudeStatusFile } from "./status-file";
+import { validateToolArguments } from "./validation";
+import { createWakeController } from "./wake";
+import { listenWorkerGate, WORKER_GATE_ANSWER_WAIT_MS } from "./worker-gate";
+import type { WorkerGateAnswer, WorkerGateListener } from "./worker-gate";
+import type { CommandRunner, WakeController, WakeTimers, WakeTiming } from "./wake";
+
+export interface McpToolResult {
+	readonly content: readonly { readonly type: "text"; readonly text: string }[];
+	readonly structuredContent?: Record<string, unknown>;
+	readonly isError?: true;
+}
+
+export interface McpToolListing {
+	readonly name: string;
+	readonly title: string;
+	readonly description: string;
+	readonly inputSchema: unknown;
+	readonly _meta?: Record<string, unknown>;
+}
+
+export interface ClaudeTaskAdapterOptions {
+	readonly environment: ClaudeEnvironment;
+	/** Test seam: a fixed core instead of the configured Wolfpack transport. */
+	readonly core?: TaskCore;
+	readonly createCore?: ConfiguredCoreFactory;
+	sendChannel(meta: Readonly<Record<string, string>>): void;
+	readonly runCommand: CommandRunner;
+	readonly timers: WakeTimers;
+	readonly timing?: WakeTiming;
+	readonly log: (message: string) => void;
+}
+
+export interface ClaudeTaskAdapter {
+	readonly tools: readonly McpToolListing[];
+	/** Channel capability is declared only for a ready Wolfpack session. */
+	readonly channel: boolean;
+	start(protocol: { readonly protocolVersion: string; readonly clientProtocolVersion: string | null }): Promise<void>;
+	callTool(name: string, args: unknown, signal: AbortSignal): Promise<McpToolResult>;
+	/** Hook endpoint: returns hook output text, empty for no decision. */
+	hook(input: unknown): Promise<string>;
+	shutdown(): Promise<void>;
+}
+
+const INBOX_TOOL = "agent_task_inbox";
+/** Any native tool name: the runtime gates every non-task tool alike, so this probe stands for all of them. */
+const GATE_PROBE_TOOL = "Bash";
+/** Events the plugin's hooks/hooks.json sends to the lifecycle tool. */
+export const LIFECYCLE_HOOK_EVENTS = Object.freeze(["prompt", "pre_tool", "tool_batch", "stop", "stop_failure"] as const);
+const LIFECYCLE_HOOK_FIELDS = Object.freeze(["session_id", "tool_name", "agent_id"] as const);
+
+export function createClaudeTaskAdapter(options: ClaudeTaskAdapterOptions): ClaudeTaskAdapter {
+	const environment = options.environment;
+	if (environment.kind !== "ready") return inactiveAdapter(environment);
+
+	const entries: unknown[] = [];
+	const sessionManager = { getEntries: (): readonly unknown[] => entries };
+	/** Model-visible messages inserted since the last inbox result. */
+	const pendingMessages: string[] = [];
+	/**
+	 * Non-triggering records (relay-loss notes) inserted outside a presentation. They wait for the next inbox
+	 * result, request no pointer, and never count as pending, so they cannot hold back later triggering mail.
+	 */
+	const deferredMessages: string[] = [];
+	const notes: string[] = [];
+	let presenting = false;
+	let lastIntake: readonly TaskInboxItem[] = [];
+	let status: ClaudeStatusFile | undefined;
+	let wake: WakeController | undefined;
+	let started = false;
+	let closed = false;
+
+	const pointerMeta = (details?: unknown): Record<string, string> => {
+		if (isRecord(details) && typeof details.taskId === "string") return { task_id: details.taskId, ...(typeof details.eventId === "string" && { event_id: details.eventId }) };
+		// Hint only: the first model-facing item of the latest intake.
+		for (const item of lastIntake) {
+			if (item.kind === "local") return { task_id: item.event.taskId, event_id: item.event.eventId };
+			if (item.delivery.envelope.kind !== TaskEnvelopeKind.intent) return { task_id: item.delivery.envelope.taskId };
+		}
+		return {};
+	};
+	const requestPointer = (details?: unknown): void => { if (!presenting) wake?.requestPointer(pointerMeta(details)); };
+
+	// Pi entry shapes, so the shared evidence index (incorporation, wakes, records) reads them unchanged.
+	const host: AgentTaskHost = {
+		sendMessage(message, delivery) {
+			entries.push({ type: "custom_message", customType: message.customType, content: message.content, display: message.display, details: message.details });
+			if (delivery.triggerTurn) requestPointer(message.details);
+			else if (presenting) pendingMessages.push(message.content);
+			else deferredMessages.push(message.content);
+		},
+		appendEntry(customType, data) { entries.push({ type: "custom", customType, data }); },
+	};
+	// Background refreshes are never idle: they hold model-visible mail and point at it. Only an inbox call presents.
+	const context: AgentTaskRuntimeContext = {
+		isIdle(): boolean {
+			if (presenting) return true;
+			requestPointer();
+			return false;
+		},
+		hasPendingMessages: (): boolean => !presenting && pendingMessages.length > 0,
+		sessionManager,
+		ui: {
+			setStatus(_key, text) { status?.update({ lastStatus: text ?? null }); },
+			notify(message, type = "info") { notes.push(`${type}: ${message}`); },
+			theme: { fg: (_color, text) => text },
+		},
+	};
+	const observeIntake = (core: TaskCore): TaskCore => ({
+		...core,
+		async intakeInbox(signal, work) {
+			const items = await core.intakeInbox(signal, work);
+			lastIntake = items;
+			return items;
+		},
+	});
+	const createCore: ConfiguredCoreFactory = options.createCore ?? ((signal, rebind) => createConfiguredTaskCore({ sessionName: environment.sessionName, rebind }, signal));
+	const runtime = options.core
+		? createAgentTaskRuntime(host, observeIntake(options.core))
+		: createAgentTaskRuntime(host, undefined, async (signal, rebind) => observeIntake(await createCore(signal, rebind)) as Awaited<ReturnType<ConfiguredCoreFactory>>);
+	const tools = new Map(runtime.tools.map((tool) => [tool.name, tool]));
+
+	// Worker mode only: the gate decision that the fail-closed PreToolUse command hook asks for over the gate socket
+	// (see worker-gate.ts). It lives only in this process, so no answer can come from a previous server lifetime.
+	const gateEnabled = runtime.workerGateEnabled;
+	const GATE_STOPPED: WorkerGateAnswer = { authorized: false, reason: `${WORKER_GATE_DENIAL_CODE}: the wolfpack-tasks MCP server stopped` };
+	let gateAnswer: WorkerGateAnswer = { authorized: false, reason: `${WORKER_GATE_DENIAL_CODE}: the worker gate has not been evaluated` };
+	let gateListener: WorkerGateListener | undefined;
+	let gateQueue: Promise<void> = Promise.resolve();
+	let queuedGateRefresh: Promise<void> | undefined;
+	/**
+	 * Re-evaluates the gate. Serialized, so an older evaluation never overwrites a newer one. A refresh that has not
+	 * started yet is shared: it still runs after every earlier change, and a hung evaluation cannot grow the queue.
+	 */
+	const refreshGate = (): Promise<void> => {
+		if (!gateEnabled) return gateQueue;
+		if (queuedGateRefresh) return queuedGateRefresh;
+		const run = gateQueue.then(async () => {
+			queuedGateRefresh = undefined;
+			if (closed) return;
+			let decision: { readonly block: boolean; readonly reason: string } | undefined;
+			try {
+				decision = await runtime.lifecycle.tool_call({ toolName: GATE_PROBE_TOOL, input: {} }, { sessionManager });
+			} catch (error) {
+				decision = { block: true, reason: error instanceof Error ? error.message : String(error) };
+			}
+			gateAnswer = decision?.block ? { authorized: false, reason: decision.reason } : { authorized: true, reason: null };
+		});
+		queuedGateRefresh = run;
+		gateQueue = run;
+		return run;
+	};
+	/** Answers one hook request: a fresh evaluation when it completes in time, otherwise the latest one. */
+	const answerGate = async (): Promise<WorkerGateAnswer> => {
+		if (closed) return GATE_STOPPED;
+		let cancelWait: (() => void) | undefined;
+		await Promise.race([refreshGate(), new Promise<void>((resolve) => { cancelWait = options.timers.setTimeout(resolve, WORKER_GATE_ANSWER_WAIT_MS); })]);
+		cancelWait?.();
+		return closed ? GATE_STOPPED : gateAnswer;
+	};
+
+	const executeTool = async (name: string, args: unknown, signal: AbortSignal): Promise<McpToolResult> => {
+		const tool = tools.get(name);
+		if (!tool) return errorResult(`unknown tool ${JSON.stringify(name.slice(0, 64))}`);
+		let params: unknown;
+		try { params = validateToolArguments(name, tool.parameters, args ?? {}); } catch (error) { return errorResult(error instanceof Error ? error.message : String(error)); }
+		// A model tool call means the session is working, even if the activity hooks are unavailable.
+		wake?.activity("busy");
+		const decision = await runtime.lifecycle.tool_call({ toolName: name, input: params }, { sessionManager, signal });
+		if (decision?.block) return errorResult(decision.reason);
+		try {
+			if (name === INBOX_TOOL) return await runInbox(tool, params, signal);
+			return mcpResult(await tool.execute(name, params as never, signal, undefined, context), []);
+		} catch (error) {
+			return errorResult(error instanceof Error ? error.message : String(error));
+		}
+	};
+
+	let inboxQueue: Promise<unknown> = Promise.resolve();
+	const runInbox = (tool: AgentTaskToolDefinition, params: unknown, signal: AbortSignal): Promise<McpToolResult> => {
+		const run = inboxQueue.then(async (): Promise<McpToolResult> => {
+			const pointed = wake?.pointerOutstanding === true;
+			wake?.inboxCalled();
+			presenting = true;
+			try {
+				let result = await tool.execute("inbox", params as never, signal, undefined, context);
+				// A refresh already in flight may have held the pointed mail before presentation began; one more pass presents it.
+				if (pointed && pendingMessages.length === 0 && !signal.aborted) result = await tool.execute("inbox", params as never, signal, undefined, context);
+				const delivered = [...deferredMessages.splice(0), ...pendingMessages.splice(0)];
+				const noted = notes.splice(0);
+				return mcpResult(result, [...delivered, ...noted]);
+			} finally {
+				presenting = false;
+			}
+		});
+		inboxQueue = run.catch(() => undefined);
+		return run;
+	};
+
+	return {
+		tools: listing(runtime, true),
+		channel: true,
+		async start(protocol) {
+			if (started || closed) return;
+			started = true;
+			const now = options.timers.now();
+			status = createStatusFile(environment.statusPath, {
+				sessionId: environment.sessionId, sessionName: environment.sessionName, pid: process.pid, wake: "channel",
+				protocolVersion: protocol.protocolVersion, clientProtocolVersion: protocol.clientProtocolVersion, startedAt: now,
+				lastPointerAt: null, lastInboxAt: null, lastNudgeAt: null, fallbackAt: null, lastNudgeError: null, statusFailures: 0, wakeStalledAt: null, lastStatus: null,
+			}, options.timers.now, options.log);
+			wake = createWakeController({
+				sessionId: environment.sessionId,
+				sendChannel: options.sendChannel,
+				runCommand: options.runCommand,
+				timers: options.timers,
+				...(options.timing && { timing: options.timing }),
+				onChange: (patch) => status?.update(patch),
+			});
+			await runtime.lifecycle.session_start({}, context);
+			if (gateEnabled && !closed) {
+				await refreshGate();
+				const listener = await listenWorkerGate({ path: environment.gateSocketPath, sessionId: environment.sessionId, answer: answerGate, log: options.log });
+				// A shutdown during listen did not see this listener.
+				if (closed) await listener?.close();
+				else gateListener = listener;
+			}
+		},
+		async callTool(name, args, signal) {
+			const result = await executeTool(name, args, signal);
+			// The next native tool call must see the authorization this result granted or revoked.
+			await refreshGate();
+			return result;
+		},
+		async hook(input) {
+			if (!isRecord(input) || closed) return "";
+			switch (input.event) {
+				case "prompt":
+					wake?.activity("busy");
+					return "";
+				case "pre_tool": {
+					wake?.activity("busy");
+					const toolName = typeof input.tool_name === "string" ? input.tool_name : "";
+					// Own tools are gated inside tools/call with their validated input.
+					if (!runtime.workerGateEnabled || toolName.startsWith(CLAUDE_PLUGIN.toolPrefix) || HARNESS_PRE_ASSIGNMENT_TOOLS.has(toolName)) return "";
+					const decision = await runtime.lifecycle.tool_call({ toolName, input: {} }, { sessionManager });
+					return decision?.block ? JSON.stringify({ hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: decision.reason } }) : "";
+				}
+				case "tool_batch":
+					void runtime.lifecycle.turn_end({}, context);
+					return "";
+				case "stop":
+				case "stop_failure":
+					wake?.activity("idle");
+					if (started) void runtime.lifecycle.agent_end({}, context);
+					return "";
+				default:
+					return "";
+			}
+		},
+		async shutdown() {
+			if (closed) return;
+			closed = true;
+			wake?.close();
+			await gateListener?.close();
+			gateListener = undefined;
+			await runtime.lifecycle.session_shutdown({}, context);
+		},
+	};
+}
+
+/** No identity or a misconfiguration: the same tool list, no runtime start, no contact, no files. */
+function inactiveAdapter(environment: Exclude<ClaudeEnvironment, { kind: "ready" }>): ClaudeTaskAdapter {
+	const refuse = async (): Promise<never> => { throw new TaskProtocolError("RELAY_UNAVAILABLE", "task runtime is inactive", { retryable: false }); };
+	const inert: AgentTaskHost = { sendMessage() { /* inactive */ }, appendEntry() { /* inactive */ } };
+	const runtime = createAgentTaskRuntime(inert, undefined, refuse);
+	const message = environment.kind === "inactive"
+		? "not a wolfpack session: WOLFPACK_SESSION_ID and WOLFPACK_SESSION_NAME are required; task tools are unavailable"
+		: `wolfpack tasks misconfigured: ${environment.variable} ${environment.reason}`;
+	return {
+		tools: listing(runtime, false),
+		channel: false,
+		async start() { /* inactive */ },
+		async callTool() { return errorResult(message); },
+		async hook() { return ""; },
+		async shutdown() { /* inactive */ },
+	};
+}
+
+function listing(runtime: AgentTaskRuntime, active: boolean): McpToolListing[] {
+	const tools: McpToolListing[] = runtime.tools.map((tool) => ({
+		name: tool.name,
+		title: tool.label,
+		description: tool.description,
+		inputSchema: JSON.parse(JSON.stringify(tool.parameters)) as unknown,
+		// The pointer names agent_task_inbox, so it must not be deferred behind tool search in a live session.
+		...(active && tool.name === INBOX_TOOL && { _meta: { "anthropic/alwaysLoad": true } }),
+	}));
+	tools.push({
+		name: CLAUDE_PLUGIN.lifecycleTool,
+		title: "Task lifecycle hook endpoint",
+		description: "Internal endpoint for this plugin's Claude Code hooks. Model calls are rejected.",
+		inputSchema: {
+			type: "object",
+			additionalProperties: false,
+			required: ["event"],
+			properties: { event: { type: "string", enum: [...LIFECYCLE_HOOK_EVENTS] }, ...Object.fromEntries(LIFECYCLE_HOOK_FIELDS.map((key) => [key, { type: "string", maxLength: 256 }])) },
+		},
+		_meta: { "anthropic/alwaysLoad": false },
+	});
+	return tools;
+}
+
+function mcpResult(result: AgentTaskToolResult, delivered: readonly string[]): McpToolResult {
+	const details = isRecord(result.details) ? result.details : { value: result.details };
+	const isError = isRecord(details.error);
+	return {
+		content: [...delivered, ...result.content.map((part) => part.text)].map((text) => ({ type: "text" as const, text })),
+		structuredContent: delivered.length > 0 ? { ...details, delivered } : details,
+		...(isError && { isError: true as const }),
+	};
+}
+
+function errorResult(text: string): McpToolResult {
+	return { content: [{ type: "text", text }], isError: true };
+}

package/src/claude/constants.ts

@@ -0,0 +1,40 @@
+/**
+ * Every Claude Code name the adapter, plugin manifests, hooks and tests agree on.
+ * Hook server names follow Claude Code's `plugin:<plugin>:<server>`; tool names follow `mcp__plugin_<plugin>_<server>__<tool>`.
+ */
+export const CLAUDE_PLUGIN = Object.freeze({
+	marketplace: "wolfpack-tasks",
+	plugin: "wolfpack-tasks",
+	/** Marketplace-relative plugin root. */
+	pluginSource: "./claude-plugin",
+	/** `mcpServers` key in the plugin manifest. */
+	serverKey: "tasks",
+	serverName: "wolfpack-tasks",
+	hookServer: "plugin:wolfpack-tasks:tasks",
+	toolPrefix: "mcp__plugin_wolfpack-tasks_tasks__",
+	/** Hook-only tool; model calls are rejected. */
+	lifecycleTool: "lifecycle",
+	skill: "wolfpack-task-delegation",
+	/** Plugin-root-relative bundle path. */
+	bundle: "dist/server.mjs",
+	/** Plugin-root-relative path of the fail-closed `PreToolUse` command hook script. */
+	gateBundle: "dist/worker-gate.mjs",
+	channelMethod: "notifications/claude/channel",
+	channelCapability: "claude/channel",
+	/** The only channel content; task payloads are returned by agent_task_inbox, never pushed. */
+	pointer: "wolfpack task mail: call agent_task_inbox",
+	/** Claude Code `_meta` key on model tool calls; hook-originated calls do not carry it. */
+	toolUseMeta: "claudecode/toolUseId",
+	/** Client protocol versions below this date are echoed; others are answered with the fallback version. */
+	protocolCeiling: "2026-07-28",
+	fallbackProtocolVersion: "2025-11-25",
+	/** State-directory-relative status file directory. */
+	statusDirectory: "wolfpack-tasks/claude",
+	/** The worker gate socket lives in this mode-0700 subdirectory of the status directory as `<hash>.sock`. */
+	gateSocketDirectory: "gate",
+	/** Hex characters of the session id's SHA-256 in the gate socket name. */
+	gateSocketHashChars: 16,
+});
+
+/** Claude Code harness tools a worker may use before its assignment: ToolSearch loads the deferred task tools. */
+export const HARNESS_PRE_ASSIGNMENT_TOOLS: ReadonlySet<string> = new Set(["ToolSearch"]);

package/src/claude/environment.ts

@@ -0,0 +1,54 @@
+import { createHash } from "node:crypto";
+import { isAbsolute, join } from "node:path";
+
+import { CLAUDE_PLUGIN } from "./constants";
+
+/** Default local Wolfpack control port, the same default the configured task core uses. */
+export const DEFAULT_WOLFPACK_PORT = "18790";
+const JWT_SECRET_MIN_CHARS = 32;
+const SESSION_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+
+export type ClaudeEnvironment =
+	/** Not a Wolfpack session: no registration, no relay or CLI contact, no files, no output. */
+	| { readonly kind: "inactive" }
+	/** Wolfpack identity is present but a required value is missing or invalid. */
+	| { readonly kind: "misconfigured"; readonly variable: string; readonly reason: string }
+	| { readonly kind: "ready"; readonly sessionId: string; readonly sessionName: string; readonly port: string; readonly stateDir: string; readonly statusPath: string; readonly gateSocketPath: string };
+
+/**
+ * The identity gate is exactly WOLFPACK_SESSION_ID plus WOLFPACK_SESSION_NAME. With identity present, the values the
+ * configured core reads later are validated up front so a misconfiguration is named instead of failing per call.
+ */
+export function readClaudeEnvironment(env: Readonly<Record<string, string | undefined>>): ClaudeEnvironment {
+	const sessionId = env.WOLFPACK_SESSION_ID?.trim();
+	const sessionName = env.WOLFPACK_SESSION_NAME?.trim();
+	if (!sessionId || !sessionName) return { kind: "inactive" };
+	if (!SESSION_ID_PATTERN.test(sessionId)) return misconfigured("WOLFPACK_SESSION_ID", "must be a Wolfpack session id (letters, digits, '.', '_' or '-')");
+	const port = env.WOLFPACK_PORT ?? DEFAULT_WOLFPACK_PORT;
+	if (!/^[0-9]+$/.test(port) || Number(port) < 1 || Number(port) > 65535) return misconfigured("WOLFPACK_PORT", "must be a TCP port from 1 to 65535");
+	const secret = env.WOLFPACK_JWT_SECRET?.trim();
+	if (secret && secret.length < JWT_SECRET_MIN_CHARS) return misconfigured("WOLFPACK_JWT_SECRET", `must contain at least ${JWT_SECRET_MIN_CHARS} characters when set`);
+	let stateDir: string;
+	if (env.WOLFPACK_DIR !== undefined) {
+		if (!isAbsolute(env.WOLFPACK_DIR)) return misconfigured("WOLFPACK_DIR", "must be an absolute path when set");
+		stateDir = env.WOLFPACK_DIR;
+	} else {
+		if (!env.HOME || !isAbsolute(env.HOME)) return misconfigured("HOME", "must be an absolute path when WOLFPACK_DIR is unset");
+		stateDir = join(env.HOME, ".wolfpack");
+	}
+	const directory = join(stateDir, CLAUDE_PLUGIN.statusDirectory);
+	return { kind: "ready", sessionId, sessionName, port, stateDir, statusPath: join(directory, `${sessionId}.json`), gateSocketPath: gateSocketPath(directory, sessionId) };
+}
+
+/**
+ * The worker gate socket of a session. A session id can be 128 characters, so the file name is a short hash of it: unix
+ * socket paths are limited to 103 bytes on macOS. A longer path is refused by both the server and the hook.
+ */
+function gateSocketPath(directory: string, sessionId: string): string {
+	const name = createHash("sha256").update(sessionId).digest("hex").slice(0, CLAUDE_PLUGIN.gateSocketHashChars);
+	return join(directory, CLAUDE_PLUGIN.gateSocketDirectory, `${name}.sock`);
+}
+
+function misconfigured(variable: string, reason: string): ClaudeEnvironment {
+	return { kind: "misconfigured", variable, reason };
+}

package/src/claude/json-rpc.ts

@@ -0,0 +1,50 @@
+/** Minimal JSON-RPC 2.0 shapes for newline-delimited MCP stdio. */
+export type JsonRpcId = string | number;
+
+export type JsonRpcMessage =
+	| { readonly jsonrpc: "2.0"; readonly id: JsonRpcId; readonly method: string; readonly params?: unknown }
+	| { readonly jsonrpc: "2.0"; readonly method: string; readonly params?: unknown }
+	| { readonly jsonrpc: "2.0"; readonly id: JsonRpcId; readonly result: unknown }
+	| { readonly jsonrpc: "2.0"; readonly id: JsonRpcId | null; readonly error: JsonRpcError };
+
+export interface JsonRpcError {
+	readonly code: number;
+	readonly message: string;
+}
+
+export const JSON_RPC_ERROR = Object.freeze({
+	parse: -32700,
+	invalidRequest: -32600,
+	methodNotFound: -32601,
+	invalidParams: -32602,
+	internal: -32603,
+});
+
+export interface JsonRpcRequest {
+	readonly id?: JsonRpcId;
+	readonly method: string;
+	readonly params?: unknown;
+}
+
+/** Returns the request or notification, or the error to answer. Responses from the client are ignored (undefined). */
+export function parseJsonRpc(line: string): JsonRpcRequest | JsonRpcError | undefined {
+	let value: unknown;
+	try {
+		value = JSON.parse(line);
+	} catch {
+		return { code: JSON_RPC_ERROR.parse, message: "parse error" };
+	}
+	if (!isRecord(value) || value.jsonrpc !== "2.0") return { code: JSON_RPC_ERROR.invalidRequest, message: "invalid request" };
+	const id = value.id;
+	if (id !== undefined && typeof id !== "string" && typeof id !== "number") return { code: JSON_RPC_ERROR.invalidRequest, message: "invalid request id" };
+	if (typeof value.method !== "string") return "result" in value || "error" in value ? undefined : { code: JSON_RPC_ERROR.invalidRequest, message: "invalid request" };
+	return { ...(id !== undefined && { id }), method: value.method, ...(value.params !== undefined && { params: value.params }) };
+}
+
+export function isJsonRpcError(value: JsonRpcRequest | JsonRpcError): value is JsonRpcError {
+	return "code" in value;
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}

package/src/claude/mcp-server.ts

@@ -0,0 +1,144 @@
+import type { ConfiguredCoreFactory } from "../agent-task-runtime";
+import type { TaskCore } from "../task-core";
+import { createClaudeTaskAdapter } from "./adapter";
+import type { ClaudeTaskAdapter, McpToolResult } from "./adapter";
+import { CLAUDE_PLUGIN } from "./constants";
+import { readClaudeEnvironment } from "./environment";
+import { isJsonRpcError, isRecord, JSON_RPC_ERROR, parseJsonRpc } from "./json-rpc";
+import type { JsonRpcError, JsonRpcId, JsonRpcMessage, JsonRpcRequest } from "./json-rpc";
+import type { CommandRunner, WakeTimers, WakeTiming } from "./wake";
+
+export const SERVER_VERSION = "0.2.0";
+
+export const SERVER_INSTRUCTIONS = [
+	"Wolfpack task delegation tools (agent_task_*), the same tools and semantics as the pi extension.",
+	`A <channel source="${CLAUDE_PLUGIN.serverName}"> message is a wolfpack task notification. It carries only a pointer, never the task content.`,
+	"When one arrives, call agent_task_inbox; the inbox result contains the delivered task messages and any assignment.",
+	"The same pointer may also be typed into the prompt as a fallback when the channel does not wake the session; treat it the same way.",
+].join("\n");
+
+export interface ClaudeTaskServerOptions {
+	readonly env: Readonly<Record<string, string | undefined>>;
+	send(message: JsonRpcMessage): void;
+	/** Test seam: a fixed task core instead of the configured Wolfpack transport. */
+	readonly core?: TaskCore;
+	readonly createCore?: ConfiguredCoreFactory;
+	readonly runCommand?: CommandRunner;
+	readonly timers?: WakeTimers;
+	readonly timing?: WakeTiming;
+	readonly log?: (message: string) => void;
+}
+
+export interface ClaudeTaskServer {
+	handle(message: unknown): Promise<void>;
+	handleLine(line: string): Promise<void>;
+	shutdown(): Promise<void>;
+}
+
+/** Echo the client's protocol revision below the ceiling; answer the pinned revision otherwise. ISO dates compare lexically. */
+export function negotiateProtocolVersion(proposed: unknown): string {
+	return typeof proposed === "string" && /^\d{4}-\d{2}-\d{2}$/.test(proposed) && proposed < CLAUDE_PLUGIN.protocolCeiling ? proposed : CLAUDE_PLUGIN.fallbackProtocolVersion;
+}
+
+const realTimers: WakeTimers = {
+	now: () => Date.now(),
+	setTimeout(fire, ms) {
+		const timer = setTimeout(fire, ms);
+		timer.unref?.();
+		return () => clearTimeout(timer);
+	},
+};
+
+const noCommands: CommandRunner = async () => { throw new Error("no command runner configured"); };
+
+/** Hand-rolled MCP over newline-delimited JSON-RPC. No SDK: the surface is initialize, ping, tools and one notification. */
+export function createClaudeTaskServer(options: ClaudeTaskServerOptions): ClaudeTaskServer {
+	const environment = readClaudeEnvironment(options.env);
+	const send = options.send;
+	const adapter: ClaudeTaskAdapter = createClaudeTaskAdapter({
+		environment,
+		...(options.core && { core: options.core }),
+		...(options.createCore && { createCore: options.createCore }),
+		sendChannel: (meta) => send({ jsonrpc: "2.0", method: CLAUDE_PLUGIN.channelMethod, params: { content: CLAUDE_PLUGIN.pointer, meta } }),
+		runCommand: options.runCommand ?? noCommands,
+		timers: options.timers ?? realTimers,
+		...(options.timing && { timing: options.timing }),
+		log: options.log ?? (() => undefined),
+	});
+	let negotiated: { protocolVersion: string; clientProtocolVersion: string | null } | undefined;
+	const inFlight = new Map<JsonRpcId, AbortController>();
+	let closed = false;
+
+	const reply = (id: JsonRpcId, result: unknown): void => send({ jsonrpc: "2.0", id, result });
+	const fail = (id: JsonRpcId | null, error: JsonRpcError): void => send({ jsonrpc: "2.0", id, error });
+
+	const callTool = async (id: JsonRpcId, params: unknown): Promise<void> => {
+		if (!isRecord(params) || typeof params.name !== "string") { fail(id, { code: JSON_RPC_ERROR.invalidParams, message: "tools/call requires a tool name" }); return; }
+		const meta = isRecord(params._meta) ? params._meta : {};
+		let result: McpToolResult;
+		if (params.name === CLAUDE_PLUGIN.lifecycleTool) {
+			// Hooks call without a tool-use id; a model call always carries one.
+			result = meta[CLAUDE_PLUGIN.toolUseMeta] !== undefined
+				? { content: [{ type: "text", text: "lifecycle is reserved for this plugin's Claude Code hooks" }], isError: true }
+				: { content: [{ type: "text", text: await adapter.hook(params.arguments) }] };
+		} else {
+			const controller = new AbortController();
+			inFlight.set(id, controller);
+			try { result = await adapter.callTool(params.name, params.arguments, controller.signal); } finally { inFlight.delete(id); }
+		}
+		reply(id, result);
+	};
+
+	const dispatch = async (request: JsonRpcRequest): Promise<void> => {
+		const { id, method, params } = request;
+		if (id === undefined) {
+			if (method === "notifications/initialized" && negotiated) await adapter.start(negotiated);
+			else if (method === "notifications/cancelled" && isRecord(params) && (typeof params.requestId === "string" || typeof params.requestId === "number")) inFlight.get(params.requestId)?.abort();
+			return;
+		}
+		switch (method) {
+			case "initialize": {
+				const proposed = isRecord(params) ? params.protocolVersion : undefined;
+				negotiated = { protocolVersion: negotiateProtocolVersion(proposed), clientProtocolVersion: typeof proposed === "string" ? proposed : null };
+				reply(id, {
+					protocolVersion: negotiated.protocolVersion,
+					capabilities: { tools: {}, ...(adapter.channel && { experimental: { [CLAUDE_PLUGIN.channelCapability]: {} } }) },
+					serverInfo: { name: CLAUDE_PLUGIN.serverName, version: SERVER_VERSION },
+					instructions: SERVER_INSTRUCTIONS,
+				});
+				return;
+			}
+			case "ping":
+				reply(id, {});
+				return;
+			case "tools/list":
+				reply(id, { tools: adapter.tools });
+				return;
+			case "tools/call":
+				await callTool(id, params);
+				return;
+			default:
+				fail(id, { code: JSON_RPC_ERROR.methodNotFound, message: `method not found: ${method.slice(0, 64)}` });
+		}
+	};
+
+	const server: ClaudeTaskServer = {
+		handle(message) { return server.handleLine(JSON.stringify(message)); },
+		async handleLine(line) {
+			if (closed || line.trim() === "") return;
+			const parsed = parseJsonRpc(line);
+			if (parsed === undefined) return;
+			if (isJsonRpcError(parsed)) { fail(null, parsed); return; }
+			try { await dispatch(parsed); } catch (error) {
+				if (parsed.id !== undefined) fail(parsed.id, { code: JSON_RPC_ERROR.internal, message: error instanceof Error ? error.message : String(error) });
+			}
+		},
+		async shutdown() {
+			if (closed) return;
+			closed = true;
+			for (const controller of inFlight.values()) controller.abort();
+			await adapter.shutdown();
+		},
+	};
+	return server;
+}