Agents

KodaCode exposes agents as explicit runtime definitions, not prompt-only personas. Agent markdown can narrow tool access, select a primary model, and add prompt text, while runtime code still owns workflow phases, permissions, tool execution, and replay.

Built-in agents

KodaCode currently ships four built-in agents.

Built-in agents:

• builder
• engineer
• reviewer
• planner

builder and engineer are the common interactive choices. They have a clear boundary: builder is the plain direct-execution agent, while engineer owns structured workflow task tracking. reviewer and planner are selectable and can also be used by runtime workflow phases.

When web_search is configured at the runtime level, all built-in agents can use it. builder and engineer inherit it from the current turn surface, and reviewer and planner explicitly allow it in their built-in policies.

builder

The default direct-execution agent. It is meant for normal coding work: inspect the code, make changes, run checks, and finish the task. It does not own workflow task tracking.

Its policy is “all tools except task_workflow and task_review.” That includes the full code-intelligence surface, including read-only tools such as symbols, definition, diagnostics, refs, and trace, plus mutation tools such as rename_symbol and code_action.

engineer

A structured execution agent with access to runtime task tools such as task_workflow. Use it when the work benefits from saved task state or a more explicit execution workflow. Its intended boundary is: narrow local planning stays inline, while configured workflow phases can separate planning, approval, implementation, verification, review, and summary behavior.

Its policy is “all tools except task_review.” That includes the full code-intelligence surface. engineer can use read-only semantic tools for impact analysis and can use rename_symbol or code_action when a language-server refactor or fix is safer than manual text edits.

reviewer

A read-only agent for checking current changes. It has fewer tools than the coding agents and does not own file-editing tools. When external checks help, it can also use web_search and web_fetch.

reviewer has read-only code-intelligence tools:

• symbols
• definition
• diagnostics
• refs
• trace

It does not have mutation code-intelligence tools such as rename_symbol or code_action.

planner

A read-only planning agent for repository analysis and implementation planning. It is available in the runtime catalog, but it is usually more useful for analysis than direct implementation. It can use read tools, read-only code-intelligence tools, question for bounded user decisions, and web_search when that runtime capability is configured.

Primary planner turns use a runtime-owned plan approval flow. The planner first shows the complete plan, then signals the question tool with the planner_save_plan purpose. Runtime records the visible plan and asks whether to save, apply, revise, or stop. Saving writes the accepted plan under .kodacode/plans/; applying continues with engineer; revising continues with planner.

planner has the same read-only code-intelligence set as reviewer:

• symbols
• definition
• diagnostics
• refs
• trace

It does not have mutation tools, including apply_patch, write, rename_symbol, or code_action.

Workflow and review

The structured workflow path is centered on engineer, planner, and reviewer.

• engineer owns task_workflow for saved implementation task state
• planner owns read-only planning phases and primary plan approval turns
• reviewer owns task_review for saved task review outcomes
• workflow review phases use workflow_review_result to record required review-pass outcomes

The top-level workflow config controls whether runtime injects an automatic review turn:

• workflow.review_mode: off: runtime never starts an automatic review turn
• workflow.review_mode: manual: review stays agent-driven; runtime does not add a follow-up review turn automatically
• workflow.review_mode: auto: runtime starts a reviewer turn only after an engineer turn completes, every current task is already completed, and at least one completed task still lacks a review outcome

workflow.review_model can route that automatic review turn to a designated review model without changing the main implementation route.

Switching agents

Inside the TUI:

• Tab cycles forward through available agents
• Shift+Tab cycles backward

Available agents are resolved from the runtime catalog for the current workspace.

Custom agents

You can define additional agents in markdown:

