pi-task-dispatcher 1.0.0 → 2.0.0

package/README.md

@@ -1,133 +1,124 @@
 # pi-task-dispatcher
 
-Delegate bounded mechanical and engineering subtasks to configurable Pi worker models without replacing the model selected for the main Pi session.
+Delegate bounded tasks from a Pi session to dedicated mechanical and engineering worker models while the selected main model remains in control.
 
-## How it works
+## Features
 
-Your selected Pi model remains the **orchestrator**: it decides whether to delegate, supplies a self-contained task, evaluates the worker report, reviews material changes, and owns the final answer. This package adds two model-only tools:
+- **Two focused worker roles:** route precise execution work to a mechanic model and broader implementation work to an engineer model.
+- **Least-privilege delegation:** every call supplies an exact tool allowlist selected from tools active for the main agent. Workers cannot invoke the delegation tools recursively.
+- **Live progress:** streamed worker text, tool activity, and an elapsed-time heartbeat keep long-running tasks visible.
+- **Recoverable interruption:** approaching time and turn limits request a worker-authored checkpoint. A hard timeout returns a synthetic fallback checkpoint.
+- **Explicit continuation:** a checkpoint never starts another worker automatically. The main agent reviews current state and decides what happens next.
 
-| Tool | Use it when |
+## Worker tools
+
+The package adds two model-only tools to Pi:
+
+| Tool | Intended use |
 | --- | --- |
-| `delegate_mechanical` | The outcome and constraints are precise and the work is bounded, multi-step, and primarily inspection, exact edits, repetitive transformation, commands, retrieval, or verification. Use a direct tool for a single trivial operation. |
-| `delegate_engineering` | A self-contained engineering subtask needs investigation, implementation, debugging, refactoring, testing, review, research, or analysis. Include the outcome, constraints, and acceptance conditions. |
+| `delegate_mechanical` | Bounded multi-step inspection, exact edits, repetitive transformations, commands, retrieval, or verification with precise acceptance conditions. |
+| `delegate_engineering` | Self-contained investigation, implementation, debugging, refactoring, testing, review, research, or analysis. |
 
-Both workers operate in the current workspace and can modify files when their configured tools permit it.
+The main model remains the **orchestrator**. It defines the delegated task, selects the smallest sufficient tool allowlist, evaluates the report, reviews material changes, performs required verification, and owns the final answer.
 
-After the orchestrator selects a delegation tool, its role is routed deterministically to that role's configured `provider/model`. That routing does **not** make a worker's output, changes, or correctness deterministic; treat every worker report as input to review and verification.
+Workers operate in the current workspace and can modify files only when their selected tools permit it. Role routing to the configured `provider/model` is deterministic; worker output and correctness are not. Treat every worker report as input to review rather than proof of completion.
 
 ## Requirements
 
-- Pi 1.0.0 or later
+- Pi 1.0.2 or later
 - Node.js 22.19.0 or later
-- A configured, authenticated Pi model for each worker role you invoke
-
-## Install
-
-Install the published package for your Pi user configuration:
+- A configured and authenticated Pi model for each worker role you use
 
-```sh
-pi install npm:pi-task-dispatcher@1.0.0
-```
+## Installation
 
-For a local checkout, run this from its parent directory:
+Install the package for your Pi user configuration:
 
 ```sh
-pi install ./pi-task-dispatcher
+pi install npm:pi-task-dispatcher
 ```
 
-To register either source in the current project's `.pi/settings.json` instead, add `--local`:
+To install it only for the current project, add `--local`:
 
 ```sh
-pi install npm:pi-task-dispatcher@1.0.0 --local
+pi install npm:pi-task-dispatcher --local
 ```
 
-Project packages load only after that project is trusted. In an already running Pi session, run:
+Project packages load only after the project is trusted. In an active Pi session, load the extension with:
 
 ```text
 /reload
 ```
 
-`/reload` reloads extensions and other discovered resources. The worker configuration below is read again for every delegation.
-
-## Default workers
-
-| Role | Model | Thinking | Timeout | Turn limit |
-| --- | --- | --- | ---: | ---: |
-| Mechanic | `openai-codex/gpt-5.6-luna` | `max` | 300 seconds | 20 |
-| Engineer | `openai-codex/gpt-5.6-terra` | `max` | 900 seconds | 30 |
-
-By default, both workers receive this explicit tool allowlist:
-
-```text
-read,bash,edit,write
-```
-
-`pi-task-dispatcher` provides only these four native Pi tools by default; it does not provide `web_search`, `fetch_content`, `get_search_content`, or `source_check`. If you have the separate `pi-web-access` package installed, you may explicitly add those tools to a role's `tools` array:
-
-```json
-{
-  "mechanic": {
-    "tools": ["read", "bash", "edit", "write", "web_search", "fetch_content", "get_search_content", "source_check"]
-  }
-}
-```
+## Configuration
 
