pi-daddy 0.41.0 → 0.43.0

package/dist/products/episode-report.js

@@ -0,0 +1,311 @@
+/** Read-only episode accounting over the governance ledger and activity timeline. */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { readRecords } from "../governance/record.js";
+const execFileAsync = promisify(execFile);
+const TERMINAL = new Set(["completed", "failed"]);
+const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const number = (value) => (typeof value === "number" && Number.isFinite(value) ? value : 0);
+const text = (value) => (typeof value === "string" ? value : "");
+const joined = (values) => [...values].filter(Boolean).sort().join(",");
+function timestamp(value, fallback) {
+    const parsed = Date.parse(typeof value === "string" ? value : fallback);
+    return Number.isFinite(parsed) ? parsed : Date.parse(fallback);
+}
+function episodeOf(episodes, id, at) {
+    const existing = episodes.get(id);
+    if (existing) {
+        existing.startedMs = Math.min(existing.startedMs, at);
+        existing.endedMs = Math.max(existing.endedMs, at);
+        return existing;
+    }
+    const episode = {
+        episode: id,
+        startedMs: at,
+        endedMs: at,
+        definitions: new Set(),
+        hashes: new Set(),
+        models: new Set(),
+        modelIds: new Set(),
+        modelSources: new Set(),
+        thinkingLevels: new Set(),
+        thinkingSources: new Set(),
+        inputTokens: 0,
+        outputTokens: 0,
+        cacheReadTokens: 0,
+        reasoningTokens: 0,
+        cost: 0,
+        compactions: 0,
+        turns: 0,
+        children: new Set(),
+        terminalExecutions: new Set(),
+    };
+    episodes.set(id, episode);
+    return episode;
+}
+function percentile(values, fraction) {
+    if (values.length === 0)
+        return 0;
+    const sorted = [...values].sort((a, b) => a - b);
+    return sorted[Math.ceil(sorted.length * fraction) - 1] ?? 0;
+}
+export function reportEpisodes(input) {
+    const episodes = new Map();
+    const outcomes = new Map();
+    const ledger = readRecords(input.ledgerText);
+    if (ledger.damage)
+        throw new Error(`grants ledger damaged at line ${ledger.damage.line}: ${ledger.damage.reason}`);
+    for (const record of ledger.records) {
+        if (!object(record.body))
+            continue;
+        const body = record.body;
+        const episodeId = text(body.episodeId);
+        if (!episodeId)
+            continue;
+        if (body.event === "episode_outcome") {
+            if (["positive", "negative", "unknown"].includes(text(body.label)))
+                outcomes.set(episodeId, body.label);
+            continue;
+        }
+        const episode = episodeOf(episodes, episodeId, timestamp(body.ts, record.at));
+        if (text(body.definitionHash))
+            episode.hashes.add(text(body.definitionHash).slice(0, 12));
+        if (body.event === "capability_decision") {
+            if (body.agentType !== "delegate")
+                episode.definitions.add(text(body.agentType));
+            continue;
+        }
+        if (body.event !== "child_lifecycle")
+            continue;
+        const executionId = text(body.executionId);
+        if (executionId)
+            episode.children.add(executionId);
+        if (!TERMINAL.has(text(body.state)) || episode.terminalExecutions.has(executionId))
+            continue;
+        episode.terminalExecutions.add(executionId);
+        if (object(body.resolvedModel)) {
+            const provider = text(body.resolvedModel.provider), modelId = text(body.resolvedModel.modelId);
+            if (modelId) {
+                episode.modelIds.add(modelId);
+                episode.models.add(provider ? `${provider}/${modelId}` : modelId);
+            }
+        }
+        if (text(body.modelSource))
+            episode.modelSources.add(text(body.modelSource));
+        if (object(body.thinkingLevel)) {
+            if (text(body.thinkingLevel.level))
+                episode.thinkingLevels.add(text(body.thinkingLevel.level));
+            if (text(body.thinkingLevel.source))
+                episode.thinkingSources.add(text(body.thinkingLevel.source));
+        }
+        if (text(body.thinkingSource))
+            episode.thinkingSources.add(text(body.thinkingSource));
+        const usage = object(body.usage) ? body.usage : undefined;
+        if (object(body.tokenDetail)) {
+            episode.inputTokens += number(body.tokenDetail.inputTokens);
+            episode.outputTokens += number(body.tokenDetail.outputTokens);
+            episode.cacheReadTokens += number(body.tokenDetail.cacheReadTokens);
+            episode.reasoningTokens += number(body.tokenDetail.reasoningTokens);
+        }
+        else if (usage) {
+            episode.inputTokens += number(usage.input);
+            episode.outputTokens += number(usage.output);
+            episode.cacheReadTokens += number(usage.cacheRead);
+            episode.reasoningTokens += number(usage.reasoning);
+        }
+        if (usage && object(usage.cost))
+            episode.cost += number(usage.cost.total);
+        episode.compactions += number(body.compactionCount);
+    }
+    const activity = readRecords(input.activityText);
+    if (activity.damage)
+        throw new Error(`activity ledger damaged at line ${activity.damage.line}: ${activity.damage.reason}`);
+    for (const record of activity.records) {
+        if (record.kind !== "activity" || !object(record.body))
+            continue;
+        const event = record.body;
+        const episodeId = text(event.episodeId);
+        if (!episodeId)
+            continue;
+        const episode = episodeOf(episodes, episodeId, timestamp(event.at, record.at));
+        if (event.kind === "task_started" && !text(event.agentId))
+            episode.turns += 1;
+    }
+    const since = input.options.since ? Date.parse(input.options.since) : Number.NEGATIVE_INFINITY;
+    let rows = [...episodes.values()]
+        .map((episode) => ({
+        episode: episode.episode,
+        started: new Date(episode.startedMs).toISOString(),
+        definition: joined(episode.definitions),
+        definitionHash: joined(episode.hashes),
+        resolvedModel: joined(episode.models),
+        modelSource: joined(episode.modelSources),
+        thinkingLevel: joined(episode.thinkingLevels),
+        thinkingSource: joined(episode.thinkingSources),
+        inputTokens: episode.inputTokens,
+        outputTokens: episode.outputTokens,
+        cacheReadTokens: episode.cacheReadTokens,
+        reasoningTokens: episode.reasoningTokens,
+        cost: episode.cost,
+        compactions: episode.compactions,
+        turns: episode.turns,
+        durationMs: Math.max(0, episode.endedMs - episode.startedMs),
+        children: episode.children.size,
+        commit: input.commitByEpisode.get(episode.episode) ?? "",
+        outcome: outcomes.get(episode.episode) ?? "",
+    }))
+        .filter((row) => Date.parse(row.started) >= since)
+        .filter((row) => !input.options.definition || row.definition.split(",").includes(input.options.definition))
+        .filter((row) => {
+        if (!input.options.model)
+            return true;
+        const source = episodes.get(row.episode);
+        return source.modelIds.has(input.options.model) || source.models.has(input.options.model);
+    })
+        .sort((a, b) => Date.parse(a.started) - Date.parse(b.started) || a.episode.localeCompare(b.episode));
+    if (input.options.groupBy) {
+        const field = input.options.groupBy === "thinking"
+            ? "thinkingLevel"
+            : input.options.groupBy === "model"
+                ? "resolvedModel"
+                : "definition";
+        const groups = new Map();
+        for (const row of rows) {
+            const value = row[field] || "(none)";
+            const group = groups.get(value) ?? {
+                value,
+                count: 0,
+                inputTokens: 0,
+                outputTokens: 0,
+                cacheReadTokens: 0,
+                reasoningTokens: 0,
+                cost: 0,
+            };
+            group.count += 1;
+            group.inputTokens += row.inputTokens;
+            group.outputTokens += row.outputTokens;
+            group.cacheReadTokens += row.cacheReadTokens;
+            group.reasoningTokens += row.reasoningTokens;
+            group.cost += row.cost;
+            groups.set(value, group);
+        }
+        return {
+            rows: [],
+            groups: [...groups.values()].sort((a, b) => a.value.localeCompare(b.value)),
+            groupBy: input.options.groupBy,
+        };
+    }
+    const costs = rows.map((row) => row.cost);
+    return {
+        rows,
+        totals: {
+            episodes: rows.length,
+            cost: costs.reduce((sum, value) => sum + value, 0),
+            tokens: rows.reduce((sum, row) => sum + row.inputTokens + row.outputTokens, 0),
+            p50EpisodeCost: percentile(costs, 0.5),
+            p95EpisodeCost: percentile(costs, 0.95),
+        },
+    };
+}
+const escapeCell = (value) => String(value).replaceAll("|", "\\|").replaceAll("\n", " ");
+const cost = (value) => value.toFixed(6).replace(/\.?0+$/, "") || "0";
+function duration(ms) {
+    const seconds = Math.round(ms / 1000);
+    const minutes = Math.floor(seconds / 60);
+    return minutes ? `${minutes}m ${seconds % 60}s` : `${seconds}s`;
+}
+function table(headers, rows) {
+    return [
+        `| ${headers.join(" | ")} |`,
+        `| ${headers.map(() => "---").join(" | ")} |`,
+        ...rows.map((row) => `| ${row.map(escapeCell).join(" | ")} |`),
+    ].join("\n");
+}
+export function renderEpisodeReport(report, json) {
+    if (json)
+        return `${JSON.stringify(report, null, 2)}\n`;
+    if (report.groups && report.groupBy) {
+        const headers = [
+            report.groupBy,
+            "count",
+            "inputTokens",
+            "outputTokens",
+            "cacheReadTokens",
+            "reasoningTokens",
+            "cost",
+        ];
+        return `${table(headers, report.groups.map((group) => [
+            group.value,
+            group.count,
+            group.inputTokens,
+            group.outputTokens,
+            group.cacheReadTokens,
+            group.reasoningTokens,
+            cost(group.cost),
+        ]))}\n`;
+    }
+    const headers = [
+        "episode",
+        "started",
+        "definition",
+        "definitionHash",
+        "resolvedModel",
+        "modelSource",
+        "thinkingLevel",
+        "thinkingSource",
+        "inputTokens",
+        "outputTokens",
+        "cacheReadTokens",
+        "reasoningTokens",
+        "cost",
+        "compactions",
+        "turns",
+        "duration",
+        "children",
+        "commit",
+        "outcome",
+    ];
+    const rows = report.rows.map((row) => [
+        row.episode,
+        row.started,
+        row.definition,
+        row.definitionHash,
+        row.resolvedModel,
+        row.modelSource,
+        row.thinkingLevel,
+        row.thinkingSource,
+        row.inputTokens,
+        row.outputTokens,
+        row.cacheReadTokens,
+        row.reasoningTokens,
+        cost(row.cost),
+        row.compactions,
+        row.turns,
+        duration(row.durationMs),
+        row.children,
+        row.commit,
+        row.outcome,
+    ]);
+    const totals = report.totals;
+    const totalsTable = table(["episodes", "cost", "tokens", "p50 episode cost", "p95 episode cost"], [[totals.episodes, cost(totals.cost), totals.tokens, cost(totals.p50EpisodeCost), cost(totals.p95EpisodeCost)]]);
+    return `${table(headers, rows)}\n\n${totalsTable}\n`;
+}
+export function commitsFromGitLog(log) {
+    const commits = new Map();
+    for (const entry of log.split("\u001e")) {
+        const [sha, ...body] = entry.trim().split("\n");
+        if (!/^[a-f0-9]{8,40}$/i.test(sha ?? ""))
+            continue;
+        for (const match of body.join("\n").matchAll(/^Pi-Episode:\s*(\S+)\s*$/gim)) {
+            const episode = match[1].startsWith("episode:") ? match[1] : `episode:${match[1]}`;
+            if (!commits.has(episode))
+                commits.set(episode, sha.slice(0, 8));
+        }
+    }
+    return commits;
+}
+export async function commitsForRepo(cwd) {
+    const { stdout } = await execFileAsync("git", ["log", "--format=%H%n%B%x1e"], { cwd, maxBuffer: 16 * 1024 * 1024 });
+    return commitsFromGitLog(stdout);
+}
+//# sourceMappingURL=episode-report.js.map

