@leing2021/super-pi 0.16.0 → 0.17.0

package/README.md

@@ -99,14 +99,14 @@ Next time `02-plan` or `04-review` runs, a grep-first search strategy automatica
 | `08-status` | Scan artifacts, report progress | `workflow_state`, `session_history` |
 | `09-help` | Usage guide | — |
 
-### 13 Tools (underlying capabilities)
+### 15 Tools (underlying capabilities)
 
 | Tool | What it does |
 |------|-------------|
 | `task_splitter` | Union-Find algorithm analyzes file dependencies, auto-groups parallel-safe units |
 | `session_checkpoint` | JSON-persisted checkpoints with save/load/fail/retry operations |
 | `plan_diff` | Incremental plans: compare detects diffs, patch applies changes |
-| `parallel_subagent` | `Promise.allSettled`-style parallel subagent execution |
+| `parallel_subagent` | `Promise.allSettled`-style parallel subagent execution with context slimming |
 | `review_router` | Auto-assign reviewer personas from diff metadata |
 | `pattern_extractor` | Extract and categorize patterns from artifacts |
 | `brainstorm_dialog` | Multi-round dialog state machine (start → refine × N → summarize) |
@@ -115,13 +115,15 @@ Next time `02-plan` or `04-review` runs, a grep-first search strategy automatica
 | `worktree_manager` | Full git worktree lifecycle management |
 | `artifact_helper` | Artifact path resolution and directory creation |
 | `ask_user_question` | Structured user prompts (choices / free input) |
-| `subagent` | Serial subagent chain |
+| `subagent` | Serial subagent chain with depth guard and context control |
+| `subagent-depth-guard` | Env-based recursion depth tracking (prevents runaway nesting) |
+| `async-mutex` | Serializes `process.env` mutation for concurrency-safe child process spawning |
 
 ---
 
 ## Code Scale
 
-~2000 lines of TypeScript implementing 13 tools, 22 Markdown reference files driving 9 skills' behavioral strategies, 95 tests covering all tool logic.
+~2500 lines of TypeScript implementing 15 tools, 22 Markdown reference files driving 9 skills' behavioral strategies, 162 tests covering all tool logic.
 
 Not a heavy framework. Each tool has a single responsibility, each skill works independently, and together they form a complete workflow.
 
@@ -236,6 +238,22 @@ Not a fork. Not a wrapper. The methodologies are extracted and rebuilt with Pi's
 
 ## Changelog
 
+### 0.17.0 — Subagent safety
+- Recursion depth guard (`PI_SUBAGENT_DEPTH` / `PI_SUBAGENT_MAX_DEPTH`) prevents runaway nesting
+- Async mutex for `process.env` concurrency safety during parallel subagent execution
+- Context slimming: `inheritSkills` parameter, parallel workers default to slim context (`--no-skills`)
+- Shared `createSubagentRunner` factory (deduped runner closures)
+- 162 tests passing
+
+### 0.16.0 — Context optimization
+- Read output filter: structural compression for large code files, lock files, markdown
+- Compaction optimizer: focused summary instructions for session compaction
+- Bash output filter improvements
+
+### 0.15.0 — Output filtering
+- Bash output filter: smart truncation by command type (install, test, build)
+- Read output filter: preserves structure while cutting verbosity
+
 ### 0.14.0 — Structured solution retrieval
 - YAML frontmatter tagging + grep-first two-level search
 - 95 tests passing

package/extensions/ce-core/index.ts

@@ -16,6 +16,51 @@ import { createPatternExtractorTool } from "./tools/pattern-extractor"
 import { filterBashOutput } from "./tools/bash-output-filter"
 import { filterReadOutput } from "./tools/read-output-filter"
 import { COMPACTION_FOCUS_INSTRUCTIONS } from "./tools/compaction-optimizer"
