pi-cohort 7.6.1 → 7.6.3

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [7.6.3] - 2026-10-28
+
+### Added
+- Every child process gets `PI_SUBAGENT_PARENT_SESSION_ID`, the pi session id of the session that launched it, so a session roster can link each child to its parent without parsing the session name. A nested child gets its immediate parent's id. The README now lists `PI_SUBAGENT_CHILD`, `PI_SUBAGENT_CHILD_AGENT`, `PI_SUBAGENT_RUN_ID`, and `PI_SUBAGENT_PARENT_SESSION_ID` as stable inputs for other extensions. (#34)
+
+## [7.6.2] - 2026-10-28
+
+### Added
+- Each child session is named `<agent> <run id prefix>[/<index>] from <parent>`, where `<parent>` is the parent session's name or, when unnamed, its id. `/resume`, terminal titles, and live-session rosters now tell children apart instead of listing unnamed sessions. (#32)
+
 ## [7.6.1] - 2026-10-26
 
 ### Added

package/README.md

@@ -167,6 +167,25 @@ Review and delivery workflows live in pi-gauntlet; pi-cohort ships delegation pr
 
 `context: "fork"` starts a child from a real branched session instead of a fresh one, when it needs the parent's history. Cost across the whole subtree - main loop plus every foreground/background/nested child - rolls up into one `Σ$` total in the footer; see [doc/observability.md](doc/observability.md).
 
+Each child session is named `<agent> <run id prefix>[/<index>] from <parent>`, so `/resume`, terminal titles, and live-session rosters can tell children apart:
+
+| Child | Session name |
+|---|---|
+| Single `scout` from a session named `billing reports` | `scout 3f9a2c1e from billing reports` |
+| Third task (index 2) of the same parallel run | `scout 3f9a2c1e/2 from billing reports` |
+| `scout` from an unnamed session | `scout 3f9a2c1e from <parent session id>` |
+
+The run id prefix works as the `id` for `subagent` status, interrupt, and resume; the index is the child `index` for resume. A nested child names its parent child: `worker 7b41d0aa from scout 3f9a2c1e from billing reports`.
+
+Every child process also gets these environment variables, stable inputs for other extensions (for example, a session roster linking each child to its parent):
+
+| Variable | Value | Set |
+|---|---|---|
+| `PI_SUBAGENT_CHILD` | `1` | on every child |
+| `PI_SUBAGENT_CHILD_AGENT` | the child's agent name | when the agent is known |
+| `PI_SUBAGENT_RUN_ID` | the full run id; its prefix appears in the session name | when the run id is known |
+| `PI_SUBAGENT_PARENT_SESSION_ID` | the pi session id of the session that launched the child | on every child; a nested child gets its immediate parent's id, never an inherited ancestor's |
+
 Full reference: agent/chain authoring in [doc/agents-and-chains.md](doc/agents-and-chains.md), exact command syntax in [doc/commands.md](doc/commands.md), the raw tool API in [doc/programmatic-api.md](doc/programmatic-api.md).
 
 ## Key concepts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-cohort",
-  "version": "7.6.1",
+  "version": "7.6.3",
   "description": "Delegate Pi work to focused child agents: code review, scouting, implementation, parallel audits, saved chains, and background jobs.",
   "author": "Jacek Juraszek",
   "license": "MIT",

package/src/runs/background/async-execution.ts

@@ -57,6 +57,10 @@ interface AsyncExecutionContext {
 	parentModel?: string;
 	/** Parent session thinking level, captured at dispatch */
 	parentThinking?: string;
+	/** Parent session display name, or its id when unnamed, captured at dispatch */
+	parentSessionLabel?: string;
+	/** Parent session id, captured at dispatch */
+	parentSessionId?: string;
 	executionBackend?: string;
 }
 
