pi-herdr-agents 3.0.0 → 3.0.2

package/CHANGELOG.md

@@ -7,10 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 
-## [v3.0.0](https://github.com/giuseppecrj/pi-herdr-agents/compare/v2.0.5...v3.0.0)
+## [v3.0.2](https://github.com/giuseppecrj/pi-herdr-agents/compare/v3.0.1...v3.0.2)
 
 ### Merged
 
+- fix(subagents): resolve submodule sources and refresh fallback context [`#76`](https://github.com/giuseppecrj/pi-herdr-agents/pull/76)
+
+## [v3.0.1](https://github.com/giuseppecrj/pi-herdr-agents/compare/v3.0.0...v3.0.1) - 2026-10-06
+
+### Merged
+
+- docs: README accuracy and install confidence for 3.0.0 [`#75`](https://github.com/giuseppecrj/pi-herdr-agents/pull/75)
+
+### Commits
+
+- docs: README for 3.0.0: pstack ships poteto-mode not a role, safety and uninstall, contents, agent pointer [`7ed9969`](https://github.com/giuseppecrj/pi-herdr-agents/commit/7ed99693b1a2d25137d4ba2430f23255923ce3ea)
+- chore: release v3.0.1 [`ba349db`](https://github.com/giuseppecrj/pi-herdr-agents/commit/ba349db4a4280a39b70a067fb62e7816f9a2061f)
+- docs: hero image uses generic agent labels instead of removed role names [`70ad6f0`](https://github.com/giuseppecrj/pi-herdr-agents/commit/70ad6f04d492f58e04062e01c1a529ddd1708431)
+- docs: address review: full write footprint, worktree cleanup before uninstall, skill table delimiter [`ababee3`](https://github.com/giuseppecrj/pi-herdr-agents/commit/ababee3a3f18d2112ec8959303986e1a08e3dc2a)
+
+## [v3.0.0](https://github.com/giuseppecrj/pi-herdr-agents/compare/v2.0.5...v3.0.0) - 2026-10-06
+
+### Merged
+
+- Release 3.0.0 [`#74`](https://github.com/giuseppecrj/pi-herdr-agents/pull/74)
 - Add subagent_cancel for ordinary managed subagents [`#73`](https://github.com/giuseppecrj/pi-herdr-agents/pull/73)
 - Add the pi-herdr-agents operating skill [`#72`](https://github.com/giuseppecrj/pi-herdr-agents/pull/72)
 - Conditional task-model writes with expectedConfigRevision [`#71`](https://github.com/giuseppecrj/pi-herdr-agents/pull/71)
@@ -36,7 +56,9 @@ Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 - docs: add subagent-lifecycle host skill [`bfce217`](https://github.com/giuseppecrj/pi-herdr-agents/commit/bfce2177984a7b5fededc2b3a7fe255cc966e46c)
 - fix: keep a failed SIGTERM to a live identity unconfirmed and drop overdue provider answers [`4a3992d`](https://github.com/giuseppecrj/pi-herdr-agents/commit/4a3992d865eeb0a11a23350ff4de92dd892e30c2)
 - docs: fix host operating skill review findings and packaging wording [`bbeb580`](https://github.com/giuseppecrj/pi-herdr-agents/commit/bbeb580a5fb38d780209babcd8b5f7848b8543e2)
+- docs: add 3.0.0 release notes and clarify bare-spawn systemPrompt delivery [`b8b23a0`](https://github.com/giuseppecrj/pi-herdr-agents/commit/b8b23a0893d5d9e6176703305838e24bc91391e8)
 - docs(skill): document subagent_cancel in host operating guide [`7a3508c`](https://github.com/giuseppecrj/pi-herdr-agents/commit/7a3508cfe886b5f7932bdf77d3d3a516d2a7dfcd)
+- chore: release v3.0.0 [`b383574`](https://github.com/giuseppecrj/pi-herdr-agents/commit/b383574778aad1498c12ddeb48af6dd32f383856)
 - test(integration): scope the untouched-pane check to the runner's own workspace [`fa483ea`](https://github.com/giuseppecrj/pi-herdr-agents/commit/fa483ea918f862da35162ca4d73ae6191288fa99)
 - docs: scope the pack-neutral claim to roles and workflows [`e75bea8`](https://github.com/giuseppecrj/pi-herdr-agents/commit/e75bea84a79218c9367ea5a165cbab161e2fb217)
 - fix: declare pi.skills so the lifecycle skill actually loads [`5b45e7f`](https://github.com/giuseppecrj/pi-herdr-agents/commit/5b45e7fb17080fe7b5d1d7e675d234fc140ed144)

package/README.md

@@ -1,6 +1,8 @@
 # Pi Herdr Agents
 
-![Pi Herdr Agents: parallel Pi agents running asynchronously in dedicated Herdr panes and managed worktrees.](https://raw.githubusercontent.com/giuseppecrj/pi-herdr-agents/main/docs/assets/pi-herdr-agents-gallery.png)
+![Pi Herdr Agents: a parent Pi session delegating to parallel child agents in dedicated Herdr panes, an isolated worktree and a retained session, with a live status widget.](https://raw.githubusercontent.com/giuseppecrj/pi-herdr-agents/main/docs/assets/pi-herdr-agents-gallery.png)
+
+> **Agents:** the tool list is in [What's Included](#whats-included) and the operating guide is [`skills/pi-herdr-agents/SKILL.md`](skills/pi-herdr-agents/SKILL.md). Contributors: read [`AGENTS.md`](AGENTS.md).
 
 Asynchronous subagents for [Pi](https://github.com/earendil-works/pi), running exclusively in [Herdr](https://herdr.dev).
 
@@ -48,36 +50,24 @@ pi
 
 Restart or `/reload` Pi after installation. Review package source before installing any Pi package.
 
-## Release notes
+> **Upgrading from 2.x?** Bundled roles and several commands moved out. See [3.0.0 release notes](#300).
 
-[`CHANGELOG.md`](CHANGELOG.md) is generated from Git history on each release.
-Hand-written upgrade notes for breaking releases live here.
+## Contents
 
-### 3.0.0
+- [Requirements](#requirements), [Install](#install), [Safety and uninstall](#safety-and-uninstall)
+- [Quick start](#quick-start), [Release notes](#release-notes), [How it works](#how-it-works)
+- [What's Included](#whats-included): tools, commands, the operating skill, role packs
+- [Async Subagent Flow](#async-subagent-flow): status, configuration, model routing
+- [Spawning Subagents](#spawning-subagents), [Persistent specialists](#persistent-specialists), [Interrupting](#interrupting-a-running-subagent), [Cancelling](#cancelling-a-running-subagent)
+- [The `/worktree` Workflow](#the-worktree-workflow), [Custom Agents](#custom-agents), [Tool Access Control](#tool-access-control)
+- [Development](#development), [License](#license)
 
-3.0.0 makes the host pack-neutral. It also adds conditional task-model writes
-(`expectedConfigRevision`, an advisory lock, and the reported `configRevision`),
-the `pi-herdr-agents` operating skill, and `subagent_cancel`.
+## Safety and uninstall
 
-**Breaking changes.** The package no longer ships the seven former bundled roles,
-`/plan` and its plan skill, or `/skill:orchestrate`; these moved to optional role
-packs. `/iterate`, `/btw`, and `/btw-close` were removed without replacement.
-`roles.bundled` is now a deprecated no-op. A named launch of a role that no
-definition or installed pack supplies now fails before Herdr creates a pane or
-worktree.
-
-**Migration.**
-
-- Install `pi-herdr-roles` for the six generic roles (`scout`, `planner`,
-  `worker`, `reviewer`, `adversarial-reviewer`, `visual-tester`), `/plan`, and
-  `/skill:orchestrate`.
-- Install `pi-herdr-pstack` for the `poteto` role.
-- Remove `roles.bundled` from `$PI_CODING_AGENT_DIR/herdr-agents/config.json`.
-- Alternatively, copy a former role's definition into `.pi/agents/` or the
-  global agents directory to keep it without a pack.
-
-See [Migrating from bundled roles](#migrating-from-bundled-roles) for the full
-mapping and pack-compatibility notes.
+- Child agents are real Pi processes running with your user account's permissions, inside Herdr panes. Worktrees isolate Git checkouts, not processes or permissions.
+- The extension creates Herdr panes, tabs and managed worktrees only when a launch asks for them. It never pushes, merges, opens pull requests, deletes branches or removes worktrees on its own; cleanup is an explicit parent action ([worktree cleanup](#explicit-worktree-cleanup)).
+- What it writes: `$PI_CODING_AGENT_DIR/herdr-agents/config.json` (only through `/subagents-init` or the writer tool, never on startup); per-launch artifacts under the parent session's `artifacts/<session-id>/` directory beside Pi's session store, which hold the child's full task text and any `systemPrompt` as Markdown files, activity snapshots and worktree manifests; and the child's own Pi session file. A managed worktree that carries its own `.pi/agent` directory receives that child's session inside the checkout. Treat task text as potentially sensitive when you share or inspect those files.
+- To uninstall: first list and remove any retained worktrees while the extension is still loaded (`/worktree list`, then `/worktree remove <target>`), because those commands leave with the package. Then run `pi remove npm:pi-herdr-agents`, and delete `$PI_CODING_AGENT_DIR/herdr-agents/` and the `artifacts/` directories above if you no longer want the configuration and launch records.
 
 ## Quick start
 
@@ -117,6 +107,38 @@ subagent({ name: "Auth summary", model: "<provider>/<fast-tier-id>", thinking: "
 
 Use ordinary panes for read-only agents. A single or sequential writer can work in the parent checkout; give each parallel independent writing agent a unique managed worktree. The parent acts as coordinator: decompose work, give each child one bounded outcome with its goal, allowed files, verification, and commit instruction, and keep dependent writes sequential. Children are leaves by default; the parent owns integration and final verification. See [Worktree subagents](docs/worktree-subagents.md).
 
+## Release notes
+
+[`CHANGELOG.md`](CHANGELOG.md) is generated from Git history on each release.
+Hand-written upgrade notes for breaking releases live here.
+
+### 3.0.0
+
+3.0.0 makes the host pack-neutral. It also adds conditional task-model writes
+(`expectedConfigRevision`, an advisory lock, and the reported `configRevision`),
+the `pi-herdr-agents` operating skill, and `subagent_cancel`.
+
+**Breaking changes.** The package no longer ships the seven former bundled roles,
+`/plan` and its plan skill, or `/skill:orchestrate`; these moved to optional role
+packs. `/iterate`, `/btw`, and `/btw-close` were removed without replacement.
+`roles.bundled` is now a deprecated no-op. A named launch of a role that no
+definition or installed pack supplies now fails before Herdr creates a pane or
+worktree.
+
+**Migration.**
+
+- Install `pi-herdr-roles` for the six generic roles (`scout`, `planner`,
+  `worker`, `reviewer`, `adversarial-reviewer`, `visual-tester`), `/plan`, and
+  `/skill:orchestrate`.
+- Install `pi-herdr-pstack` for the `poteto-mode` methodology skill and command.
+  It ships no named roles; its delegates are bare.
+- Remove `roles.bundled` from `$PI_CODING_AGENT_DIR/herdr-agents/config.json`.
+- Alternatively, copy a former role's definition into `.pi/agents/` or the
+  global agents directory to keep it without a pack.
+
+See [Migrating from bundled roles](#migrating-from-bundled-roles) for the full
+mapping and pack-compatibility notes.
+
 ## How it works
 
 ![Pi Herdr Agents lifecycle: spawn a child, run it in Herdr, supervise live state, and deliver one bounded result to the parent.](https://raw.githubusercontent.com/giuseppecrj/pi-herdr-agents/main/docs/assets/async-subagent-lifecycle.png)
@@ -172,6 +194,10 @@ Subagent tabs, panes, and worktree workspaces are created without stealing keybo
 | `subagent_resume`    | Resume a previous Pi-backed sub-agent session in a new ordinary pane (async)                          |
 | `subagents_write_task_models` | Parent-only internal tool that validates and atomically writes `models.tasks` preferences, optionally conditional on `expectedConfigRevision` |
 
+| Skill | Description |
+| ----- | ----------- |
+| `pi-herdr-agents` | Operating guide for this host: launching, supervising, interrupting, cancelling and resuming children, worktrees, persistent specialists, model routing and configuration. Loaded by agents on demand; see `skills/pi-herdr-agents/SKILL.md` |
+
 | Pi child-only tool | Description |
 | ---------------- | ------------------------------------------------------------------------- |
 | `caller_ping` | Ask the parent for help; ordinary children exit, persistent specialists stay alive |
@@ -233,7 +259,7 @@ modified.
 | `scout`, `planner`, `worker`, `reviewer`, `adversarial-reviewer`, `visual-tester` roles | Moved | `pi-herdr-roles` role pack |
 | `/plan` command and its plan skill | Moved | `pi-herdr-roles` |
 | `/skill:orchestrate` and its adversarial-review resources | Moved | `pi-herdr-roles` |
-| `poteto` role | Moved | `pi-herdr-pstack` role pack |
+| `poteto` role | Removed; replaced by the `poteto-mode` skill and `/poteto-mode` command | `pi-herdr-pstack` |
 | `/iterate` | Removed, not relocated | Call `subagent({ name, task, fork: true, interactive: true })` directly |
 | `/btw`, `/btw-close` | Removed, not relocated | None |
 | `roles.bundled` setting | Deprecated no-op | Remove it from `config.json` |
@@ -599,10 +625,17 @@ example `provider/preferred, provider/fallback`. The tool argument also accepts
 candidate before launch, then launches later candidates only after the selected
 child settles with a provider/agent error. Pi owns any automatic transient
 retrying inside that child; the extension does not infer retry counts or
-permanence from the error text. A completed child result, including a negative
-task result, never switches models. Completion metadata reports the requested
-candidate, every attempted candidate, the model actually used, and each raw
-model failure in attempt order when fallbacks are tried.
+permanence from the error text. A later candidate that launches after a parent
+`/reload`, `/new`, `/resume`, or `/fork` uses the live parent session for its
+artifacts and lineage, as completion delivery does. Its candidate list and
+thinking level stay those of the original call. The original parent directory
+and process directory remain the bases for directory resolution. Role files are
+read again for each attempt, so a changed role `cwd` can redirect a fallback
+when the tool call did not specify `cwd`. If no live parent context is available,
+that candidate fails without launching. A completed child result, including a
+negative task result, never switches models. Completion metadata reports the
+requested candidate, every attempted candidate, the model actually used, and
+each raw model failure in attempt order when fallbacks are tried.
 
 A catalog-listed model and configured authentication do not prove that the
 active provider account can use that model. Providers may reject an account /
@@ -839,7 +872,7 @@ is no other parent/child protocol.
 
 Parent sessions can call `worktree_remove({ target: "<path|branch|workspace-id>", preserve: true })` or `/worktree remove <target> [--preserve]`. Preservation is optional and never implied: dirty work is blocked unless explicitly committed first or preserved as a WIP commit. The result reports its SHA even if removal later fails or is refused. A failed preservation commit restores the pre-preservation index and never proceeds to removal. Inventory and removal reports disclose exact ignored-file counts: enumeration is streamed rather than buffered as one listing. Ignored files do not block cleanup and are not captured by preservation; failed counting still blocks removal.
 
-Eligibility is rechecked at removal time: canonical source-repository cwd containment, registered linked checkout, no detected process holder, known live child, or persistent lease, and clean Git state with no untracked files or conflicts. A successful launch from a linked checkout does not itself authorize its removal; cleanup uses the canonical principal/source repository under the invoking parent session's cwd, not `manifest.sourceCwd` or shared Git identity. Start the parent Pi session rooted at that principal checkout or an ancestor containing it, then use normal explicit cleanup; `cd` inside an existing Pi session does not change the session cwd. Unknown inspection, identity disagreements, detached HEAD, locked checkouts, and initialized submodules block removal. Out-of-scope repositories are never eligible. Open workspaces use Herdr removal; orphans use Git removal and registration pruning after checkout absence is verified. Owned reachable manifests are marked `removed`; manifests from other sessions are not required or rewritten. Stale removed manifests never govern a recreated checkout. Missing or dangling manifest paths do not affect unrelated checkouts; undecidable or conflicting manifest identity still blocks removal. A failed manifest update after removal is reported as a warning. Symlinked ancestors are supported; checkout symlinks escaping the canonical managed root are blocked. Process inspection covers observable same-user processes across sessions, regardless of runtime name, exempting only Herdr-confirmed idle retained shells, never runtimes at the same PID. Unreadable individual process details produce non-blocking warnings without an override flag; scanning continues so another observable holder still blocks removal. Human and structured inventory/removal results disclose incomplete coverage, including warnings seen before a later recheck or failure. Same-user inspection is permission-limited, and other-user processes are not inspected: a protected process could hold the checkout undetected. Warnings aggregate counts and bounded PID samples, not commands or environments. Linux uses `/proc`; macOS uses same-user `lsof` cwd records and warns for unreadable individual records. Unsupported platforms, failed global enumeration (including a failed `lsof` with partial output), and other unverifiable eligibility evidence still block removal. Cleanup Git and Herdr calls have 30-second timeouts.
+Eligibility is rechecked at removal time: canonical source-repository cwd containment, registered linked checkout, no detected process holder, known live child, or persistent lease, and clean Git state with no untracked files or conflicts. A successful launch from a linked checkout does not itself authorize its removal; cleanup uses the canonical principal/source repository under the invoking parent session's cwd, not `manifest.sourceCwd` or shared Git identity. Start the parent Pi session rooted at that principal checkout or an ancestor containing it, then use normal explicit cleanup; `cd` inside an existing Pi session does not change the session cwd. A source repository that is a Git submodule is located through the `core.worktree` setting of its shared Git directory under the superproject's `.git/modules`, not through that directory's parent. Unknown inspection, identity disagreements, detached HEAD, locked checkouts, and initialized submodules block removal. Out-of-scope repositories are never eligible. Open workspaces use Herdr removal; orphans use Git removal and registration pruning after checkout absence is verified. Owned reachable manifests are marked `removed`; manifests from other sessions are not required or rewritten. Stale removed manifests never govern a recreated checkout. Missing or dangling manifest paths do not affect unrelated checkouts; undecidable or conflicting manifest identity still blocks removal. A failed manifest update after removal is reported as a warning. Symlinked ancestors are supported; checkout symlinks escaping the canonical managed root are blocked. Process inspection covers observable same-user processes across sessions, regardless of runtime name, exempting only Herdr-confirmed idle retained shells, never runtimes at the same PID. Unreadable individual process details produce non-blocking warnings without an override flag; scanning continues so another observable holder still blocks removal. Human and structured inventory/removal results disclose incomplete coverage, including warnings seen before a later recheck or failure. Same-user inspection is permission-limited, and other-user processes are not inspected: a protected process could hold the checkout undetected. Warnings aggregate counts and bounded PID samples, not commands or environments. Linux uses `/proc`; macOS uses same-user `lsof` cwd records and warns for unreadable individual records. Unsupported platforms, failed global enumeration (including a failed `lsof` with partial output), and other unverifiable eligibility evidence still block removal. Cleanup Git and Herdr calls have 30-second timeouts.
 
 Cleanup never deletes or rewrites branches, uses force flags, or runs automatically. Session startup does not scan worktree inventory, avoiding blocking Pi initialization; use `/worktree list` or `worktree_list` for an explicit inventory. Child sessions retain `/worktree list` and `/worktree <name>`, but receive neither cleanup tools nor the remove subcommand. Their repository-local listing labels detached entries `(detached HEAD)`; a detached sibling does not prevent inspection of named branches. See [cleanup and recovery](docs/worktree-subagents.md#cleanup) for details.
 
@@ -1250,4 +1283,4 @@ This package builds on earlier open-source work by [HazAT/pi-interactive-subagen
 
 ## License
 
-MIT. Copyright notice retained from the upstream lineage (`HazAT`).
+MIT, see [LICENSE](LICENSE). Copyright notice retained from the upstream lineage (`HazAT`).

package/docs/worktree-subagents.md

@@ -223,6 +223,8 @@ The equivalent tools are `worktree_list({})` and `worktree_remove({ target, pres
 
 Authorization uses **cwd containment**: the canonical source repository root must equal or descend from the canonical session cwd. For linked checkouts, this means the canonical principal/source repository under the invoking parent session's cwd; a successful launch does not itself authorize cleanup, and authorization does not use `manifest.sourceCwd` or shared Git identity. Start the parent Pi session rooted at the principal checkout or an ancestor containing it, then use normal explicit cleanup; changing directories inside an existing Pi session does not change its session cwd. It does not use the managed checkout's location or require a current-session manifest. Discovery scans `~/.herdr/worktrees/*/*/`, joins Git registration and Herdr workspace state, and includes orphans from ended sessions. Out-of-scope entries are never removable; unregistered residue and failed probes are unknown, not clean. Inventory includes path, branch, source, workspace, Git state, manifest presence, concrete blockers, and separate process-inspection warnings. The managed root, source, and cwd are canonicalized: symlinked ancestors work normally, but a checkout symlink escaping the managed root is blocked.
 
+A source repository can be a Git submodule. Its shared Git directory lives under the superproject's `.git/modules`, so cleanup reads `core.worktree` through `git config`, which also follows included configuration files. Cleanup then requires the same top-level and common-directory proofs as for any other source. If the read or a proof fails, the entry is unknown and cannot be removed. Initialized submodules inside a managed checkout still block removal.
+
 Removal rechecks containment, Git registration, no detected process holder, known live child, or persistent-specialist lease, and no uncommitted, untracked, or conflicted files. Liveness checks observable same-user processes from any session with a cwd inside the checkout, regardless of runtime name (including thread-suffixed Node names). Only Herdr-confirmed idle retained shell PIDs are exempt; an active runtime at the same PID is not. Detached HEAD, locked checkouts, initialized submodules, and conflicting identity evidence block removal. For initialized submodules, deinitialize them deliberately or use operator removal. No force option is provided.
 
 Unreadable individual process details are **warnings, not blockers**, with no override flag. Scanning continues after each unreadable entry, so another observable holder still blocks removal. Unknown processes are not classified as unrelated. Inventory rows expose separate `blockers` and `warnings` arrays; removal results expose `warnings` and retain warnings from earlier inspections, including refusals and preservation/removal failures when available. Human-readable output includes the same warnings, with counts and at most ten sampled PIDs per inspection, not process commands or environments. Pi tool refusals and failures use thrown errors, so their warnings travel in the error message rather than structured tool details.

package/maestro/runtime/worktree-operations.ts

@@ -11,7 +11,7 @@ import {
 	unlinkSync,
 } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, isAbsolute, join, relative, sep } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { isRecord, type JsonObject } from "../core/config/type-guards.ts";
 import type { SurfaceProvider } from "../core/surface-provider.ts";
 import type {
@@ -245,7 +245,19 @@ function resolveSource(path: string): string {
 			"--git-common-dir",
 		]).trim(),
 	);
-	const root = realpathSync(dirname(common));
+	// A submodule's common directory lives under the superproject's
+	// .git/modules; only core.worktree, including included config, names its checkout.
+	const configured = git(common, [
+		`--git-dir=${common}`,
+		"config",
+		"--default",
+		"",
+		"--get",
+		"core.worktree",
+	]).trim();
+	const root = realpathSync(
+		configured ? resolve(common, configured) : dirname(common),
+	);
 	if (realpathSync(git(root, ["rev-parse", "--show-toplevel"]).trim()) !== root)
 		throw new Error("Cannot prove source repository root");
 	if (

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-herdr-agents",
-  "version": "3.0.0",
+  "version": "3.0.2",
   "description": "Asynchronous Pi subagents in Herdr, with optional isolated Git worktrees",
   "keywords": [
     "pi-package",

package/pi-extension/subagents/index.ts

@@ -1950,10 +1950,6 @@ function startWidgetRefresh() {
 	writeGlobalSlot(WIDGET_INTERVAL_KEY, widgetInterval);
 }
 
-/**
- * Normalize each actual attempt against its invocation context. Role files may
- * change between attempts; the validated runtime candidates do not.
- */
 function normalizePiAttempt(
 	params: typeof SubagentParams.static,
 	ctx: {
@@ -1975,6 +1971,7 @@ function normalizePiAttempt(
 	options: {
 		id: string;
 		controlTaskId: string;
+		origin: Pick<PiLaunchSnapshot["parent"], "cwd" | "invocationCwd">;
 	},
 ): PiAttemptSnapshot {
 	const agentDefs = params.agent
@@ -1999,15 +1996,19 @@ function normalizePiAttempt(
 	const taskId = randomUUID();
 	const parentSessionFile = ctx.sessionManager.getSessionFile();
 	if (!parentSessionFile) throw new Error("No session file");
+	const snapshot = launchSnapshot(ctx, parentThinking);
 
 	return {
-		snapshot: launchSnapshot(ctx, parentThinking),
+		snapshot: {
+			...snapshot,
+			parent: { ...snapshot.parent, ...options.origin },
+		},
 		task: {
 			id: options.controlTaskId,
 			name: params.name,
 			prompt: params.task,
 			role: params.agent ?? "",
-			cwd: ctx.cwd,
+			cwd: options.origin.cwd,
 			worktree: params.worktree ?? undefined,
 			session: { mode: resolveEffectiveSessionMode(params, agentDefs) },
 			behavior: {
@@ -2792,20 +2793,24 @@ export default function subagentsExtension(
 				);
 				runtime.latestCtx = ctx;
 				const id = randomUUID();
-				const first = normalizePiAttempt(params, ctx, parentThinking, {
+				const attempt = {
 					id,
 					controlTaskId: id,
-				});
+					origin: { cwd: ctx.cwd, invocationCwd: process.cwd() },
+				};
+				const first = normalizePiAttempt(params, ctx, parentThinking, attempt);
 				const [plan, ...fallbacks] = runtimePlans;
 				if (!plan) throw new Error("No resolved runtime plans");
 				const input: PiLaunchInput = {
 					...first,
 					plans: [plan, ...fallbacks],
-					prepareAttempt: () =>
-						normalizePiAttempt(params, ctx, parentThinking, {
-							id,
-							controlTaskId: id,
-						}),
+					// Fallbacks outlive this tool call; session replacement invalidates ctx.
+					prepareAttempt: () => {
+						const live = runtime.latestCtx;
+						if (!live)
+							throw new Error("No live parent context for the fallback launch");
+						return normalizePiAttempt(params, live, parentThinking, attempt);
+					},
 				};
 				const session = runtime.session!;
 				const handle = await session.spawnPi(input);