+import { AsyncMutex } from "./tools/async-mutex"
+import type { SubagentExecOptions, SubagentRunner } from "./tools/subagent"
+
+const _subagentEnvMutex = new AsyncMutex()
+
+/**
+ * Create a subagent runner that handles env injection with mutex protection
+ * for concurrency safety when multiple parallel subagents share the process.
+ */
+function createSubagentRunner(
+  pi: ExtensionAPI,
+  signal?: AbortSignal,
+): SubagentRunner {
+  return async (prompt: string, options?: SubagentExecOptions) => {
+    const args = ["--no-session", ...(options?.extraFlags ?? []), "-p", prompt]
+    const release = await _subagentEnvMutex.acquire()
+    const savedEnv: Record<string, string | undefined> = {}
+    const extraEnv = options?.extraEnv ?? {}
+    for (const [key, value] of Object.entries(extraEnv)) {
+      savedEnv[key] = process.env[key]
+      process.env[key] = value
+    }
+    try {
+      const execResult = await pi.exec("pi", args, {
+        signal,
+        timeout: 10 * 60 * 1000,
+      })
+
+      if (execResult.code !== 0) {
+        throw new Error(execResult.stderr || execResult.stdout || `Subagent failed for prompt: ${prompt}`)
+      }
+
+      return (execResult.stdout || "").trim()
+    } finally {
+      for (const [key, oldValue] of Object.entries(savedEnv)) {
+        if (oldValue === undefined) {
+          delete process.env[key]
+        } else {
+          process.env[key] = oldValue
+        }
+      }
+      release()
+    }
+  }
+}
 
 const artifactHelperParams = Type.Object({
   repoRoot: Type.String({ description: "Repository root where workflow artifacts should be created" }),
@@ -48,6 +93,7 @@ const subagentParams = Type.Object({
   agent: Type.Optional(Type.String({ description: "Single subagent skill name" })),
   task: Type.Optional(Type.String({ description: "Single subagent task" })),
   chain: Type.Optional(Type.Array(subagentTaskSchema, { description: "Serial subagent chain with optional {previous} placeholder" })),
+  inheritSkills: Type.Optional(Type.Boolean({ description: "Whether the subagent should inherit skills. Default: true" })),
 })
 
 const workflowStateParams = Type.Object({
@@ -79,6 +125,7 @@ const parallelSubagentTaskSchema = Type.Object({
 
 const parallelSubagentParams = Type.Object({
   tasks: Type.Array(parallelSubagentTaskSchema, { description: "Array of independent tasks to run concurrently" }),
+  inheritSkills: Type.Optional(Type.Boolean({ description: "Whether subagents should inherit skills. Default: false" })),
 })
 
 const sessionCheckpointParams = Type.Object({
@@ -263,19 +310,9 @@ export default function ceCoreExtension(pi: ExtensionAPI) {
           agent: params.agent,
           task: params.task,
           chain: params.chain,
+          inheritSkills: params.inheritSkills,
         },
-        async (prompt: string) => {
-          const execResult = await pi.exec("pi", ["--no-session", "-p", prompt], {
-            signal,
-            timeout: 10 * 60 * 1000,
-          })
-
-          if (execResult.code !== 0) {
-            throw new Error(execResult.stderr || execResult.stdout || `Subagent failed for prompt: ${prompt}`)
-          }
-
-          return (execResult.stdout || "").trim()
-        },
+        createSubagentRunner(pi, signal),
       )
 
       return {
@@ -363,19 +400,11 @@ export default function ceCoreExtension(pi: ExtensionAPI) {
     parameters: parallelSubagentParams,
     async execute(_toolCallId, params, signal) {
       const result = await parallelSubagent.execute(
-        { tasks: params.tasks },
-        async (prompt: string) => {
-          const execResult = await pi.exec("pi", ["--no-session", "-p", prompt], {
-            signal,
-            timeout: 10 * 60 * 1000,
-          })
-
-          if (execResult.code !== 0) {
-            throw new Error(execResult.stderr || execResult.stdout || `Subagent failed for prompt: ${prompt}`)
-          }
-
-          return (execResult.stdout || "").trim()
+        {
+          tasks: params.tasks,
+          inheritSkills: params.inheritSkills,
         },
+        createSubagentRunner(pi, signal),
       )
 
       return {
@@ -595,6 +624,8 @@ export default function ceCoreExtension(pi: ExtensionAPI) {
 export { createArtifactHelperTool } from "./tools/artifact-helper"
 export { createAskUserQuestionTool } from "./tools/ask-user-question"
 export { createSubagentTool } from "./tools/subagent"
+export { checkSubagentDepth, getChildDepthEnv, DEFAULT_MAX_SUBAGENT_DEPTH } from "./tools/subagent-depth-guard"
+export { AsyncMutex } from "./tools/async-mutex"
 export { createWorkflowStateTool } from "./tools/workflow-state"
 export { createWorktreeManagerTool } from "./tools/worktree-manager"
 export { createReviewRouterTool } from "./tools/review-router"

package/extensions/ce-core/tools/async-mutex.ts

@@ -0,0 +1,28 @@
+/**
+ * Async mutex for serializing critical sections that mutate shared state
+ * (e.g. process.env) across concurrent async operations.
+ */
+export class AsyncMutex {
+  private queue: (() => void)[] = []
+  private locked = false
+
+  async acquire(): Promise<() => void> {
+    return new Promise<() => void>((resolve) => {
+      const tryAcquire = () => {
+        if (!this.locked) {
+          this.locked = true
+          resolve(() => this.release())
+        } else {
+          this.queue.push(tryAcquire)
+        }
+      }
+      tryAcquire()
+    })
+  }
+
+  private release(): void {
+    this.locked = false
+    const next = this.queue.shift()
+    if (next) next()
+  }
+}

package/extensions/ce-core/tools/parallel-subagent.ts

@@ -1,3 +1,17 @@
+/**
+ * Parallel subagent tool — runs multiple skill-based subagent tasks concurrently.
+ *
+ * Features:
+ *   - Recursion depth guard (PI_SUBAGENT_DEPTH / PI_SUBAGENT_MAX_DEPTH)
+ *   - Optional context slimming via --no-skills flag
+ */
+
+import {
+  checkSubagentDepth,
+  getChildDepthEnv,
+} from "./subagent-depth-guard"
+import type { SubagentExecOptions, SubagentRunner } from "./subagent"
+
 export interface ParallelSubagentTask {
   agent: string
   task: string
@@ -5,6 +19,8 @@ export interface ParallelSubagentTask {
 
 export interface ParallelSubagentInput {
   tasks: ParallelSubagentTask[]
+  /** Whether subagents should inherit skills. Default: false for parallel */
+  inheritSkills?: boolean
 }
 
 export interface ParallelResultItem {
@@ -18,8 +34,6 @@ export interface ParallelSubagentResult {
   outputs: ParallelResultItem[]
 }
 
-export type SubagentRunner = (prompt: string) => Promise<string>
-
 function buildPrompt(agent: string, task: string): string {
   return `/skill:${agent} ${task}`
 }
@@ -28,12 +42,22 @@ export function createParallelSubagentTool() {
   return {
     name: "parallel_subagent",
     async execute(input: ParallelSubagentInput, runner: SubagentRunner): Promise<ParallelSubagentResult> {
+      // Recursion depth guard
+      const depthCheck = checkSubagentDepth()
+      if (!depthCheck.allowed) {
+        throw new Error(depthCheck.reason!)
+      }
+
       if (!input.tasks || input.tasks.length === 0) {
         throw new Error("parallel_subagent requires at least one task")
       }
 
+      // Default: parallel workers get a slim context (no inherited skills)
+      const inheritSkills = input.inheritSkills ?? false
+      const execOptions = buildParallelExecOptions(inheritSkills)
+
       const promises = input.tasks.map(({ agent, task }) =>
-        runner(buildPrompt(agent, task)),
+        runner(buildPrompt(agent, task), execOptions),
       )
 
       const settled = await Promise.allSettled(promises)
@@ -52,3 +76,25 @@ export function createParallelSubagentTool() {
     },
   }
 }
+
+/**
+ * Build exec options for parallel subagent workers.
+ * Defaults to slim context (no inherited skills).
+ */
+function buildParallelExecOptions(inheritSkills: boolean): SubagentExecOptions {
+  const flags: string[] = []
+  const env: Record<string, string> = {}
+
+  // Context slimming
+  if (!inheritSkills) {
+    flags.push("--no-skills")
+  }
+
+  // Recursion depth
+  Object.assign(env, getChildDepthEnv())
+
+  return {
+    extraFlags: flags.length > 0 ? flags : undefined,
+    extraEnv: env,
+  }
+}

package/extensions/ce-core/tools/subagent-depth-guard.ts

@@ -0,0 +1,86 @@
+/**
+ * Subagent recursion depth guard.
+ *
+ * Prevents uncontrolled recursive subagent spawning by tracking depth
+ * via environment variables. Inspired by pi-subagents' depth control
+ * but implemented as a minimal, standalone module.
+ *
+ * Environment variables:
+ *   PI_SUBAGENT_DEPTH     — current nesting depth (default: 0)
+ *   PI_SUBAGENT_MAX_DEPTH — maximum allowed depth (default: 2)
+ */
+
+/** Default maximum subagent nesting depth */
+export const DEFAULT_MAX_SUBAGENT_DEPTH = 2
+
+/**
+ * Read the current subagent depth from environment.
+ * Returns 0 if unset or invalid.
+ */
+export function getCurrentDepth(): number {
+  const raw = process.env.PI_SUBAGENT_DEPTH
+  if (!raw) return 0
+  const depth = parseInt(raw, 10)
+  return Number.isNaN(depth) ? 0 : depth
+}
+
+/**
+ * Read the maximum allowed depth from environment.
+ * Falls back to DEFAULT_MAX_SUBAGENT_DEPTH if unset or invalid.
+ */
+export function getMaxDepth(): number {
+  const raw = process.env.PI_SUBAGENT_MAX_DEPTH
+  if (!raw) return DEFAULT_MAX_SUBAGENT_DEPTH
+  const max = parseInt(raw, 10)
+  return Number.isNaN(max) || max < 0 ? DEFAULT_MAX_SUBAGENT_DEPTH : max
+}
+
+/**
+ * Check whether subagent execution is allowed at the current depth.
+ * Returns an object with:
+ *   allowed — whether execution can proceed
+ *   depth   — the current depth
+ *   max     — the maximum depth
+ *   reason  — human-readable explanation if blocked
+ */
+export function checkSubagentDepth(): {
+  allowed: boolean
+  depth: number
+  max: number
+  reason?: string
+} {
+  const depth = getCurrentDepth()
+  const max = getMaxDepth()
+
+  if (depth >= max) {
+    return {
+      allowed: false,
+      depth,
+      max,
+      reason: `Subagent recursion depth limit reached (depth=${depth}, max=${max}). ` +
+        `Set PI_SUBAGENT_MAX_DEPTH to increase the limit.`,
+    }
+  }
+
+  return { allowed: true, depth, max }
+}
+
+/**
+ * Build environment variables to pass to a child subagent process.
+ * Increments the depth counter so the child can guard its own spawns.
+ *
+ * @param overrides — optional overrides for max depth per-agent
+ */
+export function getChildDepthEnv(overrides?: {
+  maxDepth?: number
+}): Record<string, string> {
+  const currentDepth = getCurrentDepth()
+  const childDepth = currentDepth + 1
+  let maxDepth = overrides?.maxDepth ?? getMaxDepth()
+  if (maxDepth < 0) maxDepth = DEFAULT_MAX_SUBAGENT_DEPTH
+
+  return {
+    PI_SUBAGENT_DEPTH: String(childDepth),
+    PI_SUBAGENT_MAX_DEPTH: String(maxDepth),
+  }
+}

package/extensions/ce-core/tools/subagent.ts

@@ -1,3 +1,16 @@
+/**
+ * Subagent tool — runs a single skill-based subagent or a serial chain.
+ *
+ * Features:
+ *   - Recursion depth guard (PI_SUBAGENT_DEPTH / PI_SUBAGENT_MAX_DEPTH)
+ *   - Optional context slimming via --no-skills flag
+ */
+
+import {
+  checkSubagentDepth,
+  getChildDepthEnv,
+} from "./subagent-depth-guard"
+
 export interface SubagentTask {
   agent: string
   task: string
@@ -7,6 +20,8 @@ export interface SubagentInput {
   agent?: string
   task?: string
   chain?: SubagentTask[]
+  /** Whether the subagent should inherit skills. Default: true */
+  inheritSkills?: boolean
 }
 
 export interface SubagentResult {
@@ -14,12 +29,28 @@ export interface SubagentResult {
   outputs: string[]
 }
 
-export type SubagentRunner = (prompt: string) => Promise<string>
+export interface SubagentExecOptions {
+  /** Extra CLI flags to pass to the child pi process */
+  extraFlags?: string[]
+  /** Environment variables to inject into the child process */
+  extraEnv?: Record<string, string>
+}
+
+export type SubagentRunner = (
+  prompt: string,
+  options?: SubagentExecOptions,
+) => Promise<string>
 
 export function createSubagentTool() {
   return {
     name: "subagent",
     async execute(input: SubagentInput, runner: SubagentRunner): Promise<SubagentResult> {
+      // Recursion depth guard
+      const depthCheck = checkSubagentDepth()
+      if (!depthCheck.allowed) {
+        throw new Error(depthCheck.reason!)
+      }
+
       const hasSingle = Boolean(input.agent && input.task)
       const hasChain = Boolean(input.chain && input.chain.length > 0)
 
@@ -27,9 +58,11 @@ export function createSubagentTool() {
         throw new Error("Provide exactly one mode: single or chain")
       }
 
+      const execOptions = buildExecOptions(input.inheritSkills)
+
       if (hasSingle) {
         const prompt = buildPrompt(input.agent!, input.task!)
-        const output = await runner(prompt)
+        const output = await runner(prompt, execOptions)
         return {
           mode: "single",
           outputs: [output],
@@ -41,7 +74,7 @@ export function createSubagentTool() {
 
       for (const task of input.chain ?? []) {
         const prompt = buildPrompt(task.agent, task.task.replace(/\{previous\}/g, previous))
-        const output = await runner(prompt)
+        const output = await runner(prompt, execOptions)
         outputs.push(output)
         previous = output
       }
@@ -54,6 +87,28 @@ export function createSubagentTool() {
   }
 }
 
+/**
+ * Build exec options based on subagent configuration.
+ * Controls context inheritance and recursion depth.
+ */
+function buildExecOptions(inheritSkills?: boolean): SubagentExecOptions {
+  const flags: string[] = []
+  const env: Record<string, string> = {}
+
+  // Context slimming: skip skills inheritance when explicitly disabled
+  if (inheritSkills === false) {
+    flags.push("--no-skills")
+  }
+
+  // Recursion depth: pass incremented depth to child process
+  Object.assign(env, getChildDepthEnv())
+
+  return {
+    extraFlags: flags.length > 0 ? flags : undefined,
+    extraEnv: env,
+  }
+}
+
 function buildPrompt(agent: string, task: string): string {
   return `/skill:${agent} ${task}`
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leing2021/super-pi",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "private": false,
   "type": "module",
   "description": "Pi-native Compound Engineering package for iterative development workflows",