@mystilleef/pi-subagent 0.8.0 → 0.9.0

package/README.md

@@ -130,8 +130,9 @@ delegation.
 - `task`: task prompt for the child agent.
 - `agentScope`: optional lookup scope, one of `user`, `project`, or
   `both`.
-- `debug`: optional flag that includes full child messages in result
-  details.
+- `debug`: optional flag that requests child diagnostic details. Full child
+  messages and raw internals require `PI_SUBAGENT_DEBUG_ENABLED=1` in the
+  host environment.
 
 ## Security
 
@@ -143,6 +144,12 @@ executable automation.
 
 - Review project-local agents before running them.
 - Avoid delegating secrets unless the agent and tools need them.
+- Treat child-agent prompts, tool arguments, stderr, and debug transcripts as
+  potentially sensitive.
+- Enable debug details only for trusted investigations. `debug: true` or
+  `/run --debug` can expose child conversation transcripts, termination
+  internals, and stderr only when the host explicitly sets
+  `PI_SUBAGENT_DEBUG_ENABLED=1`.
 - Prefer trusted repositories for shared agent definitions.
 - Remember that child agents can call their configured tools.
 
@@ -150,12 +157,26 @@ executable automation.
 
 **Environment variables:**
 
-- `PI_SUBAGENT_DEPTH`: nested subagent depth guard. Nested calls stop at
-  depth `3`.
+- `PI_SUBAGENT_DEPTH`: current nested subagent depth counter set internally
+  for child processes.
+- `PI_SUBAGENT_MAX_DEPTH`: max nested subagent depth. Default: `3`. Values
+  above `10` clamp to the internal ceiling `10`; deeper nesting increases
+  cost, latency, and runaway delegation risk.
+- `PI_SUBAGENT_AGENT_END_GRACE_MS`: child process grace period after
+  `agent_end` before forced termination. Default: `250`.
+- `PI_SUBAGENT_MAX_STDERR_BYTES`: max captured child stderr bytes. Default:
+  `10000`.
 - `PI_SUBAGENT_MAX_OUTPUT_BYTES`: max returned output bytes. Default:
   `50000`.
 - `PI_SUBAGENT_MAX_OUTPUT_LINES`: max returned output lines. Default:
   `500`.
+- `PI_SUBAGENT_DEBUG_ENABLED`: debug detail authorization. Set to `1` to
+  allow `debug: true` or `/run --debug` to include sanitized child messages,
+  termination internals, and stderr; unset values keep non-debug detail
+  behavior.
+
+Limit variables parse as positive integers. Empty, zero, negative, decimal,
+`Infinity`, and non-numeric values fall back to defaults.
 
 ## Troubleshooting
 
@@ -173,7 +194,7 @@ executable automation.
 
 **Nested subagent blocked:**
 
-- Nested delegation hits the `PI_SUBAGENT_DEPTH` safety limit.
+- Nested delegation hits the `PI_SUBAGENT_MAX_DEPTH` safety limit.
 - Run the child task directly from the parent session instead.
 
 **Truncated output:**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mystilleef/pi-subagent",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Pi subagent for the SPAE Framework",
   "author": "Lateef Alabi-Oki <mystilleef@gmail.com>",
   "license": "MIT",
@@ -50,7 +50,7 @@
     "typecheck": "tsc --noEmit",
     "lint": "biome check --write --unsafe --error-on-warnings .",
     "migrate": "biome migrate --write",
-    "coverage": "bun test --coverage",
+    "coverage": "bun test --parallel --parallel-delay=0",
     "check": "bun lint && bun typecheck",
     "verify": "bun migrate && bun check && bun coverage",
     "pack:smoke": "bun scripts/pack-smoke.ts",
@@ -70,8 +70,8 @@
     "@earendil-works/pi-coding-agent": "^0.78.1",
     "@earendil-works/pi-tui": "^0.78.1",
     "@types/bun": "^1.3.14",
-    "@types/node": "^25.9.1",
-    "typebox": "^1.2.1",
+    "@types/node": "^25.9.2",
+    "typebox": "^1.2.2",
     "typescript": "^6.0.3"
   }
 }

package/src/agent/agents.ts

