@henryqw/pi-subagent 27.1.2 → 27.2.0

package/CONTEXT.md

@@ -36,6 +36,7 @@ Own Role-configured Pi delegation through one `delegate_task` surface:
 ### Global limits
 
 - `config/pi-subagent/config.json` is the only user execution-policy source. It owns `maxSubagents`, `maxTurns`, optional `maxTokens`, `maxCorrections`, and child idle/hard timeout.
+- The config loads through `@henryqw/pi-config-store` fields. An unknown key or an invalid bounded limit, timeout, or `roleDefaults` key warns at launch and uses its finite default. An invalid `maxTokens`, or a file that cannot be read or parsed, disables delegation with an error, because the token default is unlimited. Role Markdown files keep per-file exclusion; durable state stays strict.
 - Request fields cannot override or replenish policy. Durable requests store the policy snapshot and cumulative correction count; current config may tighten the correction allowance.
 - Productive execution has no whole-run wall-clock deadline. Long productive work and later resume remain valid. Direct Herdr observation also has no whole-task elapsed deadline; worker idleness is bounded.
 - Child idle/hard runtime, turn/token handling, outer abort, process I/O, status inspection, termination, and cleanup remain independently bounded. Direct Herdr workers use idle limits, not ephemeral child hard runtime.

package/README.md

@@ -220,11 +220,19 @@ pi-subagent owns `~/.pi/agent/config/pi-subagent/config.json`. If the file is mi
 | `maxCorrections` | Same-worker automatic corrections per isolated request | Safe integer ≥ 0 | `1` |
 | `timeout.idleMinutes` | Direct worker and ephemeral child idle timeout | Positive and within Node's timer range | `10` |
 | `timeout.maxMinutes` | Ephemeral child hard runtime | Greater than idle and within Node's timer range | `30` |
-| `roleDefaults` | Optional `extensions`, `tools`, and `skills` arrays merged into every built-in and user Role, with the same validation as Role fields | Object; unknown keys rejected | None |
+| `roleDefaults` | Optional `extensions`, `tools`, and `skills` arrays merged into every built-in and user Role, with the same validation as Role fields | Object with `extensions`, `tools`, or `skills` | None |
 
 In each merged list, `roleDefaults` entries come first, and the entries of the Role follow. The merge removes duplicates and occurs before resource resolution. Use `roleDefaults` for the provider extension that every child needs. Limits come only from this global file. Request fields cannot override or replenish them. Existing durable requests keep their recorded policy, but a lower current correction limit can tighten recovery. Intentionally, there is no whole-run timeout setting.
 
-Malformed or unreadable JSON, unknown keys, and invalid values block delegation with one actionable warning. The extension preserves the file and never rewrites it automatically.
+A bad config never stops the extension. At launch, and again each time it reads the file (a `delegate_task` call, each later worker of a direct chain, each isolated Role launch, `/subagent roles`, or a status inspection), the extension shows each new problem one time:
+
+- An unknown key shows a warning. The extension ignores the key.
+- A misspelled key that is near a missing key, such as `maxToken` for `maxTokens`, counts as an invalid value of that key. The warning gives the likely key.
+- An invalid value in `maxSubagents`, `maxTurns`, `maxCorrections`, or `timeout` shows a warning. The extension uses the finite default for that key. If `timeout.maxMinutes` is not greater than `timeout.idleMinutes`, the extension uses the default `timeout`.
+- An unknown or invalid key in `roleDefaults` shows a warning. The extension ignores only that key, so Roles get fewer default resources.
+- An invalid or misspelled `maxTokens`, malformed JSON, invalid UTF-8, a file larger than 64 KiB, or an unreadable file shows an error and blocks delegation. The default token limit is unlimited, so the extension does not use a default in these cases. `/subagent` stays available. Correct the file to enable delegation again. The block also applies to work that already runs: the next worker of a direct workflow, or the next Role launch of an isolated request, fails before it starts. A workflow that runs keeps the limits that it started with. If the file had the problem when the session started, also run `/reload`, because the session took its execution limits from the defaults.
+
+No key is required. The extension preserves the file and never rewrites it automatically.
 
 ### Roles
 
@@ -274,6 +282,7 @@ The servers named in `mcps` come only from the global `~/.pi/agent/mcp.json`. In
 | Surface | Type | Purpose |
 | --- | --- | --- |
 | `loadRoleCatalog`, `findRole`, `parseRoleName`, `parseRoleDefaults` | functions | Load built-in and user Roles with `roleDefaults` and per-file errors, then select one by name. |
