Sub Agents

Sub-Agents

CortexPrism agents can spawn sub-agents — child Deno processes that run independently with their own model, tools, and system prompt. Sub-agents are used for parallel work, specialized tasks, and scope isolation.

Sub-Agent Types

Defined in src/agent/sub-agent-types.ts (13 types total):

Core Types (v0.34.0+)

Type	Label	Description	Tools	Max Turns
explore	Explorer	Fast codebase search, structural questions. Stays within task scope — read-only.	file_read, file_search, file_list, file_tree, file_info	6
general	Generalist	Full tool access for complex multi-step tasks. Reports scope expansion rather than acting unilaterally.	All available	12
plan	Planner	Creates detailed execution plans with step IDs (S1, S2, …) for dependency tracking. Read-only.	Read-only file tools	8
code	Coder	Writes and edits code. Runs tests — verification is mandatory before reporting done.	Full file system (incl. file_undo, file_redo) + shell + code_exec	10
research	Researcher	Web research and information synthesis. Source-quality hierarchy: official docs > peer-reviewed > news > blogs.	web_search + read-only file tools	8

Domain Specialists (v0.41.0+)

Type	Label	Description	Tools	Max Turns
security	Security Auditor	OWASP Top 10, secrets, CVEs, dependency/supply-chain risks. Read-only. Severity uncertainty defaults to higher.	file_read, file_search, file_list, file_tree, file_info, web_search	10
debug	Debugger	History → Reproduce → Isolate → Fix → Verify → Regression test loop.	Full file system + shell + code_exec	12
architect	Architect	System design with quantified trade-offs, ADR format. Extends existing patterns first. Read-only.	Read-only file tools	10
devops	DevOps Engineer	Docker, Kubernetes, Terraform, CI/CD, shell automation. Shows commands before destructive ops.	Full file system + shell + web_search	12
data	Data Analyst	Data queries, analysis, insights. Explicitly distinguishes correlation from causation.	shell + code_exec + db_query + web_search	12
ui	UI/UX Designer	Accessible interface design and building. WCAG 2.1 AA minimum.	Full file system (incl. file_patch) + shell + browser + web_search + code_exec	12

Quality & Documentation (v0.51.0+)

Type	Label	Description	Tools	Max Turns
reviewer	Code Reviewer	Structured PR review: BLOCKER / SUGGESTION / NITPICK / QUESTION categories. Read-only.	file_read, file_search, file_list, file_tree, file_info, web_search	10
writer	Technical Writer	Writes/edits docs, changelogs, READMEs, API references. Reads source before writing.	file_read, file_write, file_edit, file_search, file_list, file_tree, shell, web_search	10

Spawning Flow

Parent Agent (agent/loop.ts)
  │  Tool call: sub_agent(type="code", task="...")
  ▼
tools/builtin/sub_agent.ts
  │  resolveSubAgentType() → typeDef
  ▼
agent/sub-agent.ts → spawnSubAgent()
  │  Apply type overrides → effective agent config
  │  Spawn: deno run packages/infra/src/processes/sub-agent-entry.ts
  │  Send init via stdin: { type:"init", config:{ ... }, agentConfig:{ ... } }
  ▼
processes/sub-agent-entry.ts
  │  Create session: channel="subagent:code", parent_session_id=<parentId>
  │  Build provider, tool registry, embedder
  │  Send { type:"ready" }
  │  Run agentTurn({ userMessage: instruction, stream: true })
  │  Send { type:"done", result:{ response, tokensIn, tokensOut, costUsd, durationMs } }
  ▼
Parent receives streamed chunks → tool result

Protocol

Parent ↔ Child communication uses stdin/stdout JSON-line protocol:

Parent → Child:

{ "type": "init", "config": { "id": "...", "parentSessionId": "...", "instruction": "...", "subAgentType": "code", "config": {...} }, "agentConfig": {...} }

Child → Parent:

{ "type": "ready" }
{ "type": "chunk", "delta": "..." }
{ "type": "done", "result": { "success": true, "response": "...", "tokensIn": 100, "tokensOut": 50, "costUsd": 0.001, "durationMs": 800 } }
{ "type": "error", "error": "..." }

Session Tracking

Every sub-agent session records its parent via parent_session_id in the sessions table:

API Endpoint	Description
GET /api/sessions/:id/children	Returns all sub-agent sessions
getChildSessions(parentId)	DB query for child sessions
getParentSession(childId)	Find a session's parent
countChildSessions(parentId)	Count sub-agents

Web UI shows channel type badges (explore, code) and ⤷ child badges. Session detail shows ← parent link and clickable children.

System Prompt Guidance

The default agent soul includes a "Sub-Agents" section documenting all 13 types with:

• When to use each type
• Anti-patterns to avoid
• Parallel spawning strategies

Parallel Sub-Agent Dispatcher (#58)

A task board tracks all active and completed sub-agent tasks:

• Active tasks show pulsing green indicators
• Completed/failed tasks with status badges
• Auto-refresh every 3 seconds when tab is selected
• GET /api/workflows/tasks endpoint for task board data
• In-memory tracking (max 100 completed tasks in rolling history)

See Also

• Agent Loop — How sub-agents integrate into the agent lifecycle
• Architecture — System overview including sub-agent subsystem