@oldflag2333333/pi-subagent 0.1.4 → 0.1.6

package/README.md

@@ -77,7 +77,7 @@ Ask the reviewer profile to review src/auth for bugs and missing tests.
 | Finish with a specialist | Ask Pi to close the Sub, or close its Herdr tab |
 | Remove Sub sessions and communication files left by deleted Mains | `/clean-sub` |
 
-Within the same Main session, repeated `/sub:reviewer` commands reuse that profile's open Sub. If it is busy, your next task is queued. Finishing a task does not automatically close the tab.
+Within the same Main session, repeated `/sub:reviewer` commands reuse that profile's open Sub. If it is busy, your next task is queued. Finishing a task does not automatically close the tab. Subs can report progress through `talk` without stopping; `endTurn: true` explicitly ends their current turn when finished or waiting for Main.
 
 The **Sub-agents** list shows only assistants created by the current Main: all **Open** Subs (including idle or unknown status) and **Resumable** persistent sessions confirmed closed with saved files still available. Other Main sessions and forks do not inherit them or gain access to resume them. Reloading or resuming the same Main preserves ownership.
 
@@ -164,21 +164,28 @@ These instructions apply only to your main Pi, not to its Subs. Keep shared proj
 
 ## Clean up deleted sessions
 
-Persistent Sub histories are grouped by their owning Main, using Pi's native `--session-dir`:
+Persistent Subs use Pi's native session store alongside ordinary sessions, with IDs of the form `sub-<UUID>`:
 
 ```text
-~/.pi/agent/subagent/sessions/<main-session-id>/*.jsonl
+~/.pi/agent/sessions/<encoded-cwd>/<timestamp>_sub-<UUID>.jsonl
 ```
 
-Run `/clean-sub` to immediately delete both the Sub session directory and runtime communication directory for any Main ID no longer found among saved Pi sessions. It checks Pi's default session store and the current session directory, always preserves the current Main, and creates no index. Unreadable session files or invalid headers stop cleanup instead of being treated as deleted.
+Same-cwd Subs inherit Main's session directory (including `--session-dir` overrides); Subs launched in another cwd use Pi's normal storage for that cwd. Ephemeral Subs still use `--no-session`. Native `/resume` can discover saved Subs; `--continue` may therefore select a Sub if it is the most recent session.
 
-Close any orphaned Sub tabs before cleaning; the command only deletes files. Profiles and global settings are untouched. Older Sub files outside the managed directory still need manual deletion. If you moved Main files or use other custom session directories, make them available in the scanned locations before cleaning.
+Ownership is stored in both directions: Main's `subagent-run` custom entries record Sub IDs and paths, and each Sub's `subagent-owner` custom entry records its own ID and Main's ID and file path. These entries do not enter model context. Reloading or resuming does not duplicate unchanged ownership metadata.
+
+- `/clean-sub` permanently deletes orphaned Sub JSONL files across Pi's native session store and the current custom session directory, plus orphaned runtime communication directories. A Sub is orphaned when its recorded Main ID cannot be found. Recorded Main file paths also protect owners stored outside native discovery.
+- On Pi exit (`session_shutdown` with reason `quit`), the same cleanup runs automatically, limited to Subs whose session-header cwd matches the current cwd. Switching sessions, forking, and reloading do not trigger cleanup. Main existence is still checked across projects to protect cross-cwd Subs.
+- The current session/owning Main is always preserved, including unsaved sessions. Missing ownership metadata is preserved with a warning; unreadable files, invalid headers, or conflicting ownership abort cleanup before deletion. Shared session directories, ordinary sessions, profiles, and settings are never deleted. No separate index or legacy-storage migration is used.
+
+Close orphaned Sub tabs before cleaning; cleanup deletes files, not running agents. Custom stores other than the current session directory are not scanned for Sub files; run `/clean-sub` from those stores when needed.
 
 ## Things to know
 
 Messages use custom inbox cards and Pi’s native run preparation, without extra user-role wake messages. See [messaging behavior](docs/messaging.md).
 
 - **Herdr is required for Subs.** There is no headless fallback. Up to four Subs can be open at once, and Subs cannot delegate further.
+- **Subs cannot fork or clone.** `/fork` and `/clone` are cancelled in Sub tabs; Main sessions are unaffected.
 - **Profiles are not a sandbox.** Subs run as your OS user. A read-only role is not a filesystem permission boundary.
 - **MCP follows Pi's normal configuration.** Profiles select non-MCP tools; they do not isolate or filter MCP servers. Custom non-MCP tools must come from extensions already loaded in Main.
 - **Subs have separate conversations.** They receive their task, profile, and normal project context—not Main's chat history. Include the details they need in the task.

package/README.zh-CN.md

