feat: subagent-tool — add subAgent tool for spawning child-process agents

[avoidwork]

Description

Implemented the subAgent tool that spawns child processes (node index.js "PROMPT") to execute prompts as independent sub-agents. Supports single execution and fan-out (parallel/sequential) modes with configurable concurrency, timeout, and error handling.

Type of Change

• New feature (non-breaking change which adds functionality)

Implementation Summary

Files Changed

• src/tools/subAgent.js (388 lines) — Core tool implementation
• src/tools/index.js — Tool registration (TOOL_PERMISSIONS, TOOL_FACTORIES)
• src/skills/validator.js — Defensive fix: guard against undefined errors in metadata validation
• config.yaml — Added process.subAgent configuration section
• tests/unit/tools/subAgent.test.js (143 lines) — Unit tests
• openspec/specs/subagent/spec.md — Spec requirements (12 added)
• openspec/changes/archive/2026-06-21-subagent-tool/ — Archived OpenSpec artifacts

Key Features Implemented

1. Single execution mode — Spawn one sub-agent with delegation + context, return structured result
2. Fan-out mode — Parallel/sequential task execution with configurable maxConcurrent limit
3. Marker-based stdout parsing — # SubAgent marker for result extraction (mirrors compaction tool)
4. Response contract — { ok, result, error? } matching compaction tool pattern
5. Process tracking — Shared processTracker from terminal.js for PID tracking and lifecycle management
6. Timeout resolution — Per-call > env var > config default priority
7. Parameter extraction — Optional returnParams for JSON result filtering with fallback
8. Session isolation modes — isolated (fresh), forked (compaction), shared (parent)
9. Shell escaping — Handles quotes, backticks, dollar signs, newlines, tabs, carriage returns
10. Error handling — continue vs fail-fast strategies for fan-out batches

Configuration Added

process:
  subAgent:
    timeout: 600000
    maxConcurrent: 4
    sessionMode: isolated
    defaultStrategy: parallel
    defaultOnError: continue

Testing

• Unit tests: 19 test cases covering parseSubAgentOutput, escapeShellArg, resolveTimeout
• Full test suite: 1176 pass, 0 fail, 1 skipped
• Lint: 0 warnings, 0 errors

Coverage

• 100% line coverage maintained

Checklist

• npm run lint passes
• Tests pass with 100% line coverage
• No forbidden patterns used
• Conventional Commit style applied

[avoidwork]

Audit Results: subAgent Tool

Iteration 1

Goal Fulfillment: PASS

All 10 detailed goals from feature-goals.md are satisfied:

1. Single execution mode — Implemented via spawnSubAgentProcess()
2. Fan-out mode — Implemented via executeFanOut() with parallel/sequential strategies
3. Prompt construction — Implemented with PROMPT_SEPARATOR and escapeShellArg()
4. Marker-based stdout parsing — Implemented with parseSubAgentOutput()
5. Response contract — Returns { ok, result, error? } matching compaction pattern
6. Process tracking — Uses shared trackProcess() from terminal.js
7. Timeout resolution — Implemented with resolveTimeout() (per-call > env var > config)
8. Configuration — Added process.subAgent section to config.yaml
9. Tool registration — Added to TOOL_PERMISSIONS and TOOL_FACTORIES in index.js
10. Parameter extraction — Implemented returnParams filtering with JSON fallback

Spec Compliance: PASS

All 11 requirements in specs/subagent/spec.md are implemented:

• Sub-agent spawning ✅
• Prompt construction with separator ✅
• Marker-based stdout parsing ✅
• Response contract ✅
• Single execution mode ✅
• Fan-out parallel execution ✅
• Fan-out sequential execution ✅
• Timeout enforcement ✅
• Process tracking ✅
• Session isolation modes ✅
• Tool registration ✅
• Configuration ✅

Task Completion: PASS

All 35 tasks in tasks.md are marked [x] and implemented.

Quality Check: PASS

• Tests: 1176 pass, 0 fail, 1 skipped
• Lint: 0 warnings, 0 errors
• Application: Starts correctly (TUI raw mode error is expected in non-interactive environments)

Verdict: No errors found. Proceeding to Step 10 (Archive).