@sgtbeatdown/pi-tasks 0.1.0 → 0.1.1

package/skills/wolfpack-pi-task-delegation/SKILL.md

@@ -1,75 +1,44 @@
 ---
 name: wolfpack-pi-task-delegation
-description: Use this whenever the user asks to open, spawn, create, or use a Wolfpack/Pi subagent to do work, delegate work to another session, or check delegated task results. This skill connects existing Wolfpack session-control knowledge with the agent_task communication tools so agents spawn/select sessions, send work with agent_task_send, and avoid terminal-output completion polling.
+description: Use when opening, selecting, delegating to, checking, or cleaning up a Wolfpack Pi subagent through the gateway-backed agent task tools.
 ---
 
-# Wolfpack Pi Task Delegation
+# wolfpack pi task delegation
 
-This skill is the Wolfpack transport guidance for the task communication layer. It does not replace `wolfpack-tailnet-control`; use that
-skill/instructions for opening, selecting, inspecting, or controlling Wolfpack
-sessions.
+use `wolfpack-tailnet-control` for session control. this skill covers gateway task lifecycle, curated context, and parent verification. Wolfpack's [task gateway guide](https://github.com/almogdepaz/wolfpack/blob/main/docs/task-gateway.md) is the canonical route, trust, retention, and federation reference.
 
-## Goal
+## gateway requirements and addressing
 
-When the user says something like “open a subagent and do X”, create or select a
-Wolfpack/Pi session using existing Wolfpack control, then send X through the
-structured `agent_task_*` task communication tools. Keep Wolfpack terminals
-visible and steerable, but treat task state/results as the protocol.
+- every participating Pi process needs this package and a reachable local Wolfpack v1 gateway.
+- `WOLFPACK_SESSION_NAME` is the caller selector; the local gateway resolves it to a stable broker ID. `WOLFPACK_PORT` selects the local port and defaults to `18790`.
+- address a target as `to: { machine, sessionId }`, retaining the stable broker `sessionId` from structured Wolfpack session control rather than a terminal label.
+- use `machine: "local"` for same-machine work. For remote work, use only the receiver's canonical HTTPS Tailnet origin, such as `https://worker.example.ts.net`; never a terminal name, arbitrary URL, path, query, fragment, credentials, or unexpected port.
+- v1 trusts local processes and trusted Tailnet machines. Pi calls only its local gateway; gateways use direct fetch federation. JWT federation is unsupported, so do not promise remote delivery where Wolfpack global JWT requires credentials.
 
-## Workflow
+## workflow
 
-1. If the request includes opening/spawning/creating a subagent, use the
-   existing Wolfpack control workflow (`wolfpack-tailnet-control`) to create the
-   session. Prefer the canonical CLI path:
+1. create or select an existing Pi session with canonical Wolfpack session control. Read its structured response and retain the stable broker `sessionId`.
+2. send concise opaque task instructions with `agent_task_send`. Parent normally authors optional Markdown `context.summary` and deliberately selects `context.refs` with `path`, optional `selector`, and `purpose`; refs are metadata, not copied files or transcript. Use `task-context-summary` only for recovery/reuse.
+3. include `role`, `metadata`, enforceable `preflight.requiredProject`, bounded timeout, idempotency key, and `onCompletePrompt` only when they apply. Timeout is 1000ms through 24h; default is 30 minutes. Task/context limits are 16 KiB each, assignment envelope 48 KiB, and request body 64 KiB.
+4. after durable receipt, keep working. Do not call `agent_task_wait` unless the user explicitly asks to block. Use `agent_task_status` or `agent_task_inbox` for structured follow-up.
+5. use `agent_task_message` for durable `question`, `answer`, or `information` flow. One question may be unresolved globally; answers link to it. A receiver question accepted by the sender ends the receiver turn; a parent question does not end the parent turn.
+6. assignees call `agent_task_done` exactly once as their final action with `completed`, `failed`, or `cancelled`, concise summary, and optional structured result/error/paths-only artifact metadata. No prose completion afterward.
+7. parent independently verifies files, diff, tests, and artifacts before reporting success. Then use `agent_task_inbox({ ack: true })`; remote acknowledgment is two-phase and failed propagation leaves the task visible for explicit repair. Cleanup applies only to sessions this parent spawned and only after result verification and acknowledgment. Retain reusable sessions while review or correction is pending.
 
