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:

Type	Label	Description	Tools	Max Turns
explore	Explorer	Fast codebase search, structural questions	file_read, file_search, file_list, file_tree, file_info	6
general	Generalist	Full tool access for complex multi-step tasks	All available	12
plan	Planner	Creates detailed execution plans	Read-only file tools	8
code	Coder	Writes and edits code, runs shell	Full file system + shell + code_exec	10
research	Researcher	Web research and information synthesis	web_search + read-only file tools	8

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 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 five types with:

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

See Also

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