@@ -77,7 +77,7 @@ mkdir -p ~/.pi/agent/subagent/profiles/reviewer
 | 结束使用 | 让 Pi 关闭子助手，或手动关闭其 Herdr 标签页 |
 | 清理已删除 Main 遗留的 Sub 会话和通信文件 | `/clean-sub` |
 
-在同一个主会话（Main）中，多次调用 `/sub:reviewer` 会复用该角色已打开的子助手（Sub）。如果它正在工作，新任务会排队。任务完成后，标签页不会自动关闭。
+在同一个主会话（Main）中，多次调用 `/sub:reviewer` 会复用该角色已打开的子助手（Sub）。如果它正在工作，新任务会排队。任务完成后，标签页不会自动关闭。Sub 通过 `talk` 汇报进度后默认继续工作；只有完成任务或需要等待 Main 回复时，才用 `endTurn: true` 显式结束本轮。
 
 **Sub-agents（子助手）** 列表只显示当前 Main 创建的助手：**Open** 包含所有已打开的子助手，包括空闲或状态未知的；**Resumable** 包含已确认关闭、且保存文件仍存在的持久化会话。其他 Main 或分叉会话不会继承这些助手，也不能恢复它们。重载或恢复同一个 Main 则会保留关联。
 
@@ -164,21 +164,28 @@ reviewer/
 
 ## 清理已删除会话的遗留文件
 
-持久化 Sub 使用 Pi 原生的 `--session-dir`，按所属 Main 分目录保存：
+持久化 Sub 与普通会话一起使用 Pi 原生会话目录，ID 格式为 `sub-<UUID>`：
 
 ```text
-~/.pi/agent/subagent/sessions/<main-session-id>/*.jsonl
+~/.pi/agent/sessions/<工作目录编码>/<timestamp>_sub-<UUID>.jsonl
 ```
 
-执行 `/clean-sub`，找不到对应 Main ID 时，立即删除它的 Sub 会话目录和运行时通信目录。命令检查 Pi 默认会话目录和当前会话目录，始终保留当前 Main，不新增索引。会话文件无法读取或文件头无效时会停止清理，不会将它们当作已删除。
+相同工作目录的 Sub 沿用 Main 的会话目录（包括 `--session-dir` 自定义目录）；指定其他工作目录时使用该目录对应的 Pi 常规存储。临时 Sub 仍使用 `--no-session`。原生 `/resume` 可以发现持久化 Sub；因此 `--continue` 也可能选中最近活动的 Sub。
 
-清理前请关闭遗留的 Sub 标签页，命令只删除文件。角色配置和全局设置不受影响；以前散落在专用目录之外的 Sub 文件仍需手动删除。如果移动过 Main 文件或使用其他自定义会话目录，请先确保这些会话位于扫描范围内，再执行清理。
+归属信息双向保存在 JSONL 中：Main 的 `subagent-run` 自定义条目记录 Sub ID 和文件路径；Sub 的 `subagent-owner` 自定义条目记录自身 ID、Main ID 和 Main 文件路径。这些条目不进入模型上下文，重载或恢复时不会重复写入未变化的归属信息。
+
+- `/clean-sub` 扫描 Pi 全局原生会话库及当前自定义会话目录，永久删除找不到所属 Main ID 的孤儿 Sub JSONL 文件，同时清理孤儿运行时通信目录。也会检查记录的 Main 文件路径，保护保存在扫描范围之外的 Main。
+- 退出 Pi 时（`session_shutdown` 的 `reason` 为 `quit`）自动执行清理，但只清理会话头中工作目录与当前目录相同的 Sub。切换会话、fork 和重载不触发清理；判断 Main 是否存在仍跨项目检查，避免误删跨目录委派的 Sub。
+- 始终保护当前会话或所属 Main，包括尚未保存的会话。缺失归属元数据的 Sub 会保留并警告；无法读取文件、会话头无效或归属冲突时，在删除前中止清理。不删除共享会话目录、普通会话、角色配置或设置。不新增独立索引，也不迁移旧存储。
+
+清理前请关闭孤儿 Sub 标签页；清理只删除文件，不关闭运行中的助手。当前会话目录之外的其他自定义存储不会被扫描 Sub 文件，需要从相应存储运行 `/clean-sub`。
 
 ## 使用须知
 
 助手间消息使用自定义收件卡片，由 Pi 原生处理启动准备，不再添加用户角色唤醒消息。详见[消息机制](docs/messaging.md)。
 
 - **子助手依赖 Herdr。** 不支持无界面后台运行；最多同时打开四个子助手，子助手不能继续委派。