-   ```bash
-   wolfpack agent spawn <project> --prompt 'you are a task worker. wait for structured pi.task.assignment.v1 assignments; finish assigned work only with agent_task_done.' --json
-   ```
+## delivery and recovery
 
-   `wolfpack session open <project> --prompt ... --json` is a deprecated alias;
-   use it only when that is the available command in the environment.
+`agent_task_send` returns after durable receiver-gateway receipt, not model execution. A remote initial send gets one initial attempt. The receiver stores a provisional receipt, and Pi sees the assignment only after sender receipt confirmation. Later peer events get four total attempts: initial plus retries around 1, 2, and 4 seconds with jitter. Retry exhaustion is a surfaced local delivery failure; v1 has no queue, scheduler, or offline dispatch.
 
-2. Parse the structured JSON response from Wolfpack for the created session
-   handle/name/id. Treat it as opaque. Do not infer the target from browser UI
-   labels, terminal prose, or pane previews.
+The sender gateway owns canonical order, expiry, and terminal choice; the first accepted terminal event wins. Sender timeout causes best-effort remote cancellation. The local extension polls every five seconds and injects only while idle with no pending messages. It stores `{ taskId, eventId }` in structured custom messages, replays missing events after restart, and records delivery only after structural insertion. Do not call that exactly-once execution.
 
-3. Send the real work with `agent_task_send` to the selected/spawned session.
-   The task text should be the user’s requested work, not the bootstrap prompt.
+A real second peer is not currently available for live operational verification. Isolated two-server tests cover the direct peer protocol, but do not claim that a particular remote deployment is reachable.
 
-4. Return immediately with the task id and target session unless the user asked
-   to wait. Continue local work if there is other useful work to do.
+## do not
 
-5. Use structured task tools for follow-up:
-   - `agent_task_status` for one task
-   - `agent_task_wait` only when the user wants the result now
-   - `agent_task_inbox` to check completed delegated work
-   - `agent_task_cancel` to cancel non-terminal tasks
-
-6. In target sessions, finish assigned tasks with `agent_task_done`. After
-   `agent_task_done`, do not send extra prose; the tool result is the completion
-   channel.
-
-## Do Not
-
-- Do not poll terminal output to decide that delegated work is complete.
-- Do not ask the target to report completion in prose.
-- Do not use `wolfpack session wait` for task completion; it waits for literal
-  terminal text and is the wrong protocol for this package.
-- Do not duplicate Wolfpack session-control rules here. If session control is
-  ambiguous, consult/use `wolfpack-tailnet-control`.
-
-## Examples
-
-User: “open a subagent and inspect the auth middleware”
-
-Expected approach:
-1. Spawn a Wolfpack child session with the existing Wolfpack control workflow.
-2. Call `agent_task_send` with the spawned session as `to` and “inspect the auth
-   middleware” as `task`.
-3. Tell the user the task id and that you’ll check structured results later.
-
-User: “check on the subagent”
-
-Expected approach:
-- Use `agent_task_inbox` or `agent_task_status`; do not read terminal prose to
-  infer done-ness.
+- do not use terminal output as task state or completion evidence.
+- do not ask workers to complete in prose.
+- do not inject task context while Pi is busy or has pending messages.
+- do not copy whole plans, ref contents, or transcripts into task context.
+- do not use filesystem task storage or retain old `mustReturn`, `rejected`, or semantic completion contracts.
+- do not promise JWT federation, artifact byte transfer, or background retry/offline dispatch.
+- do not make workers close their own sessions.

package/src/extension.ts

