Task Agent Discovery and Selection

This document describes how the task subsystem discovers agent definitions, merges multiple sources, and resolves a requested agent at execution time.

It covers runtime behavior as implemented today, including precedence, invalid-definition handling, and spawn/depth constraints that can make an agent effectively unavailable.

Implementation files

• src/task/discovery.ts
• src/task/agents.ts
• src/task/types.ts
• src/task/index.ts
• src/task/commands.ts
• src/prompts/agents/task.md
• src/prompts/tools/task.md
• src/discovery/helpers.ts
• src/config.ts
• src/task/executor.ts

---

Agent definition shape

Task agents normalize into AgentDefinition (src/task/types.ts):

• name, description, systemPrompt (required for a valid loaded agent)
• optional tools, spawns, model, thinkingLevel, output
• source: "bundled" | "user" | "project"
• optional filePath

Parsing comes from frontmatter via parseAgentFields() (src/discovery/helpers.ts):

• missing name or description => invalid (null), caller treats as parse failure
• tools accepts CSV or array; if provided, submit_result is auto-added
• spawns accepts *, CSV, or array
• backward-compat behavior: if spawns missing but tools includes task, spawns becomes *
• output is passed through as opaque schema data

Bundled agents

Bundled agents are embedded at build time (src/task/agents.ts) using text imports.

EMBEDDED_AGENT_DEFS defines:

• explore, plan, designer, reviewer from prompt files
• task and quick_task from shared task.md body plus injected frontmatter

Loading path:

1. loadBundledAgents() parses embedded markdown with parseAgent(..., "bundled", "fatal")
2. results are cached in-memory (bundledAgentsCache)
3. clearBundledAgentsCache() is test-only cache reset

Because bundled parsing uses level: "fatal", malformed bundled frontmatter throws and can fail discovery entirely.

Filesystem and plugin discovery

discoverAgents(cwd, home) (src/task/discovery.ts) merges agents from multiple places before appending bundled definitions.

Discovery inputs

1. User config agent dirs from getConfigDirs("agents", { project: false })
2. Nearest project agent dirs from findAllNearestProjectConfigDirs("agents", cwd)
3. Claude plugin roots (listClaudePluginRoots(home)) with agents/ subdirs
4. Bundled agents (loadBundledAgents())

Actual source order

Source-family order comes from getConfigDirs("", { project: false }), which is derived from priorityList in src/config.ts:

1. .pisces
2. .claude
3. .codex
4. .gemini

For each source family, discovery order is:

1. nearest project dir for that source (if found)
2. user dir for that source

After all source-family dirs, plugin agents/ dirs are appended (project-scope plugins first, then user-scope).

Bundled agents are appended last.

Important caveat: stale comments vs current code

discovery.ts header comments still mention .pi and do not mention .codex/.gemini. Actual runtime order is driven by src/config.ts and currently uses .pisces, .claude, .codex, .gemini.

Merge and collision rules

Discovery uses first-wins dedup by exact agent.name:

• A Set<string> tracks seen names.
• Loaded agents are flattened in directory order and kept only if name unseen.
• Bundled agents are filtered against the same set and only added if still unseen.

Implications:

• Project overrides user for same source family.
• Higher-priority source family overrides lower (.pisces before .claude, etc.).
• Non-bundled agents override bundled agents with the same name.
• Name matching is case-sensitive (Task and task are distinct).
• Within one directory, markdown files are read in lexicographic filename order before dedup.

Invalid/missing agent file behavior

Per directory (loadAgentsFromDir):

• unreadable/missing directory: treated as empty (readdir(...).catch(() => []))
• file read or parse failure: warning logged, file skipped
• parse path uses parseAgent(..., level: "warn")

Frontmatter failure behavior comes from parseFrontmatter:

• parse error at warn level logs warning
• parser falls back to a simple key: value line parser
• if required fields are still missing, parseAgentFields fails, then AgentParsingError is thrown and caught by caller (file skipped)

Net effect: one bad custom agent file does not abort discovery of other files.

Agent lookup and selection

Lookup is exact-name linear search:

• getAgent(agents, name) => agents.find(a => a.name === name)

In task execution (TaskTool.execute):

1. agents are rediscovered at call time (discoverAgents(this.session.cwd))
2. requested params.agent is resolved through getAgent
3. missing agent returns immediate tool response:
   • Unknown agent "...". Available: ...
   • no subprocess runs

Description vs execution-time discovery

TaskTool.create() builds the tool description from discovery results at initialization time (buildDescription).

execute() rediscoveres agents again. So the runtime set can differ from what was listed in the earlier tool description if agent files changed mid-session.

Structured-output guardrails and schema precedence

Runtime output schema precedence in TaskTool.execute:

1. agent frontmatter output
2. task call params.schema
3. parent session outputSchema

(effectiveOutputSchema = effectiveAgent.output ?? outputSchema ?? this.session.outputSchema)

Prompt-time guardrail text in src/prompts/tools/task.md warns about mismatch behavior for structured-output agents (explore, reviewer): output-format instructions in prose can conflict with built-in schema and produce null outputs.

This is guidance, not hard runtime validation logic in discoverAgents.

Command discovery interaction

src/task/commands.ts is parallel infrastructure for workflow commands (not agent definitions), but it follows the same overall pattern:

• discover from capability providers first
• deduplicate by name with first-wins
• append bundled commands if still unseen
• exact-name lookup via getCommand

In src/task/index.ts, command helpers are re-exported with agent discovery helpers. Agent discovery itself does not depend on command discovery at runtime.

Availability constraints beyond discovery

An agent can be discoverable but still unavailable to run because of execution guardrails.

Parent spawn policy

TaskTool.execute checks session.getSessionSpawns():

• "*" => allow any
• "" => deny all
• CSV list => allow only listed names

If denied: immediate Cannot spawn '...'. Allowed: ... response.

Blocked self-recursion env guard

PI_BLOCKED_AGENT is read at tool construction. If request matches, execution is rejected with recursion-prevention message.

Recursion-depth gating (task tool availability inside child sessions)

In runSubprocess (src/task/executor.ts):

• depth computed from taskDepth
• task.maxRecursionDepth controls cutoff
• when at max depth:
  • task tool is removed from child tool list
  • child spawns env is set to empty

So deeper levels cannot spawn further tasks even if the agent definition includes spawns.

Plan mode caveat (current implementation)

TaskTool.execute computes an effectiveAgent for plan mode (prepends plan-mode prompt, forces read-only tool subset, clears spawns), but runSubprocess is called with agent rather than effectiveAgent.

Current effect:

• model override / thinking level / output schema are derived from effectiveAgent
• system prompt and tool/spawn restrictions from effectiveAgent are not passed through in this call path

This is an implementation caveat worth knowing when reading plan-mode behavior expectations.