@henryqw/pi-subagent 27.1.1 → 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/ephemeral.d.ts

@@ -71,6 +71,8 @@ export interface EphemeralSubagentExecutor {
  * It reuses the active Pi process invocation; it does not resolve a standalone Pi installation.
  */
 export declare function createEphemeralSubagentExecutor(options: EphemeralSubagentExecutorOptions): EphemeralSubagentExecutor;
+/** Longest prefix of `text` within `maxBytes` UTF-8 bytes, never splitting a code point. */
+export declare function utf8Prefix(text: string, maxBytes: number): string;
 export declare function capEphemeralSubagentOutput(text: string): string;
 export declare function addUsage(left: Usage | undefined, right: Usage | undefined): Usage | undefined;
 export declare function formatDuration(milliseconds: number): string;

package/dist/ephemeral.js

@@ -271,7 +271,8 @@ function oversizedToolStart(prefix) {
         return;
     }
 }
-function utf8Prefix(text, maxBytes) {
+/** Longest prefix of `text` within `maxBytes` UTF-8 bytes, never splitting a code point. */
+export function utf8Prefix(text, maxBytes) {
     return new StringDecoder().write(Buffer.from(text).subarray(0, maxBytes));
 }
 function cappedPrefix(text, totalBytes) {

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/dist/runner.d.ts

@@ -1,4 +1,4 @@
-import type { EphemeralSubagentExecutor } from "./ephemeral.ts";
+import { type EphemeralSubagentExecutor } from "./ephemeral.ts";
 import type { PruneOwnership } from "./prune.ts";
 import { IntegrationGit } from "./integration-git.ts";
 import { type AllocationKind, type CheckCommand, type ChangesetTaskRequest, type CleanupKind, type ExecuteRequest, type ExecutionPolicySnapshot, type HostAllocationIntent, type HostAllocationPlan, type ModelClass, type ReviewEvidence, type ResumeRequest, type RunState, type TaskAttempt, type TaskRequest, type TaskState, type WorktreeAllocationIntent, type WorktreeAllocationPlan, type WorkspaceIdentity } from "./schema.ts";

package/dist/runner.js

@@ -1,4 +1,5 @@
 import { readFileSync, realpathSync } from "node:fs";
+import { utf8Prefix } from "./ephemeral.js";
 import { createChildWorktree, finalizeChildWorktree, inspectWorktreeDirty } from "./worktree.js";
 import { runGit } from "./git-process.js";
 import { IntegrationGit } from "./integration-git.js";
@@ -162,11 +163,7 @@ class FollowupControl {
 function bounded(value, maxBytes = MAX_PERSISTED_RUNTIME_TEXT_BYTES) {
     if (Buffer.byteLength(value, "utf8") <= maxBytes)
         return value;
-    const contentBytes = maxBytes - Buffer.byteLength(TRUNCATION_MARKER, "utf8");
-    let end = Math.min(value.length, contentBytes);
-    while (end > 0 && Buffer.byteLength(value.slice(0, end), "utf8") > contentBytes)
-        end -= 1;
-    return `${value.slice(0, end)}${TRUNCATION_MARKER}`;
+    return `${utf8Prefix(value, maxBytes - Buffer.byteLength(TRUNCATION_MARKER, "utf8"))}${TRUNCATION_MARKER}`;
 }
 function boundedRuntimeText(value, field) {
     if (typeof value !== "string")

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

@@ -2,7 +2,7 @@ import { basename } from "node:path";
 import type { JsonValue } from "@earendil-works/pi-ai";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth } from "@earendil-works/pi-tui";
-import type { EphemeralSubagentExecutor } from "../dist/ephemeral.js";
+import { utf8Prefix, type EphemeralSubagentExecutor } from "../dist/ephemeral.js";
 import type { EffectiveExecutionPolicy } from "./config.ts";
 import {
 	createCanonicalGitRootResolver,
@@ -196,9 +196,7 @@ function boundedReport(lines: readonly string[], omitted: string): string {
 
 function boundedPublicText(value: string, maxBytes = PUBLIC_EVIDENCE_MAX_BYTES): string {
 	if (Buffer.byteLength(value, "utf8") <= maxBytes) return value;
-	let end = Math.min(value.length, maxBytes);
-	while (end > 0 && Buffer.byteLength(value.slice(0, end), "utf8") > maxBytes) end -= 1;
-	return `${value.slice(0, end)}\n[truncated]`;
+	return `${utf8Prefix(value, maxBytes)}\n[truncated]`;
 }
 
 function publicFailedCheck(evidence: CheckBatchEvidence | undefined) {
@@ -484,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;
 }
 
@@ -506,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.1",
+  "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": {