+- **子助手不支持 fork 或 clone。** Sub 标签页中的 `/fork` 和 `/clone` 会被取消，不影响 Main 会话。
 - **角色配置不是沙箱。** 子助手以你的系统用户身份运行，配置“只读角色”不等于限制文件系统权限。
 - **MCP 沿用 Pi 的常规配置。** 角色只选择非 MCP 工具，不隔离或筛选 MCP 服务。自定义的非 MCP 工具必须来自主 Pi 已加载的扩展。
 - **子助手拥有独立对话。** 它会收到任务、角色配置和常规项目上下文，但不会收到主对话的聊天记录。请在任务中提供必要信息。

package/docs/messaging.md

@@ -7,6 +7,15 @@ Pi Subagent requires **Pi 1.2.0 or newer**. Main ↔ Sub messages use `pi.sendMe
 
 There are no synthetic user-role wake messages, version fallbacks, or patches to Pi internals. Custom messages do not pass through user-input processing or execute peer text as slash commands or templates.
 
+## Sub talk and turn control
+
+Sub's `talk` accepts an optional `endTurn` boolean, defaulting to `false`:
+
+- Omitted or `false`: send the message and continue working. Use this for progress updates; no acknowledgement or "continue" reply from Main is required.
+- `true`: send the message and end the current turn. Use this for completed work or a blocking question that requires Main's reply. Send a terminating `talk` on its own: Pi only ends the tool batch early when every tool result in it is terminating.
+
+Ending a turn does not close the Sub or discard queued follow-ups. Main can still send further work through `talk`. Message text should make clear whether it reports progress, asks a blocking question, or delivers completed work; Main must not treat every message as task completion. Main's own `talk` does not end its turn.
+
 ## Delivery guarantees
 
 - `content` carries the peer message and routing instructions; `details` carries rendering and receipt metadata and is not sent to the model.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oldflag2333333/pi-subagent",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Reusable specialist profiles and independent sub-agents for Pi",
   "type": "module",
   "license": "MIT",

package/src/adapters/herdr.ts

@@ -4,7 +4,6 @@ import * as path from "node:path";
 import { getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { subSessionName } from "../manual-context.js";
 import { subCapabilityArgs } from "../profiles/launch-args.js";
-import { subSessionDir } from "../sessions.js";
 import type { SubAgentStatus, SubLaunchSpec, SubSurfaceAdapter, SurfaceHandle } from "../types.js";
 
 function parseEnvelope(stdout: string): Record<string, unknown> {
@@ -41,9 +40,9 @@ function subArgs(spec: SubLaunchSpec): string[] {
 		"--no-extensions",
 		"-e", spec.entryPath,
 		...(fs.existsSync(herdrIntegration) ? ["-e", herdrIntegration] : []),
-		...(spec.profile.sessionPersistence === "persistent" || spec.resumeSessionId
-			? ["--session-dir", subSessionDir(spec.mainSessionId)] : ["--no-session"]),
-		...(spec.resumeSessionId ? ["--session", spec.resumeSessionFile ?? spec.resumeSessionId] : []),
+		...(spec.profile.sessionPersistence === "persistent"
+			? (spec.sessionDir ? ["--session-dir", spec.sessionDir] : []) : ["--no-session"]),
+		...(spec.resumeSessionFile ? ["--session", spec.resumeSessionFile] : ["--session-id", spec.sessionId]),
 		spec.projectTrusted ? "--approve" : "--no-approve",
 		"--name", subSessionName(safeLabel(spec.title), spec.origin),
 		...subCapabilityArgs(spec.profile, spec.entryPath),

package/src/channel.ts

@@ -100,6 +100,7 @@ export function readManifest(channelDir: string): DelegateManifest {
 	const value = record(readJson(path.join(channelDir, "manifest.json")));
 	if (!value || value.version !== 1 || typeof value.runId !== "string" || typeof value.mainSessionId !== "string"
 		|| typeof value.title !== "string" || typeof value.task !== "string" || typeof value.cwd !== "string"
+		|| (value.mainSessionFile !== undefined && (typeof value.mainSessionFile !== "string" || !path.isAbsolute(value.mainSessionFile)))
 		|| (value.origin !== undefined && value.origin !== "manual")
 		|| !validProfile(value.profile) || typeof value.token !== "string" || typeof value.createdAt !== "number") {
 		throw new Error("Invalid Pi Subagent channel manifest.");

package/src/commands/clean-sub.ts

@@ -1,8 +1,22 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { createInterface } from "node:readline";
 import { getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { channelPath, runtimeRoot } from "../channel.js";
-import { subSessionDir, subSessionsRoot } from "../sessions.js";
+import { channelPath, readManifest, runtimeRoot } from "../channel.js";
+import { parseSubSessionOwner, SUB_OWNER_ENTRY, SUB_SESSION_ID, type SubSessionOwner } from "../sessions.js";
+
+interface SavedSession {
+	file: string;
+	id: string;
+	cwd: string;
+	owner?: SubSessionOwner;
+}
+
+interface CleanupResult {
+	removed: number;
+	removedChannels: number;
+	errors: string[];
+}
 
 function entries(directory: string): fs.Dirent[] {
 	try { return fs.readdirSync(directory, { withFileTypes: true }); }
@@ -12,74 +26,137 @@ function entries(directory: string): fs.Dirent[] {
 	}
 }
 
-/** Read only the header; never load transcripts or treat an unreadable session as deleted. */
-function sessionId(file: string): string {
-	const fd = fs.openSync(file, "r");
+function sessionDirectories(currentSessionDir: string): string[] {
+	const root = path.join(getAgentDir(), "sessions");
+	const directories = new Set([root, ...(currentSessionDir ? [path.resolve(currentSessionDir)] : [])]);
+	for (const entry of entries(root)) {
+		if (entry.isDirectory() || entry.isSymbolicLink()) directories.add(path.join(root, entry.name));
+	}
+	return [...directories];
+}
+
+/** Read headers only for Mains; stream Sub ownership without loading transcripts into memory. */
+async function inspectSession(file: string, scopeCwd?: string, headerOnly = false): Promise<SavedSession | undefined> {
+	const input = fs.createReadStream(file, { encoding: "utf8" });
+	const lines = createInterface({ input, crlfDelay: Infinity });
+	let session: SavedSession | undefined;
 	try {
-		const buffer = Buffer.alloc(64 * 1024);
-		const length = fs.readSync(fd, buffer, 0, buffer.length, 0);
-		const text = buffer.subarray(0, length).toString("utf8");
-		const header = JSON.parse(text.split("\n", 1)[0]!);
-		if (header?.type !== "session" || typeof header.id !== "string" || !header.id) throw new Error("Invalid session header");
-		return header.id;
+		for await (const line of lines) {
+			if (!session) {
+				const header = JSON.parse(line);
+				if (header?.type !== "session" || typeof header.id !== "string" || !header.id
+					|| typeof header.cwd !== "string" || !path.isAbsolute(header.cwd)) throw new Error("Invalid session header");
+				session = { file, id: header.id, cwd: header.cwd };
+				if (headerOnly || !SUB_SESSION_ID.test(session.id) || (scopeCwd && path.resolve(session.cwd) !== scopeCwd)) break;
+				continue;
+			}
+			if (!line.includes(SUB_OWNER_ENTRY)) continue;
+			const entry = JSON.parse(line);
+			if (entry?.type !== "custom" || entry.customType !== SUB_OWNER_ENTRY) continue;
+			const owner = parseSubSessionOwner(entry.data);
+			if (owner.subSessionId !== session.id || owner.mainSessionId === session.id
+				|| (owner.mainSessionFile !== undefined && !path.isAbsolute(owner.mainSessionFile))) throw new Error("Invalid Sub session ownership");
+			if (session.owner && session.owner.mainSessionId !== owner.mainSessionId) {
+				throw new Error("Conflicting Sub session owners");
+			}
+			session.owner = owner;
+		}
+		if (!session) throw new Error("Missing session header");
+		return session;
 	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
 		throw new Error(`Cannot inspect session ${file}: ${error instanceof Error ? error.message : String(error)}`);
-	} finally { fs.closeSync(fd); }
+	} finally {
+		lines.close();
+		input.destroy();
+	}
 }
 
-export function cleanSubFiles(currentMainId: string, currentSessionDir: string): { removed: number; errors: string[] } {
-	const stores = [
-		{ root: runtimeRoot(), ownerDirectory: (id: string) => path.basename(path.dirname(channelPath(id, "unused"))) },
-		{ root: subSessionsRoot(), ownerDirectory: (id: string) => path.basename(subSessionDir(id)) },
-	].map((store) => {
-		const candidates = entries(store.root).filter((entry) => entry.isDirectory());
-		if (candidates.length && fs.lstatSync(store.root).isSymbolicLink()) throw new Error(`Refusing to clean symlinked directory: ${store.root}`);
-		return { ...store, candidates };
-	});
-	if (stores.every((store) => store.candidates.length === 0)) return { removed: 0, errors: [] };
-
-	const sessionsRoot = path.join(getAgentDir(), "sessions");
-	const directories = new Set([sessionsRoot]);
-	if (currentSessionDir) directories.add(currentSessionDir);
-	for (const entry of entries(sessionsRoot)) {
-		const file = path.join(sessionsRoot, entry.name);
-		if (entry.isDirectory() || (entry.isSymbolicLink() && fs.statSync(file).isDirectory())) directories.add(file);
+/** Global discovery establishes Main liveness even when only one cwd is being cleaned. */
+export async function cleanSubFiles(currentSessionId: string, currentSessionDir: string, cwd?: string): Promise<CleanupResult> {
+	const scopeCwd = cwd ? path.resolve(cwd) : undefined;
+	const live = new Set([currentSessionId]); // Includes unsaved/in-memory current sessions.
+	const sessions: SavedSession[] = [];
+	const errors: string[] = [];
+	const ownerFiles = new Map<string, string>();
+	for (const directory of sessionDirectories(currentSessionDir)) {
+		const files = entries(directory);
+		if (files.length && fs.lstatSync(directory).isSymbolicLink()) throw new Error(`Refusing to clean symlinked directory: ${directory}`);
+		for (const entry of files) {
+			if (!entry.name.endsWith(".jsonl")) continue;
+			const file = path.join(directory, entry.name);
+			// A linked Main still establishes liveness, but links are never deletion targets.
+			const session = await inspectSession(file, scopeCwd);
+			if (!session) continue;
+			live.add(session.id);
+			if (session.owner?.mainSessionFile) ownerFiles.set(session.owner.mainSessionFile, session.owner.mainSessionId);
+			if (entry.isFile() && SUB_SESSION_ID.test(session.id) && (!scopeCwd || path.resolve(session.cwd) === scopeCwd)) {
+				if (session.owner) sessions.push(session);
+				else errors.push(`Preserved Sub without owner metadata: ${file}`);
+			}
+		}
 	}
-	const live = new Set([currentMainId]);
-	// Complete discovery before deleting anything. A read/parse error aborts cleanup.
-	for (const directory of directories) {
-		for (const entry of entries(directory)) {
-			if (entry.name.endsWith(".jsonl")) live.add(sessionId(path.join(directory, entry.name)));
+
+	const channels: Array<{ directory: string; mainSessionId: string }> = [];
+	const runtime = runtimeRoot();
+	const owners = entries(runtime);
+	if (owners.length && fs.lstatSync(runtime).isSymbolicLink()) throw new Error(`Refusing to clean symlinked directory: ${runtime}`);
+	for (const owner of owners) {
+		if (!owner.isDirectory()) continue;
+		const ownerDir = path.join(runtime, owner.name);
+		for (const run of entries(ownerDir)) {
+			if (!run.isDirectory()) continue;
+			const directory = path.join(ownerDir, run.name);
+			const manifest = readManifest(directory);
+			if (path.resolve(channelPath(manifest.mainSessionId, manifest.runId)) !== path.resolve(directory)) throw new Error(`Invalid channel identity: ${directory}`);
+			if (scopeCwd && path.resolve(manifest.cwd) !== scopeCwd) continue;
+			if (manifest.mainSessionFile) ownerFiles.set(manifest.mainSessionFile, manifest.mainSessionId);
+			channels.push({ directory, mainSessionId: manifest.mainSessionId });
 		}
 	}
+	// Recorded paths also protect Mains using a custom store outside native discovery.
+	for (const [file, id] of ownerFiles) {
+		if (live.has(id)) continue;
+		const main = await inspectSession(file, undefined, true);
+		if (main?.id === id) live.add(id);
+	}
+
 	let removed = 0;
-	const errors: string[] = [];
-	for (const store of stores) {
-		const liveDirectories = new Set([...live].map(store.ownerDirectory));
-		for (const entry of store.candidates) {
-			if (liveDirectories.has(entry.name)) continue;
-			const directory = path.join(store.root, entry.name);
-			try {
-				// Do not follow a directory replaced with a symlink during discovery.
-				if (!fs.lstatSync(directory).isDirectory()) continue;
-				fs.rmSync(directory, { recursive: true, force: true });
-				removed++;
-			} catch (error) {
-				errors.push(`${directory}: ${error instanceof Error ? error.message : String(error)}`);
-			}
+	let removedChannels = 0;
+	// Discovery must finish successfully before any destructive operation.
+	for (const session of sessions) {
+		if (session.id === currentSessionId || live.has(session.owner!.mainSessionId)) continue;
+		try {
+			if (!fs.lstatSync(session.file).isFile()) continue;
+			fs.unlinkSync(session.file);
+			removed++;
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") errors.push(`${session.file}: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+	for (const channel of channels) {
+		if (live.has(channel.mainSessionId)) continue;
+		try {
+			if (!fs.lstatSync(channel.directory).isDirectory()) continue;
+			fs.rmSync(channel.directory, { recursive: true, force: true });
+			removedChannels++;
+			try { fs.rmdirSync(path.dirname(channel.directory)); }
+			catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOTEMPTY" && (error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") errors.push(`${channel.directory}: ${error instanceof Error ? error.message : String(error)}`);
 		}
 	}
