@hcflabs/pi-subagent 27.10.8 → 27.11.0

package/CONTEXT.md

@@ -29,7 +29,7 @@ A display and continuation reference for one recorded direct worker, such as `D7
 A new direct worker that resumes a finished worker's saved Pi conversation in a new tab with a new Direct reference.
 
 **Checkout admission**:
-The exclusive permission held by a direct write request that prevents Main and other direct writers from writing to the shared checkout. It remains held until worker termination is proven; read classification is not a sandbox.
+The exclusive permission held by a direct write request that prevents Main and other direct writers from writing to the shared checkout. A request with Repository targets holds the checkout of each target. From a non-Git parent directory, a Main call that can write covers the checkout of every Repository target in it. It remains held until worker termination is proven; read classification is not a sandbox.
 
 **Isolated request**:
 A durable goal and dependency graph of text and changeset tasks, with checked results and recovery state.

package/README.md

@@ -35,6 +35,7 @@ Commands, prompts, and UI are for you. Tools and the packaged skill are for Main
 | `/review [target] [focus]` | prompt | Tell Main to review a change with parallel `reviewer` tasks and give one ship verdict. See [Review a change](#review-a-change). |
 | `/subagent recover` | command | Classify interrupted isolated work in the canonical repository. Send Main request IDs, blockers, and next actions. Requires no UI or Herdr pane. |
 | `delegate_task` | tool | Start authorized shared-checkout work or a durable isolated checked graph. With `dryRun: true`, check the request and show the resolved plan without a launch. |
+| `subagent_repos` | tool | List the child Git repositories below the Pi working directory and the `repo` selector of each. Read-only. |
 | `subagent_status` | tool | Read saved isolated state, exact identities, failed review verdicts, and allowed continuation. Does not replay work. Supports structured output for `codemode`. |
 | `subagent_resume` | tool | Perform the reported `retry`, `verify`, or `finalize` continuation, not staging or integration. Same-worker correction retries accept optional `instruction` text. |
 | `subagent_stage` | tool | Stage, resolve, reject, or revise an exact candidate. Rejecting a staged candidate freezes its generation. |
@@ -95,7 +96,21 @@ A task packet above 64 KiB uses a private file, including the full previous answ
 
 Pi's `read` can retrieve lines of at most 50 KiB (51,200 bytes), with line offsets for more content. If any line is longer, the worker uses `bash`, even when the Role also has `read`. Without `bash`, that task fails before tab creation; use shorter lines or a Role with `bash`. A Role with neither tool also fails before tab creation. Chain context is never cut to the inline answer budget.
 
-To continue a finished worker, add `"continueFrom": "D7.1"` with the same `role`. This opens a new tab with the saved conversation and a new reference. Continue the newest reference from the original checkout and workspace. For eligibility and stop behavior, see [Continue or stop one direct worker](./docs/orchestration.md#continue-or-stop-one-direct-worker).
+### Repository targets
+
+When Pi runs in a parent directory that holds many repositories, set `repo` to select a child repository for a direct task. Use `subagent_repos` to list the selectors. Set `repo` on the request to apply it to all tasks, or on one task to override the request value:
+
+```json
+{ "mode": "direct", "repo": "team/service", "role": "scout", "name": "Map sign-in", "task": "Trace sign-in.", "access": "read" }
+```
+
+`repo` is a path relative to the Pi working directory. It must be a Git top-level directory, must not contain `..`, and must not resolve outside that directory. A subdirectory of a repository fails. No tool selects a child repository automatically.
+
+The worker opens in the current Herdr workspace with the Repository target as its working directory. Change reports and stale-read checks use that checkout, and each result names its `repo`. A write request reserves the checkout of each target at one time, so writers in different repositories can run together. When Pi runs in a parent directory that is not a Git repository, each Main call that can write covers the whole parent. Such a call waits while a direct writer owns the checkout of any Repository target in it. Main can still read files and use `subagent_repos`.
+
+Isolated mode does not accept `repo` yet.
+
+To continue a finished worker, add `"continueFrom": "D7.1"` with the same `role`. This opens a new tab with the saved conversation and a new reference. Continue the newest reference from the original checkout and workspace. For a worker that ran with `repo`, select the same `repo`. For eligibility and stop behavior, see [Continue or stop one direct worker](./docs/orchestration.md#continue-or-stop-one-direct-worker).
 
 ### Review a change
 

package/docs/orchestration.md

@@ -93,6 +93,8 @@ For example, a configured Git operator with `bash` can stage named pending files
 
 Direct writes change Main's checkout immediately. They require no clean checkout. They give no automatic checks, rollback, or isolated integration guarantee. A write request cannot start while a direct writer owns the checkout. It also cannot start while a Main call that can write is in progress there.
 
+A task with `repo` runs in that Repository target instead of Main's checkout. Admission resolves the target before the launch and reserves the checkout of each target at one time. Two checkouts conflict when one contains the other. Thus a Main call from a non-Git parent directory covers the checkout of every Repository target in it, and writers in two different Repository targets can run together. An invalid `repo` blocks the call before any reservation. Admission does not parse Bash text for a directory.
+
 A write request runs its tasks in sequence. It holds checkout admission after the initial handle returns. Competing direct writers and Main writes fail until the extension proves that all owned workers stopped. To keep Main free to write, use `mode: isolated`. This mode gives worktree checks and explicit integration, not immediate changes to the shared checkout. Parallel read requests still run concurrently.
 
 A failure in a write request stops further dispatch, but a worker with an uncertain state can still run. Chains replace each literal `{previous}` with the preceding successful answer and stop on failure. Task outcome and worker termination are separate.

package/extensions/admission.ts

@@ -1,12 +1,20 @@
 import { realpath } from "node:fs/promises";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { isWithin, resolveRepoTarget } from "@hcflabs/pi-repo";
 
 // Main's own tools that never change a checkout; every other Main call may write.
 // `codemode` mutates nothing itself: its nested tool calls are admitted by their own names.
 const MAIN_NON_WRITING_TOOLS = new Set([
-	"read", "grep", "find", "ffgrep", "fffind", "ls", "codegraph_explore", "subagent_status", "codemode",
+	"read", "grep", "find", "ffgrep", "fffind", "ls", "codegraph_explore", "subagent_status", "subagent_repos", "codemode",
 ]);
 
+/**
+ * Classification of a `delegate_task` call. `false` means the call does not write.
+ * `true` means a writer in the Pi working directory. A list names the Repository target of each task.
+ * `undefined` in the list means the Pi working directory.
+ */
+export type DirectAdmission = boolean | ReadonlyArray<string | undefined>;
+
 async function checkoutKey(pi: ExtensionAPI, ctx: ExtensionContext): Promise<string> {
 	const cwd = await realpath(ctx.cwd);
 	const result = await pi.exec("git", ["rev-parse", "--show-toplevel"], { cwd, timeout: 5_000 });
@@ -16,15 +24,23 @@ async function checkoutKey(pi: ExtensionAPI, ctx: ExtensionContext): Promise<str
 	return await realpath(root);
 }
 
+/** Two scopes conflict when one contains the other. A non-Git parent directory covers its whole subtree. */
+const overlaps = (left: string, right: string) => isWithin(left, right) || isWithin(right, left);
+
 /**
  * Reserve checkouts only for direct writers. Main writes can run together, but
- * each call must finish before a direct writer can start in that checkout.
+ * each call must finish before a direct writer can start in an overlapping checkout.
+ * A direct writer reserves the checkout of each task target at one time.
  * External processes and trusted extension lifecycle code are not intercepted.
  */
-export function registerCheckoutAdmission(pi: ExtensionAPI, directCanWrite: (input: unknown) => boolean): (toolCallId: string) => () => void {
+export type CheckoutAdmission = ((toolCallId: string) => () => void) & {
+	/** The real checkout paths that admission reserved for a direct writer call. */
+	admitted(toolCallId: string): readonly string[] | undefined;
+};
+
+export function registerCheckoutAdmission(pi: ExtensionAPI, classifyDirect: (input: unknown) => DirectAdmission): CheckoutAdmission {
 	const heldCalls = new Set<string>();
-	const ownerByCheckout = new Map<string, string>();
-	const calls = new Map<string, { direct: boolean; key?: string }>();
+	const calls = new Map<string, { direct: boolean; keys?: readonly string[] }>();
 	// One Git lookup per working directory per session; a failed lookup is retried.
 	const checkouts = new Map<string, Promise<string>>();
 	const lookup = (ctx: ExtensionContext) => {
@@ -35,32 +51,49 @@ export function registerCheckoutAdmission(pi: ExtensionAPI, directCanWrite: (inp
 		key.catch(() => { if (checkouts.get(ctx.cwd) === key) checkouts.delete(ctx.cwd); });
 		return key;
 	};
+	const targetKey = async (ctx: ExtensionContext, repo: string | undefined) => {
+		if (repo === undefined) return await lookup(ctx);
+		const target = await resolveRepoTarget(ctx.cwd, repo, {
+			runProcess: (command, args, options) => pi.exec(command, args, { cwd: options.cwd, timeout: options.timeoutMs ?? undefined, ...(options.signal ? { signal: options.signal } : {}) }),
+		});
+		return target.root;
+	};
 	const release = (toolCallId: string) => {
 		if (heldCalls.has(toolCallId)) return;
-		const call = calls.get(toolCallId);
 		calls.delete(toolCallId);
-		if (call?.key && ownerByCheckout.get(call.key) === toolCallId) ownerByCheckout.delete(call.key);
 	};
 	pi.on("tool_call", async (event, ctx) => {
 		const direct = event.toolName === "delegate_task";
-		if (direct ? !directCanWrite(event.input) : MAIN_NON_WRITING_TOOLS.has(event.toolName)) return;
-		const call: { direct: boolean; key?: string } = { direct };
+		const classified = direct ? classifyDirect(event.input) : !MAIN_NON_WRITING_TOOLS.has(event.toolName);
+		if (classified === false) return;
+		const repos: ReadonlyArray<string | undefined> = classified === true ? [undefined] : classified;
+		const call: { direct: boolean; keys?: readonly string[] } = { direct };
 		calls.set(event.toolCallId, call);
-		const key = await lookup(ctx);
+		let keys: string[];
+		try {
+			keys = [...new Set(await Promise.all(repos.map((repo) => targetKey(ctx, repo))))];
+		} catch (error) {
+			release(event.toolCallId);
+			if (!direct || repos.every((repo) => repo === undefined)) throw error;
+			return { block: true, reason: `Repository target check failed: ${error instanceof Error ? error.message : String(error)}` };
+		}
 		if (calls.get(event.toolCallId) !== call) {
 			return { block: true, reason: `Call ${event.toolCallId} already settled; use mode: isolated to keep Main free.` };
 		}
-		const owner = ownerByCheckout.get(key);
-		const main = direct ? [...calls].find(([, active]) => !active.direct && active.key === key)?.[0] : undefined;
-		if (owner || main) {
+		// A direct writer conflicts with every overlapping call. A Main call conflicts only with a direct writer.
+		const conflict = [...calls].find(([id, active]) => id !== event.toolCallId && active.keys
+			&& (direct || active.direct)
+			&& active.keys.some((held) => keys.some((key) => overlaps(held, key))));
+		if (conflict) {
+			const [owner, active] = conflict;
+			const key = active.keys!.find((held) => keys.some((candidate) => overlaps(held, candidate)))!;
 			release(event.toolCallId);
 			return {
 				block: true,
-				reason: `Checkout ${key} has ${owner ? `an admitted direct writer (${owner})` : `a Main potentially-writing call in flight (${main})`}; retry after it stops, or use mode: isolated to keep Main free.`,
+				reason: `Checkout ${key} has ${active.direct ? `an admitted direct writer (${owner})` : `a Main potentially-writing call in flight (${owner})`}; retry after it stops, or use mode: isolated to keep Main free.`,
 			};
 		}
-		call.key = key;
-		if (direct) ownerByCheckout.set(key, event.toolCallId);
+		call.keys = keys;
 	});
 	pi.on("tool_result", (event) => release(event.toolCallId));
 	pi.on("tool_execution_end", (event) => release(event.toolCallId));
@@ -71,12 +104,18 @@ export function registerCheckoutAdmission(pi: ExtensionAPI, directCanWrite: (inp
 		for (const toolCallId of calls.keys()) release(toolCallId);
 	});
 	// The tool returns a handle before its worker stops. Release only after verified termination.
-	return (toolCallId) => {
+	const hold = (toolCallId: string) => {
 		const call = calls.get(toolCallId);
-		if (!call?.direct || !call.key) {
+		if (!call?.direct || !call.keys) {
 			throw new Error(`Direct call ${toolCallId} was not admitted as a checkout writer; delegate again.`);
 		}
 		heldCalls.add(toolCallId);
 		return () => { heldCalls.delete(toolCallId); release(toolCallId); };
 	};
+	return Object.assign(hold, {
+		admitted: (toolCallId: string) => {
+			const call = calls.get(toolCallId);
+			return call?.direct ? call.keys : undefined;
+		},
+	});
 }

package/extensions/repos.ts

@@ -0,0 +1,40 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { discoverRepos } from "@hcflabs/pi-repo";
+import { Type } from "typebox";
+
+const OUTPUT_REPOS = 200;
+
+const Parameters = Type.Object({
+	path: Type.Optional(Type.String({ minLength: 1, description: "Directory to search, relative to the Pi working directory. The default is the Pi working directory." })),
+	maxDepth: Type.Optional(Type.Integer({ minimum: 1, maximum: 8, description: "Directory levels to search below path. The default is 3." })),
+	limit: Type.Optional(Type.Integer({ minimum: 1, maximum: OUTPUT_REPOS, description: `Maximum repositories to return. The default is ${OUTPUT_REPOS}.` })),
+}, { additionalProperties: false });
+
+/** Register the read-only `subagent_repos` tool. It lists child repositories and the `repo` selector for each. */
+export function registerRepoDiscovery(pi: ExtensionAPI): void {
+	pi.registerTool({
+		name: "subagent_repos",
+		label: "Subagent Repos",
+		description: "List the child Git repositories below the Pi working directory, with the repo selector that delegate_task accepts. The tool changes no files and no Git state. It does not follow symlinks and does not search inside a repository.",
+		promptSnippet: "List child Git repositories and their repo selectors for delegate_task",
+		promptGuidelines: [
+			"When the Pi working directory holds several repositories, use subagent_repos to find the repo selector, then set repo on delegate_task. Never guess a selector, and never select a repository the user did not name or authorize.",
+		],
+		parameters: Parameters,
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			const found = await discoverRepos(ctx.cwd, {
+				...(params.path === undefined ? {} : { path: params.path }),
+				...(params.maxDepth === undefined ? {} : { maxDepth: params.maxDepth }),
+				limit: params.limit ?? OUTPUT_REPOS,
+				...(signal ? { signal } : {}),
+			});
+			const lines = [
+				`${found.repos.length} repositories below ${found.base}${found.truncated ? " (truncated: a limit stopped the search)" : ""}.`,
+				...found.repos.map(({ repo, linkedWorktree }) => `${repo}${linkedWorktree ? " (linked worktree)" : ""}`),
+				...(found.issues.length ? ["Issues:", ...found.issues.slice(0, 20).map(({ path, reason }) => `${path}: ${reason}`)] : []),
+				...(found.issues.length > 20 ? [`${found.issues.length - 20} more issues omitted.`] : []),
+			];
+			return { content: [{ type: "text" as const, text: lines.join("\n") }], details: found };
+		},
+	});
+}

package/extensions/subagent.ts

@@ -3,14 +3,16 @@ import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-c
 import { type Component, Text, type TUI, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import { availableTaskModels, loadTaskModelsConfig, modelReference, type ProfileName, registerModelTask, registerTaskModelsConfigReporting, resolveAvailableModel, resolveConfiguredTaskRoute, type ResolvedTaskRoute, taskThinkingLevels } from "@hcflabs/pi-task-models";
 import { registerConfigReporting } from "@hcflabs/pi-config-store";
+import { resolveRepoTarget } from "@hcflabs/pi-repo";
 import { capEphemeralSubagentOutput as capOutput, createEphemeralSubagentExecutor, createSubagentConfigStore, DEFAULT_SUBAGENT_CONFIG, DELEGATE_TASK, findRole, formatDuration, loadRoleCatalog, prepareRoleLaunch, resolveRolePackageResources, resolveTaskRoute, ROLE_TOOL_POLICY_FLAG, type ExecutionPolicySnapshot, type Role } from "@hcflabs/pi-subagent";
 import { resolveExecutionPolicy } from "./config.ts";
 import { registerCheckoutAdmission } from "./admission.ts";
 import { registerIsolatedExtension } from "./isolated.ts";
+import { registerRepoDiscovery } from "./repos.ts";
 import { directRef, registerSubagentCommand, type DirectDisplay, type DirectTask } from "./subagent-command.ts";
 import { MODEL_CLASS_GUIDANCE } from "./model-class-policy.ts";
 import { compactCost, compactTokens, ENTRY_STATUS_PRESENTATION, formatWorkflowResult, workerOutputForMain, type BackgroundWorkflowTransportDetails, type WorkflowTransportEntry } from "./result-transport.ts";
-import { checkoutNote, DelegateTaskParameters, identifyWorkflowEntries, parseDelegateTask, runForegroundWorkflow, snapshotCheckout, writesCheckout, type CheckoutSnapshot, type ParsedWorkflow, type WorkflowEntry } from "./workflow.ts";
+import { checkoutNote, DelegateTaskParameters, identifyWorkflowEntries, parseDelegateTask, runForegroundWorkflow, snapshotCheckout, workflowRepos, writesCheckout, type CheckoutSnapshot, type ParsedWorkflow, type WorkflowEntry } from "./workflow.ts";
 import { assertSettledDirectSession, createDirectHerdr, DirectAllocationError, directTaskReader, type DirectAllocation, type DirectHandle, type DirectTab, type DirectToolActivity, type DirectUsage } from "../dist/direct-herdr.js";
 import { materializeTransientLaunch } from "../dist/launch-runtime.js";
 const WIDGET_KEY = "subagent-status";
@@ -223,15 +225,17 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 		reportConfig(ctx);
 		currentPolicy();
 	};
-	const canWrite = (input: unknown): boolean => {
+	/** A direct writer reserves the checkout of each task target. An unparsable call is a writer in the Pi working directory. */
+	const classifyDirect = (input: unknown): boolean | Array<string | undefined> => {
 		try {
 			const parsed = parseDelegateTask(input);
-			return parsed.mode === "direct" && !parsed.dryRun && writesCheckout(parsed.workflow);
+			return parsed.mode === "direct" && !parsed.dryRun && writesCheckout(parsed.workflow) && workflowRepos(parsed.workflow);
 		} catch {
 			return true;
 		}
 	};
-	const holdAdmission = registerCheckoutAdmission(pi, canWrite);
+	const holdAdmission = registerCheckoutAdmission(pi, classifyDirect);
+	registerRepoDiscovery(pi);
 	/** Resolve a Role's package resources and route for a direct Herdr launch. */
 	const prepareDirectLaunch = async (role: Role, context: ExtensionContext, options: { modelClass?: ProfileName; model?: string }) => {
 		const resources = await resolveRolePackageResources(role, context);
@@ -634,7 +638,7 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 	};
 
 	/** Dry run of a direct launch: the same checks, then a bounded plan; no tab, record, admission, or follow-up. */
-	const planDirect = async (workflow: ParsedWorkflow, sources: ReadonlyMap<number, DirectTabRecord & { turn: string }>, cwd: string, ctx: ExtensionContext) => {
+	const planDirect = async (workflow: ParsedWorkflow, sources: ReadonlyMap<number, DirectTabRecord & { turn: string }>, cwd: string, targets: readonly string[], ctx: ExtensionContext) => {
 		for (const [index, source] of sources) {
 			try { await assertSettledDirectSession(source.sessionFile, source.turn); } catch (error) {
 				throw boundedError(new Error(`Cannot continue ${workflow.delegations[index]!.continueFrom}: ${error instanceof Error ? error.message : String(error)}.`, { cause: error }));
@@ -652,6 +656,7 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 				directTaskReader(workflow.mode === "chain" ? delegation.task.replaceAll("{previous}", "") : delegation.task, prepared.tools);
 			} catch (error) { throw boundedError(error); }
 			entries.push({ index, name, role, access, model: modelReference(prepared.model), thinkingLevel: prepared.thinkingLevel,
+				...(delegation.repo === undefined ? {} : { repo: delegation.repo, cwd: targets[index]! }),
 				...(continueFrom === undefined ? {} : { continueFrom }), ...(workflow.mode === "chain" && index ? { after: index } : {}) });
 		}
 		const writes = writesCheckout(workflow);
@@ -663,8 +668,8 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 		];
 		const text = [
 			`Dry run passed: direct ${workflow.mode} request with ${entries.length} task(s) in ${cwd}. No Herdr tab, session record, checkout admission, or follow-up was created.`,
-			...entries.map((entry) => `${entry.index + 1}. ${entry.name} · ${entry.role} · ${entry.model} · thinking ${entry.thinkingLevel} · access ${entry.access}${entry.access === "write" ? " (JSON completion required)" : ""}${entry.after ? ` · after ${entry.after}` : ""}${entry.continueFrom ? ` · continues ${entry.continueFrom}` : ""}`),
-			writes ? "Write request: tasks would run serially and reserve this checkout until owned workers are proved stopped."
+			...entries.map((entry) => `${entry.index + 1}. ${entry.name} · ${entry.role} · ${entry.model} · thinking ${entry.thinkingLevel} · access ${entry.access}${entry.access === "write" ? " (JSON completion required)" : ""}${entry.repo ? ` · repo ${entry.repo} (${entry.cwd})` : ""}${entry.after ? ` · after ${entry.after}` : ""}${entry.continueFrom ? ` · continues ${entry.continueFrom}` : ""}`),
+			writes ? `Write request: tasks would run serially and reserve ${new Set(targets).size > 1 ? "each target checkout" : "this checkout"} until owned workers are proved stopped.`
 				: "Read request: tasks would run concurrently without checkout admission.",
 			...notChecked.map((reason) => `Not checked: ${reason}.`),
 		].join("\n");
@@ -720,7 +725,25 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 			const branchTabs = ctx.sessionManager.getBranch().flatMap((entry) =>
 				entry.type === "custom" && entry.customType === DIRECT_TAB_TYPE && entry.data ? [entry.data as DirectTabRecord] : []);
 			const policy = currentPolicy();
-			const herdr = createDirectHerdr(pi, ctx.cwd, policy.childIdleMs);
+			// Resolve each Repository target before continuation checks, admission evidence, or Herdr calls.
+			const targets: string[] = [];
+			for (const [index, { repo }] of workflow.delegations.entries()) {
+				if (repo === undefined) { targets.push(ctx.cwd); continue; }
+				try {
+					targets.push((await resolveRepoTarget(ctx.cwd, repo, signal ? { signal } : {})).root);
+				} catch (error) {
+					throw boundedError(new Error(`Task ${index + 1} repo ${repo}: ${error instanceof Error ? error.message : String(error)}`, { cause: error }));
+				}
+			}
+			// Workers open in the caller's Herdr workspace with the target as their working directory.
+			const herdrByCwd = new Map<string, ReturnType<typeof createDirectHerdr>>();
+			const herdrFor = (cwd: string) => {
+				let client = herdrByCwd.get(cwd);
+				if (!client) herdrByCwd.set(cwd, client = createDirectHerdr(pi, cwd, policy.childIdleMs));
+				return client;
+			};
+			const herdr = herdrFor(ctx.cwd);
+			const entryCwd = (index: number) => herdrFor(targets[index]!).cwd;
 			const sources = new Map<number, DirectTabRecord & { turn: string }>();
 			for (const [index, { continueFrom, role }] of workflow.delegations.entries()) {
 				if (continueFrom === undefined) continue;
@@ -731,27 +754,28 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 				const source = matches[0]!;
 				if (source.display!.role !== role) throw refuse(`it ran with Role ${source.display!.role}, not ${role}; use the recorded Role`);
 				if (source.turn === undefined) throw refuse("its record has no turn identity (saved by an older pi-subagent), so it is not continuable; start a fresh task");
-				if (source.workspaceId !== herdr.workspaceId || source.cwd !== herdr.cwd) {
-					throw refuse(`it ran in ${source.cwd ?? "an unrecorded checkout"} (Herdr workspace ${source.workspaceId ?? "unrecorded"}), not this checkout and workspace; start a fresh task here`);
+				const target = herdrFor(targets[index]!);
+				if (source.workspaceId !== target.workspaceId || source.cwd !== target.cwd) {
+					throw refuse(`it ran in ${source.cwd ?? "an unrecorded checkout"} (Herdr workspace ${source.workspaceId ?? "unrecorded"}), not in ${target.cwd} and this workspace; select the repo where it ran, or start a fresh task`);
 				}
 				if ([...directTasks.values()].some(({ tabs, continues }) => continues?.has(source.sessionFile)
 					|| tabs.some(({ sessionFile }) => sessionFile === source.sessionFile))) throw refuse("a locally active direct task still owns its session");
 				if ([...sources.values()].some(({ sessionFile }) => sessionFile === source.sessionFile)) throw refuse("this request already continues its session");
 				sources.set(index, { ...source, turn: source.turn });
 			}
-			if (parsed.dryRun) return await planDirect(workflow, sources, herdr.cwd, latestCtx ?? ctx);
+			if (parsed.dryRun) return await planDirect(workflow, sources, herdr.cwd, workflow.delegations.map((_, index) => entryCwd(index)), latestCtx ?? ctx);
 			const writes = writesCheckout(workflow);
 			const entries = identifyWorkflowEntries(toolCallId, workflow);
 			const states = new Map<string, WorkflowTransportEntry>(entries.map(({ id, index, delegation }) => [id, {
 				id, index, role: delegation.role, status: "pending",
-				name: delegation.continueFrom === undefined ? delegation.name : `${delegation.name} (continued from ${delegation.continueFrom})`,
+				name: `${delegation.continueFrom === undefined ? delegation.name : `${delegation.name} (continued from ${delegation.continueFrom})`}${delegation.repo === undefined ? "" : ` · repo ${delegation.repo}`}`,
 			}]));
 			const startedAt = new Map<string, number>();
 			// Launch snapshots: write requests report changes; read requests detect a stale checkout.
 			const snapshots = new Map<string, CheckoutSnapshot | Error | undefined>();
-			const checkout = async ({ id, delegation }: WorkflowEntry) => {
+			const checkout = async ({ id, index, delegation }: WorkflowEntry) => {
 				if (!snapshots.has(id)) return {};
-				const note = await checkoutNote(ctx.cwd, snapshots.get(id), writes, delegation.paths);
+				const note = await checkoutNote(entryCwd(index), snapshots.get(id), writes, delegation.paths);
 				return note ? { checkout: note } : {};
 			};
 			const measured = (id: string, usage: DirectUsage | undefined) => ({
@@ -780,6 +804,16 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 			const settled = new Promise<void>((resolve) => { resolveSettled = resolve; });
 			// Register before Herdr can create a tab: session switches must await this
 			// launch, including its identity callback, before copying recovery records.
+			if (writes) {
+				// A selector can point somewhere else after admission resolved it, for example through a symlink.
+				// Launch only in the exact checkouts that admission reserved.
+				const admitted = holdAdmission.admitted(toolCallId) ?? [];
+				for (const [index, { repo }] of workflow.delegations.entries()) {
+					if (repo !== undefined && !admitted.includes(targets[index]!)) {
+						throw boundedError(new Error(`Task ${index + 1} repo ${repo} resolves to ${targets[index]}, which admission did not reserve (${admitted.join(", ") || "none"}). The target changed after admission; delegate again.`));
+					}
+				}
+			}
 			const releaseAdmission = writes ? holdAdmission(toolCallId) : () => {};
 			const local: NonNullable<ReturnType<typeof directTasks.get>> = { controller, settled, handles, tabs,
 				continues: new Set([...sources.values()].map(({ sessionFile }) => sessionFile)) };
@@ -795,7 +829,7 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 					const proof = (async () => {
 						entryControllers.get(entryId)!.abort();
 						await handle.cancel().catch(() => undefined);
-						await herdr.stop(tab, inScope);
+						await herdrFor(tab.cwd ?? ctx.cwd).stop(tab, inScope);
 					})();
 					stopProofs.set(entryId, proof);
 					return proof;
@@ -805,7 +839,7 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 				const inScope = () => current() && (local.closeScope?.() ?? true);
 				try {
 					if (local.allocation) throw new Error(local.allocation.failure);
-					for (const tab of tabs) await herdr.stop(tab, inScope);
+					for (const tab of tabs) await herdrFor(tab.cwd ?? ctx.cwd).stop(tab, inScope);
 					if (!inScope()) throw new Error("Direct task scope changed; reopen /subagent.");
 					releaseAdmission();
 					directTasks.delete(taskId);
@@ -831,10 +865,10 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 				startWidgetItem(entry.id, taskId, display, prepared.model.id, prepared.thinkingLevel, ctx);
 				const transient = await materializeTransientLaunch({ launch: prepared, prompt: prepared.systemPrompt,
 					promptArgIndex: prepared.promptArgIndex }, activeSignal);
-				snapshots.set(entry.id, await snapshotCheckout(ctx.cwd).catch((error: unknown) => error instanceof Error ? error : new Error(String(error))));
+				snapshots.set(entry.id, await snapshotCheckout(entryCwd(entry.index)).catch((error: unknown) => error instanceof Error ? error : new Error(String(error))));
 				let handle: DirectHandle;
 				try {
-					handle = await herdr.start({ ...prepared, args: [...transient.launch.args] },
+					handle = await herdrFor(targets[entry.index]!).start({ ...prepared, args: [...transient.launch.args] },
 						`d-${randomUUID().replaceAll("-", "").slice(0, 24)}`, `${directRef(display)} ${display.title}`,
 						`${entry.delegation.access === "read" ? `${entry.delegation.task}\n\n${READ_ACCESS_NOTICE}` : entry.delegation.task}\n\nFinal answer budget: ${answerBytes} bytes, conclusions first. Main sees only that much inline; a longer answer is saved to a file.`, activeSignal, (tab) => {
 							const record = { taskId, entryId: entry.id, display, ...tab };
@@ -867,7 +901,7 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 					try {
 						await assertSettledDirectSession(source.sessionFile, source.turn);
 						// Close only an idle or done exact agent; an absent one still needs two empty lease scans.
-						await herdr.stop(source, () => launchEpoch === sessionEpoch && !controller.signal.aborted, true);
+						await herdrFor(targets[index]!).stop(source, () => launchEpoch === sessionEpoch && !controller.signal.aborted, true);
 					} catch (error) {
 						throw new Error(`Cannot continue ${workflow.delegations[index]!.continueFrom}: ${error instanceof Error ? error.message : String(error)}.`, { cause: error });
 					}

package/extensions/workflow.ts

@@ -33,6 +33,11 @@ const AccessSchema = StringEnum(DIRECT_ACCESS, { description: ACCESS_GUIDANCE })
 const DryRunSchema = Type.Boolean({ description: "Optional. When true, run every launch validation and return the resolved plan without starting workers, saving state, or reserving the checkout." });
 const ContinueFromSchema = Type.String({ pattern: "^D[1-9][0-9]*\\.[1-9][0-9]*$", description: "Optional direct worker reference such as D7.1. Continues that finished worker's Pi session in a new tab with this task; role must equal the recorded Role." });
 
+const RepoSchema = Type.String({
+	minLength: 1,
+	description: "Optional Repository target: a child Git repository as a path relative to the Pi working directory, such as team/service. The worker runs there, and admission reserves that checkout. A task value overrides the request value. Omit it to use the Pi working directory. Use subagent_repos to list targets.",
+});
+
 const PathsSchema = Type.Array(Type.String({ minLength: 1 }), {
 	minItems: 1,
 	maxItems: 32,
@@ -46,6 +51,7 @@ export const DelegationSchema = Type.Object({
 	access: AccessSchema,
 	paths: Type.Optional(PathsSchema),
 	continueFrom: Type.Optional(ContinueFromSchema),
+	repo: Type.Optional(RepoSchema),
 	kind: Type.Optional(DirectKindSchema),
 	model: Type.Optional(ModelSchema),
 	modelClass: Type.Optional(ModelClassSchema),
@@ -59,6 +65,7 @@ export const DirectWorkflowSchema = Type.Object({
 	access: Type.Optional(AccessSchema),
 	paths: Type.Optional(PathsSchema),
 	continueFrom: Type.Optional(ContinueFromSchema),
+	repo: Type.Optional(RepoSchema),
 	kind: Type.Optional(DirectKindSchema),
 	model: Type.Optional(ModelSchema),
 	modelClass: Type.Optional(ModelClassSchema),
@@ -114,8 +121,18 @@ function normalizePaths(value: Static<typeof DelegationSchema>, path: string): s
 	});
 }
 
-function normalizeDelegation(value: Static<typeof DelegationSchema>, path: string): Delegation {
+/** Check the selector shape here. Admission and launch resolve it against the Pi working directory. */
+function normalizeRepo(value: string, path: string): string {
+	const normalized = text(value, path);
+	if (/[\u0000-\u001f\u007f-\u009f]/.test(normalized) || normalized.startsWith("/") || normalized.split(/[\\/]/).includes("..")) {
+		throw new Error(`${path} must be a relative path without control characters or .. components.`);
+	}
+	return normalized;
+}
+
+function normalizeDelegation(value: Static<typeof DelegationSchema>, path: string, requestRepo?: string): Delegation {
 	const paths = normalizePaths(value, path);
+	const repo = value.repo === undefined ? requestRepo : normalizeRepo(value.repo, `${path}.repo`);
 	return {
 		role: text(value.role, `${path}.role`),
 		name: normalizeTaskName(value.name, `${path}.name`),
@@ -123,6 +140,7 @@ function normalizeDelegation(value: Static<typeof DelegationSchema>, path: strin
 		access: value.access,
 		...(paths === undefined ? {} : { paths }),
 		...(value.continueFrom === undefined ? {} : { continueFrom: value.continueFrom }),
+		...(repo === undefined ? {} : { repo }),
 		kind: "text",
 		...(value.model === undefined ? {} : { model: text(value.model, `${path}.model`) }),
 		...(value.modelClass === undefined ? {} : { modelClass: value.modelClass }),
@@ -164,9 +182,10 @@ export function parseWorkflow(value: unknown): ParsedWorkflow {
 	if (!mode) throw new Error("direct workflow must select exactly one of single, tasks, or chain.");
 	const input = value as DirectInput;
 	if (mode === "single" && !hasDelegation(input)) throw new Error("direct workflow requires role, name, task, and access.");
+	const repo = input.repo === undefined ? undefined : normalizeRepo(input.repo, "workflow.repo");
 	const workflow: ParsedWorkflow = mode === "single" ? { mode, delegations: [normalizeDelegation(input as Static<typeof DelegationSchema>, "workflow")] }
-		: mode === "parallel" ? { mode, delegations: input.tasks!.map((item, index) => normalizeDelegation(item, `tasks[${index}]`)) }
-		: { mode, delegations: input.chain!.map((item, index) => normalizeDelegation(item, `chain[${index}]`)) };
+		: mode === "parallel" ? { mode, delegations: input.tasks!.map((item, index) => normalizeDelegation(item, `tasks[${index}]`, repo)) }
+		: { mode, delegations: input.chain!.map((item, index) => normalizeDelegation(item, `chain[${index}]`, repo)) };
 	const continued = workflow.delegations.flatMap(({ continueFrom }) => continueFrom === undefined ? [] : [continueFrom]);
 	if (new Set(continued).size !== continued.length) throw new Error("A direct request may continue each worker at most once.");
 	return workflow;
@@ -175,6 +194,9 @@ export function parseWorkflow(value: unknown): ParsedWorkflow {
 /** A direct request is a writer request when any task declares write access. */
 export const writesCheckout = (workflow: ParsedWorkflow): boolean => workflow.delegations.some(({ access }) => access === "write");
 
+/** The Repository target of each task. `undefined` means the Pi working directory. */
+export const workflowRepos = (workflow: ParsedWorkflow): Array<string | undefined> => workflow.delegations.map(({ repo }) => repo);
+
 /** `dryRun` is a tool-call option, not part of the direct workflow or the durable isolated request. */
 export function parseDelegateTask(value: unknown): ParsedDelegateTask {
 	let dryRun = false;
@@ -185,6 +207,7 @@ export function parseDelegateTask(value: unknown): ParsedDelegateTask {
 		value = rest;
 	}
 	if (value && typeof value === "object" && !Array.isArray(value) && (value as { mode?: unknown }).mode === "isolated") {
+		if (Object.hasOwn(value, "repo")) throw new Error("mode isolated does not accept repo yet. Start Pi in the repository, or use mode direct.");
 		return { mode: "isolated", request: parseExecuteRequest(value), dryRun };
 	}
 	return { mode: "direct", workflow: parseWorkflow(value), dryRun };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hcflabs/pi-subagent",
-  "version": "27.10.8",
+  "version": "27.11.0",
   "description": "Delegate bounded direct work or durable checked isolated task graphs to Pi roles.",
   "keywords": [
     "pi-package",
@@ -74,6 +74,7 @@
     "@hcflabs/pi-herdr": "^0.5.0",
     "@hcflabs/pi-multi-codex": "^3.0.0",
     "@hcflabs/pi-process": "^0.2.0",
+    "@hcflabs/pi-repo": "^0.1.0",
     "@hcflabs/pi-task-models": "^9.0.0",
     "proper-lockfile": "^4.1.2"
   },