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.

Launching a named profile (implement or a custom agent) asks for confirmation under Default Approvals; Autopilot and Full Access launch it without prompting. research launches never ask. In every mode, the child’s own tool calls are then gated per call by the same approval policy as the parent’s.

All subagents are non-interactive — the interactive question tools are withheld from child runs — so they 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. Child tool calls stay owned by the parent chat session, so terminal processes, Stop, and session cleanup remain scoped to the task. Nested Kodik-proxy model requests carry the parent task id too, so usage is attributed to the chat that launched the child. 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 hard child-specific exclusions are sub_agent (removed inside child runs to prevent recursion), todo_write and generate_plan (the todo and plan panels belong to the parent conversation — a child’s progress is already shown by its card’s step rows), and the interactive ask_questions/check_understanding tools (a subagent cannot talk to the user; it reports findings or blocking questions back in its final summary).

Background Subagents

Passing background: true to sub_agent launches the child without pausing the parent: the tool returns a launch receipt (with an agent_id) immediately and the main agent keeps working while the child investigates. When the child settles — finished, stopped, or interrupted — its report re-enters the conversation automatically:

• If the parent turn is still running, the report is folded into its next step.
• If the chat has gone idle, the report starts a new turn by itself, shown as a compact “agent reported back” row in the transcript.

The agent can also check on a background child with the agent_status tool (using the agent_id from the launch receipt), or pass wait: true to block until the child settles when it needs the result before continuing. A settled report retrieved through agent_status counts as delivered — the automatic notification for that agent is skipped, so the agent never receives the same findings twice.

While background children are running:

• A panel above the chat input shows how many agents are running in the background. Expand it to see each agent’s goal and live steps, or stop one with its Stop button. The panel is per-session — each chat lists only its own agents.
• The session’s sidebar status keeps reading “working” until all of its children settle.
• Stopping the main turn does not stop background children — they keep working and report back later. Stop them from the panel or their card, or by deleting the session.

Background children run unattended, so they are limited to the read-only research toolset (read_file, glob, rg, codebase_search, read_lints, web_fetch, web_search) — no edits, shell commands, or browser. Use a normal foreground sub_agent call for write-capable delegation. Restarting the IDE interrupts still-running background children; the agent is told about the interruption on your next message so it can relaunch the investigation if it is still needed.

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)	~/.kodik/Agents/*.md	Personal agents not tied to any project.
Plugin	<plugin root>/agents/*.md	Distributed via the plugin system.

Enabled project, user, and plugin profiles are listed in the main assistant’s system prompt so it can choose them for delegation. Settings → Sub Agents and the running assistant discover these custom profiles from the same sources.

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.
• Parent-owned panels stay parent-owned — todo_write and generate_plan are removed inside a subagent; the todo list and the plan panel belong to the parent conversation, and the child’s progress is shown by its card’s steps.
• Non-interactive — ask_questions and check_understanding are removed inside a subagent; it reports findings or blocking questions back to the parent in its final summary.
• 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 activity panel shows normalized child-step rows instead of raw tool-call JSON. 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.