pi-legion 4.0.0 → 5.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-legion",
-  "version": "4.0.0",
-  "description": "Pi Legion v2: recursive centurion trees on headless Pi RPC; shared SQLite WAL legion.db. Four-stage planning/implementing/reviewing/verifying state machine, parent/child/sibling legion_mail, three-layer /legion UI, upward MR trees, squad resume.",
+  "version": "5.0.0",
+  "description": "Pi Legion v2: recursive centurion teams on Pi. Children run in-process by default (rpc only for a worktree-owning centurion); shared SQLite WAL legion.db. Declarative per-team phase machine (built-in default: planning/implementing/reviewing/verifying), parent/child/sibling legion_mail, three-layer /legion UI, upward MR trees, squad resume.",
   "type": "module",
   "license": "MIT",
   "repository": {

package/src/agents/agents.ts

@@ -19,7 +19,6 @@ import {
 	type AcceptanceCriterion,
 	type OnBlockedPolicy,
 	type SpawnMode,
-	SPAWN_MODES,
 	type SystemPromptMode,
 	type ToolBudgetConfig,
 	type TurnBudgetConfig,
@@ -31,16 +30,19 @@ import {
 } from "./frontmatter.ts";
 import { getAgentDir } from "./paths.ts";
 import { ignoredKindMessage, reportIgnoredOnce } from "../shared/ignored-kind.ts";
+import {
+	type PhaseDefinition,
+	type PhaseMachine,
+	type PhaseTransitionRule,
+	normalizePhaseMachine,
+	validatePhaseMachine,
+} from "../legion/phase-machine.ts";
+import type { PhaseCondition } from "../legion/phase-conditions.ts";
 
 export const BUILTIN_AGENT_NAMES = [
 	"scout",
-	"planner",
-	"reviewer",
 	"worker",
 	"centurion",
-	"advisor",
-	"designer",
-	"prototype",
 ] as const;
 
 /**
@@ -177,15 +179,6 @@ function int(value: unknown): number | undefined {
 	return undefined;
 }
 
-function spawnModeOf(value: unknown, filePath: string): SpawnMode | undefined {
-	if (value === undefined || value === null || value === "") return undefined;
-	const raw = typeof value === "string" ? value.trim() : String(value);
-	if ((SPAWN_MODES as readonly string[]).includes(raw)) return raw as SpawnMode;
-	throw new Error(
-		`Agent '${filePath}' has invalid spawnMode '${raw}'; expected one of: ${SPAWN_MODES.join(", ")}.`,
-	);
-}
-
 
 /**
  * Accept `tools: read, bash`, `tools: [read, bash]`, and block-list spellings.
@@ -413,28 +406,281 @@ function parseCriteria(value: unknown): AcceptanceCriterion[] | undefined {
 	return criteria.length > 0 ? criteria : undefined;
 }
 
-function parseBudget(value: unknown): ToolBudgetConfig | undefined {
-	const raw = str(value);
-	if (!raw) return undefined;
-	try {
-		const parsed = JSON.parse(raw) as Record<string, unknown>;
-		const max = int(parsed.maxToolCalls);
-		return max === undefined ? undefined : { maxToolCalls: max };
-	} catch {
-		return undefined;
+/**
+ * Read an indented `phases:` block into the machine shape (#298).
+ *
+ * The shared frontmatter parser is flat — nested lists come back as raw text —
+ * so this walks the text itself. The grammar is deliberately tiny and matches
+ * only what a card can express:
+ *
+ * ```text
+ * - id: planning                  # a phase
+ *   require: [contract_file]      # inline condition list
+ *   timeoutMs: 900000
+ *   terminal: false
+ *   next:                         # a list of transitions
+ *     - to: implementing
+ *       require: [contract_file]
+ *       actorRole: centurion
+ *       rework: true
+ *     - to: failed
+ * ```
+ *
+ * Anything outside this shape is an error rather than a silent skip, because a
+ * half-read machine is worse than none: it would run with the transitions it
+ * happened to parse.
+ */
+function parsePhaseBlock(text: string): PhaseMachine | undefined {
+	// `id` is filled from the `- id: ...` line; validatePhaseMachine rejects a
+	// machine where it is missing, so the assertion at the end is safe.
+	type PhaseDraft = Record<string, unknown> & { id: string; next?: Array<Record<string, unknown>> };
+	const phases: PhaseDraft[] = [];
+	let currentPhase: PhaseDraft | undefined;
+	let currentRule: Record<string, unknown> | undefined;
+	// Column where list items live. The first `- ` we see sets it, so the block may
+	// be indented by any amount relative to the document.
+	let itemIndent = -1;
+
+	const scalar = (value: string): unknown => {
+		const trimmed = value.trim();
+		if (trimmed === "true") return true;
+		if (trimmed === "false") return false;
+		if (/^-?\d+$/.test(trimmed)) return Number(trimmed);
+		if (trimmed.startsWith("[") && trimmed.endsWith("]")) {
+			const inner = trimmed.slice(1, -1).trim();
+			if (!inner) return [];
+			return inner.split(",").map((part) => part.trim().replace(/^["']|["']$/g, "")).filter(Boolean);
+		}
+		return trimmed.replace(/^["']|["']$/g, "");
+	};
+
+	for (const rawLine of text.split("\n")) {
+		if (!rawLine.trim()) continue;
+		const indent = rawLine.length - rawLine.trimStart().length;
+		const line = rawLine.trim();
+
+		if (line.startsWith("- ")) {
+			if (itemIndent === -1) itemIndent = indent;
+			const body = line.slice(2).trim();
+			const entry: Record<string, unknown> = {};
+			const colon = body.indexOf(":");
+			if (colon > 0) entry[body.slice(0, colon).trim()] = scalar(body.slice(colon + 1));
+			// A `- ` at the item column opens a phase; deeper opens a transition.
+			if (indent <= itemIndent) {
+				currentPhase = entry as PhaseDraft;
+				currentPhase.next = [];
+				phases.push(currentPhase);
+				currentRule = undefined;
+			} else if (currentPhase) {
+				currentRule = entry;
+				currentPhase.next!.push(entry);
+			}
+			continue;
+		}
+
+		const colon = line.indexOf(":");
+		if (colon <= 0) continue;
+		const key = line.slice(0, colon).trim();
+		const value = line.slice(colon + 1).trim();
+		const target = currentRule ?? currentPhase;
+		if (!target) continue;
+		if (value === "") {
+			// `next:` with nothing after it — the transitions follow as `- to:` lines.
+			if (key === "next") target.next = target.next ?? [];
+			continue;
+		}
+		target[key] = scalar(value);
+	}
+
+	if (phases.length === 0) return undefined;
+	// Convert the walked drafts into the declared shape explicitly instead of
+	// asserting it. `validatePhaseMachine` runs right after this and rejects
+	// anything malformed, but doing the coercion here means the compiler — not just
+	// the validator — has seen every field.
+	const converted: PhaseDefinition[] = phases.map((draft) => {
+		const rules: PhaseTransitionRule[] = (draft.next ?? []).map((rule) => {
+			const out: PhaseTransitionRule = { to: String(rule.to ?? "") };
+			if (Array.isArray(rule.require)) out.require = rule.require.map(String) as PhaseCondition[];
+			if (typeof rule.actorRole === "string") out.actorRole = rule.actorRole;
+			if (rule.rework === true) out.rework = true;
+			if (rule.notifyParent === true) out.notifyParent = true;
+			return out;
+		});
+		const phase: PhaseDefinition = { id: String(draft.id ?? ""), next: rules };
+		if (Array.isArray(draft.require)) phase.require = draft.require.map(String) as PhaseCondition[];
+		if (typeof draft.timeoutMs === "number") phase.timeoutMs = draft.timeoutMs;
+		if (draft.terminal === true) phase.terminal = true;
+		return phase;
+	});
+	const machine: PhaseMachine = { phases: converted };
+	if (typeof (phases as unknown as { start?: unknown }).start === "string") {
+		machine.start = String((phases as unknown as { start: string }).start);
 	}
+	return machine;
 }
 
-function parseTurnBudget(value: unknown): TurnBudgetConfig | undefined {
-	const raw = str(value);
-	if (!raw) return undefined;
-	try {
-		const parsed = JSON.parse(raw) as Record<string, unknown>;
-		const max = int(parsed.maxTurns);
-		return max === undefined ? undefined : { maxTurns: max };
-	} catch {
-		return undefined;
+/**
+ * Parse a declared phase machine from `phases:` (#298).
+ *
+ * Accepts the YAML shape directly (a list of phase objects), or the same thing
+ * as a JSON string, matching how `toolBudget` is written.
+ *
+ * Validation happens HERE, at load, and every problem is reported at once. A
+ * machine that only fails mid-run would surface after a team had already spent
+ * tokens on a workflow that could never complete.
+ */
+function parsePhaseMachine(value: unknown, filePath: string): PhaseMachine | undefined {
+	if (value === undefined || value === null) return undefined;
+	let raw: unknown = value;
+	if (typeof value === "string") {
+		const text = value.trim();
+		if (!text) return undefined;
+		// The frontmatter parser is FLAT, so a nested `phases:` block arrives here
+		// as raw text — exactly the situation `parseAcceptance` already handles.
+		// Two spellings are therefore accepted: an indented YAML block (what the
+		// card looks like) and a one-line JSON string (easier to generate).
+		let parsedText: unknown;
+		let wasJson = true;
+		try {
+			parsedText = JSON.parse(text);
+		} catch {
+			wasJson = false;
+			parsedText = parsePhaseBlock(text);
+		}
+		if (!wasJson && parsedText === undefined) {
+			throw new Error(
+				`Agent '${filePath}' has invalid phases: could not read the block. ` +
+					`Expected an indented list of "  - id: <name>" entries, or a JSON string.`,
+			);
+		}
+		raw = parsedText;
 	}
+	// Accept both `[{...}]` and `{ phases: [...] }`.
+	const shaped = Array.isArray(raw)
+		? ({ phases: raw } as unknown)
+		: raw;
+	if (shaped === null || typeof shaped !== "object") {
+		throw new Error(`Agent '${filePath}' has invalid phases: expected a list or an object with a 'phases' key.`);
+	}
+	const machine = shaped as PhaseMachine;
+	if (!Array.isArray(machine.phases)) {
+		throw new Error(`Agent '${filePath}' has invalid phases: 'phases' must be a list.`);
+	}
+	// Inject the universal terminals before validating, so reachability is judged
+	// on the machine as it will actually run.
+	const normalized = normalizePhaseMachine(machine);
+	const errors = validatePhaseMachine(normalized);
+	if (errors.length > 0) {
+		const detail = errors.map((error) => `  - ${error.path}: ${error.message}`).join("\n");
+		throw new Error(`Agent '${filePath}' has an invalid phase machine:\n${detail}`);
+	}
+	return normalized;
+}
+
+/**
+ * Parse a child budget (`toolBudget` / `turnBudget`) strictly.
+ *
+ * These used to swallow every error and return `undefined`, so a typo became
+ * "no limit" -- the same silent-acceptance failure the frontmatter field check
+ * exists to prevent. Worse, a NEGATIVE number was accepted: `-3` reached the
+ * child, `toolCalls > -3` was true immediately, and the first tool call was
+ * blocked while the author believed they had set a limit of 3.
+ *
+ * `0` is meaningful here ("no calls allowed", per `extension/budget.ts`), so it
+ * must survive rather than decay into "unset". Anything that is not a
+ * non-negative integer is an error naming the file and the field.
+ */
+function parseBudgets(fm: AgentFrontmatter, filePath: string): {
+	tool?: ToolBudgetConfig;
+	turn?: TurnBudgetConfig;
+} {
+	const read = (
+		field: "toolBudget" | "turnBudget",
+		key: "maxToolCalls" | "maxTurns",
+	): number | undefined => {
+		const raw = str(fm[field]);
+		if (!raw) return undefined;
+		let parsed: unknown;
+		try {
+			parsed = JSON.parse(raw);
+		} catch {
+			throw new Error(
+				`Agent '${filePath}' has invalid ${field}: expected a JSON object like '{"${key}": 10}', got '${raw}'.`,
+			);
+		}
+		if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+			throw new Error(
+				`Agent '${filePath}' has invalid ${field}: expected a JSON object with a '${key}' key.`,
+			);
+		}
+		const value = (parsed as Record<string, unknown>)[key];
+		if (value === undefined) return undefined;
+		if (typeof value !== "number" || !Number.isInteger(value)) {
+			throw new Error(
+				`Agent '${filePath}' has invalid ${field}.${key}: expected a non-negative integer, got ${JSON.stringify(value)}.`,
+			);
+		}
+		if (value < 0) {
+			throw new Error(
+				`Agent '${filePath}' has invalid ${field}.${key}: ${value} is negative. ` +
+					`0 means "none allowed"; omit the field for "no limit".`,
+			);
+		}
+		return value;
+	};
+	const toolMax = read("toolBudget", "maxToolCalls");
+	const turnMax = read("turnBudget", "maxTurns");
+	return {
+		...(toolMax !== undefined ? { tool: { maxToolCalls: toolMax } } : {}),
+		...(turnMax !== undefined ? { turn: { maxTurns: turnMax } } : {}),
+	};
+}
+
+/**
+ * Every frontmatter key a role card may declare.
+ *
+ * Kept next to the parser on purpose: an unknown key used to be silently
+ * ignored, so a typo (`maxSubagentdepth`, `inheritSkill`) produced a card that
+ * looked accepted but did nothing. That is the worst failure mode for a config
+ * file — the author believes the setting is in effect. Cards are now validated
+ * against this list and an unknown key is a hard error.
+ *
+ * When adding a field, add it here AND parse it; a name in this list that no
+ * parser reads is just as misleading as the reverse.
+ */
+const AGENT_FRONTMATTER_FIELDS: ReadonlySet<string> = new Set([
+	// identity
+	"name", "description", "kind", "model", "thinking", "alias", "aliases",
+	"preset", "team", "output", "fallbackModels",
+	// prompt / context
+	"systemPromptMode", "inheritProjectContext", "inheritSkills", "inheritExtensions",
+	"excludeExtensions",
+	"phases",
+	"skillPath", "skills", "defaultReads",
+	// tools
+	"tools", "extensions", "subagentOnlyExtensions",
+	// budgets / guards / lifecycle
+	"defaultProgress", "async", "timeoutMs", "toolTimeoutMs", "completionGuard",
+	"maxSubagentDepth", "allowNestedSubagents", "renewable", "maxRenewals",
+	"utility", "disabled", "worktree", "steer", "onBlocked",
+	"acceptance", "toolBudget", "turnBudget",
+]);
+
+/**
+ * Throw when a card declares a key this parser does not understand.
+ *
+ * Names are compared case-sensitively: YAML keys are case-sensitive, and a
+ * near-miss (`MaxRenewals`) is exactly the typo this is meant to catch.
+ */
+function assertKnownFrontmatter(frontmatter: Record<string, unknown>, filePath: string): void {
+	const unknown = Object.keys(frontmatter).filter((key) => !AGENT_FRONTMATTER_FIELDS.has(key));
+	if (unknown.length === 0) return;
+	const known = [...AGENT_FRONTMATTER_FIELDS].sort().join(", ");
+	throw new Error(
+		`Agent '${filePath}' has unknown frontmatter ${unknown.length === 1 ? "field" : "fields"}: ` +
+			`${unknown.map((key) => `'${key}'`).join(", ")}. ` +
+			`Known fields: ${known}.`,
+	);
 }
 
 /**
@@ -448,6 +694,7 @@ export function parseAgentDocument(
 ): AgentConfig | null {
 	const { frontmatter, body } = parseFrontmatter(content);
 	const fm = frontmatter as AgentFrontmatter;
+	assertKnownFrontmatter(fm, filePath);
 
 	const name = str(fm.name);
 	const description = str(fm.description);
@@ -543,6 +790,7 @@ function applyCapabilityFields(
 	setIf(config, "skills", listOrFalse(fm.skills));
 	setIf(config, "skillPath", list(fm.skillPath));
 	setIf(config, "extensions", list(fm.extensions));
+	if (list(fm.excludeExtensions)) config.excludeExtensions = list(fm.excludeExtensions);
 	setIf(config, "subagentOnlyExtensions", list(fm.subagentOnlyExtensions));
 	setIf(config, "alias", list(fm.alias) ?? list(fm.aliases));
 	setIf(config, "output", str(fm.output));
@@ -558,14 +806,23 @@ function applyBehaviorFields(config: AgentConfig, fm: AgentFrontmatter): void {
 	setIf(config, "completionGuard", bool(fm.completionGuard));
 	setIf(config, "maxSubagentDepth", int(fm.maxSubagentDepth));
 	setIf(config, "allowNestedSubagents", bool(fm.allowNestedSubagents));
+	// D5/D6: parsed verbatim and left absent when undeclared — the defaults live
+	// with the consumers (DEFAULT_RENEWABLE / DEFAULT_MAX_RENEWALS), so this
+	// layer never has to guess whether the role was explicit. `int()` returns 0
+	// for `maxRenewals: 0`, and `setIf` only skips `undefined`, so the
+	// "renewal disabled" spelling survives instead of decaying to the default.
+	setIf(config, "renewable", bool(fm.renewable));
+	setIf(config, "maxRenewals", int(fm.maxRenewals));
 	setIf(config, "utility", bool(fm.utility));
 	setIf(config, "disabled", bool(fm.disabled));
 	setIf(config, "worktree", bool(fm.worktree));
 	setIf(config, "steer", bool(fm.steer));
-	setIf(config, "spawnMode", spawnModeOf(fm.spawnMode, config.filePath));
 	setIf(config, "acceptance", parseAcceptance(fm.acceptance, config.name));
-	setIf(config, "toolBudget", parseBudget(fm.toolBudget));
-	setIf(config, "turnBudget", parseTurnBudget(fm.turnBudget));
+	const phases = parsePhaseMachine(fm.phases, config.filePath);
+	if (phases) config.phases = phases;
+	const budgets = parseBudgets(fm, config.filePath);
+	setIf(config, "toolBudget", budgets.tool);
+	setIf(config, "turnBudget", budgets.turn);
 	// #214 / contract §9: only centurion holds worktree isolation. Writers no
 	// longer auto-default to worktree:true — members work in-place; parallel
 	// isolated writers are N root-dispatched centurions. Explicit worktree:true

package/src/agents/overrides.ts

@@ -31,19 +31,21 @@ export const OVERRIDE_FIELDS = [
 	"inheritProjectContext",
 	"inheritSkills",
 	"inheritExtensions",
+	"excludeExtensions",
 	"defaultProgress",
 	"async",
 	"completionGuard",
 	"allowNestedSubagents",
+	"renewable",
 	"utility",
 	"disabled",
 	"worktree",
 	"steer",
-	"spawnMode",
 	// numbers
 	"timeoutMs",
 	"toolTimeoutMs",
 	"maxSubagentDepth",
+	"maxRenewals",
 	// arrays (a `false` value is meaningful for skills/extensions)
 	"tools",
 	"skills",

package/src/agents/settings.ts

@@ -18,7 +18,6 @@ import {
 	type InProcessLimits,
 	type RpcSettings,
 	type SubagentsSettings,
-	SPAWN_MODES,
 	type TeamConfig,
 	type TeamMember,
 } from "../shared/types.ts";
@@ -471,13 +470,12 @@ function overrideFieldExpected(field: string): string | undefined {
 	if (["description", "model", "preset", "output", "systemPrompt"].includes(field)) return "a string";
 	if (field === "thinking") return "a string or false";
 	if (field === "kind") return `one of: ${AGENT_KINDS.join(", ")}`;
-	if (field === "spawnMode") return `one of: ${SPAWN_MODES.join(", ")}`;
 	if (field === "onBlocked") return "a valid onBlocked policy";
 	if (field === "systemPromptMode") return "replace or append";
-	if (["inheritProjectContext", "inheritSkills", "inheritExtensions", "defaultProgress", "async", "completionGuard", "allowNestedSubagents", "utility", "disabled", "worktree", "steer"].includes(field)) return "a boolean";
-	if (["timeoutMs", "toolTimeoutMs", "maxSubagentDepth"].includes(field)) return "a number";
+	if (["inheritProjectContext", "inheritSkills", "inheritExtensions", "defaultProgress", "async", "completionGuard", "allowNestedSubagents", "utility", "disabled", "worktree", "steer", "renewable"].includes(field)) return "a boolean";
+	if (["timeoutMs", "toolTimeoutMs", "maxSubagentDepth", "maxRenewals"].includes(field)) return "a number";
 	if (field === "skills") return "an array of strings or false";
-	if (["tools", "extensions", "subagentOnlyExtensions", "skillPath", "defaultReads", "fallbackModels", "alias"].includes(field)) return "an array of strings";
+	if (["tools", "extensions", "subagentOnlyExtensions", "excludeExtensions", "skillPath", "defaultReads", "fallbackModels", "alias"].includes(field)) return "an array of strings";
 	return undefined;
 }
 
@@ -485,13 +483,12 @@ function isValidOverrideField(field: string, value: unknown): boolean {
 	if (["description", "model", "preset", "output", "systemPrompt"].includes(field)) return typeof value === "string";
 	if (field === "thinking") return typeof value === "string" || value === false;
 	if (field === "kind") return typeof value === "string" && (AGENT_KINDS as readonly string[]).includes(value);
-	if (field === "spawnMode") return typeof value === "string" && (SPAWN_MODES as readonly string[]).includes(value);
 	if (field === "onBlocked") return typeof value === "string" && VALID_ON_BLOCKED_POLICIES.has(value);
 	if (field === "systemPromptMode") return value === "replace" || value === "append";
-	if (["inheritProjectContext", "inheritSkills", "inheritExtensions", "defaultProgress", "async", "completionGuard", "allowNestedSubagents", "utility", "disabled", "worktree", "steer"].includes(field)) return typeof value === "boolean";
-	if (["timeoutMs", "toolTimeoutMs", "maxSubagentDepth"].includes(field)) return typeof value === "number";
+	if (["inheritProjectContext", "inheritSkills", "inheritExtensions", "defaultProgress", "async", "completionGuard", "allowNestedSubagents", "utility", "disabled", "worktree", "steer", "renewable"].includes(field)) return typeof value === "boolean";
+	if (["timeoutMs", "toolTimeoutMs", "maxSubagentDepth", "maxRenewals"].includes(field)) return typeof value === "number";
 	if (field === "skills") return value === false || isStringArray(value);
-	if (["tools", "extensions", "subagentOnlyExtensions", "skillPath", "defaultReads", "fallbackModels", "alias"].includes(field)) return isStringArray(value);
+	if (["tools", "extensions", "subagentOnlyExtensions", "excludeExtensions", "skillPath", "defaultReads", "fallbackModels", "alias"].includes(field)) return isStringArray(value);
 	return true;
 }
 
@@ -635,15 +632,6 @@ function parseAgentOverrides(
 				`Subagent settings in '${filePath}' have invalid 'agentOverrides.${name}.utility'; expected a boolean.`,
 			);
 		}
-		if (
-			normalized.spawnMode !== undefined &&
-			(typeof normalized.spawnMode !== "string" ||
-				!(SPAWN_MODES as readonly string[]).includes(normalized.spawnMode))
-		) {
-			throw new Error(
-				`Subagent settings in '${filePath}' have invalid 'agentOverrides.${name}.spawnMode'; expected one of: ${SPAWN_MODES.join(", ")}.`,
-			);
-		}
 		parsed[name] = normalized as AgentOverride;
 	}
 	return parsed;

package/src/extension/child-guard.ts

@@ -17,6 +17,7 @@ import {
 	budgetExceededReason,
 	childBudgetFromEnv,
 	wrapBashWithTimeout,
+	type ChildBudget,
 } from "./budget.ts";
 import { shellChunks } from "./playbook.ts";
 
@@ -349,9 +350,32 @@ export function effectiveChildGuardEnv(
 	return childGuardEnvFromProcess(env);
 }
 
+/**
+ * The budget this child session enforces (#295).
+ *
+ * Same precedence as {@link effectiveChildGuardEnv}: the async-local child
+ * context wins, `process.env` is the fallback for rpc children (whose process
+ * really owns those values).
+ *
+ * Why the context is needed at all: the parent computes budgets into
+ * `SpawnInput.env`. An rpc child receives that object as its environment, so
+ * `process.env` has it. An IN-PROCESS child shares the host's `process.env`
+ * instead — the object never becomes environment — so reading only the process
+ * gave the guard the parent's (absent) values and `toolBudget: 3` permitted 12
+ * tool calls.
+ */
+export function effectiveChildBudget(
+	ctx: ChildLaunchContext | undefined = currentChildContext(),
+	env: NodeJS.ProcessEnv = process.env,
+): ChildBudget {
+	const fromContext = ctx?.budget;
+	if (fromContext !== undefined) return fromContext;
+	return childBudgetFromEnv(env);
+}
+
 /** Child-only extension: intercept tools; do not register the parent tool. */
 export function registerChildGuard(pi: ExtensionAPI): void {
-	const budget = childBudgetFromEnv();
+	const budget = effectiveChildBudget();
 	let toolCalls = 0;
 	let turns = 0;
 	pi.on("turn_start", () => { turns += 1; });