-	return { removed, errors };
+	return { removed, removedChannels, errors };
 }
 
-export function registerCleanSubCommand(pi: ExtensionAPI): void {
+export function registerCleanSubCommand(pi: ExtensionAPI, owningMainId?: string): void {
 	pi.registerCommand("clean-sub", {
-		description: "Delete managed Sub sessions and communication directories whose Main session can no longer be found.",
+		description: "Delete orphaned Sub sessions across Pi's native session store and orphaned communication files.",
 		handler: async (_args, ctx) => {
 			try {
-				const result = cleanSubFiles(ctx.sessionManager.getSessionId(), ctx.sessionManager.getSessionDir());
+				const result = await cleanSubFiles(owningMainId ?? ctx.sessionManager.getSessionId(), ctx.sessionManager.getSessionDir());
 				ctx.ui.notify([
-					`Removed ${result.removed} orphaned Sub data directories (sessions and communication).`,
+					`Removed ${result.removed} orphaned Sub sessions and ${result.removedChannels} communication directories.`,
 					...result.errors,
 				].join("\n"), result.errors.length ? "warning" : "info");
 			} catch (error) {
@@ -87,4 +164,13 @@ export function registerCleanSubCommand(pi: ExtensionAPI): void {
 			}
 		},
 	});
+	pi.on("session_shutdown", async (event, ctx) => {
+		if (event.reason !== "quit") return;
+		try {
+			const result = await cleanSubFiles(owningMainId ?? ctx.sessionManager.getSessionId(), ctx.sessionManager.getSessionDir(), ctx.cwd);
+			if (result.errors.length) ctx.ui.notify(`Sub cleanup: ${result.errors.join("\n")}`, "warning");
+		} catch (error) {
+			ctx.ui.notify(`Sub cleanup aborted: ${error instanceof Error ? error.message : String(error)}`, "warning");
+		}
+	});
 }

package/src/profiles/system-prompt.ts

@@ -13,7 +13,9 @@ export function bindPromptSections(pi: ExtensionAPI, keys: readonly string[], ge
 }
 
 export const SUB_PROTOCOL = `## Pi Subagent Sub protocol
-You are an isolated Sub Pi working with a Main Pi. You have not received the Main's conversation and must not read Pi session files. Use talk whenever you need information from the Main or need to deliver work. Each talk sends one message to the Main and ends the current turn. Remain available after delivery. The Main alone decides whether to respond, request more work, or close this Sub session. Never close the session yourself.`;
+You are an isolated Sub Pi working with a Main Pi. You have not received the Main's conversation and must not read Pi session files.
+Use talk to report progress, ask for information, or deliver completed work. Make clear in the message whether it is a progress update, a blocking question, or completed work. By default, talk only sends the message. After a progress update, continue the assigned task without waiting for Main to acknowledge or say 'continue'.
+Set endTurn=true only when the task is complete or you must wait for Main's reply before proceeding. Call terminating talk on its own, without other tools in the same batch. Ending a turn does not close the session; remain available for follow-ups. The Main alone decides whether to respond, request more work, or close this Sub session. Never close the session yourself.`;
 
 export function applySubPromptSections(sections: Record<string, string>, profile: ResolvedProfile): void {
 	sections.subagent_sub_protocol = SUB_PROTOCOL;

package/src/run-manager.ts

@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
+import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { AdapterRegistry } from "./adapters/index.js";
@@ -189,11 +190,16 @@ export class MainRunManager {
 		}
 		const runId = randomUUID();
 		const mainSessionId = this.ctx.sessionManager.getSessionId();
+		const mainSessionFile = this.ctx.sessionManager.getSessionFile();
+		const subSessionId = resume?.sessionId ?? `sub-${randomUUID()}`;
 		const projectTrusted = this.ctx.isProjectTrusted();
 		const cwd = resume?.cwd ?? input.cwd;
+		const sessionDir = resume ? path.dirname(resume.sessionFile)
+			: path.resolve(cwd) === path.resolve(this.ctx.cwd) ? this.ctx.sessionManager.getSessionDir() : undefined;
 		const channel = createChannel({
 			runId,
 			mainSessionId,
+			...(mainSessionFile ? { mainSessionFile } : {}),
 			title: input.title,
 			task: input.task,
 			cwd,
@@ -212,7 +218,8 @@ export class MainRunManager {
 			channelDir: channel.channelDir,
 			createdAt: Date.now(),
 			updatedAt: Date.now(),
-			...(resume ? { subSessionId: resume.sessionId, subSessionFile: resume.sessionFile } : {}),
+			subSessionId,
+			...(resume ? { subSessionFile: resume.sessionFile } : {}),
 		};
 		try {
 			this.save(run);
@@ -226,7 +233,9 @@ export class MainRunManager {
 				cwd,
 				projectTrusted,
 				...(input.origin ? { origin: input.origin } : {}),
-				...(resume ? { resumeSessionId: resume.sessionId, resumeSessionFile: resume.sessionFile } : {}),
+				sessionId: subSessionId,
+				sessionDir,
+				...(resume ? { resumeSessionFile: resume.sessionFile } : {}),
 				profile: input.profile,
 				channelDir: channel.channelDir,
 				token: channel.token,

package/src/sessions.ts

@@ -1,15 +1,43 @@
 import * as fs from "node:fs";
-import * as path from "node:path";
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext, SessionEntry } from "@earendil-works/pi-coding-agent";
 import type { RunSnapshot } from "./types.js";
 
-export function subSessionsRoot(): string {
-	return path.join(getAgentDir(), "subagent", "sessions");
+export const SUB_OWNER_ENTRY = "subagent-owner";
+export const SUB_SESSION_ID = /^sub-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+export interface SubSessionOwner {
+	version: 1;
+	subSessionId: string;
+	mainSessionId: string;
+	mainSessionFile?: string;
+}
+
+export function parseSubSessionOwner(value: unknown): SubSessionOwner {
+	const owner = value as Partial<SubSessionOwner> | undefined;
+	if (!owner || owner.version !== 1 || typeof owner.subSessionId !== "string"
+		|| typeof owner.mainSessionId !== "string" || !owner.mainSessionId
+		|| (owner.mainSessionFile !== undefined && typeof owner.mainSessionFile !== "string")) {
+		throw new Error("Invalid Sub session owner metadata.");
+	}
+	return owner as SubSessionOwner;
 }
 
-export function subSessionDir(mainSessionId: string): string {
-	if (!mainSessionId || mainSessionId === "." || mainSessionId === "..") throw new Error("Invalid Main session ID.");
-	return path.join(subSessionsRoot(), encodeURIComponent(mainSessionId));
+/** Ownership is session-wide, not branch-relative. Never silently reassign a Sub. */
+export function recordSubSessionOwner(pi: ExtensionAPI, ctx: ExtensionContext, mainSessionId: string, mainSessionFile?: string): void {
+	const subSessionId = ctx.sessionManager.getSessionId();
+	const entries = ctx.sessionManager.getEntries().filter((entry): entry is SessionEntry & { type: "custom" } =>
+		entry.type === "custom" && entry.customType === SUB_OWNER_ENTRY);
+	let previous: SubSessionOwner | undefined;
+	for (const entry of entries) {
+		const owner = parseSubSessionOwner(entry.data);
+		if (owner.subSessionId !== subSessionId || owner.mainSessionId !== mainSessionId) {
+			throw new Error("Sub session owner does not match this Main.");
+		}
+		previous = owner;
+	}
+	if (!previous || previous.mainSessionFile !== mainSessionFile) {
+		pi.appendEntry(SUB_OWNER_ENTRY, { version: 1, subSessionId, mainSessionId, ...(mainSessionFile ? { mainSessionFile } : {}) } satisfies SubSessionOwner);
+	}
 }
 
 export interface ResumableSubSession {

package/src/tools/main.ts

@@ -58,7 +58,7 @@ export function registerMainTools(pi: ExtensionAPI, manager: MainRunManager): vo
 			"Use delegate for work assigned by MAIN.md or a separable task that benefits from an independent context; select an explicitly configured profile and provide a short informative title.",
 			"After delegate launches, do not wait or repeatedly poll. Pi Subagent will wake the Main when the Sub uses talk.",
 			"For Subs labeled user-invoked specialists, follow up only on the user's task and results. Do not assign unrelated work or substitute them for general consulting profiles. New tasks are initiated by the user through a profile command.",
-			"Use talk to respond to an existing Sub, interrupt_sub to stop its current turn without closing it, and close_sub only after its delivery is accepted or the user asks to close it.",
+			"Use talk to respond to an existing Sub, interrupt_sub to stop its current turn without closing it, and close_sub only after its completed work is accepted or the user asks to close it.",
 		],
 		parameters: Type.Object({
 			title: Type.String({ description: "Short Herdr tab title, up to 48 displayed characters." }),
@@ -131,6 +131,7 @@ export function registerMainTools(pi: ExtensionAPI, manager: MainRunManager): vo
 		label: "talk",
 		description: "Send one message to an existing Sub Pi. Messages enter the Sub's native follow-up queue and are processed after its current work. Format non-trivial messages as readable Markdown with paragraph breaks and lists.",
 		promptSnippet: "Send a message to an existing Sub Pi",
+		promptGuidelines: ["Sub talk messages may be progress updates while the Sub keeps working. Do not send routine 'continue' replies or close a Sub merely for reporting progress; respond with talk when input is needed, and use close_sub only after completed work is accepted or the user asks to close it."],
 		executionMode: "sequential",
 		parameters: Type.Object({
 			runId: Type.String({ description: "Full Sub run ID or a unique prefix." }),

package/src/tools/sub.ts

@@ -21,6 +21,8 @@ import { applyProfileTools } from "../profiles/tool-selection.js";
 import { MANUAL_SUB_GUIDANCE, subSessionName } from "../manual-context.js";
 import { talkView } from "../talk-render.js";
 import { ChannelMonitor } from "../channel-monitor.js";
+import { recordSubSessionOwner } from "../sessions.js";
+import { registerCleanSubCommand } from "../commands/clean-sub.js";
 import { bindInboxEvents } from "../inbox-state.js";
 import { deliverTalk, ProtocolErrors } from "../talk-delivery.js";
 import type { ActiveTurn, DelegateManifest } from "../types.js";
@@ -61,6 +63,12 @@ export function registerSub(pi: ExtensionAPI): void {
 	);
 	bindInboxEvents(pi, () => activeContext, () => monitor.wakeAll());
 
+	// Fork/clone would copy ownership metadata into a different session.
+	pi.on("session_before_fork", (_event, ctx) => {
+		ctx.ui.notify("Sub sessions do not support /fork or /clone.", "warning");
+		return { cancel: true };
+	});
+
 	// Pi emits resource discovery after all session_start handlers, including
 	// extensions that register the profile's tools dynamically during startup.
 	pi.on("resources_discover", (_event, ctx) => {
@@ -77,6 +85,7 @@ export function registerSub(pi: ExtensionAPI): void {
 
 	pi.on("session_start", (_event, ctx) => {
 		activeContext = ctx;
+		recordSubSessionOwner(pi, ctx, loaded.manifest.mainSessionId, loaded.manifest.mainSessionFile);
 		pi.setSessionName(subSessionName(loaded.manifest.title, loaded.manifest.origin));
 		ctx.ui.setTitle(`[sub] ${loaded.manifest.title}`);
 		ctx.ui.setStatus("subagent", `sub · ${loaded.manifest.profile.name}`);
@@ -174,12 +183,16 @@ export function registerSub(pi: ExtensionAPI): void {
 		name: "talk",
 		label: "talk",
 		exposure: "model-only",
-		description: "Send one message to the Main Pi and end the current turn. Use it to ask for information or deliver work. Format non-trivial messages as readable Markdown with paragraph breaks and lists.",
-		promptSnippet: "Send a message to the Main Pi",
-		promptGuidelines: ["Use talk whenever the Sub needs to communicate with the Main; the Main decides when to close the Sub session."],
+		description: "Send one message to the Main Pi. Continue working by default; set endTurn=true only when the task is complete or you must wait for Main's reply. Format non-trivial messages as readable Markdown with paragraph breaks and lists.",
+		promptSnippet: "Send a message to the Main Pi, optionally ending the current turn",
+		promptGuidelines: [
+			"Use talk for progress updates, questions, and completed work. After progress updates, continue the task without waiting for an acknowledgement.",
+			"Set talk endTurn=true only when the task is complete or you must wait for Main's reply. Call terminating talk on its own, without other tools in the same batch. The Main decides when to close the Sub session.",
+		],
 		executionMode: "sequential",
 		parameters: Type.Object({
 			message: Type.String({ description: "Message to the other Agent. For non-trivial content, use readable Markdown with paragraph breaks and lists." }),
+			endTurn: Type.Optional(Type.Boolean({ description: "End the current turn after sending. Defaults to false: continue working. Set true only when the task is complete or you must wait for Main's reply." })),
 		}),
 		renderCall(args, theme, context) {
 			const message = typeof args.message === "string" ? args.message : "";
@@ -196,7 +209,7 @@ export function registerSub(pi: ExtensionAPI): void {
 			return {
 				content: [{ type: "text", text: "Message queued for the Main Pi." }],
 				details: { messageId: message.id },
-				terminate: true,
+				terminate: params.endTurn === true,
 			};
 		},
 		renderResult(result, _options, theme, context) {
@@ -212,4 +225,6 @@ export function registerSub(pi: ExtensionAPI): void {
 			writeSubClosed(loaded.channelDir, loaded.manifest, "The Sub session was closed manually.");
 		}
 	});
+	// Run after the Sub shutdown protocol, and preserve its still-active owning Main.
+	registerCleanSubCommand(pi, loaded.manifest.mainSessionId);
 }

package/src/types.ts

@@ -4,6 +4,7 @@ export interface DelegateManifest {
 	version: 1;
 	runId: string;
 	mainSessionId: string;
+	mainSessionFile?: string;
 	title: string;
 	task: string;
 	cwd: string;
@@ -96,8 +97,9 @@ export interface SubLaunchSpec {
 	cwd: string;
 	projectTrusted: boolean;
 	origin?: "manual";
-	resumeSessionId?: string;
-	/** Recorded path also supports sessions saved before per-Main directories. */
+	sessionId: string;
+	/** Same-cwd Subs inherit Main's session directory, including custom stores. */
+	sessionDir?: string;
 	resumeSessionFile?: string;
 	profile: ResolvedProfile;
 	channelDir: string;