pi-subagents 0.52.0 → 0.52.1

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## [Unreleased]
 
+## [0.52.1] - 2026-08-20
+
+### Highlights
+- Model setup errors now point to the right alternate provider when there is one clear match.
+- Surf's optional `gpt-pro` package agent has a smoother path to run ChatGPT Pro web jobs through the external-job bridge when the user is logged in.
+- External-job providers can add metadata or extra operations without breaking provider discovery.
+- The packaged skill now includes a concise guide for coordinating multiple tasks, worktrees, and repositories.
+- Pi extension worktrees now have clearer guidance to avoid duplicate auto-loaded tools and shortcuts.
+
+### Fixed
+- Suggest the unique alternate provider model when an explicit qualified subagent model is unavailable, without resolving across providers. Thanks to [@lallenlowe](https://github.com/lallenlowe) for #1280.
+- Accept extra fields on registered external-job providers, such as `kind`, `wakeChannels`, or additional operations. This keeps integrations such as Surf's `gpt-pro` package agent from breaking provider discovery as they add browser-backed job metadata, while job payload validation stays strict.
+
+### Changed
+- Add a pi-subagents reference for coordinating multiple tasks, worktrees, and repositories, including guidance for keeping Pi extension worktrees outside auto-discovered extension directories.
+
 ## [0.52.0] - 2026-08-19
 
 ### Highlights

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents",
-  "version": "0.52.0",
+  "version": "0.52.1",
   "description": "Pi extension for single-agent delegation and scripted multi-agent workflows",
   "author": "Nico Bailon",
   "license": "MIT",

package/skills/pi-subagents/SKILL.md

@@ -22,6 +22,7 @@ Read the matching reference file before acting. Paths are relative to this `SKIL
 | --- | --- |
 | Decide whether to delegate, choose agents, compare tool versus slash commands, apply prompt techniques, or understand builtin roles | `references/prompting-and-roles.md` |
 | Run one-child, scripted, async, scheduled, mission-backed, forked, watchdog, oracle, or intercom-coordinated workflows | `references/execution-controls.md` |
+| Coordinate several independent tasks, worktrees, repositories, or writer lanes | `references/multi-lane-orchestration.md` |
 | List/create/update/delete/eject/disable agents, inspect legacy chain records, edit agent files, use prompt-template integration, or expose extension RPC | `references/management-authoring-rpc.md` |
 | Check safety constraints, best practices, standard workflows, or error handling | `references/constraints-and-recipes.md` |
 
@@ -30,6 +31,7 @@ For broad or uncertain requests, read more than one reference. For complex work,
 ## Always-on constraints
 
 - Keep the parent as orchestrator and final decision-maker.
+- Before multiple mutation-capable lanes, record a lane board and each lane's isolation path.
 - For plan, design, or architecture advice that asks to consult, discuss with, or come to agreement with `oracle`, use a short same-session consultation loop: read the first result, resume once with a targeted challenge when material tradeoffs remain, then synthesize the parent decision. Keep explicit one-shot, trivial, and fully settled consultations one-shot.
 - Use one writer per cwd/worktree unless isolated worktrees are intentional.
 - For cross-codebase work, record the target repo, explicit `cwd`, authority boundary, and expected output before launch. Do not assume the parent session cwd is the child repo.

package/skills/pi-subagents/references/multi-lane-orchestration.md

@@ -0,0 +1,39 @@
+# Multi-Lane Orchestration
+
+Use this reference when several independent tasks need coordinated workers, worktrees, or repositories. It defines lane ownership; use the other pi-subagents references for run controls, prompts, and mission details. The parent remains the final decision-maker.
+
+## Lane board and authority
+
+Before multiple mutation-capable lanes start, record this board in the parent context:
+
+`Lane | repo/cwd | exact decision | claimed files or contract | isolation path | authority | next gate | handoff | why independent`
+
+Record the isolation path before the first mutation. Do not split one source seam or decision into duplicate lanes. Make overlapping work one lane with one source of truth.
+
+For every lane, record the delivery target, allowed actions, required validation, and review rigor. For cross-repository work, name the shared contract and which repository changes first. A blocked decision is a lane state: record the owner, options, recommended default, and evidence needed to continue.
+
+## Partitioned runs
+
+Use one writer per repo/cwd or worktree. Mutation lanes need distinct isolation paths and explicit `cwd` values. Set `worktree: true` when a run needs managed worktree isolation within one repository. Read-only runs can share a checkout only when they cannot change state or create generated files.
+
+For Pi extension repositories, keep lane worktrees outside auto-discovered extension directories such as `~/.pi/agent/extensions`. A stale extension worktree there can auto-load duplicate tools and shortcuts. Remove or move it only after its handoff is durable, the worktree is clean, and no run owns it.
+
+Partition fanout by repository, source seam, decision, or review angle. Each run needs a stable key, lane-specific task, and durable output path. Do not launch prompts that differ only by item name or broad file glob.
+
+Use one async `workflowScript` for a coordinated wave. Use `runs.all` for independent lanes and `runs.run` for dependent lane stages. Give cross-repository runs explicit `cwd` values and lane-qualified outputs. Use `outputMode: "file-only"` when a report must survive the run or feed a later stage.
+
+## Keep independent work moving
+
+While one lane waits, run safe independent preparation, validation, or fresh read-only review lanes. Do not block the parent just because a run is active. If no safe lane remains, record the blocker and the event that will reopen work.
+
+An ordinary coordinated workflow has one mission. Use its durable state, artifacts, run records, and receipts for recovery. Treat a receipt as evidence, not as authority or acceptance.
+
+After a writer produces a candidate, run the required fresh-context, read-only reviewer. The reviewer inspects the exact worktree and returns evidence-backed findings. The parent decides which findings are in scope and whether the lane is ready. Send accepted fixes to that lane's sole writer, then rerun only the affected gate.
+
+## Handoff, cleanup, and recovery
+
+Use stable lane-qualified paths for reports and review output. A handoff states the lane status, repository and worktree, changed files, validation, open decisions, next action, and artifact or receipt paths.
+
+Keep a worktree until its handoff is durable, no run owns it, and no later gate needs it. Clean up only inside the recorded authority boundary. If a run stops or needs attention, preserve its worktree and artifacts, record the last known state and recovery owner, then resume that run or create one replacement lane from the handoff. Do not start another writer while worktree ownership is uncertain.
+
+Before completion, inspect the board. Every lane must be terminal or blocked with a named next action. Confirm one writer per repo/cwd or worktree, required validation, required fresh read-only review, and a durable handoff. The parent reports outcomes, evidence, residual risks, and the next decision.

package/src/api/external-job-provider.ts

@@ -146,8 +146,9 @@ export function validateExternalJobResult(provider: string, value: unknown, fiel
 function validateProvider(value: unknown): ExternalJobProvider {
 	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("External-job provider must be an object.");
 	const provider = value as Record<string, unknown>;
-	const unknownFields = Object.keys(provider).filter((key) => !["name", "start", "status", "result", "reattach"].includes(key));
-	if (unknownFields.length > 0) throw new Error(`External-job provider has unknown fields: ${unknownFields.join(", ")}.`);
+	// Tolerate extra provider fields (for example kind, wakeChannels, or future
+	// operations) so one evolving provider cannot poison registry reads for all
+	// providers. Payload validation stays strict.
 	const name = validateString(provider.name, "External-job provider name", MAX_PROVIDER_NAME_LENGTH);
 	for (const op of ["start", "status", "result", "reattach"] as const) {
 		if (typeof provider[op] !== "function") throw new Error(`External-job provider '${name}' must expose ${op}().`);

package/src/extension/schemas.ts

@@ -341,7 +341,7 @@ const SubagentParamProperties = {
 	})),
 	outputMode: Type.Optional(OutputModeOverride),
 	skill: Type.Optional(SkillOverride),
-	model: Type.Optional(Type.String({ description: "Default child model override (e.g. 'anthropic/claude-sonnet-4')" })),
+	model: Type.Optional(Type.String({ description: "Default child model override. Full provider/id values are accepted; bare ids resolve from the active registry." })),
 	outputSchema: Type.Optional(JsonSchemaObject),
 	agentContract: Type.Optional(AgentContractOverride),
 	acceptance: Type.Optional(AcceptanceOverride),

package/src/runs/shared/model-fallback.ts

@@ -205,6 +205,21 @@ function resolveSubagentModelCandidate(
 	return resolvedBase ? `${resolvedBase}${thinkingSuffix}` : undefined;
 }
 
+function suggestAlternateProviderModel(
+	model: string,
+	availableModels: AvailableModelInfo[] | undefined,
+): string | undefined {
+	if (!availableModels || availableModels.length === 0) return undefined;
+	const { baseModel, thinkingSuffix } = splitThinkingSuffix(model);
+	const { queryProvider, queryIdRaw } = splitQualifiedModelQuery(baseModel, availableModels);
+	if (queryProvider === undefined) return undefined;
+	const suggestion = resolveBaseModelCandidate(queryIdRaw, availableModels);
+	if (!suggestion) return undefined;
+	const matched = availableModels.find((entry) => entry.fullId === suggestion);
+	if (!matched || normalizeModelSegment(matched.provider) === queryProvider) return undefined;
+	return `${suggestion}${thinkingSuffix}`;
+}
+
 function resolveRequiredSubagentModelCandidate(
 	model: string,
 	availableModels: AvailableModelInfo[] | undefined,
@@ -212,7 +227,10 @@ function resolveRequiredSubagentModelCandidate(
 ): string {
 	const resolved = resolveSubagentModelCandidate(model, availableModels, preferredProvider);
 	if (resolved) return resolved;
-	throw new Error(`Unknown subagent model '${model}' in the active Pi model registry.`);
+	const suggestion = suggestAlternateProviderModel(model, availableModels);
+	throw new Error(
+		`Unknown subagent model '${model}' in the active Pi model registry.${suggestion ? ` Did you mean '${suggestion}'?` : ""}`,
+	);
 }
 
 export interface ResolveSubagentModelOverrideOptions {