@mystilleef/pi-subagent 0.7.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 `2`.
+- `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.7.0",
+  "version": "0.9.0",
   "description": "Pi subagent for the SPAE Framework",
   "author": "Lateef Alabi-Oki <mystilleef@gmail.com>",
   "license": "MIT",
@@ -48,12 +48,11 @@
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "lint": "biome check --error-on-warnings .",
-    "fix": "biome check --write --unsafe .",
+    "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 fix && bun typecheck && bun coverage",
+    "verify": "bun migrate && bun check && bun coverage",
     "pack:smoke": "bun scripts/pack-smoke.ts",
     "release": "sh -c 'npm version \"$1\" -m \"chore(release): %s\" && git push --follow-tags' --"
   },
@@ -66,13 +65,13 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.16",
-    "@earendil-works/pi-agent-core": "^0.78.0",
-    "@earendil-works/pi-ai": "^0.78.0",
-    "@earendil-works/pi-coding-agent": "^0.78.0",
-    "@earendil-works/pi-tui": "^0.78.0",
+    "@earendil-works/pi-agent-core": "^0.78.1",
+    "@earendil-works/pi-ai": "^0.78.1",
+    "@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.1.39",
+    "@types/node": "^25.9.2",
+    "typebox": "^1.2.2",
     "typescript": "^6.0.3"
   }
 }

package/src/agent/agent-cache.ts

@@ -9,12 +9,14 @@ import {
   discoverAgentsAsync,
   emptyScopeResult,
   getUserAgentsDir,
-  readMarkdownDirEntriesAsync,
+  readMarkdownDirWithStatusAsync,
 } from "./agents.js";
 
 interface AgentDiscoveryScopeSnapshot {
   markdownFiles: string[];
   fileHashes: Record<string, string | null>;
+  listingTrusted: boolean;
+  directory: string | null;
 }
 
 type AgentDiscoverySnapshots = Record<AgentSource, AgentDiscoveryScopeSnapshot>;
@@ -52,7 +54,12 @@ function getFreshCacheEntry(
 }
 
 function emptySnapshot(): AgentDiscoveryScopeSnapshot {
-  return { markdownFiles: [], fileHashes: {} };
+  return {
+    markdownFiles: [],
+    fileHashes: {},
+    listingTrusted: false,
+    directory: null,
+  };
 }
 
 function cloneScopeSnapshot(
@@ -62,6 +69,8 @@ function cloneScopeSnapshot(
   return {
     markdownFiles: [...snapshot.markdownFiles],
     fileHashes: { ...snapshot.fileHashes },
+    listingTrusted: snapshot.listingTrusted,
+    directory: snapshot.directory,
   };
 }
 
@@ -71,14 +80,17 @@ function equalStringSets(a: string[], b: string[]): boolean {
   return b.every((value) => set.has(value));
 }
 
-function snapshotsEqual(
-  left: AgentDiscoveryScopeSnapshot,
-  right: AgentDiscoveryScopeSnapshot,
+function snapshotHasRequiredMetadata(
+  snapshot: AgentDiscoveryScopeSnapshot,
 ): boolean {
-  if (!equalStringSets(left.markdownFiles, right.markdownFiles)) return false;
-  return left.markdownFiles.every(
-    (fileName) => left.fileHashes[fileName] === right.fileHashes[fileName],
-  );
+  if (typeof snapshot.listingTrusted !== "boolean") return false;
+  if (snapshot.directory !== null && typeof snapshot.directory !== "string")
+    return false;
+  if (
+    !equalStringSets(snapshot.markdownFiles, Object.keys(snapshot.fileHashes))
+  )
+    return false;
+  return true;
 }
 
 function scopeAgentsMatchListing(
@@ -118,16 +130,20 @@ async function hashMarkdownFileAsync(
 async function buildScopeSnapshotAsync(
   dir: string | null,
 ): Promise<AgentDiscoveryScopeSnapshot> {
-  if (!dir) return emptySnapshot();
-  const entries = await readMarkdownDirEntriesAsync(dir);
-  const markdownFiles = entries.map((entry) => entry.name);
+  const listing = await readMarkdownDirWithStatusAsync(dir);
+  const markdownFiles = listing.entries.map((entry) => entry.name);
   const hashPairs = await Promise.all(
     markdownFiles.map(
       async (fileName) =>
-        [fileName, await hashMarkdownFileAsync(dir, fileName)] as const,
+        [fileName, await hashMarkdownFileAsync(dir ?? "", fileName)] as const,
     ),
   );
-  return { markdownFiles, fileHashes: Object.fromEntries(hashPairs) };
+  return {
+    markdownFiles,
+    fileHashes: Object.fromEntries(hashPairs),
+    listingTrusted: listing.ok,
+    directory: dir ? path.resolve(dir) : null,
+  };
 }
 
 async function buildCacheSnapshotsAsync(
@@ -146,13 +162,22 @@ async function canTrustDerivedScopeAsync(
 ): Promise<boolean> {
   const dir =
     source === "user" ? getUserAgentsDir() : bothEntry.projectAgentsDir;
+  const resolvedDir = dir ? path.resolve(dir) : null;
   const scopeResult = bothEntry.scopes[source];
   const cachedSnapshot = bothEntry.snapshots?.[source];
   if (!cachedSnapshot) return false;
+  if (!snapshotHasRequiredMetadata(cachedSnapshot)) return false;
+  if (!cachedSnapshot.listingTrusted) return false;
+  if (cachedSnapshot.directory !== resolvedDir) return false;
   if (!scopeAgentsMatchListing(scopeResult, source, dir)) return false;
   if (!equalStringSets(scopeResult.markdownFiles, cachedSnapshot.markdownFiles))
     return false;
-  return snapshotsEqual(cachedSnapshot, await buildScopeSnapshotAsync(dir));
+  const listing = await readMarkdownDirWithStatusAsync(dir);
+  if (!listing.ok) return false;
+  return equalStringSets(
+    cachedSnapshot.markdownFiles,
+    listing.entries.map((entry) => entry.name),
+  );
 }
 
 function buildSourceRecord<T>(
@@ -220,11 +245,14 @@ async function primeScopedCacheEntriesAsync(
   ctx: CacheOperationContext,
   bothEntry: AgentDiscoveryCacheEntry,
 ): Promise<void> {
-  for (const source of AGENT_SOURCES) {
-    const scopedKey = cacheKey(ctx.cwd, source);
-    if (getFreshCacheEntry(ctx, scopedKey)) continue;
-    await deriveOrDiscoverScopedEntryAsync(ctx, source, bothEntry);
-  }
+  const missingSources = AGENT_SOURCES.filter(
+    (source) => !getFreshCacheEntry(ctx, cacheKey(ctx.cwd, source)),
+  );
+  await Promise.all(
+    missingSources.map((source) =>
+      deriveOrDiscoverScopedEntryAsync(ctx, source, bothEntry),
+    ),
+  );
 }
 
 export async function getCachedAgentDiscovery(

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;
@@ -143,7 +143,7 @@ async function loadAgentsFromDirAsync(
   dir: string,
   source: AgentSource,
 ): Promise<AgentDiscoveryScopeResult> {
-  const markdownEntries = await readMarkdownDirEntriesAsync(dir);
+  const markdownEntries = (await readMarkdownDirWithStatusAsync(dir)).entries;
   const markdownFiles = markdownEntries.map((entry) => entry.name);
   const parsedAgents = await Promise.all(
     markdownEntries.map((entry) =>
@@ -162,15 +162,20 @@ export function isMarkdownDirent(entry: Dirent): boolean {
   );
 }
 
-export async function readMarkdownDirEntriesAsync(
+export interface MarkdownDirListing {
+  entries: Dirent[];
+  ok: boolean;
+}
+
+export async function readMarkdownDirWithStatusAsync(
   dir: string | null,
-): Promise<Dirent[]> {
-  if (!dir) return [];
+): Promise<MarkdownDirListing> {
+  if (!dir) return { entries: [], ok: true };
   try {
     const entries = await fsPromises.readdir(dir, { withFileTypes: true });
-    return entries.filter(isMarkdownDirent);
+    return { entries: entries.filter(isMarkdownDirent), ok: true };
   } catch {
-    return [];
+    return { entries: [], ok: false };
   }
 }
 

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 };