@nredd/pi-subagents 0.22.0-nredd.8 → 0.22.0-nredd.9

package/src/plan-mode-children.ts

@@ -0,0 +1,176 @@
+/**
+ * plan-mode-children.ts -- keeps a child started while the parent plans in Plan
+ * mode (#437), as Claude Code keeps a subagent spawned in plan mode in plan mode.
+ *
+ * pi-plan-mode gates only its own session's tool calls, and a child is a separate
+ * session on a separate event bus. So right before a child runs, the manager asks
+ * the parent's pi-plan-mode, synchronously on the parent's `pi.events`, whether it
+ * is planning; when it is, the answer carries the Plan tool policy, and this
+ * module applies it to every call the child makes. No answer means pi-plan-mode is
+ * not installed, and nothing changes.
+ *
+ * The contract mirrors `packages/plan-mode/src/child-policy.ts`, repeated rather
+ * than imported because either package installs without the other.
+ */
+import type { ToolInfo } from "@earendil-works/pi-coding-agent";
+import type { AgentRecord } from "./types.js";
+
+export const PLAN_MODE_STATE_QUERY = "pi-plan-mode:state-query";
+/** pi-plan-mode asks here whether a compatible gate is installed; answering is the handshake. */
+export const PLAN_MODE_GATE_QUERY = "pi-plan-mode:gate-query";
+const PLAN_MODE_STATE_VERSION = 1;
+
+/** Buses on which pi-plan-mode has shown itself by asking {@link PLAN_MODE_GATE_QUERY}. */
+const planModeSeen = new WeakSet<object>();
+
+/**
+ * Answer pi-plan-mode's gate query, so Plan admits `Agent` and friends, and remember that Plan
+ * mode is installed on this bus: from then on a state query nobody answers fails closed.
+ */
+export function answerPlanGateQueries(events: { on(channel: string, handler: (data: unknown) => void): unknown }): void {
+  events.on(PLAN_MODE_GATE_QUERY, (data) => {
+    planModeSeen.add(events);
+    const reply = (data as { reply?: unknown } | undefined)?.reply;
+    if (typeof reply === "function") reply({ version: PLAN_MODE_STATE_VERSION, gate: "@nredd/pi-subagents" });
+  });
+}
+
+/** Thrown when pi-plan-mode is installed but did not answer whether it is planning. */
+export const PLAN_MODE_SILENT_ERROR =
+  "Plan mode is installed but did not answer whether it is planning, so this subagent was not started. Reload Pi, or update @nredd/pi-plan-mode and @nredd/pi-subagents together.";
+
+/** One tool call inside a child session. */
+interface PlanModeChildToolCall {
+  toolName: string;
+  input: unknown;
+  cwd: string;
+  tool: ToolInfo | undefined;
+}
+
+/** Why Plan mode refuses a child's tool call, or `undefined` when it may run. */
+export type PlanToolPolicy = (call: PlanModeChildToolCall) => string | undefined;
+
+/**
+ * The Plan restriction one child run is under. Mutable on purpose: it is decided
+ * per run (a spawn, then each resume) while the hooks reading it are installed
+ * once, on the child's session.
+ */
+export interface PlanGate {
+  policy?: PlanToolPolicy;
+}
+
+/** Tools a child keeps without asking: safe built-ins only. */
+const FAIL_CLOSED_TOOLS: ReadonlySet<string> = new Set(["read", "grep", "find", "ls"]);
+
+/**
+ * For a planner that says it is active but sent no policy this host understands:
+ * nothing beyond the safe built-ins, so a contract mismatch can never run a child
+ * unrestricted.
+ */
+const failClosedPolicy: PlanToolPolicy = ({ toolName }) =>
+  FAIL_CLOSED_TOOLS.has(toolName)
+    ? undefined
+    : `Plan mode is active and sent no tool policy this subagent understands, so '${toolName}' is blocked.`;
+
+/**
+ * Ask the parent's pi-plan-mode whether a child started now must plan. Returns
+ * the policy to run it under, or `undefined` when nobody is planning. Several
+ * answers (two Plan extensions) combine fail-closed: any active one restricts.
+ * A malformed answer (not version 1 with a boolean `active`) restricts like an unusable one.
+ * When Plan mode is installed but nothing answers, a new child is refused
+ * (`silent: "refuse"`, which throws) and a resumed one runs fail-closed.
+ */
+export function queryPlanPolicy(
+  events: { emit(channel: string, data: unknown): void } | undefined,
+  silent: "refuse" | "restrict" = "refuse",
+): PlanToolPolicy | undefined {
+  // Hosts without an event bus (bare programmatic callers) cannot run pi-plan-mode either.
+  if (!events) return undefined;
+  const policies: PlanToolPolicy[] = [];
+  let answered = false;
+  events.emit(PLAN_MODE_STATE_QUERY, {
+    version: PLAN_MODE_STATE_VERSION,
+    reply: (state: unknown) => {
+      const answer = state as { version?: unknown; active?: unknown; evaluate?: unknown } | undefined;
+      // Only a well-formed answer says whether Plan is on; anything else restricts, never frees.
+      if (answer?.version !== PLAN_MODE_STATE_VERSION || typeof answer.active !== "boolean") {
+        policies.push(failClosedPolicy);
+        return;
+      }
+      answered = true;
+      if (!answer.active) return;
+      policies.push(typeof answer.evaluate === "function" ? (answer.evaluate as PlanToolPolicy) : failClosedPolicy);
+    },
+  });
+  if (!answered && policies.length === 0 && planModeSeen.has(events)) {
+    if (silent === "refuse") throw new Error(PLAN_MODE_SILENT_ERROR);
+    return failClosedPolicy;
+  }
+  if (policies.length === 0) return undefined;
+  return (call) => {
+    for (const policy of policies) {
+      const reason = policy(call);
+      if (reason !== undefined) return reason;
+    }
+    return undefined;
+  };
+}
+
+/**
+ * Whether a Plan policy is active on `events` now, failing closed: an installed Plan mode that
+ * answers badly or not at all counts as planning. For work that would otherwise outlive Plan
+ * unrestricted (a schedule, a quota-parked dispatch, steering an unrestricted child).
+ */
+export function planningNow(events: { emit(channel: string, data: unknown): void } | undefined): boolean {
+  return queryPlanPolicy(events, "restrict") !== undefined;
+}
+
+/**
+ * Whether a steer must be refused: the agent is running or queued under no Plan policy (it started
+ * before Plan) while Plan is active, so the steer would drive it with its full surface. The one
+ * predicate for `steer_subagent` and `subagents:rpc:steer`.
+ */
+export function planSteerBlocked(
+  record: Pick<AgentRecord, "status" | "planGate">,
+  events: { emit(channel: string, data: unknown): void } | undefined,
+): boolean {
+  return (record.status === "running" || record.status === "queued") && !record.planGate?.policy && planningNow(events);
+}
+
+/** Plan's model must not steer a child that runs without Plan's restrictions. */
+export function planSteerRefusal(id: string): string {
+  return (
+    `Cannot steer agent "${id}" while Plan mode is active: it started before Plan and runs without Plan's restrictions, so a steer could make it edit. ` +
+    "Wait for it to finish and steer it then (that resumes it read-only), stop it with stop_subagent, or leave Plan mode (/plan exit) first."
+  );
+}
+
+/** A scheduled agent fires as a fresh spawn, after Plan, with nothing restricting it. */
+export const PLAN_SCHEDULE_REFUSAL =
+  "Cannot schedule an agent while Plan mode is active: it would start later, after Plan, without Plan's restrictions. Start it now, or leave Plan mode first.";
+
+/** A quota-parked dispatch is a scheduled job too. */
+export const PLAN_PARK_REFUSAL =
+  "The agent was not started or parked: Plan mode is active, and a parked agent would start after Plan without Plan's restrictions. Retry after the reset, or leave Plan mode first.";
+
+/**
+ * The refusal for one child tool call, or `undefined`. Tools this extension
+ * injects (nested delegation, whose children inherit the gate; StructuredOutput;
+ * the workflow refusal) are exempt: Plan's policy has no entry for them.
+ */
+export function planGateReason(
+  gate: PlanGate | undefined,
+  call: { toolName: string; input: unknown; cwd: string },
+  tools: () => ToolInfo[],
+  exempt: ReadonlySet<string>,
+): string | undefined {
+  const policy = gate?.policy;
+  if (!policy || exempt.has(call.toolName)) return undefined;
+  return policy({ ...call, tool: tools().find((tool) => tool.name === call.toolName) });
+}
+
+/** Told to a child started while planning, so a refused write is not a surprise. */
+export const PLAN_MODE_CHILD_PROMPT = `<plan_mode>
+Your parent is in Plan mode, so you are too: investigate and report, do not change anything.
+edit and write are blocked, bash runs only reviewed read-only commands, and other tools run only when Plan mode admits them.
+</plan_mode>`;

