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:

research — read-only investigator. Restricted to read_file, glob, rg, and web_fetch. It cannot edit files, run shell commands, or spawn further subagents. Use it to gather facts, map a codebase, or cross-reference information before the parent decides what to do.

implement — write-capable executor. Gets the full default toolset: read_file, edit_file, edit_files, edit_notebook, shell, command_status, codebase_search, rg, glob, web_fetch, read_lints, and todo_write. The sub_agent tool is forbidden so it cannot recursively spawn further subagents. Inherits the parent’s approval posture — in default mode it asks before each edit or command; in autopilot it runs them automatically.

Both built-in agents are non-interactive: they cannot ask the user questions 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.

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.
tools: read_file, glob, rg, web_fetch
disallowedTools: shell, edit_file
---

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.
tools	Explicit allowlist. Omit to inherit the broad default toolset. An empty value means no tools.
disallowedTools	Denylist applied before the allowlist narrows (for excluding specific tools from the default set).

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:

• Non-interactive — they cannot ask the user questions or use tools like ask_questions or check_understanding.
• No recursive delegation — the sub_agent tool is always forbidden inside a subagent, regardless of the profile’s tools field.
• No task-management tools — generate_plan, new_task, and report_bug are reserved for the parent.

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.