@@ -632,6 +636,8 @@ export function executeAsyncChain(
 				sessionDir: path.join(sessionRoot ?? path.join(RUN_STATE_ROOT_DIR, "sessions"), `async-${id}`),
 				asyncDir,
 				sessionId: ctx.currentSessionId,
+				parentSessionLabel: ctx.parentSessionLabel,
+				parentSessionId: ctx.parentSessionId,
 				runtime: ctx.runtime,
 				forwardedFlags,
 				worktreeSetupHook,
@@ -846,6 +852,8 @@ export function executeAsyncSingle(
 				sessionDir: path.join(sessionRoot ?? path.join(RUN_STATE_ROOT_DIR, "sessions"), `async-${id}`),
 				asyncDir,
 				sessionId: ctx.currentSessionId,
+				parentSessionLabel: ctx.parentSessionLabel,
+				parentSessionId: ctx.parentSessionId,
 				runtime: ctx.runtime,
 				forwardedFlags,
 				worktreeSetupHook,

package/src/runs/background/subagent-runner.ts

@@ -117,6 +117,8 @@ interface SubagentRunConfig {
 	sessionDir?: string;
 	asyncDir: string;
 	sessionId?: string | null;
+	parentSessionLabel?: string;
+	parentSessionId?: string;
 	runtime: PiRuntimeIdentity;
 	forwardedFlags?: string[];
 	worktreeSetupHook?: string;
@@ -625,6 +627,8 @@ export interface SingleStepContext {
 	outputFile: string;
 	runtime: PiRuntimeIdentity;
 	forwardedFlags?: string[];
+	parentSessionLabel?: string;
+	parentSessionId?: string;
 	registerInterrupt?: (interrupt: (() => void) | undefined) => void;
 	nestedRoute?: NestedRouteInfo;
 	onAttemptStart?: (attempt: { model?: string; thinking?: string }) => void;
@@ -790,6 +794,8 @@ export async function runSingleStep(
 					runId: ctx.id,
 					childAgentName: step.agent,
 					childIndex: ctx.flatIndex,
+					parentSessionLabel: ctx.parentSessionLabel,
+					parentSessionId: ctx.parentSessionId,
 					parentEventSink: ctx.nestedRoute?.eventSink,
 					parentControlInbox: ctx.nestedRoute?.controlInbox,
 					parentRootRunId: ctx.nestedRoute?.rootRunId,
@@ -936,6 +942,8 @@ export async function runSingleStep(
 			runId: ctx.id,
 			childAgentName: step.agent,
 			childIndex: ctx.flatIndex,
+			parentSessionLabel: ctx.parentSessionLabel,
+			parentSessionId: ctx.parentSessionId,
 			parentEventSink: ctx.nestedRoute?.eventSink,
 			parentControlInbox: ctx.nestedRoute?.controlInbox,
 			parentRootRunId: ctx.nestedRoute?.rootRunId,
@@ -1978,6 +1986,8 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 					runtime: config.runtime,
 					controlConfig: config.controlConfig,
 					forwardedFlags: config.forwardedFlags,
+					parentSessionLabel: config.parentSessionLabel,
+					parentSessionId: config.parentSessionId,
 					executionBackendCoordinator,
 					executionBackendConfig,
 					nestedRoute: config.nestedRoute,
@@ -2268,6 +2278,8 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 							runtime: config.runtime,
 							controlConfig: config.controlConfig,
 							forwardedFlags: config.forwardedFlags,
+							parentSessionLabel: config.parentSessionLabel,
+							parentSessionId: config.parentSessionId,
 							executionBackendCoordinator,
 							executionBackendConfig,
 							nestedRoute: config.nestedRoute,
@@ -2448,6 +2460,8 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 				runtime: config.runtime,
 				controlConfig: config.controlConfig,
 				forwardedFlags: config.forwardedFlags,
+				parentSessionLabel: config.parentSessionLabel,
+				parentSessionId: config.parentSessionId,
 				executionBackendCoordinator,
 				executionBackendConfig,
 				nestedRoute: config.nestedRoute,

package/src/runs/foreground/chain-execution.ts

@@ -9,6 +9,7 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { AgentConfig } from "../../agents/agents.ts";
 import { ChainClarifyComponent, type ChainClarifyResult, type BehaviorOverride } from "./chain-clarify.ts";
 import { parentModelFullId, toModelInfo, type ModelInfo } from "../../shared/model-info.ts";
+import { resolveSessionLabel } from "../../shared/session-identity.ts";
 import {
 	resolveChainTemplates,
 	createChainDir,
@@ -318,6 +319,8 @@ async function runParallelChainTasks(input: ParallelChainRunInput): Promise<Sing
 				preferredModelProvider: input.ctx.model?.provider,
 				parentModel: parentModelFullId(input.ctx.model),
 				parentThinking: input.ctx.thinkingLevel,
+				parentSessionLabel: resolveSessionLabel(input.ctx.sessionManager),
+				parentSessionId: input.ctx.sessionManager.getSessionId(),
 				skills: behavior.skills === false ? [] : behavior.skills,
 				structuredOutput: structuredRuntime,
 				acceptance: task.acceptance,
@@ -1161,6 +1164,8 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 					preferredModelProvider: ctx.model?.provider,
 					parentModel: parentModelFullId(ctx.model),
 					parentThinking: ctx.thinkingLevel,
+					parentSessionLabel: resolveSessionLabel(ctx.sessionManager),
+					parentSessionId: ctx.sessionManager.getSessionId(),
 					skills: behavior.skills === false ? [] : behavior.skills,
 					structuredOutput: structuredRuntime,
 					acceptance: seqStep.acceptance,

package/src/runs/foreground/execution.ts

@@ -158,6 +158,8 @@ async function runSingleAttempt(
 		runId: options.runId,
 		childAgentName: agent.name,
 		childIndex: options.index ?? 0,
+		parentSessionLabel: options.parentSessionLabel,
+		parentSessionId: options.parentSessionId,
 		parentEventSink: options.nestedRoute?.eventSink,
 		parentControlInbox: options.nestedRoute?.controlInbox,
 		parentRootRunId: options.nestedRoute?.rootRunId,

package/src/runs/foreground/external-single-attempt.ts

@@ -92,6 +92,8 @@ export async function runExternalSingleAttempt(input: RunExternalSingleAttemptIn
 		runId: options.runId,
 		childAgentName: agent.name,
 		childIndex: options.index ?? 0,
+		parentSessionLabel: options.parentSessionLabel,
+		parentSessionId: options.parentSessionId,
 		parentEventSink: options.nestedRoute?.eventSink,
 		parentControlInbox: options.nestedRoute?.controlInbox,
 		parentRootRunId: options.nestedRoute?.rootRunId,

package/src/runs/foreground/subagent-executor.ts

@@ -37,7 +37,7 @@ import {
 import { discoverAvailableSkills, normalizeSkillInput } from "../../agents/skills.ts";
 import { executeAsyncChain, executeAsyncSingle, formatAsyncStartedMessage, isAsyncAvailable } from "../background/async-execution.ts";
 import { createForkContextResolver } from "../../shared/fork-context.ts";
-import { resolveCurrentSessionId } from "../../shared/session-identity.ts";
+import { resolveCurrentSessionId, resolveSessionLabel } from "../../shared/session-identity.ts";
 import { formatControlNoticeMessage, resolveControlConfig, shouldNotifyControlEvent } from "../shared/subagent-control.ts";
 import { finalizeSingleOutput, injectSingleOutputInstruction, normalizeTopLevelOutput, resolveParallelTaskOutputPath, resolveSingleOutputPath, validateFileOnlyOutputMode } from "../shared/single-output.ts";
 import { blockedLine } from "../shared/completion-guard.ts";
@@ -225,6 +225,8 @@ function buildAsyncContext(ctx: ExtensionContext, deps: CallExecutorDeps, cwd: s
 		currentModelProvider: ctx.model?.provider,
 		parentModel: parentModelFullId(ctx.model),
 		parentThinking: ctx.thinkingLevel,
+		parentSessionLabel: resolveSessionLabel(ctx.sessionManager),
+		parentSessionId: ctx.sessionManager.getSessionId(),
 		executionBackend: deps.config.executionBackend,
 	};
 }
@@ -1503,6 +1505,8 @@ async function runForegroundParallelTasks(input: ForegroundParallelRunInput): Pr
 			preferredModelProvider: input.ctx.model?.provider,
 			parentModel: parentModelFullId(input.ctx.model),
 			parentThinking: input.ctx.thinkingLevel,
+			parentSessionLabel: resolveSessionLabel(input.ctx.sessionManager),
+			parentSessionId: input.ctx.sessionManager.getSessionId(),
 			skills: effectiveSkills === false ? [] : effectiveSkills,
 			acceptance: task.acceptance,
 			acceptanceContext: { mode: "parallel" },
@@ -2064,6 +2068,8 @@ async function runSinglePath(data: ExecutionContextData, deps: CallExecutorDeps)
 		preferredModelProvider: currentProvider,
 		parentModel: parentModelFullId(ctx.model),
 		parentThinking: ctx.thinkingLevel,
+		parentSessionLabel: resolveSessionLabel(ctx.sessionManager),
+		parentSessionId: ctx.sessionManager.getSessionId(),
 		skills: effectiveSkills,
 		acceptance: params.acceptance,
 		acceptanceContext: { mode: "single" },

package/src/runs/shared/pi-args.ts

@@ -24,6 +24,7 @@ export const SUBAGENT_PARENT_CHILD_INDEX_ENV = "PI_SUBAGENT_PARENT_CHILD_INDEX";
 export const SUBAGENT_PARENT_DEPTH_ENV = "PI_SUBAGENT_PARENT_DEPTH";
 export const SUBAGENT_PARENT_PATH_ENV = "PI_SUBAGENT_PARENT_PATH";
 export const SUBAGENT_PARENT_CAPABILITY_TOKEN_ENV = "PI_SUBAGENT_PARENT_CAPABILITY_TOKEN";
+export const SUBAGENT_PARENT_SESSION_ID_ENV = "PI_SUBAGENT_PARENT_SESSION_ID";
 
 interface BuildPiArgsInput {
 	baseArgs: string[];
@@ -45,6 +46,9 @@ interface BuildPiArgsInput {
 	runId?: string;
 	childAgentName?: string;
 	childIndex?: number;
+	/** Parent session display name, or its id when unnamed; names the child session. */
+	parentSessionLabel?: string;
+	parentSessionId?: string;
 	parentEventSink?: string;
 	parentControlInbox?: string;
 	parentRootRunId?: string;
@@ -79,6 +83,13 @@ export function applyThinkingSuffix(model: string | undefined, thinking: string
 	return `${model}:${thinking}`;
 }
 
+function childSessionName(input: BuildPiArgsInput): string | undefined {
+	if (!input.childAgentName || !input.runId) return undefined;
+	const index = input.childIndex ? `/${input.childIndex}` : "";
+	const parent = input.parentSessionLabel ? ` from ${input.parentSessionLabel}` : "";
+	return `${input.childAgentName} ${input.runId.slice(0, 8)}${index}${parent}`;
+}
+
 export function buildPiArgs(input: BuildPiArgsInput, fileSystem: BuildPiArgsFileSystem = fs): BuildPiArgsResult {
 	const args = [...input.baseArgs];
 	// Forwarded flags are already name-deduped by deriveForwardedFlags; append only
@@ -100,6 +111,11 @@ export function buildPiArgs(input: BuildPiArgsInput, fileSystem: BuildPiArgsFile
 		}
 	}
 
+	const sessionName = childSessionName(input);
+	if (sessionName) {
+		args.push("--name", sessionName);
+	}
+
 	const modelArg = applyThinkingSuffix(input.model, input.thinking);
 	if (modelArg) {
 		args.push("--model", modelArg);
@@ -204,6 +220,8 @@ export function buildPiArgs(input: BuildPiArgsInput, fileSystem: BuildPiArgsFile
 	env[SUBAGENT_PARENT_CAPABILITY_TOKEN_ENV] = fanoutAuthorized
 		? input.parentCapabilityToken ?? process.env[SUBAGENT_PARENT_CAPABILITY_TOKEN_ENV] ?? ""
 		: "";
+	// Always set, so a grandchild sees its immediate parent rather than an inherited ancestor.
+	env[SUBAGENT_PARENT_SESSION_ID_ENV] = input.parentSessionId ?? "";
 	env.PI_SUBAGENT_INHERIT_PROJECT_CONTEXT = input.inheritProjectContext ? "1" : "0";
 	env.PI_SUBAGENT_INHERIT_SKILLS = input.inheritSkills ? "1" : "0";
 	if (input.runId) {

package/src/shared/session-identity.ts

@@ -3,8 +3,18 @@ interface SessionIdentityManager {
 	getSessionId(): string | null | undefined;
 }
 
+interface SessionLabelManager {
+	getSessionName(): string | undefined;
+	getSessionId(): string;
+}
+
 export function resolveCurrentSessionId(sessionManager: SessionIdentityManager): string {
 	const sessionId = sessionManager.getSessionFile() ?? sessionManager.getSessionId();
 	if (!sessionId) throw new Error("Current session identity is unavailable.");
 	return sessionId;
 }
+
+/** The session's display name, or its id when unnamed. */
+export function resolveSessionLabel(sessionManager: SessionLabelManager): string {
+	return sessionManager.getSessionName() || sessionManager.getSessionId();
+}

package/src/shared/types.ts

@@ -830,6 +830,10 @@ export interface RunSyncOptions {
 	parentModel?: string;
 	/** Parent session thinking level; used when the agent sets no `thinking` */
 	parentThinking?: string;
+	/** Parent session display name, or its id when unnamed; names the child session */
+	parentSessionLabel?: string;
+	/** Parent session id; exported to the child as PI_SUBAGENT_PARENT_SESSION_ID */
+	parentSessionId?: string;
 	/** Skills to inject (overrides agent default if provided) */
 	skills?: string[];
 	structuredOutput?: {