@@ -20,9 +20,9 @@ export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
 export interface AgentConfig {
   name: string;
   description: string;
-  tools?: string[];
-  skills?: string[];
-  thinking?: ThinkingLevel;
+  tools?: string[] | undefined;
+  skills?: string[] | undefined;
+  thinking?: ThinkingLevel | undefined;
   systemPrompt: string;
   source: AgentSource;
   filePath: string;

package/src/child/child-events.ts

@@ -1,11 +1,10 @@
 import { makeToolPreview } from "../output/normalize.js";
 import type { ToolActivity } from "../shared/types.js";
 
-// Extracts results[0] from details; null-safe for malformed input.
 function tryFirstResult(details: unknown): Record<string, unknown> | null {
   try {
     if (typeof details !== "object" || details === null) return null;
-    const results = (details as Record<string, unknown>).results;
+    const results = (details as Record<string, unknown>)["results"];
     if (!Array.isArray(results) || results.length === 0) return null;
     const nested = results[0];
     if (typeof nested !== "object" || nested === null) return null;
@@ -15,7 +14,6 @@ function tryFirstResult(details: unknown): Record<string, unknown> | null {
   }
 }
 
-// Malformed details (null result) falls back to { toolName }.
 function parseToolActivity(
   toolName: string,
   partialResult: { content?: unknown; details?: unknown },
@@ -24,23 +22,25 @@ function parseToolActivity(
   if (!nestedRecord) return { toolName, inputSummary: toolName };
   const isSubagent = toolName === "subagent";
   const activity: ToolActivity = { toolName };
-  const agent = typeof nestedRecord.agent === "string" && nestedRecord.agent;
+  const agent =
+    typeof nestedRecord["agent"] === "string" && nestedRecord["agent"];
   activity.inputSummary =
     isSubagent && agent ? makeToolPreview(toolName, nestedRecord) : toolName;
   if (
-    typeof nestedRecord.instanceName === "string" &&
-    nestedRecord.instanceName
+    typeof nestedRecord["instanceName"] === "string" &&
+    nestedRecord["instanceName"]
   ) {
-    activity.instanceName = nestedRecord.instanceName;
+    activity.instanceName = nestedRecord["instanceName"] as string;
   }
-  const progress = nestedRecord.progress;
+  const progress = nestedRecord["progress"];
   if (typeof progress === "object" && progress !== null) {
-    const activeToolActivity = (progress as Record<string, unknown>)
-      .activeToolActivity;
+    const activeToolActivity = (progress as Record<string, unknown>)[
+      "activeToolActivity"
+    ];
     if (
       typeof activeToolActivity === "object" &&
       activeToolActivity !== null &&
-      typeof (activeToolActivity as Record<string, unknown>).toolName ===
+      typeof (activeToolActivity as Record<string, unknown>)["toolName"] ===
         "string"
     ) {
       const childActivity = activeToolActivity as ToolActivity;
@@ -96,21 +96,21 @@ export function parseChildEventLine(line: string): ChildEventParseResult {
     typeof event === "object" &&
     event !== null &&
     "type" in event &&
-    typeof (event as Record<string, unknown>).type === "string" &&
-    KNOWN_TYPES.has((event as Record<string, unknown>).type as string)
+    typeof (event as Record<string, unknown>)["type"] === "string" &&
+    KNOWN_TYPES.has((event as Record<string, unknown>)["type"] as string)
   ) {
     const record = event as Record<string, unknown>;
-    if (record.type === TOOL_EXECUTION_UPDATE_EVENT) {
+    if (record["type"] === TOOL_EXECUTION_UPDATE_EVENT) {
       if (
-        typeof record.toolName !== "string" ||
-        typeof record.partialResult !== "object" ||
-        record.partialResult === null
+        typeof record["toolName"] !== "string" ||
+        typeof record["partialResult"] !== "object" ||
+        record["partialResult"] === null
       ) {
         return { kind: "unknown", event };
       }
-      record.toolActivity = parseToolActivity(
-        record.toolName as string,
-        record.partialResult as { content?: unknown; details?: unknown },
+      record["toolActivity"] = parseToolActivity(
+        record["toolName"] as string,
+        record["partialResult"] as { content?: unknown; details?: unknown },
       );
     }
     return { kind: "known", event: event as ChildKnownEvent };

package/src/child/process.ts

@@ -32,12 +32,14 @@ import {
   detectMessageError,
   getPiInvocation,
   getSubagentDepth,
+  getSubagentRuntimeLimits,
   resolveAgentSkillArgs,
   subagentDepthEnv,
   truncateOutput,
   writePromptToTempFile,
 } from "../shared/utils.js";
 import {
+  type ChildEventParseResult,
   type ChildKnownEvent,
   parseChildEventLine,
   TOOL_EXECUTION_UPDATE_EVENT,
@@ -48,8 +50,6 @@ import {
   terminateChildProcess,
 } from "./termination.js";
 
-const MAX_STDERR_BYTES = 10_000;
-const AGENT_END_GRACE_MS = 250;
 export function resolveThinkingLevel(
   requested: ThinkingLevel,
   provider: string,
@@ -73,15 +73,17 @@ export function resolveThinkingLevel(
   return { level: clamped, warning: mkWarning(clamped) };
 }
 
-const MAX_SUBAGENT_DEPTH = 3;
 export const TOOL_RESULT_FAILED_MESSAGE = "Subagent tool result failed.";
 
+type RuntimeLimits = ReturnType<typeof getSubagentRuntimeLimits>;
 type RuntimeResult = SingleResult & { messages: Message[] };
 
 export class SubagentAbortError extends Error {
-  constructor(public readonly result: SingleResult) {
+  readonly result: SingleResult;
+  constructor(result: SingleResult) {
     super("Subagent was aborted");
     this.name = "SubagentAbortError";
+    this.result = result;
   }
 }
 
@@ -91,6 +93,7 @@ type PromptSetupResult = { tmpPrompt: TempPrompt | null } | { error: unknown };
 
 interface SubagentState {
   result: RuntimeResult;
+  runtimeLimits: RuntimeLimits;
   spawnError?: Error;
   wasAborted: boolean;
   agentEndGraceTimer?: ReturnType<typeof setTimeout>;
@@ -99,25 +102,41 @@ interface SubagentState {
 
 function appendWithByteLimit(
   current: string,
-  data: string,
+  data: string | Buffer,
   max: number,
 ): string {
-  if (current.length >= max) return current;
-  return current + data.slice(0, max - current.length);
+  const currentBytes = Buffer.from(current, "utf-8");
+  if (currentBytes.length >= max) return current;
+  const incomingBytes = Buffer.isBuffer(data)
+    ? data
+    : Buffer.from(data, "utf-8");
+  const combined = Buffer.concat([currentBytes, incomingBytes]);
+  if (combined.length <= max) return combined.toString("utf-8");
+  return truncateValidUtf8(combined, max);
+}
+
+function truncateValidUtf8(buffer: Buffer, max: number): string {
+  let end = Math.min(max, buffer.length);
+  while (end > 0) {
+    const candidate = buffer.subarray(0, end).toString("utf-8");
+    if (!candidate.endsWith("�")) return candidate;
+    end -= 1;
+  }
+  return "";
 }
 
 /**
- * Attempts to resolve the context window token limit for a given message's model.
  * Rationale: Subagent usage reporting needs context window awareness to provide
  * meaningful "context full" indicators to the parent.
  */
 function resolveContextWindowTokens(msg: Message): number | undefined {
   const m = msg as unknown as Record<string, unknown>;
-  if (typeof m.provider !== "string" || typeof m.model !== "string") return;
+  if (typeof m["provider"] !== "string" || typeof m["model"] !== "string")
+    return;
   try {
     const contextWindow = getModel(
-      m.provider as never,
-      m.model as never,
+      m["provider"] as never,
+      m["model"] as never,
     )?.contextWindow;
     return Number.isFinite(contextWindow) && contextWindow > 0
       ? contextWindow
@@ -134,11 +153,6 @@ function getAbortReason(signal: AbortSignal): string {
   return "abort";
 }
 
-/**
- * Verifies if the agent produced any textual output or final response.
- * Precondition: Called after process exit to distinguish between clean completion
- * and silent failures where the process exited 0 but did nothing.
- */
 function hasCompletedAgentOutput(result: RuntimeResult): boolean {
   if (result.finalOutput.trim()) return true;
   return result.messages.some(
@@ -151,7 +165,6 @@ function hasCompletedAgentOutput(result: RuntimeResult): boolean {
 }
 
 /**
- * Determines the exit code for processes terminated via the agent_end timeout.
  * Rationale: `pi` processes in JSON mode might hang after finishing their task;
  * we force-kill them after a grace period and treat it as success (0) if they
  * actually produced output.
@@ -168,7 +181,6 @@ function getAgentEndTimeoutExitCode(
 }
 
 /**
- * Orchestrates the cleanup and exit code capture of a child process.
  * Safety: Implements a dual-timer strategy (idle and hard) to ensure streams
  * are destroyed and promises settled even if the process or its pipes hang.
  */
@@ -278,8 +290,9 @@ function accumulateUsage(result: RuntimeResult, msg: Message): void {
   result.usage.cacheWrite += usage.cacheWrite || 0;
   result.usage.cost += usage.cost?.total || 0;
   result.usage.contextTokens = usage.totalTokens || 0;
-  result.usage.contextWindowTokens =
-    resolveContextWindowTokens(msg) ?? result.usage.contextWindowTokens;
+  const ctxWindowTokens = resolveContextWindowTokens(msg);
+  if (ctxWindowTokens !== undefined)
+    result.usage.contextWindowTokens = ctxWindowTokens;
 }
 
 function addMessageToResult(result: RuntimeResult, msg: Message): void {
@@ -288,7 +301,7 @@ function addMessageToResult(result: RuntimeResult, msg: Message): void {
   if (msg.role === "toolResult" && msg.isError) {
     result.errorMessage ||= TOOL_RESULT_FAILED_MESSAGE;
   } else if (result.errorMessage === TOOL_RESULT_FAILED_MESSAGE) {
-    result.errorMessage = undefined;
+    delete result.errorMessage;
   }
   if (msg.role === "assistant") {
     accumulateUsage(result, msg);
@@ -336,13 +349,14 @@ function errorForDepthLimit(
   source: "user" | "project" | "unknown",
   task: string,
   depth: number,
+  maxDepth: number,
   model?: string,
 ): SingleResult {
   return createErrorResult(
     agentName,
     source,
     task,
-    `Subagent nesting limit reached (depth ${depth}/${MAX_SUBAGENT_DEPTH}).`,
+    `Subagent nesting limit reached (depth ${depth}/${maxDepth}).`,
     model,
   );
 }
@@ -387,12 +401,6 @@ function findRecentMessagesAnchor(messages: Message[]): number {
   return -1;
 }
 
-/**
- * Derives current execution progress from accumulated messages.
- * Maps tool calls to UI-safe previews for real-time feedback.
- * Builds activeToolActivity from the most recent tool call, providing
- * a compact parent summary for subagent tools before nested child data arrives.
- */
 function deriveStreamingProgress(messages: Message[]): StreamingProgress {
   const toolCalls: { id: string; preview: string }[] = [];
   let lastToolPreview: string | undefined;
@@ -410,18 +418,15 @@ function deriveStreamingProgress(messages: Message[]): StreamingProgress {
       activeToolActivity = { toolName: part.name, inputSummary: preview };
     }
   }
+  const activityText = renderToolActivity(activeToolActivity);
   return {
     activeToolActivity,
-    activityText: renderToolActivity(activeToolActivity),
+    activityText,
     toolCalls,
     lastToolPreview,
   };
 }
 
-/**
- * Prevents leaking secrets in the CLI progress display.
- * Redacts values if the preview contains sensitive keywords.
- */
 function sanitizeProgressPreview(preview: string, toolName: string): string {
   return SENSITIVE_PATTERN.test(preview) ? toolName : preview;
 }
@@ -447,7 +452,9 @@ export function makeEmitUpdate(
     // so the parent retains nested context until newer activity arrives
     if (options?.toolResultCompleted && result.progress?.activeToolActivity) {
       progress.activeToolActivity = result.progress.activeToolActivity;
-      progress.activityText = renderToolActivity(progress.activeToolActivity);
+      const renderedText = renderToolActivity(progress.activeToolActivity);
+      if (renderedText !== undefined) progress.activityText = renderedText;
+      else delete progress.activityText;
     }
     // Handle parsed tool activity from child events
     // Merge with parent activity if this is a nested update
@@ -474,7 +481,10 @@ export function makeEmitUpdate(
       } else {
         progress.activeToolActivity = options.toolActivity;
       }
-      progress.activityText = renderToolActivity(progress.activeToolActivity);
+      const renderedActivity = renderToolActivity(progress.activeToolActivity);
+      if (renderedActivity !== undefined)
+        progress.activityText = renderedActivity;
+      else delete progress.activityText;
     }
     if (options?.toolResultCompleted) {
       progress.toolResultCompleted = true;
@@ -515,7 +525,7 @@ function makeRequestTerminator(
 function clearGraceTimer(state: SubagentState): void {
   if (!state.agentEndGraceTimer) return;
   clearTimeout(state.agentEndGraceTimer);
-  state.agentEndGraceTimer = undefined;
+  delete state.agentEndGraceTimer;
 }
 
 function handleMessageEvent(
@@ -563,12 +573,25 @@ function handleAgentEndEvent(
   }
   if (state.agentEndGraceTimer || state.terminationPromise) return;
   state.agentEndGraceTimer = setTimeout(() => {
-    state.agentEndGraceTimer = undefined;
+    delete state.agentEndGraceTimer;
     void requestTermination("agent_end_timeout");
-  }, AGENT_END_GRACE_MS);
+  }, state.runtimeLimits.agentEndGraceMs);
   state.agentEndGraceTimer.unref?.();
 }
 
+function formatUnknownEventDiagnostic(
+  line: string,
+  parseResult: Exclude<ChildEventParseResult, { kind: "known" }>,
+): string {
+  if (parseResult.kind === "invalid" && !line.trim()) {
+    return "[pi-subagent:unknown-event] blank";
+  }
+  if (parseResult.kind === "invalid") {
+    return `[pi-subagent:unknown-event] malformed: ${line}`;
+  }
+  return `[pi-subagent:unknown-event] unknown: ${JSON.stringify(parseResult.event)}`;
+}
+
 function processEventLine(
   line: string,
   state: SubagentState,
@@ -577,9 +600,17 @@ function processEventLine(
     toolResultCompleted?: boolean;
   }) => void,
   requestTermination: (reason: string) => Promise<unknown>,
+  debugEventDiagnostics: boolean,
 ): void {
   const parseResult = parseChildEventLine(line);
-  if (parseResult.kind !== "known") return;
+  if (parseResult.kind !== "known") {
+    if (debugEventDiagnostics) {
+      process.stderr.write(
+        `${formatUnknownEventDiagnostic(line, parseResult)}\n`,
+      );
+    }
+    return;
+  }
   const { event } = parseResult;
   handleMessageEvent(event, state, emitUpdate);
   handleToolExecutionUpdateEvent(event, emitUpdate);
@@ -639,28 +670,35 @@ function setupChildProcess(
     toolResultCompleted?: boolean;
   }) => void,
   requestTermination: (reason: string) => Promise<unknown>,
+  debugEventDiagnostics: boolean,
 ): void {
   proc.once("error", (error) => {
     state.spawnError = error;
     state.result.stderr = appendWithByteLimit(
       state.result.stderr,
       error.message,
-      MAX_STDERR_BYTES,
+      state.runtimeLimits.maxStderrBytes,
     );
   });
   if (proc.stdout) {
     readline
       .createInterface({ input: proc.stdout })
       .on("line", (line) =>
-        processEventLine(line, state, emitUpdate, requestTermination),
+        processEventLine(
+          line,
+          state,
+          emitUpdate,
+          requestTermination,
+          debugEventDiagnostics,
+        ),
       );
   }
   if (proc.stderr) {
-    proc.stderr.on("data", (data) => {
+    proc.stderr.on("data", (data: Buffer) => {
       state.result.stderr = appendWithByteLimit(
         state.result.stderr,
-        data.toString(),
-        MAX_STDERR_BYTES,
+        data,
+        state.runtimeLimits.maxStderrBytes,
       );
     });
   }
@@ -689,8 +727,6 @@ async function finalizeResult(
 }
 
 /**
- * Executes a single subagent task.
- *
  * Rationale: Subagents run in isolated child processes to protect the parent's
  * context window and allow specialized system prompts/tools without polluting
  * the main conversation.
@@ -716,12 +752,20 @@ export async function runSingleAgent(
   ) => SubagentDetails,
   parentModel: { provider: string; id: string } | undefined,
   parentThinking: ThinkingLevel,
+  debugEventDiagnostics = false,
 ): Promise<SingleResult> {
   const agent = agents.find((a) => a.name === agentName);
   if (!agent) return errorForUnknownAgent(agentName, agents, task);
+  const runtimeLimits = getSubagentRuntimeLimits();
   const depth = getSubagentDepth();
-  if (depth >= MAX_SUBAGENT_DEPTH) {
-    return errorForDepthLimit(agentName, agent.source, task, depth);
+  if (depth >= runtimeLimits.maxDepth) {
+    return errorForDepthLimit(
+      agentName,
+      agent.source,
+      task,
+      depth,
+      runtimeLimits.maxDepth,
+    );
   }
   const requestedThinking = agent.thinking ?? parentThinking;
   const { level: thinking, warning: thinkingWarning } = parentModel
@@ -754,6 +798,7 @@ export async function runSingleAgent(
   const startedAt = Date.now();
   const state: SubagentState = {
     result: initRuntimeResult(agentName, agent.source, task, modelDisplay),
+    runtimeLimits,
     wasAborted: false,
   };
   if (thinkingWarning) state.result.thinkingWarning = thinkingWarning;
@@ -787,7 +832,13 @@ export async function runSingleAgent(
       terminateOptions,
       state,
     );
-    setupChildProcess(proc, state, emitUpdate, requestTermination);
+    setupChildProcess(
+      proc,
+      state,
+      emitUpdate,
+      requestTermination,
+      debugEventDiagnostics,
+    );
     const onAbort = setupAbortHandler(
       signal,
       state,

package/src/child/termination.ts

@@ -4,12 +4,12 @@ export type TerminationSignal = "SIGTERM" | "SIGKILL";
 
 export type TerminationMetadata = {
   cancelRequestedAt: number;
-  cancelReason?: string;
-  terminationSignal?: TerminationSignal;
+  cancelReason?: string | undefined;
+  terminationSignal?: TerminationSignal | undefined;
   escalated: boolean;
   processTreeKilled: boolean;
   target: "direct" | "tree";
-  fallbackCause?: string;
+  fallbackCause?: string | undefined;
 };
 
 type TimerHandle = unknown;
@@ -64,7 +64,7 @@ function settleState(state: TerminationState): void {
   if (state.settled) return;
   state.settled = true;
   if (state.timer) state.clearTimeout(state.timer);
-  state.timer = undefined;
+  delete state.timer;
   state.resolve(state.metadata);
 }
 

package/src/env.d.ts

@@ -0,0 +1,13 @@
+declare namespace NodeJS {
+  interface ProcessEnv {
+    PATH?: string;
+    PI_CODING_AGENT_DIR?: string;
+    PI_SUBAGENT_DEPTH?: string;
+    PI_SUBAGENT_MAX_DEPTH?: string;
+    PI_SUBAGENT_MAX_OUTPUT_BYTES?: string;
+    PI_SUBAGENT_MAX_OUTPUT_LINES?: string;
+    PI_SUBAGENT_AGENT_END_GRACE_MS?: string;
+    PI_SUBAGENT_MAX_STDERR_BYTES?: string;
+    PI_SUBAGENT_DEBUG_ENABLED?: string;
+  }
+}

package/src/orchestration/run-registry.ts

@@ -48,7 +48,6 @@ export function cancelAllRunJobs(reason = "Cancelled"): number {
   return count;
 }
 
-export function clearRunJobsForTests(): void {
+export function resetRunRegistry(): void {
   jobs.clear();
 }
-export const resetRunRegistry = clearRunJobsForTests;

package/src/orchestration/subagent-orchestrator.ts

@@ -77,6 +77,10 @@ type DetailsBuilder = (
   options?: DetailsOptions,
 ) => SubagentDetails;
 
+function isDebugDetailsAuthorized(debugRequested: boolean): boolean {
+  return debugRequested && process.env.PI_SUBAGENT_DEBUG_ENABLED === "1";
+}
+
 interface LifecycleContext {
   pi: ExtensionAPI;
   ctx: ExtensionContext;
@@ -90,7 +94,7 @@ interface LifecycleContext {
   task: string;
   parentModel: { provider: string; id: string } | undefined;
   parentThinking: ThinkingLevel;
-  hostOnUpdate?: AgentToolUpdateCallback<SubagentDetails>;
+  hostOnUpdate?: AgentToolUpdateCallback<SubagentDetails> | undefined;
 }
 
 function createDetailsBuilder(
@@ -123,7 +127,7 @@ function sanitizeResultDetails(
     usage: { ...usageBase },
   };
   if (contextWindowTokens !== undefined) {
-    (sanitized.usage as Record<string, unknown>).contextWindowTokens =
+    (sanitized["usage"] as Record<string, unknown>)["contextWindowTokens"] =
       contextWindowTokens;
   }
   if (progress !== undefined) {
@@ -134,7 +138,7 @@ function sanitizeResultDetails(
       toolResultCompleted,
       ...progBase
     } = progress;
-    sanitized.progress = {
+    sanitized["progress"] = {
       toolCalls: progBase.toolCalls.map((tc) => ({
         id: tc.id,
         preview: tc.preview,
@@ -146,7 +150,7 @@ function sanitizeResultDetails(
     };
   }
   if (includeMessages) {
-    sanitized.messages = options?.recentMessages
+    sanitized["messages"] = options?.recentMessages
       ? [...options.recentMessages]
       : messages !== undefined
         ? [...messages]
@@ -154,7 +158,7 @@ function sanitizeResultDetails(
     if (includeDebugMessages && termination !== undefined) {
       const { cancelReason, terminationSignal, fallbackCause, ...termBase } =
         termination;
-      sanitized.termination = {
+      sanitized["termination"] = {
         ...termBase,
         ...(cancelReason !== undefined && { cancelReason }),
         ...(terminationSignal !== undefined && { terminationSignal }),
@@ -318,6 +322,7 @@ async function runSubagentLifecycle(
       lc.makeDetails,
       lc.parentModel,
       lc.parentThinking,
+      lc.debug,
     );
     return finishLifecycleResult(lc, result);
   } catch (error) {
@@ -358,7 +363,7 @@ type PrepareSubagentJobResult =
       lc: LifecycleContext;
       instanceName: string;
       requestProgressRender: () => void;
-      hostOnUpdate?: AgentToolUpdateCallback<SubagentDetails>;
+      hostOnUpdate?: AgentToolUpdateCallback<SubagentDetails> | undefined;
     }
   | { kind: "not_found"; makeDetails: DetailsBuilder }
   | { kind: "cancelled"; makeDetails: DetailsBuilder }
@@ -409,7 +414,7 @@ async function prepareSubagentJob(
   const agentScope: AgentScope = params.agentScope ?? "both";
   const discovery = await getCachedAgentDiscovery(ctx.cwd, agentScope);
   const agents = discovery.agents;
-  const debug = params.debug === true;
+  const debug = isDebugDetailsAuthorized(params.debug === true);
   const makeDetails = createDetailsBuilder(
     agentScope,
     discovery.projectAgentsDir,

package/src/progress/progress-state.ts

@@ -44,21 +44,21 @@ export const STATUS_BG: Record<ProgressStatus, ThemeBg> = {
 export interface SubagentProgressState {
   requestId: string;
   agent: string;
-  instanceName?: string;
+  instanceName?: string | undefined;
   taskPreview: string;
   status: ProgressStatus;
   startTime: number;
-  durationMs?: number;
-  activeToolActivity?: ToolActivity;
-  lastToolPreview?: string;
-  toolResultCompleted?: boolean;
+  durationMs?: number | undefined;
+  activeToolActivity?: ToolActivity | undefined;
+  lastToolPreview?: string | undefined;
+  toolResultCompleted?: boolean | undefined;
   toolCount: number;
-  inputTokens?: number;
-  outputTokens?: number;
-  contextTokens?: number;
-  contextWindowTokens?: number;
-  finalOutput?: string;
-  errorText?: string;
+  inputTokens?: number | undefined;
+  outputTokens?: number | undefined;
+  contextTokens?: number | undefined;
+  contextWindowTokens?: number | undefined;
+  finalOutput?: string | undefined;
+  errorText?: string | undefined;
 }
 
 const store = new Map<string, SubagentProgressState>();
@@ -89,6 +89,23 @@ export function getAllProgressStates(): SubagentProgressState[] {
   return [...store.values()].sort((a, b) => b.startTime - a.startTime);
 }
 
+type ProgressTransientFields = Pick<
+  SubagentProgressState,
+  "activeToolActivity" | "lastToolPreview" | "toolResultCompleted"
+>;
+
+function stripTransientFields(
+  merged: SubagentProgressState,
+): Omit<SubagentProgressState, keyof ProgressTransientFields> {
+  const {
+    activeToolActivity: _a,
+    lastToolPreview: _l,
+    toolResultCompleted: _t,
+    ...base
+  } = merged;
+  return base;
+}
+
 export function patchProgressState(
   requestId: string,
   patch: Partial<SubagentProgressState>,
@@ -96,13 +113,7 @@ export function patchProgressState(
   const state = store.get(requestId);
   if (!state) return;
   if (state.status !== "running") {
-    store.set(requestId, {
-      ...state,
-      ...patch,
-      activeToolActivity: undefined,
-      lastToolPreview: undefined,
-      toolResultCompleted: undefined,
-    });
+    store.set(requestId, stripTransientFields({ ...state, ...patch }));
     return;
   }
   store.set(requestId, { ...state, ...patch });
@@ -115,7 +126,10 @@ function storeTerminalProgressState(
   const state = store.get(requestId);
   if (!state) return;
   const durationMs = state.durationMs ?? Date.now() - state.startTime;
-  store.set(requestId, { ...state, ...patch, durationMs });
+  store.set(requestId, {
+    ...stripTransientFields({ ...state, ...patch }),
+    durationMs,
+  });
 }
 
 export function finalizeProgressState(
@@ -125,9 +139,6 @@ export function finalizeProgressState(
   storeTerminalProgressState(requestId, {
     status: "success",
     finalOutput: makeProgressFinalOutput(finalOutput),
-    activeToolActivity: undefined,
-    lastToolPreview: undefined,
-    toolResultCompleted: undefined,
   });
 }
 
@@ -136,21 +147,13 @@ export function failProgressState(requestId: string, errorText: string): void {
   storeTerminalProgressState(requestId, {
     status: "error",
     errorText: sentence,
-    activeToolActivity: undefined,
-    lastToolPreview: undefined,
-    toolResultCompleted: undefined,
   });
 }
 
 export function cancelProgressState(requestId: string, reason?: string): void {
   storeTerminalProgressState(requestId, {
     status: "cancelled",
-    activeToolActivity: undefined,
-    lastToolPreview: undefined,
-    toolResultCompleted: undefined,
-    ...(reason !== undefined
-      ? { errorText: normalizeTerminalSentence(reason) }
-      : {}),
+    errorText: reason ? normalizeTerminalSentence(reason) : undefined,
   });
 }
 
@@ -235,11 +238,11 @@ function trackNewToolCall(
 
 function extractProgressFromExistingProgress(
   progress: {
-    activityText?: string;
-    activeToolActivity?: ToolActivity;
-    lastToolPreview?: string;
+    activityText?: string | undefined;
+    activeToolActivity?: ToolActivity | undefined;
+    lastToolPreview?: string | undefined;
     toolCalls: { id: string; preview: string }[];
-    toolResultCompleted?: boolean;
+    toolResultCompleted?: boolean | undefined;
   },
   seenToolCallIds: Set<string>,
   state: DetailsProgress,
@@ -317,7 +320,7 @@ function isDerivedToolCall(part: unknown): part is {
   preview: string;
 } {
   if (!isObjectWith(part)) return false;
-  return typeof part.id === "string" && typeof part.preview === "string";
+  return typeof part["id"] === "string" && typeof part["preview"] === "string";
 }
 
 export function isToolCallPart(part: unknown): part is {
@@ -328,9 +331,9 @@ export function isToolCallPart(part: unknown): part is {
 } {
   if (!isObjectWith(part)) return false;
   return (
-    part.type === "toolCall" &&
-    typeof part.id === "string" &&
-    typeof part.name === "string"
+    part["type"] === "toolCall" &&
+    typeof part["id"] === "string" &&
+    typeof part["name"] === "string"
   );
 }
 

package/src/progress/progress.ts

@@ -89,11 +89,18 @@ export function renderSubagentProgress(
 }
 
 class DynamicSubagentProgressText implements Component {
+  private readonly requestId: string;
+  private readonly options: { expanded: boolean };
+  private readonly theme: SubagentTheme;
   constructor(
-    private readonly requestId: string,
-    private readonly options: { expanded: boolean },
-    private readonly theme: SubagentTheme,
-  ) {}
+    requestId: string,
+    options: { expanded: boolean },
+    theme: SubagentTheme,
+  ) {
+    this.requestId = requestId;
+    this.options = options;
+    this.theme = theme;
+  }
   invalidate(): void {}
   render(width: number): string[] {
     const state = getProgressState(this.requestId);

package/src/progress/result-details.ts

@@ -16,6 +16,7 @@ import {
   patchProgressState,
   renderToolActivity,
 } from "./progress.js";
+import { SENSITIVE_PATTERN } from "./progress-state.js";
 
 export function hasSubagentFailed(result: SingleResult): boolean {
   return (
@@ -41,6 +42,46 @@ export function createSubagentError(result: SingleResult): Error {
   return new Error(`Agent ${result.stopReason || "failed"}: ${msg}`);
 }
 
+const DEBUG_REDACTED_PLACEHOLDER = "[redacted]";
+const SENSITIVE_ASSIGNMENT_PATTERN =
+  /\b(?:secret|password|[A-Za-z0-9_-]*token)(?:\s*[:=]\s*)(?:"[^"]*"|'[^']*'|[^\s,;]+)/gi;
+const SENSITIVE_TERM_PATTERN = new RegExp(SENSITIVE_PATTERN.source, "gi");
+const TOKEN_COUNT_KEY_PATTERN = /tokens$/i;
+
+function redactSensitiveDebugString(text: string): string {
+  return text
+    .replace(SENSITIVE_ASSIGNMENT_PATTERN, DEBUG_REDACTED_PLACEHOLDER)
+    .replace(SENSITIVE_TERM_PATTERN, DEBUG_REDACTED_PLACEHOLDER);
+}
+
+function isSensitiveDebugKey(key: string): boolean {
+  const lowerKey = key.toLowerCase();
+  if (TOKEN_COUNT_KEY_PATTERN.test(lowerKey)) return false;
+  return (
+    lowerKey.includes("secret") ||
+    lowerKey.includes("password") ||
+    lowerKey.endsWith("token")
+  );
+}
+
+function redactSensitiveDebugValue(value: unknown): unknown {
+  if (typeof value === "string") return redactSensitiveDebugString(value);
+  if (Array.isArray(value)) return value.map(redactSensitiveDebugValue);
+  if (typeof value !== "object" || value === null) return value;
+  const redacted: Record<string, unknown> = {};
+  for (const [key, child] of Object.entries(value)) {
+    redacted[key] = isSensitiveDebugKey(key)
+      ? DEBUG_REDACTED_PLACEHOLDER
+      : redactSensitiveDebugValue(child);
+  }
+  return redacted;
+}
+
+function redactSensitiveDebugMessages(messages: unknown): unknown {
+  if (!Array.isArray(messages)) return messages;
+  return messages.map(redactSensitiveDebugValue);
+}
+
 export function sanitizeDetailsForDisplay(
   details: SubagentDetails,
   includeMessages = false,
@@ -50,9 +91,11 @@ export function sanitizeDetailsForDisplay(
     results: details.results.map(({ messages, termination, ...result }) => ({
       ...result,
       stderr: includeMessages ? result.stderr : "",
-      ...(includeMessages ? { messages, termination } : {}),
+      ...(includeMessages
+        ? { messages: redactSensitiveDebugMessages(messages), termination }
+        : {}),
     })),
-  };
+  } as SubagentDetails;
 }
 
 export function getLatestResult(
@@ -90,26 +133,27 @@ export function patchProgressFromDetails(
     nextActivity = current.activeToolActivity;
   }
   if (toolResultCompleted && nextActivity?.child) {
-    nextActivity = { ...nextActivity, child: undefined };
+    const { child: _child, ...rest } = nextActivity;
+    nextActivity = rest;
   } else if (toolResultCompleted) {
     nextActivity = undefined;
   }
-  patch.activeToolActivity = nextActivity;
+  patch["activeToolActivity"] = nextActivity;
   const renderedPreview = renderToolActivity(nextActivity);
   if (renderedPreview) {
-    patch.lastToolPreview = renderedPreview;
+    patch["lastToolPreview"] = renderedPreview;
   } else if (toolResultCompleted && !nextActivity) {
-    patch.lastToolPreview = undefined;
+    patch["lastToolPreview"] = undefined;
   }
   if (toolResultCompleted) {
-    patch.toolResultCompleted = true;
+    patch["toolResultCompleted"] = true;
   }
   // Token accounting always applies when usage data is available
   if (latestResult?.usage) {
-    patch.inputTokens = latestResult.usage.input;
-    patch.outputTokens = latestResult.usage.output;
-    patch.contextTokens = latestResult.usage.contextTokens;
-    patch.contextWindowTokens = latestResult.usage.contextWindowTokens;
+    patch["inputTokens"] = latestResult.usage.input;
+    patch["outputTokens"] = latestResult.usage.output;
+    patch["contextTokens"] = latestResult.usage.contextTokens;
+    patch["contextWindowTokens"] = latestResult.usage.contextWindowTokens;
   }
   patchProgressState(
     requestId,

package/src/shared/types.ts

@@ -15,9 +15,9 @@ export interface UsageStats {
 
 export interface ToolActivity {
   toolName: string;
-  inputSummary?: string;
-  instanceName?: string;
-  child?: ToolActivity;
+  inputSummary?: string | undefined;
+  instanceName?: string | undefined;
+  child?: ToolActivity | undefined;
 }
 
 export interface StreamingProgressToolCall {
@@ -26,30 +26,30 @@ export interface StreamingProgressToolCall {
 }
 
 export interface StreamingProgress {
-  activityText?: string;
-  activeToolActivity?: ToolActivity;
+  activityText?: string | undefined;
+  activeToolActivity?: ToolActivity | undefined;
   toolCalls: StreamingProgressToolCall[];
-  lastToolPreview?: string;
-  toolResultCompleted?: boolean;
+  lastToolPreview?: string | undefined;
+  toolResultCompleted?: boolean | undefined;
 }
 
 export interface SingleResult {
   agent: string;
-  instanceName?: string;
+  instanceName?: string | undefined;
   agentSource: "user" | "project" | "unknown";
   task: string;
   exitCode: number;
   finalOutput: string;
   stderr: string;
   usage: UsageStats;
-  model?: string;
-  stopReason?: string;
-  errorMessage?: string;
-  durationMs?: number;
-  progress?: StreamingProgress;
-  messages?: Message[];
-  termination?: TerminationMetadata;
-  thinkingWarning?: string;
+  model?: string | undefined;
+  stopReason?: string | undefined;
+  errorMessage?: string | undefined;
+  durationMs?: number | undefined;
+  progress?: StreamingProgress | undefined;
+  messages?: Message[] | undefined;
+  termination?: TerminationMetadata | undefined;
+  thinkingWarning?: string | undefined;
 }
 
 export interface SubagentDetails {

package/src/shared/utils.ts

@@ -9,35 +9,63 @@ import {
 
 export const DEFAULT_MAX_OUTPUT_BYTES = 50_000;
 export const DEFAULT_MAX_OUTPUT_LINES = 500;
+export const DEFAULT_AGENT_END_GRACE_MS = 250;
+export const DEFAULT_MAX_STDERR_BYTES = 10_000;
+export const DEFAULT_MAX_SUBAGENT_DEPTH = 3;
+export const MAX_SUBAGENT_DEPTH_CEILING = 10;
 
 export interface SubagentOutputLimits {
   maxBytes: number;
   maxLines: number;
 }
 
-type OutputLimitConfig = Partial<Record<string, string | number | undefined>>;
+export interface SubagentRuntimeLimits {
+  agentEndGraceMs: number;
+  maxStderrBytes: number;
+  maxDepth: number;
+}
+
+type EnvLimitConfig = Partial<Record<string, string | number | undefined>>;
 
 function parsePositiveInteger(
   value: string | number | undefined,
 ): number | undefined {
   const parsed = typeof value === "number" ? value : Number(value);
-  if (!Number.isFinite(parsed) || parsed < 1) return undefined;
-  return Math.floor(parsed);
+  if (!Number.isFinite(parsed) || !Number.isInteger(parsed) || parsed < 1)
+    return undefined;
+  return parsed;
 }
 
 export function getSubagentOutputLimits(
-  config: OutputLimitConfig = process.env,
+  config: EnvLimitConfig = process.env,
 ): SubagentOutputLimits {
   return {
     maxBytes:
-      parsePositiveInteger(config.PI_SUBAGENT_MAX_OUTPUT_BYTES) ??
+      parsePositiveInteger(config["PI_SUBAGENT_MAX_OUTPUT_BYTES"]) ??
       DEFAULT_MAX_OUTPUT_BYTES,
     maxLines:
-      parsePositiveInteger(config.PI_SUBAGENT_MAX_OUTPUT_LINES) ??
+      parsePositiveInteger(config["PI_SUBAGENT_MAX_OUTPUT_LINES"]) ??
       DEFAULT_MAX_OUTPUT_LINES,
   };
 }
 
+export function getSubagentRuntimeLimits(
+  config: EnvLimitConfig = process.env,
+): SubagentRuntimeLimits {
+  const maxDepth =
+    parsePositiveInteger(config["PI_SUBAGENT_MAX_DEPTH"]) ??
+    DEFAULT_MAX_SUBAGENT_DEPTH;
+  return {
+    agentEndGraceMs:
+      parsePositiveInteger(config["PI_SUBAGENT_AGENT_END_GRACE_MS"]) ??
+      DEFAULT_AGENT_END_GRACE_MS,
+    maxStderrBytes:
+      parsePositiveInteger(config["PI_SUBAGENT_MAX_STDERR_BYTES"]) ??
+      DEFAULT_MAX_STDERR_BYTES,
+    maxDepth: Math.min(maxDepth, MAX_SUBAGENT_DEPTH_CEILING),
+  };
+}
+
 export function truncateOutput(
   text: string,
   limits: SubagentOutputLimits = getSubagentOutputLimits(),

package/tsconfig.json

@@ -1,30 +1,28 @@
 {
   "compilerOptions": {
-    // Environment setup & latest features
     "lib": ["ESNext"],
     "target": "ESNext",
     "module": "Preserve",
     "moduleDetection": "force",
     "jsx": "react-jsx",
-    "allowJs": true,
     "types": ["bun"],
-
-    // Bundler mode
     "moduleResolution": "bundler",
     "allowImportingTsExtensions": true,
     "verbatimModuleSyntax": true,
     "noEmit": true,
-
-    // Best practices
     "strict": true,
     "skipLibCheck": true,
     "noFallthroughCasesInSwitch": true,
     "noUncheckedIndexedAccess": true,
     "noImplicitOverride": true,
-
-    // Some stricter flags (disabled by default)
-    "noUnusedLocals": false,
-    "noUnusedParameters": false,
-    "noPropertyAccessFromIndexSignature": false
+    "noImplicitReturns": true,
+    "erasableSyntaxOnly": true,
+    "forceConsistentCasingInFileNames": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "exactOptionalPropertyTypes": true,
+    "allowUnreachableCode": false,
+    "allowUnusedLabels": false
   }
 }