ZacharyZhang-NY
6f31415ed6
The PRD's first acceptance gate now holds: grep -RinE '\bx\.ai\b|grok' crates/ --include='*.rs' → 0 matches (exempt: NOTICE and third-party license archives, README provenance, and the required 'Based on Grok Build Open Source' attribution, now sourced from version_attribution.txt). Wire-visible renames (both sides in this repo, changed in lockstep): - Auth method id 'grok.com' → 'kimi-code' (AuthMethodKind::KimiCode). - Every x.ai/* and _x.ai/* ACP ext method and meta key → kigi/* / _kigi/* (~200 names; grokShell → kigiShell). Session-file replay keeps a read-side alias for the legacy '_x.ai/session/update' method so existing updates.jsonl histories load; writes emit only the new name (both directions test-pinned). - Agent types grok-build* → kigi* with a documented legacy-prefix alias at resolution time so persisted sessions keep resolving. - ToolNamespace/BuiltinAgentName GrokBuild* → Kigi* (wire snake_case kigi/kigi_concise/kigi_hashline; schema regenerated); grok_build implementation dirs renamed to kigi*. - x-grok-* headers → x-kigi-*, __GROK_* sentinels → __KIGI_*, themes grokday/groknight → kigiday/kiginight (old persisted values fall back to the default theme), web_fetch allowlist xAI hosts → kimi.com + moonshot platforms, changelog CDN → this repo, grok-build changelog archives deleted. - BYOK default endpoint removed: [endpoints] api_base_url is now truly optional with NO default — consumers fail fast with the flag name when unset (no silent x.ai egress). Mock harnesses inject it explicitly. - System-prompt identity fixed: 'released by xAI' → 'an unofficial community CLI for Kimi' (template + regenerated encrypted form). Also repaired pre-existing grok-era test debt found by the sweep: the stale trace_classify default-model pin, the grok-pager UA label test, pty-harness stale-binary reuse and non-hermetic moonshot routing (a PTY test could previously reach the real api.moonshot.cn), and the outdated oauth fixture scope key. Gates: §9 grep 0; fmt clean; workspace check/clippy 0/0 (-D warnings); FULL cargo test --workspace: 234 suites, 21,961 passed, 0 failed; deny advisories ok.
307 lines
14 KiB
Markdown
307 lines
14 KiB
Markdown
# Subagents and Personas
|
|
|
|
Subagents are independent child sessions that handle tasks in parallel. Each subagent has its own context window, so the main agent can delegate work (research, implementation, testing, and code review) without consuming its own context. A subagent reports a summary back to the parent when it finishes.
|
|
|
|
Subagents are enabled by default.
|
|
|
|
---
|
|
|
|
## Agents vs Personas
|
|
|
|
Agents and personas both customize behavior, but they operate at different levels:
|
|
|
|
| | **Agents** | **Personas** |
|
|
|---|---|---|
|
|
| **What they configure** | The whole session: model, tools, prompt mode, system prompt | A behavioral overlay added to a subagent's prompt |
|
|
| **Scope** | Primary session or subagent | Subagents only |
|
|
| **How you set them** | At startup, or with agent definitions (`.md` files in `.kigi/agents/` or `~/.kigi/agents/`) | In `config.toml` (`[subagents.personas]`) or `.toml` files under `.kigi/personas/`; applied during subagent resolution |
|
|
| **What they control** | Model, tool availability, prompt body, skills | Tone, output format, task focus, and input/output contracts |
|
|
| **Who edits them** | You -- create, delete, or toggle them in the agents modal or by editing files | You -- define custom personas in config or files; bundled personas are read-only |
|
|
| **Examples** | `kigi`, `explore`, `plan` | `researcher`, `concise` |
|
|
|
|
An agent defines the session itself. A persona shapes how a subagent behaves within a session. A subagent always runs as an agent type (for example, `general-purpose`), and resolution can layer a persona on top.
|
|
|
|
Manage both in the agents modal. Open it with `/config-agents` (alias `/agents`), or open the Personas tab directly with `/personas`. The modal has two tabs: **Agents** and **Personas**.
|
|
|
|
---
|
|
|
|
## Disabling Subagents
|
|
|
|
Disable subagents with an environment variable or the config file:
|
|
|
|
```bash
|
|
export KIGI_SUBAGENTS=0 # Environment variable
|
|
```
|
|
|
|
```toml
|
|
# ~/.kigi/config.toml
|
|
[subagents]
|
|
enabled = false
|
|
```
|
|
|
|
---
|
|
|
|
## How Subagents Work
|
|
|
|
When the main agent identifies work to delegate, it calls the `spawn_subagent` tool to start a child session. The child runs with:
|
|
|
|
- Its own context window, independent of the parent
|
|
- A toolset determined by its agent type and optional capability mode
|
|
- Optional persona instructions applied during resolution
|
|
|
|
The parent receives the child's output -- usually a summary -- when the child finishes.
|
|
|
|
---
|
|
|
|
## Built-in Agent Types
|
|
|
|
The `spawn_subagent` tool accepts a `subagent_type` parameter that selects the child's role:
|
|
|
|
| Type | Description |
|
|
| ----------------- | ---------------------------------------------------- |
|
|
| `general-purpose` | Default type. Full-capability agent for any task. |
|
|
| `explore` | Research agent. Searches, reads, greps, and runs shell commands, but does not edit files. Use it for codebase investigation. |
|
|
| `plan` | Planning agent. Explores the codebase and produces a structured implementation plan; does not edit files. |
|
|
|
|
Project- or user-defined agents can add new types or shadow these built-ins by name.
|
|
|
|
---
|
|
|
|
## Personas
|
|
|
|
A persona is a named behavioral overlay. Its instructions are injected into the subagent's conversation as a `<system-reminder>`, which shapes tone, output format, and task focus without changing the subagent's agent type, model, or tools.
|
|
|
|
Define personas in `config.toml` or in `.toml` files:
|
|
|
|
```toml
|
|
[subagents.personas.researcher]
|
|
instructions = "You are a thorough researcher. Always cite specific file paths."
|
|
description = "Deep investigator."
|
|
```
|
|
|
|
Kigi discovers file-based personas from these locations, in priority order:
|
|
|
|
- `.kigi/personas/*.toml` (project)
|
|
- `~/.kigi/personas/*.toml` (user)
|
|
- The bundled personas directory (lowest priority)
|
|
|
|
Each file defines one persona, and the file name (without the extension) becomes the persona name. Inline `config.toml` personas take precedence over files. Only `.toml` files are discovered.
|
|
|
|
Manage personas in the Personas tab of the agents modal (`/personas`). Bundled personas are read-only; personas you define are editable.
|
|
|
|
> **Note:** Kigi applies personas through subagent resolution and roles, not through a `spawn_subagent` parameter. The main agent does not pass a persona name when it spawns a child.
|
|
|
|
### Persona Fields
|
|
|
|
| Field | Description |
|
|
| ------------------- | ------------------------------------------------------------------- |
|
|
| `instructions` | Inline instruction text applied as the persona layer. |
|
|
| `instructions_file` | Path to an instruction file, loaded at spawn time and merged after `instructions`. |
|
|
| `description` | Short summary shown in the persona catalog. Falls back to the first paragraph of `instructions`. |
|
|
| `inputs` / `outputs`| Declared input and output contract (see below). |
|
|
| `model` | Model override applied when the persona is used. |
|
|
| `reasoning_effort` | Reasoning effort applied when the persona is used. |
|
|
| `default_isolation` | Default isolation mode (`none` or `worktree`). |
|
|
|
|
### Input/Output Contracts
|
|
|
|
A persona can declare the inputs it expects and the outputs it produces. The parent agent reads these to know what context to supply and what artifacts to expect. This lets you chain personas, so one persona's output file becomes the next persona's input:
|
|
|
|
```toml
|
|
[[subagents.personas.reviewer.inputs]]
|
|
name = "review_file"
|
|
io_type = "file"
|
|
required = true
|
|
description = "Path to the code under review"
|
|
|
|
[[subagents.personas.reviewer.outputs]]
|
|
name = "summary_file"
|
|
io_type = "file"
|
|
required = false
|
|
description = "Path to write review notes"
|
|
```
|
|
|
|
Each field has a `name`, an `io_type` (defaults to `file`), a `required` flag, and a `description`.
|
|
|
|
### Persona Resolution
|
|
|
|
When a persona applies, Kigi resolves the effective model and reasoning effort in this order, highest priority first:
|
|
|
|
1. Explicit spawn-time override
|
|
2. Role default
|
|
3. Persona default
|
|
4. Parent session
|
|
|
|
Isolation follows the same order for the first three steps but defaults to `none` (no worktree) rather than inheriting from the parent session.
|
|
|
|
If a persona is requested but cannot be resolved -- it is not found, has no instructions, or its `instructions_file` is unreadable -- the spawn fails.
|
|
|
|
---
|
|
|
|
## Spawning Subagents
|
|
|
|
The main agent calls the `spawn_subagent` tool. Its parameters:
|
|
|
|
| Parameter | Description |
|
|
| ----------------- | ---------------------------------------------------------------- |
|
|
| `prompt` | The full task prompt for the subagent. |
|
|
| `description` | A short label for the task (3-5 words). |
|
|
| `subagent_type` | The agent type to launch. Defaults to `general-purpose`. |
|
|
| `background` | Run the subagent in the background and return immediately with a subagent ID. Defaults to `false`. |
|
|
| `capability_mode` | Restrict the subagent's tools: `read-only`, `read-write`, `execute`, or `all`. |
|
|
| `isolation` | `none` (shared workspace, the default) or `worktree` (isolated git worktree). |
|
|
| `resume_from` | Continue a completed subagent's conversation. Pass its subagent ID. |
|
|
| `cwd` | Working directory for the subagent. Mutually exclusive with `isolation: worktree`; ignored when `resume_from` is set (the resumed child inherits its source's directory). |
|
|
|
|
When you run a subagent in the background, retrieve its result later with `get_command_or_subagent_output`.
|
|
|
|
---
|
|
|
|
## Capability Modes
|
|
|
|
A capability mode is an optional, coarse filter on a subagent's tools:
|
|
|
|
| Mode | Read | Write | Execute | Description |
|
|
| ------------ | ---- | ----- | ------- | -------------------------------------------- |
|
|
| `read-only` | Yes | No | No | Read, search, and inspect (also web search and LSP); no file edits or shell. |
|
|
| `read-write` | Yes | Yes | No | Read, plus create, edit, delete, and move files. No shell. |
|
|
| `execute` | Yes | No | Yes | Read, plus run shell commands and background tasks. No file edits. |
|
|
| `all` | Yes | Yes | Yes | Unrestricted tool access. |
|
|
|
|
If you omit `capability_mode`, the subagent uses its agent type's toolset. The built-in `explore` and `plan` types read, search, and run shell commands but cannot edit files; `general-purpose` ships the full toolset.
|
|
|
|
---
|
|
|
|
## Context Inheritance
|
|
|
|
### resume_from
|
|
|
|
The `resume_from` parameter lets a new subagent continue where a completed subagent left off, which is useful for multi-stage workflows:
|
|
|
|
1. Spawn a research subagent to investigate a problem.
|
|
2. Spawn a second subagent with `resume_from` set to the first subagent's ID, so it picks up with the full research context.
|
|
|
|
The new subagent inherits the source's transcript, tool state, and model; its system prompt and tools are re-rendered from the current agent definition. The source must be completed (not running), belong to the current session, and use the same agent type.
|
|
|
|
---
|
|
|
|
## Isolation: Worktree Mode
|
|
|
|
For tasks that modify files, run a subagent in an isolated git worktree with `isolation: worktree`. This keeps the child's edits from conflicting with the parent's:
|
|
|
|
- The subagent works in its own copy of the working tree.
|
|
- Its changes stay isolated from the parent until you merge them.
|
|
- The subagent's result includes the worktree path.
|
|
|
|
Kigi manages worktrees through the `x.ai/git/worktree/*` extension methods, including an apply operation that merges changes back into the main working directory.
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
### Per-Type Toggles and Model Overrides
|
|
|
|
Disable specific agent types, or route them to a different model:
|
|
|
|
```toml
|
|
[subagents.toggle]
|
|
explore = true # default -- omit to keep enabled
|
|
plan = false # disable the plan subagent
|
|
|
|
[subagents.models]
|
|
explore = "kigi" # route explore to a specific model
|
|
```
|
|
|
|
Per-type model overrides apply for any parent. Without an override, a subagent inherits the parent's model.
|
|
|
|
### Custom Roles and Personas
|
|
|
|
Define custom roles with their own capability and model defaults:
|
|
|
|
```toml
|
|
[subagents.roles.researcher]
|
|
description = "Deep research agent"
|
|
default_capability_mode = "read-only"
|
|
model = "kigi"
|
|
prompt_file = ".kigi/prompts/researcher.md"
|
|
```
|
|
|
|
Define custom personas with behavioral instructions:
|
|
|
|
```toml
|
|
[subagents.personas.concise]
|
|
instructions = "Be concise. No filler words."
|
|
# instructions_file = ".kigi/personas/concise.md" # or load from a file
|
|
```
|
|
|
|
Kigi also discovers roles from `.kigi/roles/*.toml` and personas from `.kigi/personas/*.toml`. Inline `config.toml` definitions take precedence over files.
|
|
|
|
---
|
|
|
|
## The Tasks Pane (TUI)
|
|
|
|
Kigi shows running and finished work in side panes on the agent screen:
|
|
|
|
- Press `Ctrl+B` to toggle the tasks pane, which lists active and completed subagents and background commands with their status.
|
|
- Press `Ctrl+T` to toggle the separate todo pane.
|
|
|
|
To view the available agent types and personas, open the command palette with `Ctrl+P` and choose **Manage Agents** (`/config-agents`).
|
|
|
|
Subagents appear at the top of the tasks pane in their own collapsible "Subagents" group.
|
|
|
|
---
|
|
|
|
## Viewing Subagents in the TUI
|
|
|
|
Subagents appear in several places in the interactive TUI:
|
|
|
|
### Scrollback (parent conversation history)
|
|
|
|
When a subagent is spawned, a compact lifecycle block is added to the *parent's* scrollback:
|
|
|
|
- `Subagent running: "do the thing" (Implementer · kigi-3) — Thinking`
|
|
- Or for background subagents: `Subagent started: "..."`
|
|
|
|
While running, the block shows a live activity suffix (e.g. "Running: cargo test", "Compacting", "Retrying (2/3)") pulled from the child's turn tracker. The bullet animates (or is colored) according to state.
|
|
|
|
Press **Enter** (or Ctrl-F) on the block to open the subagent's full transcript.
|
|
|
|
For blocking subagents the single entry updates its bullet color when the child finishes. For background ones, a follow-up `Subagent completed/failed/cancelled in Xs: "..."` block is appended.
|
|
|
|
### Tasks pane (Ctrl+B)
|
|
|
|
As noted above — grouped under "Subagents", with spinners, elapsed times, and quick access to kill or inspect.
|
|
|
|
### Fullscreen framed view (the child transcript)
|
|
|
|
When you open a subagent (from a scrollback block or the tasks pane), the parent view is replaced by a bordered frame containing the child's full transcript:
|
|
|
|
- Title bar inside the frame: status icon (spinner / ✓ / ✗), label + bold description + model, optional "resumed"/"forked" badge, live activity · elapsed time, and [✗] close button.
|
|
- The child's own scrollback, thinking, tool calls, and (limited) prompt area render inside the frame.
|
|
- Subagent views are largely observational — you generally cannot send new top-level prompts directly to them the way you can a parent session.
|
|
|
|
Use `q`, `Esc`, or click the close button to pop back to the parent view. The parent's scrollback continues to show the subagent's status.
|
|
|
|
---
|
|
|
|
## Depth Limits
|
|
|
|
Only the top-level session spawns subagents. A subagent cannot spawn its own subagents: the maximum nesting depth is one. If a subagent calls `spawn_subagent`, the call fails with a depth-limit error. This keeps the agent tree flat and prevents runaway spawning.
|
|
|
|
---
|
|
|
|
## When to Use Subagents
|
|
|
|
**Good use cases:**
|
|
|
|
- Researching a codebase while the parent continues other work
|
|
- Running tests in parallel while the parent implements changes
|
|
- Reviewing generated changes before you commit them
|
|
- Delegating independent tasks that do not depend on each other
|
|
|
|
**When not to use:**
|
|
|
|
- Simple tasks that the parent can handle directly
|
|
- Tasks that require tight back-and-forth with the user, since a subagent runs autonomously and isn't suited to interactive exchanges
|
|
- Tasks where the context setup cost exceeds the parallelism benefit
|