@@ -3,306 +3,220 @@ import type { AgentToolResult, ExtensionAPI, ExtensionContext } from "@earendil-
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 
-import { buildBackgroundTaskNotificationPrompt, selectUnpromptedTerminalTasks } from "./auto-notify";
-import type { TaskCommunicationLayer } from "./task-communication";
-import { createFilesystemTaskStore } from "./stores/filesystem";
-import { createWolfpackTaskTransport } from "./transports/wolfpack";
-import { buildAssignment, compactTaskResult } from "./protocol";
-import type { AgentTaskRecord, TaskResultPayload, TerminalTaskStatus } from "./types";
-import { DEFAULT_TIMEOUT_MS, TASK_PROTOCOL_VERSION } from "./types";
-
+import {
+	DEFAULT_TASK_TIMEOUT_MS,
+	GatewayClientError,
+	MAX_TASK_TIMEOUT_MS,
+	MIN_TASK_TIMEOUT_MS,
+	createWolfpackGatewayClient,
+	type TaskCompletionInput,
+	type TaskStatus,
+	type WolfpackGatewayClient,
+} from "./gateway-client";
+import { deliverTaskInbox, restoredInboxCursor } from "./task-inbox";
+
+const BACKGROUND_POLL_MS = 5_000;
 const WAIT_POLL_MS = 250;
-const BACKGROUND_POLL_MS = 5000;
-
-const SendParams = Type.Object({
-	to: Type.String({ description: "Target session, worker, or transport-specific address" }),
-	task: Type.String({ description: "Task instructions to send to the target" }),
-	timeoutMs: Type.Optional(Type.Integer({ minimum: 1000, maximum: 86_400_000 })),
-	idempotencyKey: Type.Optional(Type.String()),
-});
+const SUMMARY_MAX_CHARS = 1_200;
 
-const TaskIdParams = Type.Object({
-	taskId: Type.String({ description: "Task id, e.g. task_..." }),
+const AddressParams = Type.Object({
+	machine: Type.String({ minLength: 1, description: "local or a canonical Wolfpack machine identity" }),
+	sessionId: Type.String({ minLength: 1, description: "Stable opaque Wolfpack broker session id" }),
 });
 
-const WaitParams = Type.Object({
-	taskId: Type.String({ description: "Task id, e.g. task_..." }),
-	timeoutMs: Type.Optional(Type.Integer({ minimum: 1000, maximum: 86_400_000 })),
+const ContextRefParams = Type.Object({
+	path: Type.String({ minLength: 1 }),
+	selector: Type.Optional(Type.String()),
+	purpose: Type.Optional(Type.String()),
 });
 
-const InboxParams = Type.Object({
-	ack: Type.Optional(Type.Boolean({ default: false })),
-	includeAcknowledged: Type.Optional(Type.Boolean({ default: false })),
+const SendParams = Type.Object({
+	to: AddressParams,
+	task: Type.String({ minLength: 1, maxLength: 16 * 1024 }),
+	context: Type.Optional(Type.Object({
+		summary: Type.Optional(Type.String({ minLength: 1, maxLength: 16 * 1024 })),
+		refs: Type.Optional(Type.Array(ContextRefParams)),
+	})),
+	role: Type.Optional(Type.String()),
+	preflight: Type.Optional(Type.Object({ requiredProject: Type.Optional(Type.String()) })),
+	metadata: Type.Optional(Type.Object({
+		phaseId: Type.Optional(Type.String()),
+		issueId: Type.Optional(Type.String()),
+		verificationTier: Type.Optional(Type.String()),
+		rootCause: Type.Optional(Type.String()),
+	})),
+	onCompletePrompt: Type.Optional(Type.String({ maxLength: 4_000 })),
+	timeoutMs: Type.Optional(Type.Integer({ minimum: MIN_TASK_TIMEOUT_MS, maximum: MAX_TASK_TIMEOUT_MS })),
+	idempotencyKey: Type.Optional(Type.String({ minLength: 1 })),
 });
 
-const CancelParams = Type.Object({
-	taskId: Type.String({ description: "Task id, e.g. task_..." }),
-	reason: Type.Optional(Type.String()),
+const TaskIdParams = Type.Object({ taskId: Type.String({ minLength: 1 }) });
+const WaitParams = Type.Object({ taskId: Type.String({ minLength: 1 }), timeoutMs: Type.Optional(Type.Integer({ minimum: MIN_TASK_TIMEOUT_MS, maximum: MAX_TASK_TIMEOUT_MS })) });
+const InboxParams = Type.Object({ ack: Type.Optional(Type.Boolean({ default: false })), includeAcknowledged: Type.Optional(Type.Boolean({ default: false })) });
+const MessageParams = Type.Object({
+	taskId: Type.String({ minLength: 1 }),
+	type: StringEnum(["question", "answer", "information"] as const),
+	message: Type.String({ minLength: 1, maxLength: 16 * 1024 }),
+	replyToMessageId: Type.Optional(Type.String({ minLength: 1 })),
 });
-
 const DoneParams = Type.Object({
-	taskId: Type.String({ description: "Task id from the assignment" }),
-	status: StringEnum(["completed", "failed", "cancelled", "rejected"] as const),
-	summary: Type.String({ description: "Compact summary, max 1200 chars" }),
-	error: Type.Optional(
-		Type.Object({
-			code: Type.String(),
-			message: Type.String(),
-			retryable: Type.Boolean(),
-		}),
-	),
+	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())),
-	artifacts: Type.Optional(
-		Type.Array(
-			Type.Object({
-				name: Type.String(),
-				path: Type.Optional(Type.String()),
-				mimeType: Type.Optional(Type.String()),
-				description: Type.Optional(Type.String()),
-			}),
-		),
-	),
+	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 }), mimeType: Type.Optional(Type.String()), description: Type.Optional(Type.String()) }))),
 });
 