• global: ~/.config/kodacode/agents/*.md
• project-local: .kodacode/agents/*.md

The runtime resolves agents in this order:

1. embedded built-ins
2. global agents
3. project-local agents

That means:

• a new global agent is added to the catalog
• a global agent with the same ID as a built-in overrides the built-in
• a project-local agent with the same ID overrides both global and built-in

Agent definitions can narrow tools, provide model routes, and add prompt text, but the runtime still owns execution, permissions, and replay.

Agent file anatomy

An agent markdown file has three parts:

1. the filename, which becomes the agent ID
2. an optional YAML frontmatter block
3. the prompt body

For example, .kodacode/agents/delivery.md creates an agent with the runtime ID delivery.

Frontmatter fields

Agent markdown supports these frontmatter fields:

• description
• model
• mode
• hidden
• AllowTools
• DisallowedTools

These are the complete supported keys. Older route keys such as fallback_models are not supported.

Full example

This is a complete primary agent example for delivery-oriented work:

---
description: Delivery-focused engineer
model: openai/gpt-5-mini
mode: all
AllowTools:
  - read
  - search
  - symbols
  - definition
  - diagnostics
  - refs
  - trace
  - apply_patch
  - write
  - bash
  - git_diff
  - question
  - task_workflow
DisallowedTools:
  - task_review
---

You are the delivery agent for this repository.

<workflow>
Own the main implementation from start to finish.

Use `task_workflow` when the work naturally breaks into saved steps.
For broad planning or review, either answer directly in this agent or select a
runtime workflow that has explicit planner or reviewer phases.
</workflow>

<execution>
Read the relevant code before editing.
Prefer small, verifiable changes.
Use `question` only when a real user decision is required.
</execution>

<workflow_examples>
- Use direct engineer work for: "Add the schema change and focused tests."
- Use a workflow for: "Plan, implement, verify, and review this change."
</workflow_examples>

If you want an agent excluded from the normal picker, use hidden: true:

---
description: Release notes writer
hidden: true
AllowTools:
  - read
  - search
  - git_diff
  - write
---

You only prepare release notes and changelog updates.

What each part does

• Filename: delivery.md becomes the runtime agent ID delivery. This is the ID the TUI and workflow YAML use.
• description: short human-readable text for the picker and catalog.
• model: optional primary model override for this agent. If omitted, the turn uses the session model.
• mode: decides whether the agent is selectable in the picker, reserved as a subagent-only definition, or both.
• hidden: removes the agent from the normal picker without deleting it from the catalog.
• AllowTools: the explicit tools this agent gets.
• DisallowedTools: removes tools from the available set.
• Prompt body: the actual behavior instructions sent to the model.

The XML-like sections in the example such as <workflow> and <execution> are just prompt organization. Runtime does not parse them as structured config. They help the model read the prompt, but they do not grant tools, workflow authority, filesystem access, or network access by themselves.

Agent modes

mode controls where an agent is allowed to appear:

• primary: selectable in the normal agent picker
• subagent: not shown in the normal picker
• all: selectable in the normal agent picker and also marked as compatible with runtime paths that require subagent eligibility

If mode is omitted, runtime treats the agent as primary.

hidden: true removes an agent from the normal picker even if its mode would otherwise make it selectable.

Runtime workflow phases must use agents whose effective mode is not subagent. A phase that names a subagent-only agent is rejected during workflow validation.

Tool permission semantics

AllowTools and DisallowedTools are evaluated by runtime, not by prompt convention.

• If neither AllowTools nor DisallowedTools is set, the agent gets all tools available to the current turn.
• If AllowTools is not set and DisallowedTools is set, the agent gets all current turn tools except the denied ones.
• If AllowTools is set, the agent only gets the listed tools.
• If both are set, runtime starts from AllowTools and then removes anything listed in DisallowedTools.
• AllowTools: [] means no tools at all. That is an explicit no-tool agent, not a fallback.
• If AllowTools names a tool that is not registered in the current runtime, runtime drops it instead of treating the agent as invalid.

Tool names are matched by exact runtime tool name. MCP tools also support the wildcard mcp:*.

This tool access is not the same thing as runtime permission policy:

• AllowTools and DisallowedTools decide which tools exist in the turn
• execution.permission_mode decides the runtime posture
• top-level config.yaml permissions can default repeated actions to allow, ask, or deny
• session approvals and grants remain saved runtime state

That separation is intentional. Agent markdown can narrow tool availability, but it does not grant filesystem, execution, or network authority by itself.

Handoff metadata

Agent markdown can include a handoff: frontmatter block. Current runtime parses and stores that metadata for compatibility with agent definitions, but the user-facing built-in tool surface does not include a standalone delegate tool. For explicit multi-phase work, use runtime workflows and name the agent for each phase in workflow YAML.

Examples:

Unrestricted except a few tools:

---
description: Default coding agent minus workflow tools
DisallowedTools:
  - task_workflow
  - task_review
---

You are a general coding agent.

Read-only review agent:

---
description: Read-only reviewer
AllowTools:
  - read
  - search
  - git_diff
  - symbols
  - definition
  - diagnostics
  - refs
  - trace
---

You review code without modifying it.

No-tool reasoning agent:

---
description: Transcript-only reasoning agent
AllowTools: []
---

You only reason over the prompt and prior transcript.
Do not expect file, shell, network, or MCP access.

Deny all MCP tools while still allowing normal built-in tools:

---
description: Local-only coding agent
DisallowedTools:
  - mcp:*
---

You may use built-in local tools, but not MCP tools.

Skills vs tools

Skills are not themselves tools. Runtime lists available skills in the prompt using only each skill’s $name, description, and SKILL.md path. Mention $name or ${name} in the composer for explicit use. The search_skills and skill tools are normal tools, so an agent can be allowed or denied access to those names like any other tool.

Skills do not declare their own allowed or disallowed tools. The running agent is the authority for what the turn can and cannot do.

Skill directories:

• Global skills: $XDG_CONFIG_HOME/kodacode/skills or ~/.config/kodacode/skills
• Project skills: <workspace>/.kodacode/skills

Cost and token usage

Skills can reduce cost, but only when they replace larger always-on prompt instructions.

• Available skill metadata keeps reusable workflow guidance discoverable without loading full skill instructions into every turn.
• Explicit $name / ${name} mentions load that skill for the turn. Large skill instructions still increase input tokens when loaded.
• The search_skills and skill tools can avoid injecting a whole skill catalog into the prompt by letting the agent discover one relevant skill or load one relevant section on demand.
• Those tools are still normal tool calls, so unnecessary skill discovery can increase latency and total spend even if the prompt is smaller.

If you want the most predictable cost shape, mention the exact $skill you want. If you want maximum flexibility with a larger skill catalog, the skill tools can trade some tool overhead for a smaller base prompt.