-## Configure workers
+The package works without a configuration file using these defaults:
 
-Optionally create `~/.pi/agent/task-dispatcher.json`. If Pi's agent directory is overridden, use `<agent-dir>/task-dispatcher.json` instead. Missing role objects and fields inherit the defaults.
+| Role | Model | Thinking | Hard timeout | Checkpoint grace | Turn limit |
+| --- | --- | --- | ---: | ---: | ---: |
+| Mechanic | `openai-codex/gpt-5.6-luna` | `max` | 300 seconds | 30 seconds | 20 |
+| Engineer | `openai-codex/gpt-5.6-terra` | `max` | 900 seconds | 45 seconds | 30 |
 
-This is a complete valid configuration using the defaults:
+To override them, create `~/.pi/agent/task-dispatcher.json`. If Pi uses a custom agent directory, create `task-dispatcher.json` in that directory instead. Missing roles and fields retain their defaults.
 
 ```json
 {
-  "version": 1,
   "mechanic": {
     "model": "openai-codex/gpt-5.6-luna",
     "thinking": "max",
-    "tools": [
-      "read",
-      "bash",
-      "edit",
-      "write"
-    ],
     "timeoutSeconds": 300,
+    "checkpointGraceSeconds": 30,
     "maxTurns": 20
   },
   "engineer": {
     "model": "openai-codex/gpt-5.6-terra",
     "thinking": "max",
-    "tools": [
-      "read",
-      "bash",
-      "edit",
-      "write"
-    ],
     "timeoutSeconds": 900,
+    "checkpointGraceSeconds": 45,
     "maxTurns": 30
   }
 }
 ```
 
-| Field | Meaning |
+| Field | Description |
 | --- | --- |