+| `registerRoleDefaultsReporting(pi, agentDir?)` | function | Reports `roleDefaults` problems at each session start. Returns `report(ctx)`; call it before a lazy `loadRoleCatalog`. Each problem shows one time in each session. |
 | `resolveRoleSkills`, `resolveRoleLaunch`, `resolveConfiguredRoleLaunch` | functions | Resolve effective Pi resources and model routes. |
 | `prepareRoleLaunch`, `finalizeRoleLaunch` | functions | Prepare Role prompts, arguments, and tool policy. |
 | `createEphemeralSubagentExecutor` | function | Run bounded no-session Pi children through a FIFO pool. |

package/dist/index.d.ts

@@ -94,6 +94,40 @@ export interface ResolvedRoleSkills {
 export declare function parseRoleName(value: unknown, source?: string): RoleName;
 /** Validate `config.json` `roleDefaults` with the same rules as Role fields; `label` prefixes errors. */
 export declare function parseRoleDefaults(value: unknown, label?: string): RoleDefaults;
+export interface SubagentConfig {
+    maxSubagents: number;
+    maxTurns: number;
+    maxTokens: number | undefined;
+    maxCorrections: number;
+    timeout: {
+        idleMinutes: number;
+        maxMinutes: number;
+    };
+    roleDefaults: RoleDefaults;
+}
+export declare const DEFAULT_SUBAGENT_CONFIG: Readonly<SubagentConfig>;
+/**
+ * The user `config.json` store shared by the extension and `loadRoleCatalog`.
+ * Invalid bounded limits and `roleDefaults` keys fall back to defaults; an
+ * invalid `maxTokens` disables the config because its default is unlimited.
+ */
+export declare function createSubagentConfigStore(agentDir?: string): import("@henryqw/pi-config-store").ConfigStore<import("@henryqw/pi-config-store").FieldsValue<{
+    maxSubagents: import("@henryqw/pi-config-store").Field<number>;
+    maxTurns: import("@henryqw/pi-config-store").Field<number>;
+    maxTokens: import("@henryqw/pi-config-store").Field<number | undefined>;
+    maxCorrections: import("@henryqw/pi-config-store").Field<number>;
+    timeout: import("@henryqw/pi-config-store").Field<{
+        idleMinutes: number;
+        maxMinutes: number;
+    }>;
+    roleDefaults: import("@henryqw/pi-config-store").Field<RoleDefaults>;
+}>>;
+/**
+ * Report `roleDefaults` issues at each session start, and return a function that reports them after a lazy
+ * Role catalog load, such as `loadRoleCatalog` or `resolveRoleLaunch`. Every pi-config-store reporter shares
+ * one record, so each issue shows one time in each session, also with the pi-subagent extension active.
+ */
+export declare function registerRoleDefaultsReporting(pi: Pick<ExtensionAPI, "on">, agentDir?: string): (ctx: Pick<ExtensionContext, "hasUI" | "ui">) => void;
 declare const BUILTIN_ROLE_NAMES: readonly ["implementer", "reviewer", "scout"];
 export type BuiltinRoleName = (typeof BUILTIN_ROLE_NAMES)[number];
 export declare function loadBuiltinRole(name: BuiltinRoleName): Role;
@@ -101,7 +135,8 @@ export declare function loadBuiltinRole(name: BuiltinRoleName): Role;
  * Package-shipped Roles plus user Roles from `config/pi-subagent`, with
  * `roleDefaults` merged in. A user Role overrides a same-named built-in. Each
  * invalid or duplicate user file is reported and makes its claimed name
- * unavailable without hiding valid Roles. Malformed `roleDefaults` throws.
+ * unavailable without hiding valid Roles. Invalid `roleDefaults` keys are
+ * dropped; a `config.json` that cannot load (for example, malformed JSON) throws.
  */
 export declare function loadRoleCatalog(agentDir?: string): RoleCatalog;
 /** Select one catalog Role, naming invalid files that claim it. */

package/dist/index.js

@@ -2,8 +2,9 @@ import { readFileSync, readdirSync } from "node:fs";
 import { basename, isAbsolute, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { DefaultPackageManager, getAgentDir, parseFrontmatter, SettingsManager, } from "@earendil-works/pi-coding-agent";
-import { extensionConfigDir, extensionConfigPath } from "@henryqw/pi-config-store";
+import { createConfigStore, extensionConfigDir, field, formatConfigIssues, parsers, registerConfigReporting } from "@henryqw/pi-config-store";
 import { hasDisplayControlCharacters } from "./display-text.js";
+import { DEFAULT_MAX_TURNS } from "./ephemeral.js";
 import { loadRoleMcpConfig, parseRoleMcpAllowlist } from "./mcp-role.js";
 import { loadTaskModelsConfig, modelReference, orderedProfileRoutes, PROFILE_NAMES, resolveConfiguredTaskRoute, resolveTaskModelRoute, } from "@henryqw/pi-task-models";
 export { DISPLAY_TEXT_CONTRACT, hasDisplayControlCharacters } from "./display-text.js";
@@ -172,27 +173,97 @@ export function parseRoleDefaults(value, label = "roleDefaults") {
         ...(record.skills === undefined ? {} : { skills: stringList(record.skills, "skills", label) }),
     };
 }
-function readRoleDefaults(agentDir) {
-    const path = extensionConfigPath("pi-subagent", agentDir);
-    let raw;
-    try {
-        raw = readFileSync(path, "utf8");
-    }
-    catch (error) {
-        if (error && typeof error === "object" && "code" in error && error.code === "ENOENT")
-            return {};
-        throw error;
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch (error) {
-        throw new Error(`${path} is not valid JSON (${error instanceof Error ? error.message : String(error)}).`);
+/** Per-key `roleDefaults`: an unknown key or invalid list is reported and dropped, so fewer resources load. */
+const roleDefaultsField = (raw, report) => {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        throw new Error("must be a JSON object");
+    const defaults = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (!ROLE_DEFAULT_KEYS.includes(key)) {
+            report([key], "unknown key", "unknown-key");
+            continue;
+        }
+        try {
+            Object.assign(defaults, parseRoleDefaults({ [key]: value }));
+        }
+        catch (error) {
+            report([key], error instanceof Error ? error.message : String(error));
+        }
     }
-    // Whole-file validation belongs to the execution policy reader, which blocks delegation.
-    const value = parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed.roleDefaults : undefined;
-    return value === undefined ? {} : parseRoleDefaults(value, `${path}: roleDefaults`);
+    return defaults;
+};
+export const DEFAULT_SUBAGENT_CONFIG = Object.freeze({
+    maxSubagents: 5,
+    maxTurns: DEFAULT_MAX_TURNS,
+    maxTokens: undefined,
+    maxCorrections: 1,
+    timeout: Object.freeze({ idleMinutes: 10, maxMinutes: 30 }),
+    roleDefaults: Object.freeze({}),
+});
+const timeoutMinutes = parsers.number({ greaterThan: 0, max: 2_147_483_647 / 60_000 });
+const timeoutField = (raw, report) => {
+    const timeout = parsers.object({
+        idleMinutes: field(timeoutMinutes, DEFAULT_SUBAGENT_CONFIG.timeout.idleMinutes),
+        maxMinutes: field(timeoutMinutes, DEFAULT_SUBAGENT_CONFIG.timeout.maxMinutes),
+    })(raw, report);
+    if (timeout.maxMinutes <= timeout.idleMinutes) {
+        throw new Error(`maxMinutes (${timeout.maxMinutes}) must be greater than idleMinutes (${timeout.idleMinutes})`);
+    }
+    return timeout;
+};
+/**
+ * The user `config.json` store shared by the extension and `loadRoleCatalog`.
+ * Invalid bounded limits and `roleDefaults` keys fall back to defaults; an
+ * invalid `maxTokens` disables the config because its default is unlimited.
+ */
+export function createSubagentConfigStore(agentDir = getAgentDir()) {
+    return createConfigStore({
+        extensionId: "pi-subagent",
+        agentDir,
+        fields: {
+            maxSubagents: field(parsers.integer({ min: 1 }), DEFAULT_SUBAGENT_CONFIG.maxSubagents),
+            maxTurns: field(parsers.integer({ min: 1 }), DEFAULT_SUBAGENT_CONFIG.maxTurns),
+            maxTokens: field(parsers.integer({ min: 1 }), undefined, { onInvalid: "disable" }),
+            maxCorrections: field(parsers.integer({ min: 0 }), DEFAULT_SUBAGENT_CONFIG.maxCorrections),
+            timeout: field(timeoutField, DEFAULT_SUBAGENT_CONFIG.timeout),
+            roleDefaults: field(roleDefaultsField, DEFAULT_SUBAGENT_CONFIG.roleDefaults),
+        },
+    });
+}
+/**
+ * Read only `roleDefaults`. The extension reports and enforces the execution limits, so a bad limit does not
+ * break the Role catalog of other consumers; other keys are not this reader's issues.
+ */
+function loadRoleDefaults(agentDir) {
+    const store = createConfigStore({
+        extensionId: "pi-subagent",
+        agentDir,
+        fields: { roleDefaults: field(roleDefaultsField, DEFAULT_SUBAGENT_CONFIG.roleDefaults) },
+    });
+    const loaded = store.loadSync();
+    const issues = loaded.issues.filter(({ key }) => !key || /^roleDefaults(?![\w$])/.test(key));
+    // A file that cannot load has no trusted `roleDefaults`.
+    return issues.some(({ key }) => !key)
+        ? { store, loaded: { status: "disabled", source: loaded.source, issues } }
+        : { store, loaded: { ...loaded, issues } };
+}
+function readRoleDefaults(agentDir) {
+    const { store, loaded } = loadRoleDefaults(agentDir);
+    if (loaded.status !== "ok")
+        throw new Error(`${store.path}: ${formatConfigIssues(loaded.issues)}`);
+    return loaded.value.roleDefaults;
+}
+/**
+ * Report `roleDefaults` issues at each session start, and return a function that reports them after a lazy
+ * Role catalog load, such as `loadRoleCatalog` or `resolveRoleLaunch`. Every pi-config-store reporter shares
+ * one record, so each issue shows one time in each session, also with the pi-subagent extension active.
+ */
+export function registerRoleDefaultsReporting(pi, agentDir = getAgentDir()) {
+    const target = loadRoleDefaults(agentDir).store;
+    const reporter = registerConfigReporting(pi, []);
+    const report = (ctx) => reporter.report(ctx, target, loadRoleDefaults(agentDir).loaded);
+    pi.on("session_start", (_event, ctx) => report(ctx));
+    return report;
 }
 const withDefaults = (defaults, values) => [...new Set([...(defaults ?? []), ...values])];
 function applyRoleDefaults(role, defaults) {
@@ -262,7 +333,8 @@ function claimedRoleName(file) {
  * Package-shipped Roles plus user Roles from `config/pi-subagent`, with
  * `roleDefaults` merged in. A user Role overrides a same-named built-in. Each
  * invalid or duplicate user file is reported and makes its claimed name
- * unavailable without hiding valid Roles. Malformed `roleDefaults` throws.
+ * unavailable without hiding valid Roles. Invalid `roleDefaults` keys are
+ * dropped; a `config.json` that cannot load (for example, malformed JSON) throws.
  */
 export function loadRoleCatalog(agentDir = getAgentDir()) {
     const defaults = readRoleDefaults(agentDir);
@@ -326,13 +398,8 @@ export function findRole(catalog, name) {
     throw new Error(`Unknown Subagent role: ${name}. Available roles: ${catalog.roles.map((candidate) => candidate.name).join(", ") || "none"}.${catalog.errors.length ? ` ${catalog.errors.length} invalid Role file(s); run /subagent roles.` : ""}`);
 }
 export function resolveTaskRoute(ctx, profileName, agentDir = getAgentDir()) {
-    let config;
-    try {
-        config = loadTaskModelsConfig(agentDir).value;
-    }
-    catch {
-        throw new Error("Couldn't read task model config. Run /task-models.");
-    }
+    // A disabled config throws with the path and the problems.
+    const config = loadTaskModelsConfig(agentDir).value;
     return resolveConfiguredRoute(ctx, profileName, config.profiles[profileName]);
 }
 function resolveConfiguredRoute(ctx, profileName, profile) {

package/extensions/config.ts

@@ -1,158 +1,21 @@
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
-import { createConfigStore, extensionConfigPath } from "@henryqw/pi-config-store";
+import { formatConfigIssues, type ConfigLoad } from "@henryqw/pi-config-store";
 import type { ExecutionPolicySnapshot } from "../dist/schema.js";
-import { parseRoleDefaults, type RoleDefaults } from "@henryqw/pi-subagent";
-
-export interface SubagentTimeoutConfig {
-	/** Minutes a child may stay idle before it is asked to stop. */
-	idleMinutes?: number;
-	/** Hard cap in minutes before a child is killed regardless of activity. */
-	maxMinutes?: number;
-}
-
-export interface SubagentConfig {
-	maxSubagents?: number;
-	maxTurns?: number;
-	maxTokens?: number;
-	maxCorrections?: number;
-	timeout?: SubagentTimeoutConfig;
-	/** Merged into every Role by `loadRoleCatalog`; validated here so malformed values block delegation. */
-	roleDefaults?: RoleDefaults;
-}
-
-export interface LoadedSubagentConfig {
-	source: "file" | "missing";
-	config: SubagentConfig;
-	/** Human-readable problems; malformed files are preserved and delegation fails closed. */
-	error?: string;
-}
+import type { SubagentConfig } from "@henryqw/pi-subagent";
 
 export type EffectiveExecutionPolicy = ExecutionPolicySnapshot;
 
-type ParsedSubagentConfig = Omit<LoadedSubagentConfig, "source">;
-
-const EXTENSION_ID = "pi-subagent";
-const positive = (value: unknown): value is number =>
-	typeof value === "number" && Number.isFinite(value) && value > 0;
-const MAX_TIMER_DELAY_MS = 2_147_483_647;
-export const DEFAULT_TIMEOUT_CONFIG = { idleMinutes: 10, maxMinutes: 30 } as const;
-export const DEFAULT_EXECUTION_POLICY = {
-	maxSubagents: 5,
-	maxTurns: 50,
-	maxCorrections: 1,
-} as const;
-const INTEGER_FIELDS = ["maxSubagents", "maxTurns", "maxTokens"] as const;
-const POLICY_FIELDS = ["maxCorrections"] as const;
-const TIMEOUT_FIELDS = ["idleMinutes", "maxMinutes"] as const;
-
-export const configPath = (agentDir = getAgentDir()): string =>
-	extensionConfigPath(EXTENSION_ID, agentDir);
-
-function parseSubagentConfig(parsed: unknown, path: string): ParsedSubagentConfig {
-	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-		return { config: {}, error: `${path} must contain a JSON object; delegation is blocked until this file is corrected.` };
-	}
-	const record = parsed as Record<string, unknown>;
-	const problems: string[] = [];
-	const config: SubagentConfig = {};
-	for (const key of Object.keys(record)) {
-		if (![...INTEGER_FIELDS, ...POLICY_FIELDS, "timeout", "roleDefaults"].includes(key as never)) {
-			problems.push(`unknown config key ${JSON.stringify(key)}; expected ${[...INTEGER_FIELDS, ...POLICY_FIELDS].join(", ")}, timeout, roleDefaults`);
-		}
-	}
-	if (record.roleDefaults !== undefined) {
-		try { config.roleDefaults = parseRoleDefaults(record.roleDefaults); }
-		catch (error) { problems.push(error instanceof Error ? error.message : String(error)); }
+/** Resolve one immutable policy. A disabled config blocks delegation. */
+export function resolveExecutionPolicy(path: string, loaded: ConfigLoad<SubagentConfig>): EffectiveExecutionPolicy {
+	if (loaded.status === "disabled") {
+		throw new Error(`${path}: ${formatConfigIssues(loaded.issues)}; delegation is blocked until this file is corrected.`);
 	}
-	for (const key of INTEGER_FIELDS) {
-		const value = record[key];
-		if (value === undefined) continue;
-		if (typeof value === "number" && Number.isSafeInteger(value) && value >= 1) config[key] = value;
-		else problems.push(`${key} must be a safe integer >= 1, got ${JSON.stringify(value)}`);
-	}
-	if (record.maxCorrections !== undefined) {
-		if (!Number.isSafeInteger(record.maxCorrections) || (record.maxCorrections as number) < 0) {
-			problems.push(`maxCorrections must be a safe integer >= 0, got ${JSON.stringify(record.maxCorrections)}`);
-		} else config.maxCorrections = record.maxCorrections as number;
-	}
-	if (record.timeout !== undefined) {
-		if (!record.timeout || typeof record.timeout !== "object" || Array.isArray(record.timeout)) {
-			problems.push(`timeout must be a JSON object, got ${JSON.stringify(record.timeout)}`);
-		} else {
-			const timeoutRecord = record.timeout as Record<string, unknown>;
-			const timeout: SubagentTimeoutConfig = {};
-			for (const key of TIMEOUT_FIELDS) {
-				const value = timeoutRecord[key];
-				if (value === undefined) continue;
-				if (!positive(value)) problems.push(`timeout.${key} must be a positive number of minutes, got ${JSON.stringify(value)}`);
-				else if (value * 60_000 > MAX_TIMER_DELAY_MS) problems.push(`timeout.${key} exceeds ${MAX_TIMER_DELAY_MS} ms, got ${JSON.stringify(value)} minutes`);
-				else timeout[key] = value;
-			}
-			for (const key of Object.keys(timeoutRecord)) {
-				if (!TIMEOUT_FIELDS.includes(key as keyof SubagentTimeoutConfig)) problems.push(`unknown timeout.${key}; expected ${TIMEOUT_FIELDS.join(", ")}`);
-			}
-			if (Object.keys(timeout).length) config.timeout = timeout;
-		}
-	}
-	if (config.timeout) {
-		const idleMinutes = config.timeout.idleMinutes ?? DEFAULT_TIMEOUT_CONFIG.idleMinutes;
-		const maxMinutes = config.timeout.maxMinutes ?? DEFAULT_TIMEOUT_CONFIG.maxMinutes;
-		if (maxMinutes <= idleMinutes) {
-			problems.push(`timeout.maxMinutes (${maxMinutes}) must be greater than timeout.idleMinutes (${idleMinutes})`);
-			delete config.timeout;
-		}
-	}
-	return {
-		config,
-		error: problems.length ? `${path}: ${problems.join("; ")}; delegation is blocked until this file is corrected.` : undefined,
-	};
-}
-
-/** Resolve one immutable policy. Malformed explicit safety settings fail closed. */
-export function resolveExecutionPolicy(loaded: LoadedSubagentConfig): EffectiveExecutionPolicy {
-	if (loaded.error) throw new Error(loaded.error);
-	const timeout = loaded.config.timeout;
+	const { maxSubagents, maxTurns, maxTokens, maxCorrections, timeout } = loaded.value;
 	return Object.freeze({
-		maxSubagents: loaded.config.maxSubagents ?? DEFAULT_EXECUTION_POLICY.maxSubagents,
-		maxTurns: loaded.config.maxTurns ?? DEFAULT_EXECUTION_POLICY.maxTurns,
-		...(loaded.config.maxTokens === undefined ? {} : { maxTokens: loaded.config.maxTokens }),
-		childIdleMs: (timeout?.idleMinutes ?? DEFAULT_TIMEOUT_CONFIG.idleMinutes) * 60_000,
-		childMaxMs: (timeout?.maxMinutes ?? DEFAULT_TIMEOUT_CONFIG.maxMinutes) * 60_000,
-		maxCorrections: loaded.config.maxCorrections ?? DEFAULT_EXECUTION_POLICY.maxCorrections,
+		maxSubagents,
+		maxTurns,
+		...(maxTokens === undefined ? {} : { maxTokens }),
+		childIdleMs: timeout.idleMinutes * 60_000,
+		childMaxMs: timeout.maxMinutes * 60_000,
+		maxCorrections,
 	});
 }
-
-/** Read untrusted optional config without rewriting it. */
-export function readSubagentConfig(agentDir = getAgentDir()): LoadedSubagentConfig {
-	const path = configPath(agentDir);
-	let validationError: string | undefined;
-	const store = createConfigStore<SubagentConfig>({
-		extensionId: EXTENSION_ID,
-		agentDir,
-		defaults: () => ({}),
-		parse(value) {
-			const parsed = parseSubagentConfig(value, path);
-			validationError = parsed.error;
-			return parsed.config;
-		},
-	});
-	try {
-		const loaded = store.loadSync();
-		return {
-			source: loaded.source,
-			config: loaded.value,
-			...(validationError === undefined ? {} : { error: validationError }),
-		};
-	} catch (error) {
-		const code = error && typeof error === "object" && "code" in error ? error.code : undefined;
-		if (code !== undefined && code !== "ERR_ENCODING_INVALID_ENCODED_DATA") throw error;
-		const reason = error instanceof Error ? error.message : String(error);
-		return {
-			source: "file",
-			config: {},
-			error: error instanceof SyntaxError
-				? `${path} is not valid JSON (${reason}); delegation is blocked until this file is corrected.`
-				: `${path} couldn't be read (${reason}); delegation is blocked until this file is corrected.`,
-		};
-	}
-}

package/extensions/isolated.ts

@@ -482,6 +482,8 @@ export interface RegisterIsolatedOptions {
 	executor: EphemeralSubagentExecutor;
 	policy: EffectiveExecutionPolicy;
 	currentPolicy(): EffectiveExecutionPolicy;
+	/** Report new config issues, and throw when the config now blocks delegation, before each deferred Role launch. */
+	beforeRoleLaunch?(ctx: ExtensionContext): void;
 	componentsFactory?: CreateIsolatedComponents;
 }
 
@@ -504,7 +506,12 @@ export function registerIsolatedExtension(pi: ExtensionAPI, options: RegisterIso
 	};
 	const getComponents = () => components ??= componentsFactory({
 		pi,
-		context: latestContext,
+		// The launch runtime reads this context only to resolve a Role launch.
+		context: () => {
+			const ctx = latestContext();
+			options.beforeRoleLaunch?.(ctx);
+			return ctx;
+		},
 		executor: options.executor,
 		policy: options.policy,
 		currentPolicy: options.currentPolicy,

package/extensions/subagent.ts

@@ -1,9 +1,10 @@
 import { randomUUID } from "node:crypto";
 import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
 import { type Component, Text, type TUI, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
-import { availableTaskModels, loadTaskModelsConfig, modelReference, type ProfileName, registerModelTask, resolveAvailableModel, resolveConfiguredTaskRoute, type ResolvedTaskRoute, taskThinkingLevels } from "@henryqw/pi-task-models";
-import { capEphemeralSubagentOutput as capOutput, createEphemeralSubagentExecutor, DELEGATE_TASK, findRole, formatDuration, loadRoleCatalog, prepareRoleLaunch, resolveRolePackageResources, resolveTaskRoute, ROLE_TOOL_POLICY_FLAG, type Role } from "@henryqw/pi-subagent";
-import { readSubagentConfig, resolveExecutionPolicy, type EffectiveExecutionPolicy } from "./config.ts";
+import { availableTaskModels, loadTaskModelsConfig, modelReference, type ProfileName, registerModelTask, registerTaskModelsConfigReporting, resolveAvailableModel, resolveConfiguredTaskRoute, type ResolvedTaskRoute, taskThinkingLevels } from "@henryqw/pi-task-models";
+import { registerConfigReporting } from "@henryqw/pi-config-store";
+import { capEphemeralSubagentOutput as capOutput, createEphemeralSubagentExecutor, createSubagentConfigStore, DEFAULT_SUBAGENT_CONFIG, DELEGATE_TASK, findRole, formatDuration, loadRoleCatalog, prepareRoleLaunch, resolveRolePackageResources, resolveTaskRoute, ROLE_TOOL_POLICY_FLAG, type Role } from "@henryqw/pi-subagent";
+import { resolveExecutionPolicy, type EffectiveExecutionPolicy } from "./config.ts";
 import { registerCheckoutAdmission } from "./admission.ts";
 import { registerIsolatedExtension } from "./isolated.ts";
 import { directRef, registerSubagentCommand, type DirectDisplay, type DirectTask } from "./subagent-command.ts";
@@ -180,20 +181,45 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 	const widgetItems = new Map<string, WidgetItem>();
 	const tokenHandles = new Map<string, DirectHandle>();
 	const samplingTokens = new Set<string>();
-	const loadedConfig = readSubagentConfig();
-	let initialPolicy: EffectiveExecutionPolicy;
-	try {
-		initialPolicy = resolveExecutionPolicy(loadedConfig);
-	} catch {
-		initialPolicy = resolveExecutionPolicy({ source: "missing", config: {} });
-	}
+	const configStore = createSubagentConfigStore();
+	const configReporter = registerConfigReporting(pi, [configStore]);
+	const reportTaskModels = registerTaskModelsConfigReporting(pi);
+	/** Report new issues before a lazy Role catalog, route, or policy read. */
+	const reportConfig = (ctx: Pick<ExtensionContext, "hasUI" | "ui">): void => {
+		configReporter.report(ctx, configStore, configStore.loadSync());
+		reportTaskModels(ctx);
+	};
+	const loadedConfig = configStore.loadSync();
+	// A disabled config blocks each delegation; the executor still needs finite limits.
+	const initialPolicy = resolveExecutionPolicy(configStore.path, loadedConfig.status === "ok" ? loadedConfig
+		: { status: "ok", source: loadedConfig.source, value: DEFAULT_SUBAGENT_CONFIG, issues: [] });
 	const executor = createEphemeralSubagentExecutor({
 		maxConcurrency: initialPolicy.maxSubagents,
 		maxTurns: initialPolicy.maxTurns,
 		maxTokens: initialPolicy.maxTokens,
 		timeout: { idleMs: initialPolicy.childIdleMs, maxMs: initialPolicy.childMaxMs },
 	});
-	const currentPolicy = (): EffectiveExecutionPolicy => resolveExecutionPolicy(readSubagentConfig());
+	// The isolated runner reads the policy lazily without a context, so each read reports through the session's.
+	let latestCtx: ExtensionContext | undefined;
+	const currentPolicy = (): EffectiveExecutionPolicy => {
+		const loaded = configStore.loadSync();
+		if (latestCtx) configReporter.report(latestCtx, configStore, loaded);
+		const policy = resolveExecutionPolicy(configStore.path, loaded);
+		// The executor took its limits from the defaults, which can be unlimited, so a repaired file needs a reload.
+		if (loadedConfig.status === "disabled") {
+			throw new Error(`${configStore.path} was disabled when the session started; run /reload to apply its execution limits.`);
+		}
+		return policy;
+	};
+	/**
+	 * Before a deferred Role launch: report new issues, then revalidate so a now-disabled config blocks the child.
+	 * The workflow keeps the limits that it admitted at entry (direct idle timeout and concurrency, or the durable
+	 * isolated request's recorded policy); a limit change applies to the next workflow.
+	 */
+	const beforeRoleLaunch = (ctx: ExtensionContext): void => {
+		reportConfig(ctx);
+		currentPolicy();
+	};
 	const canWrite = (input: unknown): boolean => {
 		try {
 			const parsed = parseDelegateTask(input);
@@ -222,6 +248,7 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 		executor,
 		policy: initialPolicy,
 		currentPolicy,
+		beforeRoleLaunch,
 	});
 	let directSequence = 0;
 	const directTasks = new Map<string, {
@@ -237,7 +264,6 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 		return tab.entryId === saved.entryId && tab.name === saved.name && tab.tabId === saved.tabId
 			&& tab.paneId === saved.paneId && tab.sessionFile === saved.sessionFile;
 	});
-	let latestCtx: ExtensionContext | undefined;
 	let sessionEpoch = 0;
 	// Shutdown still saves outgoing identities; only a session start defers records to its carry loop.
 	let directRecordEpoch = 0;
@@ -311,6 +337,7 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 			if (!current()) throw new Error("Session or branch changed before status inspection.");
 			const snapshot = notices.join("\n");
 			if (Buffer.byteLength(snapshot, "utf8") > 32_000) throw new Error("Status exceeds the 32 KiB inspection limit; use subagent_status for exact evidence.");
+			reportConfig(ctx);
 			const role = findRole(loadRoleCatalog(), "scout");
 			const prepared = await prepareDirectLaunch(role, ctx, { modelClass: "fast" });
 			const herdr = createDirectHerdr(pi, ctx.cwd, currentPolicy().childIdleMs);
@@ -354,6 +381,7 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 		roles(ctx) {
 			const message = (error: unknown) => error instanceof Error ? error.message : String(error);
 			let catalog: ReturnType<typeof loadRoleCatalog>;
+			reportConfig(ctx);
 			try { catalog = loadRoleCatalog(); } catch (error) { return `Role catalog unavailable: ${message(error)}`; }
 			const list = (values: readonly string[] | undefined) => values?.length ? values.join(", ") : "none";
 			const lines = catalog.roles.flatMap((role) => {
@@ -507,13 +535,12 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 		}
 		latestCtx = ctx;
 		ensureWidget(ctx);
-		if (loadedConfig.error !== undefined) ctx.ui.notify(loadedConfig.error, "warning");
 		try {
 			if (loadTaskModelsConfig().source === "missing") {
 				ctx.ui.notify("Task model config is missing; run /task-models to configure it.", "warning");
 			}
 		} catch {
-			// Route resolution retains the existing malformed shared-config error.
+			// A disabled shared config throws; the task-models config reporter already shows the path and the problems.
 		}
 	});
 	pi.on("session_shutdown", async (_event, ctx) => {
@@ -620,6 +647,8 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 		},
 		async execute(toolCallId, params, signal, _onUpdate, ctx) {
 			signal?.throwIfAborted();
+			// Isolated requests read the policy in the runner; report it here with the tool's context.
+			reportConfig(ctx);
 			const parsed = parseDelegateTask(params);
 			if (parsed.mode === "isolated") return await isolatedSurface.execute(parsed.request, signal, ctx);
 			const workflow = parsed.workflow;
@@ -719,6 +748,8 @@ export default function subagentExtension(pi: ExtensionAPI): void {
 			directTasks.set(taskId, local);
 			const launch = async (entry: WorkflowEntry, activeSignal: AbortSignal) => {
 				activeSignal.throwIfAborted();
+				// A later worker launches after earlier ones finish; report and revalidate config edits made meanwhile.
+				beforeRoleLaunch(latestCtx ?? ctx);
 				const role = findRole(loadRoleCatalog(), entry.delegation.role);
 				const { modelClass, model } = entry.delegation;
 				const prepared = await prepareDirectLaunch(role, latestCtx ?? ctx, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-subagent",
-  "version": "27.1.2",
+  "version": "27.2.0",
   "description": "Delegate bounded direct work or durable checked isolated task graphs to Pi roles.",
   "keywords": [
     "pi-package",
@@ -66,11 +66,11 @@
     "image": "https://raw.githubusercontent.com/HenryQW/pi-harness/main/extensions/pi-subagent/example.png"
   },
   "dependencies": {
-    "@henryqw/pi-config-store": "^3.0.0",
+    "@henryqw/pi-config-store": "^4.0.0",
     "@henryqw/pi-herdr": "^0.5.0",
     "@henryqw/pi-multi-codex": "^3.0.0",
     "@henryqw/pi-process": "^0.2.0",
-    "@henryqw/pi-task-models": "^8.0.0",
+    "@henryqw/pi-task-models": "^9.0.0",
     "proper-lockfile": "^4.1.2"
   },
   "devDependencies": {