package/src/prompts.ts

@@ -2,6 +2,7 @@
  * prompts.ts — System prompt builder for agents.
  */
 
+import { PLAN_MODE_CHILD_PROMPT } from "./plan-mode-children.js";
 import type { AgentConfig, EnvInfo } from "./types.js";
 
 /** Extra sections to inject into the system prompt (memory, skills, etc.). */
@@ -16,6 +17,8 @@ export interface PromptExtras {
    * to stay in the copy.
    */
   worktreeBase?: string;
+  /** Set when the parent was planning at spawn: the child is told it plans too (#437). */
+  planMode?: boolean;
   /**
    * Set only for a workflow's own children, and only when they have no
    * `StructuredOutput` tool to answer through.
@@ -93,6 +96,8 @@ Return only the answer, in exactly the shape the prompt asks for — no preamble
 </workflow_child>`
     : "";
 
+  const planModeBlock = extras?.planMode ? `\n\n${PLAN_MODE_CHILD_PROMPT}` : "";
+
   const nestingBlock = extras?.nestingDisabled
     ? `\n\n<nesting_disabled>
 Nested subagents are disabled for this session, so you have no Agent tool. Do the work yourself, inline.
@@ -137,7 +142,7 @@ You are operating as a sub-agent invoked to handle a specific task.
     // placed verbatim (no wrapper tag) so it forms an identical byte prefix
     // with the parent session, maximising KV cache hits. The <active_agent>
     // tag and env block vary per call and are placed after the cached prefix.
-    return identity + "\n\n" + bridge + "\n\n" + activeAgentTag + envBlock + worktreeBlock + workflowBlock + nestingBlock + customSection + extrasSuffix;
+    return identity + "\n\n" + bridge + "\n\n" + activeAgentTag + envBlock + worktreeBlock + planModeBlock + workflowBlock + nestingBlock + customSection + extrasSuffix;
   }
 
   // "replace" mode — env header + the config's full system prompt
@@ -146,7 +151,7 @@ You have been invoked to handle a specific task autonomously.
 
 ${envBlock}`;
 
-  return activeAgentTag + replaceHeader + worktreeBlock + workflowBlock + nestingBlock + "\n\n" + config.systemPrompt + extrasSuffix;
+  return activeAgentTag + replaceHeader + worktreeBlock + planModeBlock + workflowBlock + nestingBlock + "\n\n" + config.systemPrompt + extrasSuffix;
 }
 
 /** Fallback base prompt when parent system prompt is unavailable in append mode. */

package/src/quota-admission.ts

@@ -56,8 +56,9 @@ export async function checkAdmission(
   model: string,
   timeoutMs = ADMIT_TIMEOUT_MS,
   clock: Clock = realClock,
+  signal?: AbortSignal,
 ): Promise<QuotaBlock | undefined> {
-  return (await admissionOutcome(events, model, timeoutMs, clock)).block;
+  return (await admissionOutcome(events, model, timeoutMs, clock, signal)).block;
 }
 
 /** Retain the physical admission label and whether the router supplied a signal. */
@@ -66,15 +67,23 @@ export function admissionOutcome(
   model: string,
   timeoutMs = ADMIT_TIMEOUT_MS,
   clock: Clock = realClock,
+  signal?: AbortSignal,
 ): Promise<TierAdmission> {
+  if (signal?.aborted) return Promise.reject(new DOMException("Admission cancelled", "AbortError"));
   const requestId = nanoid();
-  return new Promise(resolve => {
-    let done = false;
-    const finish = (outcome: TierAdmission) => {
-      if (done) return;
-      done = true;
+  return new Promise((resolve, reject) => {
+    // Every step is idempotent and a promise settles once, so no `done` latch is needed.
+    const cleanup = () => {
       timer.cancel();
       unsubscribe();
+      signal?.removeEventListener("abort", abort);
+    };
+    const abort = () => {
+      cleanup();
+      reject(new DOMException("Admission cancelled", "AbortError"));
+    };
+    const finish = (outcome: TierAdmission) => {
+      cleanup();
       resolve(outcome);
     };
     const unsubscribe = events.on(`${ADMIT_CHANNEL}:reply:${requestId}`, raw => {
@@ -90,6 +99,7 @@ export function admissionOutcome(
       } });
     });
     const timer = clock.setTimeout(() => finish({ quotaSignal: false }), timeoutMs);
+    signal?.addEventListener("abort", abort, { once: true });
     events.emit(ADMIT_CHANNEL, { requestId, model });
   });
 }

package/src/resource-loader.ts

@@ -1,5 +1,5 @@
 /** Normalize explicit settings paths before Pi's real package manager resolves them. */
-import { DefaultResourceLoader, SettingsManager } from "@earendil-works/pi-coding-agent";
+import { DefaultPackageManager, DefaultResourceLoader, SettingsManager } from "@earendil-works/pi-coding-agent";
 import { normalizeHomePath } from "./home-paths.js";
 
 type ResourceLoaderOptions = ConstructorParameters<typeof DefaultResourceLoader>[0];
@@ -35,10 +35,10 @@ export function normalizeResourceSettings(settings: ResourceSettings, homeDir: s
   return normalized;
 }
 
-/** Use the real loader/manager while preventing ambient-home expansion of explicit settings. */
-export function createHomeResourceLoader(options: ResourceLoaderOptions, homeDir?: string): DefaultResourceLoader {
-  if (homeDir === undefined) return new DefaultResourceLoader(options);
-  const settingsManager = options.settingsManager ?? SettingsManager.create(options.cwd, options.agentDir);
+type PackageManagerOptions = ConstructorParameters<typeof DefaultPackageManager>[0];
+
+/** Wrap settings readers once so Pi receives injected-home resource paths. */
+function normalizeHomeResourceSettings(settingsManager: SettingsManager, homeDir: string): SettingsManager {
   const globalSettings = settingsManager.getGlobalSettings.bind(settingsManager);
   const projectSettings = settingsManager.getProjectSettings.bind(settingsManager);
   // Wrap the public readers, not a cached snapshot: reload and project-trust
@@ -47,5 +47,19 @@ export function createHomeResourceLoader(options: ResourceLoaderOptions, homeDir
     getGlobalSettings: () => normalizeResourceSettings(globalSettings(), homeDir),
     getProjectSettings: () => normalizeResourceSettings(projectSettings(), homeDir),
   });
-  return new DefaultResourceLoader({ ...options, settingsManager });
+  return settingsManager;
+}
+
+/** Build Pi's package manager with injected-home settings normalization. */
+export function createHomePackageManager(options: PackageManagerOptions, homeDir?: string): DefaultPackageManager {
+  if (homeDir === undefined) return new DefaultPackageManager(options);
+  // `homeDir` also redirects Pi's automatic `<home>/.agents/skills` root (nredd/pi#13).
+  return new DefaultPackageManager({ ...options, homeDir, settingsManager: normalizeHomeResourceSettings(options.settingsManager, homeDir) });
+}
+
+/** Use the real loader/manager while preventing ambient-home expansion of explicit settings. */
+export function createHomeResourceLoader(options: ResourceLoaderOptions, homeDir?: string): DefaultResourceLoader {
+  if (homeDir === undefined) return new DefaultResourceLoader(options);
+  const settingsManager = options.settingsManager ?? SettingsManager.create(options.cwd, options.agentDir);
+  return new DefaultResourceLoader({ ...options, homeDir, settingsManager: normalizeHomeResourceSettings(settingsManager, homeDir) });
 }

package/src/schedule.ts

@@ -51,6 +51,14 @@ export interface NewJobInput {
   quotaParked?: boolean;
 }
 
+/** What `start()` binds, captured by a fire so a later session switch cannot leak into it. */
+interface BoundSession {
+  store: ScheduleStore;
+  pi: ExtensionAPI;
+  ctx: ExtensionContext;
+  manager: AgentManager;
+}
+
 /** Optional in-process scheduling dependencies; omitted clock uses native time. */
 export interface SubagentSchedulerOptions {
   homeDir?: string;
@@ -61,6 +69,10 @@ export class SubagentScheduler {
   private readonly clock: Clock;
   private jobs = new Map<string, Cron>();
   private intervals = new Map<string, TimerHandle>();
+  private scheduled = new Map<string, object>();
+  private admissions = new Map<string, Set<AbortController>>();
+  /** Newest pending admission per job that wrote "running", with the status it replaced. */
+  private pendingRuns = new Map<string, { token: AbortController; prior: ScheduledSubagent["lastStatus"] }>();
   private store: ScheduleStore | undefined;
   private pi: ExtensionAPI | undefined;
   private ctx: ExtensionContext | undefined;
@@ -72,6 +84,7 @@ export class SubagentScheduler {
 
   /** Start the scheduler: bind to a session's store and arm enabled jobs. */
   start(pi: ExtensionAPI, ctx: ExtensionContext, manager: AgentManager, store: ScheduleStore): void {
+    this.stop();
     this.pi = pi;
     this.ctx = ctx;
     this.manager = manager;
@@ -88,6 +101,10 @@ export class SubagentScheduler {
     this.jobs.clear();
     for (const t of this.intervals.values()) t.cancel();
     this.intervals.clear();
+    for (const admissions of this.admissions.values()) for (const admission of admissions) admission.abort();
+    this.admissions.clear();
+    this.pendingRuns.clear();
+    this.scheduled.clear();
     this.store = undefined;
     this.pi = undefined;
     this.ctx = undefined;
@@ -138,7 +155,7 @@ export class SubagentScheduler {
     }
     const job = this.buildJob(input);
     store.add(job);
-    if (job.enabled) this.scheduleJob(job);
+    this.scheduleJob(job); // buildJob always creates an enabled job
     this.emit({ type: "added", job });
     return job;
   }
@@ -183,8 +200,8 @@ export class SubagentScheduler {
   // ── Scheduling primitives ────────────────────────────────────────────
 
   private scheduleJob(job: ScheduledSubagent): void {
-    const store = this.store;
-    if (!store) return;
+    const store = this.requireStore();
+    this.scheduled.set(job.id, {});
     try {
       if (job.scheduleType === "interval" && job.intervalMs) {
         const t = this.clock.setInterval(() => this.executeJob(job.id), job.intervalMs);
@@ -206,6 +223,7 @@ export class SubagentScheduler {
           this.intervals.set(job.id, t);
         } else {
           // Past timestamp — disable, mark error, never fire
+          this.scheduled.delete(job.id);
           store.update(job.id, { enabled: false, lastStatus: "error" });
           this.emit({ type: "error", jobId: job.id, error: `Scheduled time ${job.schedule} is in the past` });
         }
@@ -214,11 +232,16 @@ export class SubagentScheduler {
         this.jobs.set(job.id, cron);
       }
     } catch (err) {
+      // Nothing armed, so no token: a stale entry would admit a fire for a job with no timer.
+      this.scheduled.delete(job.id);
       this.emit({ type: "error", jobId: job.id, error: err instanceof Error ? err.message : String(err) });
     }
   }
 
   private unscheduleJob(id: string): void {
+    this.scheduled.delete(id);
+    for (const admission of this.admissions.get(id) ?? []) admission.abort();
+    this.admissions.delete(id);
     const cron = this.jobs.get(id);
     if (cron) {
       cron.stop();
@@ -241,10 +264,15 @@ export class SubagentScheduler {
     const pi = this.pi;
     const ctx = this.ctx;
     const manager = this.manager;
-    if (!store || !pi || !ctx || !manager) return;
+    const scheduled = this.scheduled.get(id);
+    if (!store || !pi || !ctx || !manager || !scheduled) return;
     const job = store.get(id);
     if (!job?.enabled) return;
 
+    // A fire that overlaps a pending admission inherits its prior status.
+    const previous = this.pendingRuns.get(id);
+    const prior = previous ? previous.prior : job.lastStatus;
+    this.pendingRuns.delete(id);
     store.update(id, { lastStatus: "running" });
 
     // Resolve the original request at fire time, using the same type and model
@@ -268,13 +296,28 @@ export class SubagentScheduler {
     // waited for may have refilled while another is still exhausted.
     const admissionModel = selection.model;
     if ((job.quotaParked || selection.tierBinding) && admissionModel) {
+      const controller = new AbortController();
+      const admissions = this.admissions.get(id) ?? new Set<AbortController>();
+      admissions.add(controller);
+      this.admissions.set(id, admissions);
+      this.pendingRuns.set(id, { token: controller, prior });
+      // Cancelled before spawn: undo this admission's "running", never a newer one's.
+      controller.signal.addEventListener("abort", () => {
+        if (this.pendingRuns.get(id)?.token !== controller) return;
+        this.pendingRuns.delete(id);
+        if (store.get(id)?.lastStatus === "running") store.update(id, { lastStatus: prior });
+      }, { once: true });
       const admission = selection.tierBinding
-        ? admitModelSelection(selection, ctx.modelRegistry, pi.events)
-        : checkAdmission(pi.events, modelRef(admissionModel));
+        ? admitModelSelection(selection, ctx.modelRegistry, pi.events, this.clock, controller.signal)
+        : checkAdmission(pi.events, modelRef(admissionModel), undefined, this.clock, controller.signal);
+      const settle = (): void => {
+        if (this.pendingRuns.get(id)?.token === controller) this.pendingRuns.delete(id);
+      };
       void admission.then(block => {
-        if (this.store !== store || this.ctx !== ctx) return;
+        if (this.store !== store || this.ctx !== ctx || this.scheduled.get(id) !== scheduled) return;
+        settle();
         if (!block) {
-          this.spawnJob(id, selection);
+          this.spawnJob({ store, pi, ctx, manager }, id, selection);
         } else if (mayPark(block) && block.resetAt > this.clock.now()) {
           this.repark(id, block.resetAt);
         } else {
@@ -285,18 +328,25 @@ export class SubagentScheduler {
           this.emit({ type: "error", jobId: id, error: `${describeBlock(block)} The agent was not started.` });
         }
       }).catch(error => {
-        if (this.store !== store) return;
+        if (this.store !== store || this.scheduled.get(id) !== scheduled) return;
+        settle();
         store.update(id, { lastStatus: "error" });
         this.emit({ type: "error", jobId: id, error: error instanceof Error ? error.message : String(error) });
+      }).finally(() => {
+        admissions.delete(controller);
+        if (admissions.size === 0 && this.admissions.get(id) === admissions) this.admissions.delete(id);
       });
       return;
     }
-    this.spawnJob(id, selection);
+    this.spawnJob({ store, pi, ctx, manager }, id, selection);
   }
 
-  /** Re-arm a quota-parked one-shot at a later reset instead of starting it. */
+  /**
+   * Re-arm a quota-parked one-shot at a later reset instead of starting it.
+   * A job removed while admission was pending stays removed: `updateJob` is a
+   * no-op for an unknown id.
+   */
   private repark(id: string, resetAt: number): void {
-    if (!this.store?.get(id)) return;
     this.updateJob(id, {
       enabled: true,
       schedule: new Date(resetAt + QUOTA_RESTART_GRACE_MS).toISOString(),
@@ -306,12 +356,7 @@ export class SubagentScheduler {
   }
 
   /** Spawn a fired job (bypassing the concurrency queue) and persist its outcome. */
-  private spawnJob(id: string, selection: ModelSelection): void {
-    const store = this.store;
-    const pi = this.pi;
-    const ctx = this.ctx;
-    const manager = this.manager;
-    if (!store || !pi || !ctx || !manager) return;
+  private spawnJob({ store, pi, ctx, manager }: BoundSession, id: string, selection: ModelSelection): void {
     const job = store.get(id);
     if (!job) return;
 
@@ -447,7 +492,8 @@ export class SubagentScheduler {
       new Cron(expr, () => {});
       return { valid: true };
     } catch (e) {
-      return { valid: false, error: e instanceof Error ? e.message : "Invalid cron expression" };
+      // Croner only throws Error subclasses (TypeError, RangeError).
+      return { valid: false, error: (e as Error).message };
     }
   }
 

package/src/settings.ts

@@ -6,8 +6,10 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { NO_FALLBACK } from "./agent-types.js";
 import { readEnterpriseLocalManifest } from "./enterprise-local.js";
+import { errorMessage } from "./error-message.js";
 import { resolveAgentDir } from "./home-paths.js";
 import { type ModelResolution, parseTierBinding, setModelTiers } from "./model-tiers.js";
+import { NOTIFICATION_RESULT_CHARS_CEILING } from "./notification-result.js";
 import { type BudgetPolicy, DEFAULT_BUDGET_POLICY } from "./process-budget.js";
 import type { AgentMentionMode, JoinMode, ViewerMarkdownMode, WidgetMode } from "./types.js";
 
@@ -66,6 +68,15 @@ export interface SubagentsSettings {
    */
   defaultMaxTurns?: number;
   graceTurns?: number;
+  /**
+   * Result characters a background completion notice carries per agent,
+   * defaulting to `16000`. Past it the notice keeps the head and tail and
+   * names the transcript and `get_subagent_result`; agents that finish
+   * together share four times this. A result delivered whole counts as read.
+   * `0` restores the 500-character preview (300 per `group` member). See
+   * `notification-result.ts`.
+   */
+  notificationResultChars?: number;
   defaultJoinMode?: JoinMode;
   /**
    * Whether a top-level `Agent` spawn that doesn't say runs detached.
@@ -391,6 +402,7 @@ export interface SettingsAppliers {
   setBudgetPolicy: (policy: BudgetPolicy) => void;
   setDefaultMaxTurns: (n: number) => void;
   setGraceTurns: (n: number) => void;
+  setNotificationResultChars: (n: number) => void;
   setDefaultJoinMode: (mode: JoinMode) => void;
   setBackgroundByDefault: (b: boolean) => void;
   setSchedulingEnabled: (b: boolean) => void;
@@ -502,6 +514,13 @@ function sanitize(raw: unknown): SubagentsSettings {
   ) {
     out.graceTurns = r.graceTurns as number;
   }
+  if (
+    Number.isInteger(r.notificationResultChars) &&
+    (r.notificationResultChars as number) >= 0 &&
+    (r.notificationResultChars as number) <= NOTIFICATION_RESULT_CHARS_CEILING
+  ) {
+    out.notificationResultChars = r.notificationResultChars as number;
+  }
   if (
     Number.isInteger(r.maxSubagentDepth) &&
     (r.maxSubagentDepth as number) >= 0 &&
@@ -671,7 +690,7 @@ function readSettingsFile(path: string): SubagentsSettings {
   try {
     return sanitize(JSON.parse(readFileSync(path, "utf-8")));
   } catch (err) {
-    const reason = err instanceof Error ? err.message : String(err);
+    const reason = errorMessage(err);
     console.warn(`[pi-subagents] Ignoring malformed settings at ${path}: ${reason}`);
     return {};
   }
@@ -753,6 +772,7 @@ export function applySettings(s: SubagentsSettings, appliers: SettingsAppliers):
   }
   if (typeof s.defaultMaxTurns === "number") appliers.setDefaultMaxTurns(s.defaultMaxTurns);
   if (typeof s.graceTurns === "number") appliers.setGraceTurns(s.graceTurns);
+  if (typeof s.notificationResultChars === "number") appliers.setNotificationResultChars(s.notificationResultChars);
   if (typeof s.maxSubagentDepth === "number") appliers.setMaxSubagentDepth(s.maxSubagentDepth);
   if (typeof s.fallbackSubagent === "string") appliers.setFallbackSubagent(s.fallbackSubagent);
   // Module state: reset when a session omits it, or the previous activation's aliases leak.