-| `version` | Optional. When present, it must be `1`. |
-| `mechanic`, `engineer` | Optional per-role objects. Each supplied field overrides that role's default. |
-| `model` | A `provider/model` string. Pi verifies that the exact model exists in its registry and has usable authentication before starting the worker. |
-| `thinking` | One of `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`. |
-| `tools` | A non-empty array of tool names. It replaces, rather than extends, the default allowlist; duplicate names are removed. |
-| `timeoutSeconds` | Positive integer wall-clock limit for the worker process. |
-| `maxTurns` | Positive integer limit for a continuing tool-using worker loop. |
+| `mechanic`, `engineer` | Optional role objects. Each supplied field overrides that role's default. |
+| `model` | Exact `provider/model` identity. The dispatcher verifies model availability and authentication before starting a worker. |
+| `thinking` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`. |
+| `timeoutSeconds` | Positive integer hard wall-clock limit for the worker process. |
+| `checkpointGraceSeconds` | Positive integer period reserved before the hard timeout for a graceful checkpoint. It must be less than `timeoutSeconds`. |
+| `maxTurns` | Positive integer work-turn limit. The dispatcher allows a final checkpoint response after the limit is reached. |
+
+Configuration is read for every delegation, so configuration-only changes do not require `/reload`.
+
+Tool access is deliberately absent from role configuration. Every delegation selects its own exact allowlist from the main agent's currently active tools; `[]` gives the worker no tools. A continuation must select its tools again and does not inherit the previous allowlist.
+
+## Usage
+
+Give the main model a bounded objective and let it choose whether delegation is useful. For example:
+
+> Use the engineering worker to diagnose the failing parser test. Do not change public APIs. Run the focused test and report the cause, changed files, and test result.
+
+For tighter control, name the role and allowed tools:
+
+> Delegate this to the mechanic worker with only `read` and `bash`: inspect the generated manifest, run its validation command, and report exact mismatches. Do not modify files.
+
+A direct tool remains preferable for one trivial operation. Delegation is most useful when a self-contained episode would otherwise consume multiple agent turns or produce bulky intermediate output.
+
+## Limits and checkpoints
+
+Each delegation runs in a separate Pi RPC child process with an in-memory, no-session conversation. The worker receives its role prompt, selected model, thinking level, and only the allowlist chosen for that call.
 
-## Isolation, limits, and safety
+The dispatcher propagates parent cancellation and reports live text and tool activity. Before the hard timeout, it steers the worker to stop at the next safe turn boundary and produce a checkpoint. Reaching the turn limit uses the same checkpoint flow. If the worker cannot settle before the hard deadline, the dispatcher terminates it and reports observed completed and interrupted activity in a fallback checkpoint.
 
-Each delegation starts a separate, no-session Pi child process in the current workspace. The worker receives its role prompt, selected model, thinking level, and only the configured `tools` allowlist. The dispatcher does not register either delegation tool inside worker processes, so workers cannot recursively delegate through this package.
+Non-completed results include the stopping reason, available partial worker text, observed activity, and a warning when filesystem effects may remain. The main agent then chooses whether to:
 
-The parent cancellation signal is propagated to the child. Workers are stopped on timeout, and an ongoing tool-using loop is stopped at its configured turn limit. While a worker runs, its tool activity can be reported as progress. Its final tool result includes the role, model, thinking level, configured tool names, status, turns, duration, exit information, activity, and aggregated usage; non-completed runs are returned as errors with a diagnostic and any available partial report. Reported failure states include configuration, model, and process errors, cancellation, timeout, turn-limit, and incomplete outcomes.
+- inspect and continue directly;
+- delegate a bounded continuation with a newly selected allowlist;
+- request user input; or
+- stop and report a limitation.
 
-> **Security warning:** Worker process isolation is not a security sandbox. A worker can use every tool in its configured allowlist with the Pi host's permissions in the current environment. Use the smallest practical allowlist and delegate only work you are prepared to authorize.
+Continuation is never automatic.
 
-## Short workflow
+## Security
 
-1. Select the normal Pi model that should orchestrate the task.
-2. Give it a bounded request, for example: “Use `delegate_engineering` to diagnose the failing parser test. Do not change public APIs; run the focused test; return the cause, files changed, and test result.”
-3. The orchestrator calls the selected worker tool, receives its report, inspects relevant changes and verification, then produces the final response.
+Worker process separation is **not** a security sandbox. A worker uses its selected tools with the Pi host's permissions in the current environment. Tool availability does not establish task scope, authorization, or safety. Use the smallest practical allowlist and delegate only work you are prepared to authorize and review.

package/extensions/task-dispatcher.ts

@@ -25,8 +25,8 @@ type WorkerStatus =
 interface WorkerConfig {
 	model: string;
 	thinking: ThinkingLevel;
-	tools: string[];
 	timeoutSeconds: number;
+	checkpointGraceSeconds: number;
 	maxTurns: number;
 }
 
@@ -52,6 +52,21 @@ interface UsageTotals {
 	};
 }
 
+interface WorkerActivity {
+	toolCallId: string;
+	label: string;
+	status: "running" | "completed" | "failed";
+}
+
+interface WorkerCheckpoint {
+	reason: Exclude<WorkerStatus, "running" | "completed">;
+	task: string;
+	lastAssistantText?: string;
+	completedActivities: string[];
+	activeActivities: string[];
+	filesystemEffectsMayRemain: boolean;
+}
+
 interface WorkerDetails {
 	role: Role;
 	status: WorkerStatus;
@@ -64,7 +79,8 @@ interface WorkerDetails {
 	stopReason?: string;
 	diagnostic?: string;
 	stderr?: string;
-	activity: string[];
+	activity: WorkerActivity[];
+	checkpoint?: WorkerCheckpoint;
 }
 
 interface WorkerResult {
@@ -74,45 +90,51 @@ interface WorkerResult {
 }
 
 interface ParsedEvent {
+	id?: string;
 	type?: string;
+	success?: boolean;
+	error?: string;
 	message?: {
 		role?: string;
 		content?: Array<{ type?: string; text?: string; name?: string; arguments?: unknown }>;
-		usage?: Partial<UsageTotals> & { cost?: Partial<UsageTotals["cost"]> };
+		usage?: EventUsage;
 		stopReason?: string;
 		errorMessage?: string;
 	};
+	usage?: EventUsage;
+	assistantMessageEvent?: {
+		type?: string;
+		contentIndex?: number;
+		delta?: string;
+		content?: string;
+	};
+	toolCallId?: string;
 	toolName?: string;
 	args?: unknown;
+	isError?: boolean;
 }
 
-type EventUsage = NonNullable<NonNullable<ParsedEvent["message"]>["usage"]>;
+type EventUsage = Partial<UsageTotals> & { cost?: Partial<UsageTotals["cost"]> };
 
 const CONFIG_PATH = path.join(getAgentDir(), "task-dispatcher.json");
 const WORKER_ENV = "PI_TASK_DISPATCHER_WORKER";
 const RESULT_LIMIT = 24_000;
 const STDERR_LIMIT = 8_000;
-const DEFAULT_TOOLS = [
-	"read",
-	"bash",
-	"edit",
-	"write",
-];
 const THINKING_LEVELS = new Set<ThinkingLevel>(["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
 
 const DEFAULT_CONFIG: DispatcherConfig = {
 	mechanic: {
 		model: "openai-codex/gpt-5.6-luna",
 		thinking: "max",
-		tools: DEFAULT_TOOLS,
 		timeoutSeconds: 300,
+		checkpointGraceSeconds: 30,
 		maxTurns: 20,
 	},
 	engineer: {
 		model: "openai-codex/gpt-5.6-terra",
 		thinking: "max",
-		tools: DEFAULT_TOOLS,
 		timeoutSeconds: 900,
+		checkpointGraceSeconds: 45,
 		maxTurns: 30,
 	},
 };
@@ -155,6 +177,10 @@ const DelegateParams = Type.Object({
 		maxLength: 12_000,
 		description: "A self-contained task with its objective, scope, constraints, and completion checks.",
 	}),
+	tools: Type.Array(Type.String({ minLength: 1 }), {
+		maxItems: 32,
+		description: "The exact worker tool allowlist selected from the main agent's active tools. Use the smallest sufficient set; use an empty array for no tools.",
+	}),
 });
 
 /** Identify plain objects before reading user-controlled JSON configuration fields. */
@@ -164,7 +190,7 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 
 /** Copy defaults so loaded configuration cannot mutate shared role settings. */
 function copyWorkerConfig(config: WorkerConfig): WorkerConfig {
-	return { ...config, tools: [...config.tools] };
+	return { ...config };
 }
 
 /** Validate and merge one role's optional configuration over its package defaults. */
@@ -189,16 +215,8 @@ function parseWorkerConfig(role: Role, value: unknown): WorkerConfig {
 		result.thinking = value.thinking as ThinkingLevel;
 	}
 
-	// Require an explicit non-empty allowlist when tools are overridden.
-	if (value.tools !== undefined) {
-		if (!Array.isArray(value.tools) || value.tools.length === 0 || value.tools.some((tool) => typeof tool !== "string" || !tool.trim())) {
-			throw new Error(`"${role}.tools" must be a non-empty array of tool names`);
-		}
-		result.tools = [...new Set(value.tools as string[])];
-	}
-
 	// Bound worker lifetime settings to positive integers.
-	for (const field of ["timeoutSeconds", "maxTurns"] as const) {
+	for (const field of ["timeoutSeconds", "checkpointGraceSeconds", "maxTurns"] as const) {
 		const candidate = value[field];
 		if (candidate !== undefined) {
 			if (!Number.isInteger(candidate) || (candidate as number) <= 0) {
@@ -207,6 +225,9 @@ function parseWorkerConfig(role: Role, value: unknown): WorkerConfig {
 			result[field] = candidate as number;
 		}
 	}
+	if (result.checkpointGraceSeconds >= result.timeoutSeconds) {
+		throw new Error(`"${role}.checkpointGraceSeconds" must be less than "${role}.timeoutSeconds"`);
+	}
 
 	return result;
 }
@@ -227,9 +248,6 @@ function loadConfig(): DispatcherConfig {
 		throw new Error(`Cannot parse ${CONFIG_PATH}: ${error instanceof Error ? error.message : String(error)}`);
 	}
 	if (!isRecord(parsed)) throw new Error(`${CONFIG_PATH} must contain a JSON object`);
-	if (parsed.version !== undefined && parsed.version !== 1) {
-		throw new Error(`${CONFIG_PATH} has unsupported version ${String(parsed.version)}`);
-	}
 
 	return {
 		mechanic: parseWorkerConfig("mechanic", parsed.mechanic),
@@ -296,24 +314,45 @@ function formatActivity(name: string, args: unknown): string {
 	return name;
 }
 
+/** Format a stopped worker's observed state for the orchestrator's continuation decision. */
+function formatCheckpoint(checkpoint: WorkerCheckpoint): string {
+	const completed = checkpoint.completedActivities.length > 0 ? checkpoint.completedActivities.join("; ") : "none observed";
+	const active = checkpoint.activeActivities.length > 0 ? checkpoint.activeActivities.join("; ") : "none observed";
+	const text = checkpoint.lastAssistantText ? `\nLast worker text:\n${truncate(checkpoint.lastAssistantText, 4_000)}` : "";
+	return [
+		"Worker checkpoint:",
+		`- Stop reason: ${checkpoint.reason}`,
+		`- Delegated task: ${truncate(checkpoint.task, 2_000)}`,
+		`- Completed tool activity: ${completed}`,
+		`- Active or interrupted tool activity: ${active}`,
+		`- Filesystem effects may remain: ${checkpoint.filesystemEffectsMayRemain ? "yes" : "no"}`,
+		text,
+		"Continuation is not automatic. Inspect material state, then decide whether to continue directly, delegate a bounded continuation with a newly selected tool allowlist, request user input, or stop with a limitation.",
+	].filter(Boolean).join("\n");
+}
+
 /** Run one isolated Pi worker through its full tool-using agent loop. */
 async function runWorker(
 	role: Role,
 	task: string,
 	config: WorkerConfig,
+	tools: string[],
 	cwd: string,
 	signal: AbortSignal | undefined,
 	onUpdate: ((result: { content: Array<{ type: "text"; text: string }>; details: WorkerDetails }) => void) | undefined,
 ): Promise<WorkerResult> {
 	const startedAt = Date.now();
 	const usage = emptyUsage();
-	const activity: string[] = [];
+	const activity: WorkerActivity[] = [];
+	const activeActivity = new Map<string, WorkerActivity>();
+	const streamingText = new Map<number, string>();
 	let turns = 0;
 	let finalOutput = "";
 	let stopReason: string | undefined;
 	let modelError: string | undefined;
 	let stderr = "";
 	let forcedStatus: WorkerStatus | undefined;
+	let checkpointRequestedReason: "timeout" | "turn_limit" | undefined;
 	let processError: string | undefined;
 
 	// Keep role instructions out of the command line and remove them after the worker exits.
@@ -325,18 +364,15 @@ async function runWorker(
 
 		const args = [
 			"--mode",
-			"json",
-			"-p",
+			"rpc",
 			"--no-session",
 			"--model",
 			config.model,
 			"--thinking",
 			config.thinking,
-			"--tools",
-			config.tools.join(","),
+			...(tools.length > 0 ? ["--tools", tools.join(",")] : ["--no-tools"]),
 			"--append-system-prompt",
 			promptPath,
-			`Delegated ${role} task:\n${task}`,
 		];
 
 		const exitCode = await new Promise<number | null>((resolve) => {
@@ -344,7 +380,7 @@ async function runWorker(
 			const child = spawn(invocation.command, invocation.args, {
 				cwd,
 				shell: false,
-				stdio: ["ignore", "pipe", "pipe"],
+				stdio: ["pipe", "pipe", "pipe"],
 				env: { ...process.env, [WORKER_ENV]: role },
 			});
 			let stdoutBuffer = "";
@@ -364,7 +400,41 @@ async function runWorker(
 				}, 5_000);
 			};
 
-			// Retain in-flight usage while treating completed messages as authoritative.
+			// Ask the worker to stop at the next safe turn boundary and author its handoff report.
+			const requestCheckpoint = (reason: "timeout" | "turn_limit") => {
+				if (checkpointRequestedReason || settled || child.stdin.writableEnded) return;
+				checkpointRequestedReason = reason;
+				const message =
+					reason === "timeout"
+						? "The delegation time limit is approaching. Stop starting new work. At the next safe boundary, return a concise checkpoint with completed work, files changed, checks run, current state, interrupted work, and unresolved items. Do not continue implementation."
+						: "The delegation turn limit has been reached. After current tool calls finish, stop work and return a concise checkpoint with completed work, files changed, checks run, current state, interrupted work, and unresolved items. Do not continue implementation.";
+				child.stdin.write(`${JSON.stringify({ id: `checkpoint-${reason}`, type: "steer", message })}\n`);
+			};
+
+			let lastProgressAt = 0;
+			const currentStreamingText = () =>
+				[...streamingText.entries()].sort(([left], [right]) => left - right).map(([, text]) => text).join("\n").trim();
+			const emitProgress = (text: string, force = false) => {
+				const now = Date.now();
+				if (!force && now - lastProgressAt < 250) return;
+				lastProgressAt = now;
+				onUpdate?.({
+					content: [{ type: "text", text }],
+					details: {
+						role,
+						status: "running",
+						model: config.model,
+						thinking: config.thinking,
+						tools,
+						turns,
+						durationMs: now - startedAt,
+						exitCode: null,
+						activity: activity.map((item) => ({ ...item })),
+					},
+				});
+			};
+
+			// Reduce the documented JSON event stream into live progress and a recoverable checkpoint.
 			const processLine = (line: string) => {
 				if (!line.trim()) return;
 				let event: ParsedEvent;
@@ -373,10 +443,65 @@ async function runWorker(
 				} catch {
 					return;
 				}
+
+				// Fail promptly when RPC rejects the initial prompt instead of waiting for the wall-clock limit.
+				if (event.type === "response" && event.id === "delegated-task" && event.success === false) {
+					processError = event.error || "Pi rejected the delegated RPC prompt.";
+					stopChild("process_error");
+					return;
+				}
+
+				if (event.type === "agent_settled") {
+					if (checkpointRequestedReason && !forcedStatus) forcedStatus = checkpointRequestedReason;
+					if (!child.stdin.writableEnded) child.stdin.end();
+					return;
+				}
+
 				if (event.type === "message_update") {
-					if (event.message?.usage) unfinishedUsage = event.message.usage;
+					if (event.usage) unfinishedUsage = event.usage;
+					const update = event.assistantMessageEvent;
+					if (typeof update?.contentIndex === "number") {
+						if (update.type === "text_start") streamingText.set(update.contentIndex, "");
+						if (update.type === "text_delta" && update.delta) {
+							streamingText.set(update.contentIndex, (streamingText.get(update.contentIndex) ?? "") + update.delta);
+							emitProgress(`${role}: ${truncate(currentStreamingText(), 500) || "working..."}`);
+						}
+						if (update.type === "text_end" && update.content !== undefined) {
+							streamingText.set(update.contentIndex, update.content);
+							emitProgress(`${role}: ${truncate(currentStreamingText(), 500) || "working..."}`, true);
+						}
+					}
+					return;
+				}
+
+				if (event.type === "tool_execution_start" && event.toolCallId && event.toolName) {
+					const item: WorkerActivity = {
+						toolCallId: event.toolCallId,
+						label: formatActivity(event.toolName, event.args),
+						status: "running",
+					};
+					activity.push(item);
+					activeActivity.set(item.toolCallId, item);
+					emitProgress(`${role}: running ${item.label}`, true);
+					return;
+				}
+
+				if (event.type === "tool_execution_update" && event.toolCallId) {
+					const item = activeActivity.get(event.toolCallId);
+					if (item) emitProgress(`${role}: running ${item.label}`);
+					return;
+				}
+
+				if (event.type === "tool_execution_end" && event.toolCallId) {
+					const item = activeActivity.get(event.toolCallId);
+					if (item) {
+						item.status = event.isError ? "failed" : "completed";
+						activeActivity.delete(event.toolCallId);
+						emitProgress(`${role}: ${item.status} ${item.label}`, true);
+					}
 					return;
 				}
+
 				if (event.type !== "message_end" || event.message?.role !== "assistant") return;
 
 				turns++;
@@ -384,33 +509,23 @@ async function runWorker(
 				modelError = event.message.errorMessage ?? modelError;
 				addUsage(usage, event.message.usage ?? unfinishedUsage);
 				unfinishedUsage = undefined;
-
-				// Preserve the latest final text and surface worker tool activity as progress.
-				for (const part of event.message.content ?? []) {
-					if (part.type === "text" && part.text) finalOutput = part.text;
-					if (part.type === "toolCall" && part.name) {
-						const label = formatActivity(part.name, part.arguments);
-						activity.push(label);
-						onUpdate?.({
-							content: [{ type: "text", text: `${role}: ${label}` }],
-							details: {
-								role,
-								status: "running",
-								model: config.model,
-								thinking: config.thinking,
-								tools: config.tools,
-								turns,
-								durationMs: Date.now() - startedAt,
-								exitCode: null,
-								activity: [...activity],
-							},
-						});
-					}
-				}
-
-				if (turns >= config.maxTurns && stopReason === "toolUse") stopChild("turn_limit");
+				const completedText = (event.message.content ?? [])
+					.filter((part) => part.type === "text" && part.text)
+					.map((part) => part.text as string)
+					.join("\n")
+					.trim();
+				if (completedText) finalOutput = completedText;
+				streamingText.clear();
+				if (turns >= config.maxTurns && stopReason === "toolUse") requestCheckpoint("turn_limit");
 			};
 
+			// Keep long model and tool waits visibly alive even when the child emits no stream event.
+			const heartbeat = setInterval(() => {
+				const running = [...activeActivity.values()].map((item) => item.label).join("; ");
+				const elapsedSeconds = Math.floor((Date.now() - startedAt) / 1_000);
+				emitProgress(`${role}: ${running ? `running ${running}` : "working"} (${elapsedSeconds}s)`, true);
+			}, 1_000);
+
 			// Stream-decode UTF-8 before splitting complete JSONL records, retaining a trailing fragment.
 			child.stdout.on("data", (chunk) => {
 				stdoutBuffer += stdoutDecoder.decode(chunk, { stream: true });
@@ -425,9 +540,13 @@ async function runWorker(
 			child.on("error", (error) => {
 				processError = error.message;
 			});
+			child.stdin.on("error", (error) => {
+				processError ??= error.message;
+			});
 			// Flush decoder state and charge at most one unfinished streamed assistant response.
 			child.on("close", (code) => {
 				settled = true;
+				clearInterval(heartbeat);
 				if (forceKillTimer) clearTimeout(forceKillTimer);
 				stdoutBuffer += stdoutDecoder.decode();
 				stderr = truncate(stderr + stderrDecoder.decode(), STDERR_LIMIT);
@@ -436,8 +555,18 @@ async function runWorker(
 				resolve(code);
 			});
 
+			// Start the RPC run after all stream handlers are ready.
+			child.stdin.write(
+				`${JSON.stringify({ id: "delegated-task", type: "prompt", message: `Delegated ${role} task:\n${task}` })}\n`,
+			);
+
+			const checkpointLeadMs = (config.timeoutSeconds - config.checkpointGraceSeconds) * 1_000;
+			const checkpointTimer = setTimeout(() => requestCheckpoint("timeout"), checkpointLeadMs);
 			const timeout = setTimeout(() => stopChild("timeout"), config.timeoutSeconds * 1_000);
-			child.once("close", () => clearTimeout(timeout));
+			child.once("close", () => {
+				clearTimeout(checkpointTimer);
+				clearTimeout(timeout);
+			});
 
 			// Propagate cancellation from the parent Pi turn to the worker process.
 			if (signal) {
@@ -456,14 +585,23 @@ async function runWorker(
 		else if (stopReason && stopReason !== "stop") status = "incomplete";
 		else if (!finalOutput.trim()) status = "incomplete";
 
-		// Put failure context ahead of output emitted before the worker reached a completed state.
-		const partialOutput = finalOutput.trim();
+		// Put failure context and a synthetic checkpoint ahead of any partial worker report.
+		const streamedOutput = [...streamingText.entries()]
+			.sort(([left], [right]) => left - right)
+			.map(([, text]) => text)
+			.join("\n")
+			.trim();
+		const partialOutput = finalOutput.trim() || streamedOutput;
 		const stderrOutput = stderr.trim();
 		const statusDiagnostic =
 			status === "timeout"
-				? `Worker timed out after ${config.timeoutSeconds} seconds.`
+				? checkpointRequestedReason === "timeout" && exitCode === 0
+					? `Worker reached the time limit and returned a checkpoint during the ${config.checkpointGraceSeconds}-second grace period.`
+					: `Worker timed out after ${config.timeoutSeconds} seconds.`
 				: status === "turn_limit"
-					? `Worker reached the configured ${config.maxTurns}-turn limit.`
+					? checkpointRequestedReason === "turn_limit" && exitCode === 0
+						? `Worker reached the configured ${config.maxTurns}-turn limit and returned a checkpoint.`
+						: `Worker reached the configured ${config.maxTurns}-turn limit.`
 					: status === "aborted"
 						? "Worker was aborted."
 						: status === "process_error"
@@ -473,10 +611,22 @@ async function runWorker(
 								: `Worker did not complete${stopReason ? ` (stop reason: ${stopReason})` : ""}.`;
 		const diagnostic =
 			status === "completed" ? undefined : modelError || processError || stderrOutput || statusDiagnostic;
-		const output =
-			status !== "completed" && diagnostic
-				? `${diagnostic}${partialOutput ? `\n\n${partialOutput}` : ""}`
-				: partialOutput || stderrOutput || "The worker produced no final report.";
+		const checkpoint: WorkerCheckpoint | undefined =
+			status === "completed"
+				? undefined
+				: {
+						reason: status,
+						task,
+						lastAssistantText: partialOutput || undefined,
+						completedActivities: activity
+							.filter((item) => item.status !== "running")
+							.map((item) => `${item.status}: ${item.label}`),
+						activeActivities: activity.filter((item) => item.status === "running").map((item) => item.label),
+						filesystemEffectsMayRemain: activity.length > 0,
+					};
+		const output = checkpoint
+			? `${diagnostic ?? statusDiagnostic}\n\n${formatCheckpoint(checkpoint)}`
+			: partialOutput || stderrOutput || "The worker produced no final report.";
 		return {
 			output: truncate(output, RESULT_LIMIT),
 			details: {
@@ -484,7 +634,7 @@ async function runWorker(
 				status,
 				model: config.model,
 				thinking: config.thinking,
-				tools: config.tools,
+				tools,
 				turns,
 				durationMs: Date.now() - startedAt,
 				exitCode,
@@ -492,6 +642,7 @@ async function runWorker(
 				diagnostic,
 				stderr: stderrOutput || undefined,
 				activity,
+				checkpoint,
 			},
 			usage,
 		};
@@ -512,6 +663,20 @@ function validateModel(config: WorkerConfig, ctx: ExtensionToolContext): void {
 	}
 }
 
+/** Validate the exact per-delegation allowlist against tools active for the orchestrator. */
+function validateDelegatedTools(requested: string[], pi: ExtensionAPI): string[] {
+	const tools = [...new Set(requested.map((tool) => tool.trim()).filter(Boolean))];
+	const forbidden = new Set(["delegate_mechanical", "delegate_engineering"]);
+	const recursive = tools.filter((tool) => forbidden.has(tool));
+	if (recursive.length > 0) throw new Error(`Delegation tools cannot be delegated recursively: ${recursive.join(", ")}`);
+	const active = new Set(pi.getActiveTools());
+	const unavailable = tools.filter((tool) => !active.has(tool));
+	if (unavailable.length > 0) {
+		throw new Error(`Requested worker tools are not active for the main agent: ${unavailable.join(", ")}`);
+	}
+	return tools;
+}
+
 /** Register one role-specific public tool over the shared worker executor. */
 function registerDelegate(pi: ExtensionAPI, role: Role): void {
 	const toolName = role === "mechanic" ? "delegate_mechanical" : "delegate_engineering";
@@ -524,7 +689,9 @@ function registerDelegate(pi: ExtensionAPI, role: Role): void {
 			role === "mechanic"
 				? "Use delegate_mechanical for bounded multi-step execution with precise desired results; give it a self-contained contract and integrate its report."
 				: "Use delegate_engineering broadly for self-contained investigation or production work; give it the outcome, constraints, and acceptance conditions, then integrate its report.",
+			"Select the smallest exact worker tool allowlist from tools active for the main agent; tool availability does not establish scope or authorization.",
 			"Delegation results are worker reports, not proof of correctness; inspect material changes and retain responsibility for the final answer.",
+			"When a worker returns a checkpoint, inspect current state and decide whether to continue directly, delegate a bounded continuation with a newly selected tool allowlist, request user input, or stop with a limitation. Continuation is never automatic.",
 		],
 		parameters: DelegateParams,
 		exposure: "model-only",
@@ -538,9 +705,11 @@ function registerDelegate(pi: ExtensionAPI, role: Role): void {
 
 		async execute(_toolCallId, params, signal, onUpdate, ctx) {
 			let config: WorkerConfig;
+			let tools: string[];
 			try {
 				config = loadConfig()[role];
 				validateModel(config, ctx);
+				tools = validateDelegatedTools(params.tools, pi);
 			} catch (error) {
 				const message = error instanceof Error ? error.message : String(error);
 				return {
@@ -550,7 +719,7 @@ function registerDelegate(pi: ExtensionAPI, role: Role): void {
 						status: "configuration_error" as const,
 						model: "",
 						thinking: "off" as const,
-						tools: [],
+						tools: params.tools,
 						turns: 0,
 						durationMs: 0,
 						exitCode: null,
@@ -561,7 +730,7 @@ function registerDelegate(pi: ExtensionAPI, role: Role): void {
 				};
 			}
 
-			const result = await runWorker(role, params.task, config, ctx.cwd, signal, onUpdate);
+			const result = await runWorker(role, params.task, config, tools, ctx.cwd, signal, onUpdate);
 			const heading = `${role} worker ${result.details.status} via ${result.details.model} (${result.details.thinking})`;
 			return {
 				content: [{ type: "text", text: `${heading}\n\n${result.output}` }],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-task-dispatcher",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "Delegate bounded mechanical and engineering tasks to configurable Pi worker models.",
   "type": "module",
   "keywords": [