Subagents

Subagents let Kodik delegate focused work to child tasks. Each subagent runs in its own context window and returns a result to the parent agent. This keeps the parent’s context clean while handling research or implementation work in parallel or in sequence.

Built-in Agents

Kodik ships two built-in subagent profiles. Profiles choose the child agent’s persona, model preference, and prompt; they do not define a separate runtime tool allowlist.

research — evidence-focused investigator for gathering facts, mapping a codebase, and cross-referencing information before the parent decides what to do. It prefers inspection tools, but it inherits the same effective tool catalog as the parent turn.

implement — implementation-focused executor for scoped changes, commands, and verification. It also inherits the parent turn’s effective tool catalog and follows the current approval mode.

Both built-in agents are prompted to be non-interactive: they should return findings or blockers to the parent instead of asking the user directly.

The sub_agent Tool

The agent invokes subagents via the sub_agent tool. Each call specifies:

• agent — which profile to use (e.g. research, implement, or a custom agent id).
• goal — the task description the subagent receives.
• scope — optional path or area to stay within.
• expectedDeliverables — optional description of what the subagent should return.

The subagent runs as a real child task, with its own message history and API calls. Results are returned to the parent as a markdown report. See Tools for the full tool reference.

Subagents inherit the exact provider tools available to the parent turn after mode filtering, user tool settings, per-action pruning, MCP availability, approvals, hooks, and the current worktree root are applied. Ask, Plan, and Educator mode child runs therefore stay read-only because the parent tool catalog is read-only. Code and Debug mode child runs can use the same write-capable and MCP tools the parent can use. The only hard child-specific exclusion is sub_agent itself, which is removed inside child runs to prevent recursion.

Custom Agent Profiles

You can define your own subagent profiles as .md files with YAML frontmatter.

Frontmatter Fields

---
name: my-agent
description: One-line description shown to the main assistant.
model: inherit
color: blue
---

You are the my-agent sub-agent. Describe behavior and constraints here.
The body becomes the agent's system prompt verbatim.

Field	Description
name	Short identifier (used as the agent id).
description	Shown to the main assistant when it decides whether to delegate.
model	Optional model preference for this profile. Use inherit to use the parent model.
color	Optional color chip shown in settings.

Use the body prompt to describe the agent’s preferred behavior. Runtime tools always come from the current chat mode and Agent Tools settings, not from each profile.

Where to Put Agent Files

Scope	Location	Notes
Project	.kodik/agents/*.md in the workspace root	Checked into version control; all teammates share the same agents.
User (global)	~/Documents/Kodik/Agents/*.md	Personal agents not tied to any project.
Plugin	<plugin root>/agents/*.md	Distributed via the plugin system.

Kodik also recognizes .agents/agents/*.md as a neutral location compatible with other tools.

When two agents share the same short name, .kodik/agents/ takes precedence over .agents/agents/.

Naming and IDs

• Project agents are namespaced as project:<name>.
• User agents are namespaced as user:<name>.
• Plugin agents are namespaced as <pluginId>:<name>.

Pass the full namespaced id to the sub_agent tool when you want to invoke a specific custom agent.

Constraints

All subagents, built-in and custom, share these constraints:

• Inherited tools — they receive the same effective tools the parent turn received, including MCP tools when those are available to the parent.
• No recursive delegation — the sub_agent tool is always removed inside a subagent, regardless of profile frontmatter.
• Read-only modes stay read-only — Ask, Plan, and Educator modes can still delegate, but their child runs inherit the read-only parent catalog.
• Tool turns stay structured — subagent tool calls use the same native argument normalization as parent tool calls, including batched turns. The delegation itself is not cut off by a fixed wall-clock timeout; if a subagent’s file listing or text search takes too long, Kodik returns a tool error so it can narrow the query instead of stalling the whole run.

When to Use Subagents

Subagents are most useful when:

• You need broad context gathered from multiple areas of the codebase before the parent makes changes.
• A well-scoped implementation task can run in isolation without touching files the parent is also editing.
• You want the parent to orchestrate several parallel investigations and synthesize the results.

For small, focused tasks where the agent already has enough context, invoking a subagent adds overhead without benefit.