package/dist/products/episode-report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"episode-report.js","sourceRoot":"","sources":["../../src/products/episode-report.ts"],"names":[],"mappings":"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"}

package/extensions/chain-ledger.ts

@@ -41,6 +41,8 @@ export async function recordChainRefusal(input: {
       humanDenied: input.approval?.humanDenied,
       gateOutcome: input.approval?.gateOutcome,
       definitionDigest: input.plan.definitionDigest,
+      definitionHash: input.plan.definitionHash,
+      definitionPackageVersion: input.plan.definitionPackageVersion,
       taskDigest: input.plan.taskDigest,
       correlation: input.plan.correlation,
       // An approval banked before a later chain decline is a yes that led to no spawn, not the stale

package/extensions/chain-plan.ts

@@ -37,6 +37,7 @@ export async function planChain(
   steps: ChainStep[],
   executionIds: readonly string[],
   preflightModel?: (model: string | undefined) => StructuredRefusal | undefined,
+  resolveModel?: (step: ChainStep) => string | undefined,
 ): Promise<ChainPlan> {
   const requests: GateRequest[] = [];
   const uses = new Map<number, Set<string>>();
@@ -49,12 +50,13 @@ export async function planChain(
   const { stageHandoff: _stageHandoff, ...context } = await session.delegationContext();
 
   for (const [index, step] of steps.entries()) {
+    const model = resolveModel?.(step) ?? step.model;
     const plan = planDelegation(
       {
         task: step.task,
         agent: step.agent,
         tools: step.tools,
-        model: step.model,
+        model,
         thinking: step.thinking,
         context: step.context,
         correlation: step.workspace
@@ -71,7 +73,7 @@ export async function planChain(
       },
     );
 
-    const modelRefusal = preflightModel?.(step.model);
+    const modelRefusal = preflightModel?.(model);
     if (modelRefusal) {
       return {
         requests: [],

package/extensions/context-shape.ts

@@ -7,7 +7,12 @@
  * first. This shape exists to tell the model what the parameter is for.
  */
 import { Type } from "typebox";
-import { CONTEXT_MODES } from "../src/kernel/context-handoff.ts";
+import {
+  CONTEXT_MODES,
+  DEFAULT_CONTEXT_TURNS,
+  MAX_CONTEXT_FILES,
+  MAX_CONTEXT_TURNS,
+} from "../src/kernel/context-handoff.ts";
 
 export function contextShape() {
   return Type.Object({
@@ -18,13 +23,23 @@ export function contextShape() {
           "What of YOUR session this sub-agent receives. none: nothing beyond its definition and the task. " +
           "files: the contents of paths you name. pruned: recent turns of your session plus turns naming those " +
           "files. summary: what you write in 'summary'. fork: your whole session (needs a human's approval). " +
-          "A definition's allowed-tools caps this; asking for more than it permits is refused.",
+          "A definition's allowed-tools caps this; asking for more than it permits is refused. If the child has " +
+          "read tools in the same workspace, prefer none and ask it to inspect the checkout instead of embedding files.",
       },
     ),
     files: Type.Optional(
-      Type.Array(Type.String(), { description: "Repository-relative paths, for files and pruned." }),
+      Type.Array(Type.String({ minLength: 1 }), {
+        maxItems: MAX_CONTEXT_FILES,
+        description: `At most ${MAX_CONTEXT_FILES} repository-relative paths, for files and pruned.`,
+      }),
     ),
     summary: Type.Optional(Type.String({ description: "What the sub-agent needs to know, in your own words." })),
-    turns: Type.Optional(Type.Number({ description: "For pruned: how many recent turns to keep. Default 6." })),
+    turns: Type.Optional(
+      Type.Integer({
+        minimum: 1,
+        maximum: MAX_CONTEXT_TURNS,
+        description: `For pruned: how many recent turns to keep. Default ${DEFAULT_CONTEXT_TURNS}.`,
+      }),
+    ),
   });
 }

package/extensions/dashboard-session-server.ts

@@ -0,0 +1,86 @@
+import { randomBytes } from "node:crypto";
+import { chmod, rm } from "node:fs/promises";
+import { createServer, type Server } from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { GrantsSession } from "./session.ts";
+import { saveSessionModelEdits, sessionModelRows } from "./session-model-prompt.ts";
+
+export interface DashboardSessionEndpoint {
+  socketPath: string;
+  token: string;
+  close(): Promise<void>;
+}
+
+const endpoints = new WeakMap<GrantsSession, Promise<DashboardSessionEndpoint>>();
+
+export function ensureDashboardSessionServer(session: GrantsSession): Promise<DashboardSessionEndpoint> {
+  const existing = endpoints.get(session);
+  if (existing) return existing;
+  const started = start(session);
+  endpoints.set(session, started);
+  return started;
+}
+
+async function start(session: GrantsSession): Promise<DashboardSessionEndpoint> {
+  const socketPath = join(tmpdir(), `pi-daddy-${process.pid}-${randomBytes(8).toString("hex")}.sock`);
+  const token = randomBytes(24).toString("hex");
+  const server = createServer((socket) => {
+    let input = "";
+    socket.setEncoding("utf8");
+    socket.on("data", (chunk) => {
+      input += chunk;
+      if (input.length > 16 * 1024) socket.destroy(new Error("dashboard request too large"));
+      if (!input.includes("\n")) return;
+      const line = input.slice(0, input.indexOf("\n"));
+      void respond(session, token, line)
+        .then((value) => socket.end(`${JSON.stringify(value)}\n`))
+        .catch((error) => socket.end(`${JSON.stringify({ ok: false, error: String(error) })}\n`));
+    });
+  });
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(socketPath, () => resolve());
+  });
+  await chmod(socketPath, 0o600);
+  const cleanup = () => {
+    close(server, socketPath);
+  };
+  process.once("exit", cleanup);
+  server.unref();
+  return {
+    socketPath,
+    token,
+    close: async () => {
+      process.off("exit", cleanup);
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+      await rm(socketPath, { force: true });
+    },
+  };
+}
+
+async function respond(session: GrantsSession, token: string, line: string): Promise<Record<string, unknown>> {
+  const request = JSON.parse(line) as { token?: unknown; action?: unknown; edits?: unknown };
+  if (request.token !== token) return { ok: false, error: "unauthorised dashboard request" };
+  if (request.action === "set") {
+    if (typeof request.edits !== "string") return { ok: false, error: "dashboard edits must be a string" };
+    const invalid = await saveSessionModelEdits(
+      session,
+      request.edits,
+      [...session.definitions.keys()].sort(),
+      "grants-models",
+    );
+    if (invalid) return { ok: false, error: invalid };
+  } else if (request.action !== "get") return { ok: false, error: "unknown dashboard action" };
+  return {
+    ok: true,
+    rows: sessionModelRows(session, [...session.definitions.keys()].sort()),
+    cost: session.episodeCostGate.cost,
+    ceiling: session.episodeCostGate.ceiling,
+  };
+}
+
+function close(server: Server, socketPath: string): void {
+  server.close();
+  void rm(socketPath, { force: true });
+}

package/extensions/definition-runtime.ts

@@ -0,0 +1,93 @@
+/** Per-definition child model and thinking configuration, resolved before a delegation is planned. */
+
+export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
+export type ModelSource = "explicit" | "session" | "definition" | "global" | "pi";
+export type ThinkingSource = ModelSource | "advisor";
+export interface DefinitionRuntimeChoice {
+  model?: string;
+  thinking?: ThinkingLevel;
+}
+export interface DefinitionRuntimeSettings {
+  defaults: DefinitionRuntimeChoice;
+  definitions: Map<string, DefinitionRuntimeChoice>;
+}
+export interface ResolvedDefinitionRuntime {
+  model?: string;
+  modelSource: ModelSource;
+  thinking?: ThinkingLevel;
+  thinkingSource: ThinkingSource;
+}
+
+const isObject = (value: unknown): value is Record<string, unknown> =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
+export const parseThinkingLevel = (value: unknown): ThinkingLevel | undefined =>
+  typeof value === "string" && (THINKING_LEVELS as readonly string[]).includes(value)
+    ? (value as ThinkingLevel)
+    : undefined;
+export const parseConfiguredModel = (value: unknown): string | undefined => {
+  if (typeof value !== "string") return undefined;
+  const colon = value.indexOf(":");
+  if (colon <= 0 || colon === value.length - 1 || /\s/.test(value)) return undefined;
+  return `${value.slice(0, colon)}/${value.slice(colon + 1)}`;
+};
+const choice = (value: unknown): DefinitionRuntimeChoice => {
+  if (!isObject(value)) return {};
+  return {
+    ...(parseConfiguredModel(value.model) ? { model: parseConfiguredModel(value.model) } : {}),
+    ...(parseThinkingLevel(value.thinking) ? { thinking: parseThinkingLevel(value.thinking) } : {}),
+  };
+};
+
+export function definitionRuntimeSettingsFrom(raw: unknown): DefinitionRuntimeSettings {
+  const definitions = new Map<string, DefinitionRuntimeChoice>();
+  if (isObject(raw) && Array.isArray(raw.definitions)) {
+    for (const entry of raw.definitions) {
+      if (!isObject(entry) || typeof entry.name !== "string") continue;
+      definitions.set(entry.name, choice(entry));
+    }
+  }
+  return { defaults: isObject(raw) ? choice(raw.defaults) : {}, definitions };
+}
+
+export function resolvedModelOf(value: string | undefined): { provider: string; modelId: string } | null {
+  if (!value) return null;
+  const slash = value.indexOf("/");
+  return slash > 0 && slash < value.length - 1
+    ? { provider: value.slice(0, slash), modelId: value.slice(slash + 1) }
+    : null;
+}
+
+export function resolveDefinitionRuntime(input: {
+  definition?: string;
+  explicit: { model?: string; thinking?: string };
+  session: ReadonlyMap<string, DefinitionRuntimeChoice>;
+  settings: DefinitionRuntimeSettings;
+  piModel?: string;
+  advisorThinking?: string;
+}): ResolvedDefinitionRuntime {
+  const session = input.definition ? input.session.get(input.definition) : undefined;
+  const definition = input.definition ? input.settings.definitions.get(input.definition) : undefined;
+  const modelCandidates: Array<[string | undefined, ModelSource]> = [
+    [input.explicit.model, "explicit"],
+    [session?.model, "session"],
+    [definition?.model, "definition"],
+    [input.settings.defaults.model, "global"],
+    [input.piModel, "pi"],
+  ];
+  const thinkingCandidates: Array<[string | undefined, ThinkingSource]> = [
+    [input.explicit.thinking, "explicit"],
+    [session?.thinking, "session"],
+    [input.advisorThinking, "advisor"],
+    [definition?.thinking, "definition"],
+    [input.settings.defaults.thinking, "global"],
+  ];
+  const selectedModel = modelCandidates.find(([value]) => value !== undefined) ?? [undefined, "pi" as const];
+  const selectedThinking = thinkingCandidates.find(([value]) => value !== undefined) ?? [undefined, "pi" as const];
+  return {
+    model: selectedModel[0],
+    modelSource: selectedModel[1],
+    thinking: parseThinkingLevel(selectedThinking[0]),
+    thinkingSource: selectedThinking[1],
+  };
+}

package/extensions/delegate-chain.ts

@@ -43,6 +43,8 @@ import { newExecutionId } from "../src/kernel/execution-id.ts";
 import { planChain, type GateRequest } from "./chain-plan.ts";
 import { contextShape } from "./context-shape.ts";
 import { preflightModel } from "../src/kernel/model-preflight.ts";
+import { resolveDefinitionRuntime } from "./definition-runtime.ts";
+import { ensureSessionModelPrompt } from "./session-model-prompt.ts";
 import { assertDelegationAuthority } from "./delegation-authority.ts";
 
 /** One chain step is one execution occurrence, however many capability dialogs contributed to its answer. */
@@ -100,6 +102,9 @@ export function registerChainTool(pi: ExtensionAPI, session: GrantsSession): voi
       maxItems: MAX_CHAIN_STEPS,
       description: "The steps to run IN ORDER. Each one sees the previous one's output.",
     }),
+    episodeCostCeiling: Type.Optional(
+      Type.Number({ exclusiveMinimum: 0, description: "Override the USD ceiling for this whole episode." }),
+    ),
   });
 
   pi.registerTool({
@@ -130,12 +135,35 @@ export function registerChainTool(pi: ExtensionAPI, session: GrantsSession): voi
       const split = splitBudget(session.fanoutBudget, steps.length);
       if (!split.ok) throw new GovernanceRefusal(refusal("FANOUT_EXCEEDED", `chain refused: ${split.reason}`));
 
+      await ensureSessionModelPrompt(
+        session,
+        steps.flatMap((step) => (step.agent ? [step.agent] : [])),
+        {
+          hasUI: ctx.hasUI && typeof ctx.ui.input === "function",
+          input: (title, placeholder) => ctx.ui.input(title, placeholder),
+          notify: (message, type) => ctx.ui.notify(message, type),
+        },
+      );
+
       // Plan every step first. A step that can never run refuses the chain HERE, before anyone is asked — see
       // `planChain`.
       const executionIds = steps.map(() => newExecutionId());
       const parentExecutionId = session.ownExecutionId ?? null;
-      const chainPlan = await planChain(session, steps, executionIds, (model) =>
-        preflightModel(model, ctx.modelRegistry, session.modelResolutionCache, session.allowUnresolvedModels),
+      const piModel = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined;
+      const chainPlan = await planChain(
+        session,
+        steps,
+        executionIds,
+        (model) =>
+          preflightModel(model, ctx.modelRegistry, session.modelResolutionCache, session.allowUnresolvedModels),
+        (step) =>
+          resolveDefinitionRuntime({
+            definition: step.agent,
+            explicit: { model: step.model, thinking: step.thinking },
+            session: session.definitionRuntimeOverrides,
+            settings: session.definitionRuntimeSettings,
+            piModel,
+          }).model,
       );
       if (chainPlan.doomed) {
         const message =
@@ -274,6 +302,7 @@ export function registerChainTool(pi: ExtensionAPI, session: GrantsSession): voi
        */
       let available = [...preApproved];
 
+      if (args.episodeCostCeiling !== undefined) session.episodeCostGate.setCeiling(args.episodeCostCeiling);
       for (const [index, step] of steps.entries()) {
         const childId = childSpawnId(session.ownSpawnId, index);
         const availableForStep = available.filter((approval) => {