-export function createDefaultTaskCommunicationLayer(pi: ExtensionAPI): TaskCommunicationLayer {
-	return {
-		store: createFilesystemTaskStore(),
-		transport: createWolfpackTaskTransport({
-			exec: (command, args, options) => pi.exec(command, [...args], options),
-		}),
-	};
-}
-
-export function registerAgentTaskTools(pi: ExtensionAPI, communication: TaskCommunicationLayer): void {
-	const { store, transport } = communication;
+export function registerAgentTaskTools(pi: ExtensionAPI, client: WolfpackGatewayClient = createWolfpackGatewayClient()): void {
 	let backgroundTimer: ReturnType<typeof setInterval> | undefined;
-	const notifiedTaskIds = new Set<string>();
-	const autoPromptedTaskIds = new Set<string>();
 
-	pi.on("session_start", async (_event, ctx) => {
-		const sessionName = transport.getCurrentSessionName(process.env);
-		ctx.ui.setStatus("wolfpack-tasks", ctx.ui.theme.fg("dim", `tasks: ${sessionName}`));
+	const refreshInbox = async (ctx: ExtensionContext): Promise<void> => {
+		const cursor = restoredInboxCursor(ctx.sessionManager.getEntries());
+		await deliverTaskInbox(pi, client, ctx, cursor);
+	};
 
+	pi.on("session_start", async (_event, ctx) => {
+		ctx.ui.setStatus("wolfpack-tasks", ctx.ui.theme.fg("dim", `tasks: ${client.callerSession}`));
 		backgroundTimer = setInterval(() => {
-			void refreshInboxStatus(ctx.cwd, sessionName, ctx).catch(() => {
-				ctx.ui.setStatus("wolfpack-tasks", ctx.ui.theme.fg("warning", "tasks: unavailable"));
-			});
+			void refreshInbox(ctx).catch(() => ctx.ui.setStatus("wolfpack-tasks", ctx.ui.theme.fg("warning", "tasks: unavailable")));
 		}, BACKGROUND_POLL_MS);
-
-		await refreshInboxStatus(ctx.cwd, sessionName, ctx).catch(() => undefined);
+		await refreshInbox(ctx).catch(() => undefined);
 	});
-
 	pi.on("agent_end", async (_event, ctx) => {
-		const sessionName = transport.getCurrentSessionName(process.env);
-		setTimeout(() => {
-			void refreshInboxStatus(ctx.cwd, sessionName, ctx).catch(() => undefined);
-		}, 0);
+		setTimeout(() => { void refreshInbox(ctx).catch(() => undefined); }, 0);
 	});
-
-	pi.on("session_shutdown", async () => {
-		if (backgroundTimer) {
-			clearInterval(backgroundTimer);
-			backgroundTimer = undefined;
-		}
+	pi.on("session_shutdown", () => {
+		if (backgroundTimer) clearInterval(backgroundTimer);
+		backgroundTimer = undefined;
 	});
 
-	async function refreshInboxStatus(projectDir: string, sessionName: string, ctx: ExtensionContext): Promise<void> {
-		const inbox = await store.listInbox(projectDir, sessionName, { includeAcknowledged: false });
-		const count = inbox.length;
-		ctx.ui.setStatus("wolfpack-tasks", ctx.ui.theme.fg(count > 0 ? "accent" : "dim", `tasks: ${count} inbox`));
-		for (const task of inbox) {
-			if (notifiedTaskIds.has(task.id)) continue;
-			notifiedTaskIds.add(task.id);
-			ctx.ui.notify(`task ${task.id} ${task.status}: ${task.targetSession}`, task.status === "completed" ? "info" : "warning");
-		}
-		triggerIdleInboxPrompt(inbox, ctx);
-	}
-
-	function triggerIdleInboxPrompt(inbox: readonly AgentTaskRecord[], ctx: ExtensionContext): void {
-		if (!ctx.isIdle() || ctx.hasPendingMessages()) return;
-
-		const tasksToPrompt = selectUnpromptedTerminalTasks(inbox, autoPromptedTaskIds);
-		if (tasksToPrompt.length === 0) return;
-
-		try {
-			pi.sendUserMessage(buildBackgroundTaskNotificationPrompt(tasksToPrompt));
-			for (const task of tasksToPrompt) {
-				autoPromptedTaskIds.add(task.id);
-			}
-		} catch {
-			ctx.ui.notify("task results ready; parent is busy, will retry", "info");
-		}
-	}
-
 	pi.registerTool({
-		name: "agent_task_send",
-		label: "Send Agent Task",
-		description: "Send a structured task to another agent/session/worker and return immediately without waiting.",
-		promptSnippet: "Send nonblocking structured tasks to other agents/sessions/workers",
-		promptGuidelines: [
-			"Use agent_task_send instead of natural-language polling when delegating work to another agent/session/worker",
-			"After agent_task_send returns, keep working unless the user explicitly asks to wait for the task.",
-		],
+		name: "agent_task_send", label: "Send Agent Task", description: "Durably send a bounded task to an existing Wolfpack Pi session.",
+		promptSnippet: "Send nonblocking structured tasks through the local Wolfpack gateway",
+		promptGuidelines: ["Use agent_task_send for normal nonblocking delegation; do not wait unless the user explicitly asks."],
 		parameters: SendParams,
-		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
-			const parentSession = transport.getCurrentSessionName(process.env);
-
-			const createdTask = await store.createOrReuseDispatchedTask({
-				projectDir: ctx.cwd,
-				parentSession,
-				targetSession: params.to,
-				taskText: params.task,
-				assignment: (taskId: string) => buildAssignment({ taskId, fromSession: parentSession, instructions: params.task }),
-				timeoutMs: params.timeoutMs ?? DEFAULT_TIMEOUT_MS,
-				idempotencyKey: params.idempotencyKey,
-				targetTaskProtocol: TASK_PROTOCOL_VERSION,
-			});
-			const task = createdTask.task;
-			if (!createdTask.created) {
-				return taskToolResult(compactTaskResult(task, await store.readTaskResult(ctx.cwd, task.id)));
-			}
-
-			const assignment = buildAssignment({ taskId: task.id, fromSession: parentSession, instructions: params.task });
-			const dispatch = await transport.dispatchTask({ projectDir: ctx.cwd, task, target: params.to, assignment, signal });
-			if (!dispatch.ok) {
-				const rejected = await store.completeTask(ctx.cwd, task.id, "rejected", {
-					summary: `dispatch failed: ${dispatch.message}`,
-					error: {
-						code: "dispatch_failed",
-						message: dispatch.message,
-						retryable: dispatch.retryable,
-					},
-				});
-				return taskToolResult(compactTaskResult(rejected, await store.readTaskResult(ctx.cwd, task.id)));
-			}
-
-			return taskToolResult({
-				schemaVersion: 1,
-				taskId: task.id,
-				status: task.status,
-				summary: `dispatched to ${params.to}`,
-				artifacts: [task.assignmentRef].filter((value): value is string => Boolean(value)),
-				error: null,
-			});
-		},
-		renderResult(result, _options, theme) {
-			return new Text(theme.fg("accent", getText(result)));
-		},
+		async execute(_toolCallId, params, signal) {
+			try {
+				const receipt = await client.send(params, signal);
+				return toolResult(receipt, `## task received\n- task: \`${receipt.taskId}\`\n- target: \`${params.to.machine}/${params.to.sessionId}\`\n${warnings(receipt.warnings)}`);
+			} catch (error) { return clientError(error); }
+		}, renderResult(result, _options, theme) { return new Text(theme.fg("accent", text(result))); },
 	});
 
 	pi.registerTool({
-		name: "agent_task_status",
-		label: "Task Status",
-		description: "Read compact structured status for a task.",
-		parameters: TaskIdParams,
-		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-			const task = await store.expireTaskIfOverdue(ctx.cwd, params.taskId);
-			return taskToolResult(compactTaskResult(task, await store.readTaskResult(ctx.cwd, params.taskId)));
-		},
+		name: "agent_task_status", label: "Task Status", description: "Read compact structured task status from Wolfpack.", parameters: TaskIdParams,
+		async execute(_toolCallId, params, signal) {
+			try { const status = await client.status(params.taskId, signal); return statusResult(status); } catch (error) { return clientError(error); }
+		}, renderResult(result, _options, theme) { return new Text(theme.fg("accent", text(result))); },
 	});
 
 	pi.registerTool({
-		name: "agent_task_wait",
-		label: "Wait Agent Task",
-		description: "Wait in tool code for a task to become terminal. Use only when the user wants the result now.",
-		parameters: WaitParams,
-		async execute(_toolCallId, params, _signal, onUpdate, ctx) {
-			const waitMs = params.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-			const sessionName = transport.getCurrentSessionName(process.env);
-			const progressTimer = setInterval(() => {
-				onUpdate?.({ content: [{ type: "text", text: `waiting for ${params.taskId}...` }], details: {} });
-			}, 2000);
+		name: "agent_task_wait", label: "Wait Agent Task", description: "Block only when explicitly invoked until a task reaches a terminal state or this wait times out.", parameters: WaitParams,
+		async execute(_toolCallId, params, signal, onUpdate) {
+			const deadline = Date.now() + (params.timeoutMs ?? DEFAULT_TASK_TIMEOUT_MS);
 			try {
-				const task = await store.waitForTask(ctx.cwd, params.taskId, { timeoutMs: waitMs, pollMs: WAIT_POLL_MS, ackParentSession: sessionName });
-				return taskToolResult(compactTaskResult(task, await store.readTaskResult(ctx.cwd, params.taskId)));
-			} catch (error) {
-				const task = await store.readTask(ctx.cwd, params.taskId);
-				return taskToolResult({
-					schemaVersion: 1,
-					taskId: task.id,
-					status: task.status,
-					summary: error instanceof Error ? error.message : "task wait failed",
-					artifacts: task.resultRef ? [task.resultRef] : [],
-					error: { code: "wait_timeout", message: "task wait timed out", retryable: true },
-				});
-			} finally {
-				clearInterval(progressTimer);
-			}
-		},
+				for (;;) {
+					throwIfAborted(signal);
+					const status = await client.status(params.taskId, signal);
+					if (terminal(status.status)) return statusResult(status);
+					if (Date.now() >= deadline) return toolResult({ taskId: params.taskId, status: status.status, error: { code: "WAIT_TIMEOUT", retryable: true } }, `## task wait\n- task: \`${params.taskId}\`\n- status: ${status.status}\n- wait timed out`);
+					onUpdate?.({ content: [{ type: "text", text: `waiting for ${params.taskId}...` }], details: {} });
+					await sleep(Math.min(WAIT_POLL_MS, Math.max(1, deadline - Date.now())), signal);
+				}
+			} catch (error) { return clientError(error); }
+		}, renderResult(result, _options, theme) { return new Text(theme.fg("accent", text(result))); },
 	});
 
 	pi.registerTool({
-		name: "agent_task_inbox",
-		label: "Task Inbox",
-		description: "List terminal tasks for this parent session. Results are only shown to the model when this tool is called.",
-		parameters: InboxParams,
-		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-			const sessionName = transport.getCurrentSessionName(process.env);
-			const tasks = await store.listInbox(ctx.cwd, sessionName, { includeAcknowledged: params.includeAcknowledged ?? false });
-			const compact = [];
-			for (const task of tasks) {
-				compact.push(compactTaskResult(task, await store.readTaskResult(ctx.cwd, task.id)));
-				if (params.ack) {
-					await store.ackTask(ctx.cwd, task.id, sessionName);
+		name: "agent_task_inbox", label: "Task Inbox", description: "Read inbox task events and optionally acknowledge terminal parent tasks.", parameters: InboxParams,
+		async execute(_toolCallId, params, signal) {
+			try {
+				let cursor = "0";
+				const taskIds = new Set<string>();
+				for (;;) {
+					const page = await client.inbox(cursor, params.includeAcknowledged ?? false, signal);
+					for (const event of page.events) taskIds.add(event.taskId);
+					if (!page.hasMore) break;
+					cursor = page.nextCursor;
 				}
-			}
-			return taskToolResult({ tasks: compact });
-		},
+				const tasks = await Promise.all([...taskIds].map((taskId) => client.status(taskId, signal)));
+				if (params.ack) await Promise.all(tasks.filter((task) => terminal(task.status)).map((task) => client.ack(task.task.taskId, signal)));
+				return toolResult({ tasks }, `## task inbox\n${tasks.length === 0 ? "- empty" : tasks.map((task) => `- \`${task.task.taskId}\`: ${task.status}${task.completion ? ` — ${task.completion.summary}` : ""}`).join("\n")}`);
+			} catch (error) { return clientError(error); }
+		}, renderResult(result, _options, theme) { return new Text(theme.fg("accent", text(result))); },
 	});
 
 	pi.registerTool({
-		name: "agent_task_cancel",
-		label: "Cancel Agent Task",
-		description: "Cancel a non-terminal task in the shared task store.",
-		parameters: CancelParams,
-		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-			const task = await store.cancelTask(ctx.cwd, params.taskId, params.reason);
-			return taskToolResult(compactTaskResult(task, await store.readTaskResult(ctx.cwd, params.taskId)));
-		},
+		name: "agent_task_message", label: "Message Agent Task", description: "Durably send a question, answer, or information event for a task.", parameters: MessageParams,
+		async execute(_toolCallId, params, signal) {
+			try {
+				const [identity, status] = await Promise.all([client.sessionStatus(signal), client.status(params.taskId, signal)]);
+				const receipt = await client.message(params, signal);
+				const receiverQuestion = params.type === "question" && identity.sessionId === status.task.target.sessionId;
+				return { ...toolResult(receipt, `## task ${params.type}\n- task: \`${params.taskId}\`\n${params.message}`), ...(receiverQuestion ? { terminate: true } : {}) };
+			} catch (error) { return clientError(error); }
+		}, renderResult(result, _options, theme) { return new Text(theme.fg("accent", text(result))); },
 	});
 
 	pi.registerTool({
-		name: "agent_task_done",
-		label: "Complete Agent Task",
-		description: "Finish an assigned task with structured status. Use exactly once as the final action for assigned tasks.",
-		promptSnippet: "Complete an assigned task with a terminating structured result",
-		promptGuidelines: [
-			"Use agent_task_done exactly once as the final action for pi.task.assignment.v1 tasks.",
-			"After calling agent_task_done, do not emit another assistant response in prose.",
-		],
-		parameters: DoneParams,
-		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-			const status = params.status as TerminalTaskStatus;
-			const payload: TaskResultPayload = {
-				summary: params.summary,
-				...(params.result && { result: params.result }),
-				...(params.error && { error: params.error }),
-				...(params.artifacts && { artifacts: params.artifacts }),
-			};
-			const task = await store.completeTask(ctx.cwd, params.taskId, status, payload);
-			return {
-				...taskToolResult(compactTaskResult(task, await store.readTaskResult(ctx.cwd, params.taskId))),
-				terminate: true,
-			};
-		},
+		name: "agent_task_cancel", label: "Cancel Agent Task", description: "Request cancellation for a non-terminal task through Wolfpack.", parameters: TaskIdParams,
+		async execute(_toolCallId, params, signal) {
+			try { const receipt = await client.cancel(params.taskId, signal); return toolResult(receipt, `## task cancellation requested\n- task: \`${params.taskId}\`${warnings(receipt.warnings)}`); } catch (error) { return clientError(error); }
+		}, renderResult(result, _options, theme) { return new Text(theme.fg("accent", text(result))); },
+	});
+
+	pi.registerTool({
+		name: "agent_task_done", label: "Complete Agent Task", description: "Finish an assigned task with a structured terminal result. Use exactly once as the final action.",
+		promptSnippet: "Complete an assigned task with a terminating structured result", promptGuidelines: ["Use agent_task_done exactly once as the final action for an assigned task."], parameters: DoneParams,
+		async execute(_toolCallId, params, signal) {
+			try {
+				const result: TaskCompletionInput = { summary: params.summary, ...(params.result && { result: params.result }), ...(params.error && { error: params.error }), ...(params.artifacts && { artifacts: params.artifacts }) };
+				const receipt = await client.complete({ taskId: params.taskId, status: params.status, result }, signal);
+				return { ...toolResult(receipt, `## task ${params.status}\n- task: \`${params.taskId}\`\n- ${params.summary}${warnings(receipt.warnings)}`), terminate: true };
+			} catch (error) { return clientError(error); }
+		}, renderResult(result, _options, theme) { return new Text(theme.fg("accent", text(result))); },
 	});
 }
 
 export default function piTasks(pi: ExtensionAPI): void {
-	registerAgentTaskTools(pi, createDefaultTaskCommunicationLayer(pi));
+	registerAgentTaskTools(pi);
 }
 
