Agents

Kolega Code is built around several agent types. They share the same core loop but differ in which tools they can use and what they’re specialized for. The main agent can hand off to the others when a task benefits from focus.

Agent types

Agent	Specialty	Can edit files?
Coder	The main, general-purpose coding agent. Full toolset.	Yes
Investigation	Read-only exploration of the codebase. Can run investigative commands.	No
Browser	Web navigation and interaction via Playwright.	No (browser tools only)
General	A flexible agent for self-contained workspace tasks.	Yes
Planning	Drives Plan mode: investigates and writes a plan. Can run commands but cannot edit files.	No

Dispatching sub-agents

For larger jobs, the main agent can dispatch a sub-agent and incorporate its findings. A single dispatch_agent tool takes an agent_type selecting the target; the built-in types are:

• investigation — explore and report back, without making changes.
• browser — perform a web task.
• coding — hand off a self-contained coding task.
• general — a general-purpose helper.

Custom agents add their names to the agent_type choices, and only the types available in the current session are offered.

When gigacode is enabled, the main agent can also orchestrate many of these sub-agents at once through a workflow — running them in parallel or in pipelines and collecting the results.

Background sub-agents

Dispatch is foreground by default: omitting background or setting it to false waits for the final report. To let the main agent continue independent work, ask it to delegate in the background. The actual dispatch_agent tool arguments are:

{
  "agent_type": "investigation",
  "task": "Inspect the test coverage for authentication and report gaps. Do not edit files.",
  "background": true
}

This returns an immediate receipt with state: "accepted" and a stable job_id, not the report or confirmation of success. Completion, failure, or cancellation is delivered separately. These are agent tool calls, not shell or slash commands. The main agent can inspect or cancel jobs with agent_job:

Operation	Tool arguments
List retained jobs	{"operation": "list"}
Get one job’s status and full report	{"operation": "status", "job_id": "<job_id from receipt>"}
Cancel one job and wait for it to stop	{"operation": "cancel", "job_id": "<job_id from receipt>"}

Reports remain available after completion, including failure and cancellation details. Results arrive automatically, so routine polling is unnecessary. Give each child a self-contained task; avoid concurrent edits to the same files. Background dispatch requires a supported session owner. Only the parent session can launch or manage these jobs—not sub-agents or workflow workers.

In the TUI

• While working: completions enter the main agent’s history at a safe boundary, after tool results, rather than interrupting an in-flight model request.
• While idle: the result appears in the conversation and normally starts an automatic continuation so the main agent can use it without another prompt. Startup, approval/selection screens, or rebuilding can defer delivery.
• Explicit stop (Esc / Ctrl+C): stops the main agent and pauses automatic continuation, but does not cancel background jobs or discard their results. Submit another prompt to resume the main agent; use agent_job to cancel a job.
• Same-session model/mode rebuild: keeps jobs alive and reattaches their completion delivery. Jobs retain their launch configuration and tool resources; switching settings does not reconfigure an already-running child.
• Reset, workspace switch, rewind, or quit: cancels outstanding jobs and waits for them to stop before tearing down their context and shared resources. A workspace switch preserves ordinary conversation history, but archives newly settled old-workspace reports rather than feeding them to the new workspace. Rewind intentionally removes later context; its discarded completions remain acknowledged, so resuming does not inject them again.

Background jobs survive turns, not process exit; they are not a persistent worker service. Their live cards can remain running after the main turn finishes. Use the sub-agent inspector for activity and agent_job for retained reports.

Background execution does not grant extra tools or bypass read-only/tool-scope restrictions. Like foreground sub-agents, children run unattended in Auto permission mode rather than asking for per-tool approval in their transcript.

Per-dispatch model routing

Sub-agent dispatches normally inherit the CLI/host model configuration for the target role. Custom agents continue to use their Markdown model settings and then their normal General-role inheritance. Omit model_override to keep this behavior.

When a particular task needs another model, the agent can call the read-only list_subagent_models tool. It reports configured providers, provider-qualified model IDs, exact effort options, vision support, and current role defaults without exposing credentials. Its model-facing result is a compact Markdown catalog rather than a repetitive JSON payload. The agent should use it before choosing a non-default route rather than guessing model or effort names.

An ordinary dispatch accepts one complete object under model_override:

{
  "agent_type": "investigation",
  "task": "Review the authentication design for subtle security flaws.",
  "model_override": {
    "provider": "anthropic",
    "model": "claude-opus-5",
    "thinking_effort": "high"
  }
}

All three fields are mandatory when the object is present; Kolega Code never inherits only the missing provider, model, or effort. A model with effort controls requires one of the exact thinking_effort strings returned by list_subagent_models. A model without effort controls requires an explicit "thinking_effort": null—null is valid only in that case.

Selections are revalidated at dispatch time. Unsupported provider/model pairs, unconfigured providers, incompatible Browser models, invalid efforts, and incomplete objects fail the dispatch instead of falling back to another model. A Browser dispatch must select a catalog entry with supports_vision: true. A complete dispatch override replaces a custom agent’s Markdown model and effort as a unit.

Gigacode uses the same atomic rule, but names the third field effort inside model_override. Its override applies only to the direct workflow worker; descendants keep their role defaults unless their own dispatch provides a complete override. In Plan mode, model routing never changes the forced read-only Investigation agent or its permissions.

Sub-agent activity is reported live. In the TUI each sub-agent gets a live card in the conversation, and pressing Ctrl+G opens the sub-agent inspector — a full-screen view of every sub-agent’s complete trajectory: its thinking, tool calls, and results. Lifecycle events also appear in the Logs tab. With ask, sub-agent activity surfaces as events (on stderr in plain mode, or as event objects with --json).

Custom agents

You can also define reusable, named specialists as Markdown files. A custom agent runs in a fresh sub-agent context with its own prompt and optional mode, tool, model, effort, and iteration limits, while remaining inside the invoking agent’s permission boundary.

See Custom Agents to create, validate, and invoke project or user definitions.

Modes vs. agents

It’s worth separating two ideas:

• Interaction mode (Build / Plan) is what you toggle with Shift+Tab. It determines whether the agent is editing (Build, the Coder agent) or planning read-only (Plan, the Planning agent).
• Agent type is which specialized agent is doing a piece of work — including sub-agents the main agent dispatches under the hood.

See Build & Plan Modes for the user-facing workflow.