pi-cohort 7.0.2 → 7.1.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [7.1.1] - 2026-09-24
+
+### Changed
+
+- A dispatch that names no model now runs the child on the parent session's current model and thinking level instead of the child's saved `defaultModel`; `thinking: off` is emitted as `:off`, and `max` is a recognized level. Precedence: per-call `model:` > agent `model` / `thinking` (after `agentOverrides`) > parent session > none. Pin `subagents.agentOverrides.<agent>.model` to keep a child on a fixed model. Agents that pin `model` but not `thinking` now also take the parent's thinking level; set `thinking` to keep a fixed level. Children now bill on the parent's model, and an agent with `extensions:` whose parent model comes from an extension provider fails as an unknown model would; give it a pinned model or `fallbackModels`.
+
+## [7.1.0] - 2026-09-20
+
+### Changed
+
+- `/handoff` no longer expands; `/skill:handoff [--out <path> | --key <stem>]` replaces it, writes to `<tmpdir>/pi-handoff/<primary>--<leaf>.md` by default and ends with `Handoff written: <path>`; `## Process state` is no longer produced here; argument-less `gauntlet-resume` lookup of that path lands on the pi-gauntlet side - until then resume takes the printed path. ([#18](https://github.com/jjuraszek/pi-cohort/issues/18), [pi-gauntlet#40](https://github.com/jjuraszek/pi-gauntlet/issues/40))
+
 ## [7.0.2] - 2026-09-20
 
 ### Changed

package/README.md

@@ -117,7 +117,7 @@ Run parallel reviewers: one for correctness, one for tests, and one for unnecess
 
 That's the whole surface for day-to-day use. More phrasing patterns: [doc/commands.md](doc/commands.md#prompt-cookbook-appendix).
 
-Review and delivery workflows live in pi-gauntlet; pi-cohort ships delegation primitives plus `/investigate` and `/handoff`.
+Review and delivery workflows live in pi-gauntlet; pi-cohort ships delegation primitives plus `/investigate` and `/skill:handoff [--out <path> | --key <stem>]` (the brief lands in `<tmpdir>/pi-handoff/<primary>--<leaf>.md` by default; contract in [doc/handoff-template.md](doc/handoff-template.md)).
 
 ## Architecture
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-cohort",
-  "version": "7.0.2",
+  "version": "7.1.1",
   "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/skills/handoff/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: handoff
+description: Use when the context window is nearly full and the work must continue in a fresh session.
+---
+
+# Handoff brief
+
+Write a handoff brief for a fresh session. The brief is the contract in `doc/handoff-template.md` of pi-cohort: section names and order are fixed. This file carries every rule a producer needs; a caller that follows it reads nothing else. Nothing is written into the repository.
+
+## Argument
+
+The argument text, if any, follows this block. Tokenize it shell-like (unquoted tokens end at whitespace; `".."`/`'..'` keep whitespace; `--opt=value` is one token). An option's value is the next token; a next token that is itself `--out`, `--key`, or an `--out=`/`--key=` form, or no next token, or an empty `--opt=` value, means the option has no value. `--out <path>` names the output file (relative resolves against cwd); `--key <stem>` names the file inside the shared mailbox directory; every other token is ignored.
+
+Argument failures end the reply with the line and write nothing:
+
+- an option with an empty or missing value -> `Handoff not written: <option> has no value`
+- an option given twice -> `Handoff not written: <option> given twice`
+- both options -> `Handoff not written: --out and --key are exclusive`
+
+## Rules
+
+- Scratch dir, invocation-unique so overlapping invocations never read each other's snapshot: `SCRATCH=$(node -p "require('fs').mkdtempSync(require('path').join(require('os').tmpdir(), 'pi-handoff-'))")`. If `node` is missing -> `Handoff not written: cannot resolve tmpdir`.
+- The snapshot dispatch: `async: false` and `context: "fresh"` at the top level; `reads: false`; absolute `output` under `$SCRATCH`. If it returns an async handle, a `forceTopLevelAsync` setting is active: report that in the reply, do not poll, relaunch, or continue the child, and write the brief with `## Repo state: unavailable (async handle returned)`.
+- The child is read-only against the repository; its only write is its `output` file.
+- You write `## Intent`, `## Decisions`, `## Open questions`, and `## Skills loaded` from your own transcript, before the call and after it returns. Do not fork a child for this: forking a near-full transcript is the cost this handoff avoids.
+
+## Run worktree
+
+Before the snapshot dispatch, determine the run worktree from your own transcript and interpolate it into the scout task as `Run worktree: <abs path>` or `Run worktree: none`:
+
+- A flow-level worktree the run created (any `git worktree add <path>` you ran, or a `Worktree ready at <path>` report from the skill that set up the worktree) or was told to work in (a resume brief's `worktree: yes <path>`, or a user instruction).
+- Never inferred from the session cwd; a created or assigned worktree still qualifies when it happens to equal the cwd. Never a per-task worktree from `tasks[].worktree: true` or `worktree: true` dispatches - those are ephemeral.
+- Two flow-level worktrees in the transcript: the candidate is the one most recently used by later work (a dispatch `cwd`, a `git -C <path>`, or a `cd <path>`); if that does not distinguish them, the most recent creation or assignment. The other goes into `## Open questions` as `Also seen: <path> - not recorded as the run worktree`.
+- No flow-level worktree created or named: `Run worktree: none`.
+
+## Repo snapshot
+
+```
+subagent({ async: false, context: "fresh", tasks: [
+  { agent: "scout", cwd: "<cwd>", reads: false, output: "<SCRATCH>/repo.md",
+    task: "Read-only; write only to your output path. Run worktree: <abs path|none>. Steps: (1) linked set: git worktree list --porcelain | awk '/^worktree /{print substr($0,10)}' - the first line is the primary checkout, the rest are the linked worktrees; a relative candidate resolves against the primary toplevel, not cwd. (2) candidate `none` or line absent -> target is cwd, go to (4). Otherwise if the candidate is relative, prefix it with the primary toplevel (first linked-set line) first; C=$(git -C <candidate> rev-parse --show-toplevel); valid when that succeeds and C equals one of the linked lines exactly (a line after the first; equality with the first, primary line is invalid); anything else (failure, not listed, the primary itself, prunable) is invalid -> target is cwd and emit the open-question line in (5). (3) valid -> target is $C and `worktree: yes $C`. (4) target cwd -> T=$(git rev-parse --show-toplevel); `worktree: yes $T` when $T equals one of the linked lines exactly (a line after the first; the first, primary line gives `worktree: no`), else `worktree: no`. (5) report each field on its own line, `unavailable` when a command fails, every git command as `git -C <target>`: toplevel (git -C <target> rev-parse --show-toplevel); the worktree line from (3) or (4); branch (git -C <target> branch --show-current, `detached` when empty); HEAD SHA; base (origin/HEAD short name, else origin/main or origin/master if present, else `base: unknown`); dirty (git -C <target> status --porcelain, or `clean`); diff-stat (git -C <target> diff --stat <base>...HEAD; `diff-stat: unavailable` when base is unknown); test command (<target>/package.json scripts or <target>/AGENTS.md). Invalid candidate: after the fields add the single line `open-question: producer named <candidate as submitted> as the run worktree; it is not a linked worktree of this repo`. cwd not a git repo -> the single line `not a git repo`, plus the same open-question line if a candidate was submitted." }
+]})
+```
+
+Outcomes: the fields become `## Repo state`; any `open-question:` line goes into `## Open questions` without its prefix and never into `## Repo state`; `not a git repo` -> `## Repo state: not a git repo`; child failed, file missing or empty, or async handle -> `## Repo state: unavailable (<one-line reason>)`. The brief is written in every outcome - the transcript-derived sections are the point of a handoff.
+
+## Destination
+
+Resolve after the snapshot (the default key needs its `worktree:` line). Precedence: `--out`, then `--key`, then the default key.
+
+- `--out <path>`: that path, made absolute. Its parent directory must exist, else `Handoff not written: parent directory <dir> does not exist`; never fall back to the default when the caller named a path.
+- `--key <stem>`: an exact caller-owned basename stem, written verbatim (no encoding) with `.md` appended - `--key foo.md` gives `foo.md.md`. Valid stem: non-empty after trimming, not `.` or `..`, none of `/`, `\`, NUL, control characters, or `<>:"|?*`, and not starting with `<primary>--` (the default-key prefix). Invalid -> `Handoff not written: --key is not a valid file name stem`; prefixed -> `Handoff not written: --key is reserved for the default key`. Destination `path.join(<tmpdir>, 'pi-handoff', <stem> + '.md')`.
+- Default key `<primary>--<leaf>` at `<tmpdir>/pi-handoff/<primary>--<leaf>.md`, overwritten on each run:
+
+  ```bash
+  TMP=$(node -p "require('os').tmpdir()")
+  PRIMARY=$(basename "$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")")
+  # LEAF: basename of the run worktree when the snapshot says `worktree: yes <path>`;
+  # else `git branch --show-current`; else `detached`
+  enc() { printf '%s' "$1" | sed 's/[^A-Za-z0-9._-]/-/g'; }
+  OUT="$TMP/pi-handoff/$(enc "$PRIMARY")--$(enc "$LEAF").md"
+  ```
+
+  Outside a git repo the key is `no-repo--<encoded cwd basename>`. The encoder `[^A-Za-z0-9._-]` -> `-` applies to the two generated components only, never to a `--key` value. Examples: primary checkout on `main` with no run worktree -> `pi-cohort--main.md`; run worktree `.worktrees/gh-18-handoff-skill` -> `pi-cohort--gh-18-handoff-skill.md`; branch `feat/x` -> `pi-cohort--feat-x.md`.
+- For `--key` and the default, `mkdir -p "$TMP/pi-handoff"` first. Paths are joined with `/`; `os.tmpdir()` covers Windows (`%LOCALAPPDATA%\Temp`).
+
+## Brief
+
+```markdown
+# Handoff: <one line>
+## Intent
+## Repo state
+## Decisions
+## Open questions
+## Skills loaded
+```
+
+- `## Repo state`: the snapshot fields, or one of the heading variants above.
+- `## Decisions`: bullets; rejected alternatives marked `rejected:`.
+- `## Open questions`: bullets, including any copied `open-question:` line and any `Also seen:` line.
+- `## Skills loaded`: the frontmatter `name` of every skill whose SKILL.md body is in your context (a `<skill>` block or a tool result on a `*/SKILL.md` path); it always includes `handoff`.
+
+Write nothing after `## Skills loaded`: a caller that follows this skill and continues in the same session may append its own `##` sections there. Then `rm -rf "$SCRATCH"`, echo the brief, and end the reply with the line `Handoff written: <abs path>`.

package/src/agents/agent-serializer.ts

@@ -42,7 +42,7 @@ export function serializeAgent(config: AgentConfig): string {
 	if (config.model) lines.push(`model: ${config.model}`);
 	const fallbackModelsValue = joinComma(config.fallbackModels);
 	if (fallbackModelsValue) lines.push(`fallbackModels: ${fallbackModelsValue}`);
-	if (config.thinking && config.thinking !== "off") lines.push(`thinking: ${config.thinking}`);
+	if (config.thinking) lines.push(`thinking: ${config.thinking}`);
 	lines.push(`systemPromptMode: ${config.systemPromptMode}`);
 	lines.push(`inheritProjectContext: ${config.inheritProjectContext ? "true" : "false"}`);
 	lines.push(`inheritSkills: ${config.inheritSkills ? "true" : "false"}`);

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

@@ -51,6 +51,10 @@ interface AsyncExecutionContext {
 	cwd: string;
 	currentSessionId: string;
 	currentModelProvider?: string;
+	/** Parent session model as provider/id, captured at dispatch */
+	parentModel?: string;
+	/** Parent session thinking level, captured at dispatch */
+	parentThinking?: string;
 	executionBackend?: string;
 }
 
@@ -355,8 +359,10 @@ export function executeAsyncChain(
 		taskTemplate = taskTemplate.replace(/\{chain_dir\}/g, runnerCwd);
 		const task = injectSingleOutputInstruction(`${readInstructions.prefix}${taskTemplate}${progressInstructions.suffix}`, outputPath);
 
-		const primaryModel = resolveModelCandidate(behavior.model ?? a.model, availableModels, ctx.currentModelProvider);
-		const model = applyThinkingSuffix(primaryModel, a.thinking);
+		const primaryRaw = behavior.model ?? a.model ?? ctx.parentModel;
+		const thinking = a.thinking ?? ctx.parentThinking;
+		const primaryModel = resolveModelCandidate(primaryRaw, availableModels, ctx.currentModelProvider);
+		const model = applyThinkingSuffix(primaryModel, thinking);
 		return {
 			agent: s.agent,
 			task,
@@ -366,9 +372,9 @@ export function executeAsyncChain(
 			structured: Boolean(s.outputSchema),
 			cwd: stepCwd,
 			model,
-			thinking: resolveEffectiveThinking(model, a.thinking),
-			modelCandidates: buildModelCandidates(behavior.model ?? a.model, a.fallbackModels, availableModels, ctx.currentModelProvider).map((candidate) =>
-				applyThinkingSuffix(candidate, a.thinking),
+			thinking: resolveEffectiveThinking(model, thinking),
+			modelCandidates: buildModelCandidates(primaryRaw, a.fallbackModels, availableModels, ctx.currentModelProvider).map((candidate) =>
+				applyThinkingSuffix(candidate, thinking),
 			),
 			tools: a.tools,
 			extensions: a.extensions,
@@ -670,10 +676,9 @@ export function executeAsyncSingle(
 	const validationError = validateFileOnlyOutputMode(outputMode, outputPath, `Async single run (${agent})`);
 	if (validationError) return formatAsyncStartError("single", validationError);
 	const taskWithOutputInstruction = injectSingleOutputInstruction(task, outputPath);
-	const model = applyThinkingSuffix(
-		resolveModelCandidate(params.modelOverride ?? agentConfig.model, availableModels, ctx.currentModelProvider),
-		agentConfig.thinking,
-	);
+	const primaryRaw = params.modelOverride ?? agentConfig.model ?? ctx.parentModel;
+	const thinking = agentConfig.thinking ?? ctx.parentThinking;
+	const model = applyThinkingSuffix(resolveModelCandidate(primaryRaw, availableModels, ctx.currentModelProvider), thinking);
 	let spawnResult: { pid?: number; error?: string } = {};
 	try {
 		spawnResult = spawnRunner(
@@ -685,9 +690,9 @@ export function executeAsyncSingle(
 						task: taskWithOutputInstruction,
 						cwd: runnerCwd,
 						model,
-						thinking: resolveEffectiveThinking(model, agentConfig.thinking),
-						modelCandidates: buildModelCandidates(params.modelOverride ?? agentConfig.model, agentConfig.fallbackModels, availableModels, ctx.currentModelProvider).map((candidate) =>
-							applyThinkingSuffix(candidate, agentConfig.thinking),
+						thinking: resolveEffectiveThinking(model, thinking),
+						modelCandidates: buildModelCandidates(primaryRaw, agentConfig.fallbackModels, availableModels, ctx.currentModelProvider).map((candidate) =>
+							applyThinkingSuffix(candidate, thinking),
 						),
 						tools: agentConfig.tools,
 						extensions: agentConfig.extensions,

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

@@ -11,7 +11,7 @@ import { matchesKey, visibleWidth, truncateToWidth } from "@earendil-works/pi-tu
 import type { AgentConfig } from "../../agents/agents.ts";
 import type { ResolvedStepBehavior } from "../../shared/settings.ts";
 import { resolveModelCandidate, splitThinkingSuffix } from "../shared/model-fallback.ts";
-import { findModelInfo, getSupportedThinkingLevels, type ModelInfo, type ThinkingLevel } from "../../shared/model-info.ts";
+import { findModelInfo, getSupportedThinkingLevels, splitKnownThinkingSuffix, type ModelInfo, type ThinkingLevel } from "../../shared/model-info.ts";
 
 type ClarifyMode = 'single' | 'parallel' | 'chain';
 
@@ -696,9 +696,8 @@ export class ChainClarifyComponent implements Component {
 		const currentModel = this.getEffectiveBehavior(stepIndex).model;
 		if (!currentModel) return;
 
-		const { baseModel } = splitThinkingSuffix(currentModel);
-		const newModel = level === "off" ? baseModel : `${baseModel}:${level}`;
-		this.updateBehavior(stepIndex, "model", newModel);
+		const { baseModel } = splitKnownThinkingSuffix(currentModel);
+		this.updateBehavior(stepIndex, "model", `${baseModel}:${level}`);
 	}
 
 	private filterSkills(): void {
@@ -1009,7 +1008,8 @@ export class ChainClarifyComponent implements Component {
 			"low": "Light reasoning",
 			"medium": "Moderate reasoning",
 			"high": "Deep reasoning",
-			"xhigh": "Maximum reasoning (ultrathink)",
+			"xhigh": "Extra-deep reasoning (ultrathink)",
+			"max": "Provider maximum reasoning",
 		};
 
 		const levels = this.getAvailableThinkingLevels(this.editingStep!);

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

@@ -8,7 +8,7 @@ import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 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 { toModelInfo, type ModelInfo } from "../../shared/model-info.ts";
+import { parentModelFullId, toModelInfo, type ModelInfo } from "../../shared/model-info.ts";
 import {
 	resolveChainTemplates,
 	createChainDir,
@@ -58,6 +58,7 @@ import {
 	resolveChildMaxSubagentDepth,
 } from "../../shared/types.ts";
 import { resolveModelCandidate } from "../shared/model-fallback.ts";
+import { applyThinkingSuffix } from "../shared/pi-args.ts";
 import { validateFileOnlyOutputMode } from "../shared/single-output.ts";
 import { buildWorkflowGraphSnapshot } from "../shared/workflow-graph.ts";
 import { ChainOutputValidationError, outputEntryFromResult, resolveOutputReferences, validateChainOutputBindings } from "../shared/chain-outputs.ts";
@@ -278,6 +279,8 @@ async function runParallelChainTasks(input: ParallelChainRunInput): Promise<Sing
 				modelOverride: effectiveModel,
 				availableModels: input.availableModels,
 				preferredModelProvider: input.ctx.model?.provider,
+				parentModel: parentModelFullId(input.ctx.model),
+				parentThinking: input.ctx.thinkingLevel,
 				skills: behavior.skills === false ? [] : behavior.skills,
 				structuredOutput: structuredRuntime,
 				acceptance: task.acceptance,
@@ -512,6 +515,14 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 			resolveStepBehavior(config, stepOverrides[i]!, chainSkills),
 		);
 		const flatTemplates = templates as string[];
+		// Seed what dispatch will resolve so the screen shows it and the thinking selector is enabled;
+		// untouched steps still reach runSync with no override and inherit there.
+		const parentModel = parentModelFullId(ctx.model);
+		const seededBehaviors = resolvedBehaviors.map((behavior, i) => {
+			const model = behavior.model ?? parentModel;
+			if (!model) return behavior;
+			return { ...behavior, model: applyThinkingSuffix(model, agentConfigs[i]!.thinking ?? ctx.thinkingLevel) };
+		});
 
 		const result = await ctx.ui.custom<ChainClarifyResult>(
 			(tui, theme, _kb, done) =>
@@ -522,7 +533,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 					flatTemplates,
 					originalTask,
 					chainDir,
-					resolvedBehaviors,
+					seededBehaviors,
 					availableModels,
 					ctx.model?.provider,
 					availableSkills,
@@ -1030,6 +1041,8 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 				modelOverride: effectiveModel,
 				availableModels,
 				preferredModelProvider: ctx.model?.provider,
+				parentModel: parentModelFullId(ctx.model),
+				parentThinking: ctx.thinkingLevel,
 				skills: behavior.skills === false ? [] : behavior.skills,
 				structuredOutput: structuredRuntime,
 				acceptance: seqStep.acceptance,

package/src/runs/foreground/execution.ts

@@ -684,11 +684,12 @@ export async function runSync(
 	}
 
 	const candidates = buildModelCandidates(
-		options.modelOverride ?? agent.model,
+		options.modelOverride ?? agent.model ?? options.parentModel,
 		agent.fallbackModels,
 		options.availableModels,
 		options.preferredModelProvider,
 	);
+	const effectiveAgent: AgentConfig = { ...agent, thinking: agent.thinking ?? options.parentThinking };
 	const attemptedModels: string[] = [];
 	const modelAttempts: ModelAttempt[] = [];
 	const aggregateUsage = emptyUsage();
@@ -751,7 +752,7 @@ export async function runSync(
 					owner: externalOwner,
 					attemptId: `${childId}-attempt-${i}`,
 					runtimeCwd,
-					agent,
+					agent: effectiveAgent,
 					model: candidate,
 					task: taskWithAcceptance,
 					options,
@@ -762,7 +763,7 @@ export async function runSync(
 			}
 		} else {
 			result = await (dependencies.runNativeAttempt ?? runSingleAttempt)(
-				runtimeCwd, agent, taskWithAcceptance, candidate, options, shared,
+				runtimeCwd, effectiveAgent, taskWithAcceptance, candidate, options, shared,
 			);
 		}
 		lastResult = result;

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

@@ -6,7 +6,7 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import type { AgentConfig, AgentScope } from "../../agents/agents.ts";
 import { getArtifactsDir } from "../../shared/artifacts.ts";
 import { ChainClarifyComponent, type ChainClarifyResult } from "./chain-clarify.ts";
-import { toModelInfo, type ModelInfo } from "../../shared/model-info.ts";
+import { parentModelFullId, toModelInfo, type ModelInfo } from "../../shared/model-info.ts";
 import { executeChain } from "./chain-execution.ts";
 import { resolveExecutionAgentScope } from "../../agents/agent-scope.ts";
 import { handleManagementAction } from "../../agents/agent-management.ts";
@@ -210,6 +210,18 @@ function nestedResolutionScopeForExecutor(deps: ExecutorDeps): NestedRunResoluti
 	};
 }
 
+function buildAsyncContext(ctx: ExtensionContext, deps: ExecutorDeps, cwd: string) {
+	return {
+		pi: deps.pi,
+		cwd,
+		currentSessionId: deps.state.currentSessionId!,
+		currentModelProvider: ctx.model?.provider,
+		parentModel: parentModelFullId(ctx.model),
+		parentThinking: ctx.thinkingLevel,
+		executionBackend: deps.config.executionBackend,
+	};
+}
+
 function foregroundStatusResult(control: SubagentState["foregroundControls"] extends Map<string, infer T> ? T : never): AgentToolResult<Details> {
 	let nestedWarning: string | undefined;
 	try {
@@ -591,13 +603,7 @@ async function resumeAsyncRun(input: {
 		agent: target.agent,
 		task: buildRevivedAsyncTask(target, followUp),
 		agentConfig,
-		ctx: {
-			pi: input.deps.pi,
-			cwd: input.requestCwd,
-			currentSessionId: input.deps.state.currentSessionId,
-			currentModelProvider: input.ctx.model?.provider,
-			executionBackend: input.deps.config.executionBackend,
-		},
+		ctx: buildAsyncContext(input.ctx, input.deps, input.requestCwd),
 		cwd: effectiveCwd,
 		maxOutput: input.params.maxOutput,
 		artifactsDir: input.deps.tempArtifactsDir,
@@ -974,13 +980,7 @@ function runAsyncPath(data: ExecutionContextData, deps: ExecutorDeps): AgentTool
 		};
 	}
 	const id = randomUUID();
-	const asyncCtx = {
-		pi: deps.pi,
-		cwd: ctx.cwd,
-		currentSessionId: deps.state.currentSessionId!,
-		currentModelProvider: ctx.model?.provider,
-		executionBackend: deps.config.executionBackend,
-	};
+	const asyncCtx = buildAsyncContext(ctx, deps, ctx.cwd);
 	const availableModels: ModelInfo[] = ctx.modelRegistry.getAvailable().map(toModelInfo);
 	const currentMaxSubagentDepth = resolveCurrentMaxSubagentDepth(deps.config.maxSubagentDepth);
 	const currentProvider = ctx.model?.provider;
@@ -1164,13 +1164,7 @@ async function runChainPath(data: ExecutionContextData, deps: ExecutorDeps): Pro
 			};
 		}
 		const id = randomUUID();
-		const asyncCtx = {
-			pi: deps.pi,
-			cwd: ctx.cwd,
-			currentSessionId: deps.state.currentSessionId!,
-			currentModelProvider: ctx.model?.provider,
-			executionBackend: deps.config.executionBackend,
-		};
+		const asyncCtx = buildAsyncContext(ctx, deps, ctx.cwd);
 		const asyncChain = wrapChainTasksForFork(chainResult.requestedAsync.chain, params.context);
 		return executeAsyncChain(id, {
 			chain: asyncChain,
@@ -1432,6 +1426,8 @@ async function runForegroundParallelTasks(input: ForegroundParallelRunInput): Pr
 			modelOverride: input.modelOverrides[index],
 			availableModels: input.availableModels,
 			preferredModelProvider: input.ctx.model?.provider,
+			parentModel: parentModelFullId(input.ctx.model),
+			parentThinking: input.ctx.thinkingLevel,
 			skills: effectiveSkills === false ? [] : effectiveSkills,
 			acceptance: task.acceptance,
 			acceptanceContext: { mode: "parallel" },
@@ -1605,13 +1601,7 @@ async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps):
 				};
 			}
 			const id = randomUUID();
-			const asyncCtx = {
-				pi: deps.pi,
-				cwd: ctx.cwd,
-				currentSessionId: deps.state.currentSessionId!,
-				currentModelProvider: ctx.model?.provider,
-				executionBackend: deps.config.executionBackend,
-			};
+			const asyncCtx = buildAsyncContext(ctx, deps, ctx.cwd);
 			const parallelTasks = tasks.map((t, i) => {
 				const taskText = params.context === "fork" ? wrapForkTask(taskTexts[i]!) : taskTexts[i]!;
 				const progress = taskDisallowsFileUpdates(taskText) ? false : behaviorOverrides[i]?.progress;
@@ -1883,13 +1873,7 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 				};
 			}
 			const id = randomUUID();
-			const asyncCtx = {
-				pi: deps.pi,
-				cwd: ctx.cwd,
-				currentSessionId: deps.state.currentSessionId!,
-				currentModelProvider: ctx.model?.provider,
-				executionBackend: deps.config.executionBackend,
-			};
+			const asyncCtx = buildAsyncContext(ctx, deps, ctx.cwd);
 			return executeAsyncSingle(id, {
 				agent: params.agent!,
 				task: params.context === "fork" ? wrapForkTask(task) : task,
@@ -1993,6 +1977,8 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 		modelOverride,
 		availableModels,
 		preferredModelProvider: currentProvider,
+		parentModel: parentModelFullId(ctx.model),
+		parentThinking: ctx.thinkingLevel,
 		skills: effectiveSkills,
 		acceptance: params.acceptance,
 		acceptanceContext: { mode: "single" },

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

@@ -6,7 +6,7 @@ import { encodeNestedPathEnv, parseNestedPathEnv, type NestedPathEntry } from ".
 import { STRUCTURED_OUTPUT_CAPTURE_ENV, STRUCTURED_OUTPUT_SCHEMA_ENV, STRUCTURED_OUTPUT_TOOL_NAME } from "./structured-output.ts";
 import type { JsonSchemaObject } from "../../shared/types.ts";
 
-const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"];
+const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
 const TASK_ARG_LIMIT = 8000;
 const PROMPT_RUNTIME_EXTENSION_PATH = path.join(path.dirname(fileURLToPath(import.meta.url)), "subagent-prompt-runtime.ts");
 const FANOUT_CHILD_EXTENSION_PATH = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "extension", "fanout-child.ts");
@@ -73,7 +73,7 @@ export function runDirEnv(asyncDir: string): Record<string, string> {
 }
 
 export function applyThinkingSuffix(model: string | undefined, thinking: string | undefined): string | undefined {
-	if (!model || !thinking || thinking === "off") return model;
+	if (!model || !thinking) return model;
 	const colonIdx = model.lastIndexOf(":");
 	if (colonIdx !== -1 && THINKING_LEVELS.includes(model.substring(colonIdx + 1))) return model;
 	return `${model}:${thinking}`;

package/src/shared/model-info.ts

@@ -1,4 +1,4 @@
-export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"] as const;
+export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
 export type ThinkingLevel = typeof THINKING_LEVELS[number];
 export type ThinkingLevelMap = Partial<Record<ThinkingLevel, string | null>>;
 
@@ -63,16 +63,21 @@ export function findModelInfo(model: string | undefined, availableModels: ModelI
 }
 
 export function getSupportedThinkingLevels(model: ModelInfo | undefined): ThinkingLevel[] {
-	if (!model) return [...THINKING_LEVELS];
+	if (!model) return THINKING_LEVELS.filter((level) => level !== "max");
 	if (model.reasoning === false) return ["off"];
 
-	if (!model.thinkingLevelMap) return [...THINKING_LEVELS];
+	if (!model.thinkingLevelMap) return THINKING_LEVELS.filter((level) => level !== "max");
 
 	const levels = THINKING_LEVELS.filter((level) => {
 		const mapped = model.thinkingLevelMap?.[level];
 		if (mapped === null) return false;
-		if (level === "xhigh") return mapped !== undefined;
+		if (level === "xhigh" || level === "max") return mapped !== undefined;
 		return true;
 	});
 	return levels;
 }
+
+/** Provider-qualified id of the parent session model; undefined when either part is missing (SDK hosts, minimal test contexts). */
+export function parentModelFullId(model: { provider?: string; id?: string } | undefined): string | undefined {
+	return model?.provider && model.id ? `${model.provider}/${model.id}` : undefined;
+}

package/src/shared/types.ts

@@ -776,6 +776,10 @@ export interface RunSyncOptions {
 	availableModels?: Array<{ provider: string; id: string; fullId: string }>;
 	/** Current parent-session provider to prefer for ambiguous bare model ids */
 	preferredModelProvider?: string;
+	/** Parent session model as provider/id; used when neither the call nor the agent names a model */
+	parentModel?: string;
+	/** Parent session thinking level; used when the agent sets no `thinking` */
+	parentThinking?: string;
 	/** Skills to inject (overrides agent default if provided) */
 	skills?: string[];
 	structuredOutput?: {

package/prompts/handoff.md

@@ -1,54 +0,0 @@
----
-description: "Use when the context window is nearly full and the work must continue in a fresh session."
----
-
-Write a handoff brief for a fresh session. The template is the contract in `doc/handoff-template.md` of pi-cohort; section names are fixed.
-
-Optional `--out <path>` (relative resolves against cwd):
-
-$@
-
-## Rules
-
-- `DIR=$(mktemp -d)`. The dispatch: `async: false` and `context: "fresh"` at the top level; `reads: false`; absolute `output` under `$DIR`. If it returns an async handle, a `forceTopLevelAsync` setting is active: stop and report it. Do not poll, relaunch, or continue.
-- The child is read-only against the repository; its only write is its `output` file.
-- You write `## Intent`, `## Decisions`, `## Open questions`, and `## Skills loaded` from your own transcript, before the call and after it returns. Do not fork a child for this: forking a near-full transcript is the cost this handoff avoids.
-- Write nothing into the repository; the brief goes to `--out` or `$DIR/handoff.md`.
-
-## Run worktree
-
-Before the snapshot dispatch, determine the run worktree from your own transcript and interpolate it into the scout task as `Run worktree: <abs path>` or `Run worktree: none`:
-
-- A flow-level worktree the run created (any `git worktree add <path>` you ran, or a `Worktree ready at <path>` report from `/skill:using-git-worktrees`) or was told to work in (a resume brief's `worktree: yes <path>`, or a user instruction).
-- Never inferred from the session cwd; a created or assigned worktree still qualifies when it happens to equal the cwd. Never a per-task worktree from `tasks[].worktree: true` or `worktree: true` dispatches - those are ephemeral.
-- Two flow-level worktrees in the transcript: the candidate is the one most recently used by later work (a dispatch `cwd`, a `git -C <path>`, or a `cd <path>`); if that does not distinguish them, the most recent creation or assignment. The other goes into `## Open questions` as `Also seen: <path> - not recorded as the run worktree`.
-- No flow-level worktree created or named: `Run worktree: none`.
-
-After the scout returns, copy any `open-question:` line from `repo.md` into `## Open questions` without the `open-question:` prefix; it never appears in `## Repo state`.
-
-## Repo snapshot
-
-```
-subagent({ async: false, context: "fresh", tasks: [
-  { agent: "scout", cwd: "<cwd>", reads: false, output: "<DIR>/repo.md",
-    task: "Read-only; write only to your output path. Run worktree: <abs path|none>. Steps: (1) linked set: git worktree list --porcelain | awk '/^worktree /{print substr($0,10)}' - the first line is the primary checkout, the rest are the linked worktrees; a relative candidate resolves against the primary toplevel, not cwd. (2) candidate `none` or line absent -> target is cwd, go to (4). Otherwise if the candidate is relative, prefix it with the primary toplevel (first linked-set line) first; C=$(git -C <candidate> rev-parse --show-toplevel); valid when that succeeds and C equals one of the linked lines exactly (a line after the first; equality with the first, primary line is invalid); anything else (failure, not listed, the primary itself, prunable) is invalid -> target is cwd and emit the open-question line in (5). (3) valid -> target is $C and `worktree: yes $C`. (4) target cwd -> T=$(git rev-parse --show-toplevel); `worktree: yes $T` when $T equals one of the linked lines exactly (a line after the first; the first, primary line gives `worktree: no`), else `worktree: no`. (5) report each field on its own line, `unavailable` when a command fails, every git command as `git -C <target>`: toplevel (git -C <target> rev-parse --show-toplevel); the worktree line from (3) or (4); branch (git -C <target> branch --show-current, `detached` when empty); HEAD SHA; base (origin/HEAD short name, else origin/main or origin/master if present, else `base: unknown`); dirty (git -C <target> status --porcelain, or `clean`); diff-stat (git -C <target> diff --stat <base>...HEAD; `diff-stat: unavailable` when base is unknown); test command (<target>/package.json scripts or <target>/AGENTS.md). Invalid candidate: after the fields add the single line `open-question: producer named <candidate as submitted> as the run worktree; it is not a linked worktree of this repo`. cwd not a git repo -> the single line `not a git repo`, plus the same open-question line if a candidate was submitted." }
-]})
-```
-
-## Process state
-
-Include `## Process state` only when both `phase_tracker` and `plan_tracker` tools exist AND `phase_tracker status` shows a phase `in_progress`. Then: `phase_tracker status` and `plan_tracker status` outputs verbatim; `Active task: <task name>` (the task you are working on; `none` when no plan is active or no task is active); the line `Gate history not restored - re-validate before advancing.`. Tools absent, all phases pending, or hotfix flow -> omit the section.
-
-## Brief
-
-```markdown
-# Handoff: <one line>
-## Intent
-## Repo state          (the snapshot fields; `## Repo state: not a git repo` when so)
-## Decisions           (bullets; rejected alternatives marked `rejected:`)
-## Open questions
-## Skills loaded       (frontmatter `name` of every skill whose SKILL.md body is in context - a `<skill>` block or a tool result on a `*/SKILL.md` path; `## Skills loaded: none` when there are none)
-## Process state       (only per the rule above)
-```
-
-Write it, print the path and the brief.