-function taskToolResult(details: unknown): AgentToolResult<unknown> {
-	return {
-		content: [{ type: "text", text: JSON.stringify(details) }],
-		details,
-	};
+function statusResult(status: TaskStatus): AgentToolResult<unknown> {
+	return toolResult(status, `## task status\n- task: \`${status.task.taskId}\`\n- status: ${status.status}${status.completion ? `\n- summary: ${status.completion.summary}` : ""}${warnings(status.warnings)}`);
+}
+
+function toolResult(details: unknown, markdown: string): AgentToolResult<unknown> {
+	return { content: [{ type: "text", text: markdown }], details };
 }
 
-function getText(result: { readonly content?: readonly unknown[] }): string {
+function clientError(error: unknown): AgentToolResult<unknown> {
+	const gateway = error instanceof GatewayClientError ? error : new GatewayClientError("CLIENT_ERROR", error instanceof Error ? error.message : "task gateway request failed", true);
+	return toolResult({ error: { code: gateway.code, message: gateway.message, retryable: gateway.retryable } }, `## task gateway error\n- ${gateway.code}: ${gateway.message}`);
+}
+
+function warnings(values: readonly { readonly code: string; readonly message: string }[]): string {
+	return values.length === 0 ? "" : `\n## gateway warnings\n${values.map((value) => `- ${value.code}: ${value.message}`).join("\n")}`;
+}
+
+function terminal(status: string): boolean {
+	return status === "completed" || status === "failed" || status === "cancelled" || status === "timed_out";
+}
+
+function text(result: { readonly content?: readonly unknown[] }): string {
 	const first = result.content?.[0];
-	if (!first || typeof first !== "object" || !("type" in first) || first.type !== "text" || !("text" in first)) {
-		return "";
-	}
-	return typeof first.text === "string" ? first.text : "";
+	return first && typeof first === "object" && "type" in first && first.type === "text" && "text" in first && typeof first.text === "string" ? first.text : "";
+}
+
+function throwIfAborted(signal: AbortSignal | undefined): void {
+	if (signal?.aborted) throw new GatewayClientError("ABORTED", "task wait was cancelled", true);
+}
+
+async function sleep(milliseconds: number, signal: AbortSignal | undefined): Promise<void> {
+	await new Promise<void>((resolve, reject) => {
+		const timeout = setTimeout(resolve, milliseconds);
+		const abort = (): void => { clearTimeout(timeout); reject(new GatewayClientError("ABORTED", "task wait was cancelled", true)); };
+		signal?.addEventListener("abort", abort, { once: true });
+	});
 }