kiki-agent-lite 0.3.1 → 0.3.2

package/dist/docs/en/customization/agents.md

@@ -1,10 +1,10 @@
 # Agents and Sub-Agents
 
-Every session in Kiki is driven by a **main Agent**. The main Agent understands the user's intent, plans steps, calls tools, and when needed dispatches **sub-agents** to handle more focused sub-tasks — for example, exploring an unfamiliar codebase, reviewing multiple implementations in parallel, or planning a large refactor without touching the main context.
+Every session is driven by a **main agent**, which follows your intent, plans steps, calls tools, and dispatches **sub-agents** for focused sub-tasks — exploring an unfamiliar codebase, reviewing several implementations in parallel, or planning a large refactor without filling the main context.
 
-A sub-agent receives a task description from the main Agent, works in its own isolated context, and then returns its conclusions. It does not communicate with the user directly, and its intermediate reasoning and tool call records do not mix into the main Agent's history.
+A sub-agent receives a task description, works in its own context, and returns its conclusions. It does not talk to you directly, and its intermediate reasoning and tool records stay out of the main agent's history.
 
-New to Kiki's agent system? Start with [Agent profiles: concepts and design](./agent-profiles.md) — it explains what a profile is, where the files live, and when changes take effect. This page is the field and behavior reference.
+For what a profile is and where its file lives, start with [Agent profiles: concepts and design](./agent-profiles.md). This page is the field and behavior reference.
 
 ## Built-in Sub-Agents
 
@@ -13,96 +13,122 @@ Fresh installations include the main `agent` profile and two subagent profiles:
 - **`general`**: The default subagent — a general-purpose assistant that can read and write files, execute commands, and search code, without dispatching more children.
 - **`explore`**: Dedicated to read-only codebase exploration, searching, and summarizing.
 
-Two more profiles are available as **optional examples**, not preinstalled roles: `implementer` owns an engineering task through verification and handoff; `reviewer` independently checks a decision or finished work as a read-only leaf. The GUI's first-run `/kiki-ops` conversation asks about each separately. Only if you agree, the built-in `kiki-profile` skill supplies its complete template and the agent creates that role at `$KIKI_HOME/agents/<role>.md` (default `~/.kiki/agents/`). It checks for an existing file rather than overwriting it silently. Both templates explicitly set `model_alias: inherit`, so the created role follows the parent agent's model at dispatch time without fixing a provider or a particular model. They leave `thinking_effort` unset; you can switch either role to a fixed model later in Settings.
+Two more roles are available to create on request rather than preinstalled: `implementer` owns an engineering task through verification and handoff, and `reviewer` independently checks a decision or finished work as a read-only leaf. Ask for one in conversation (the GUI's first-run `/kiki-ops` conversation offers both) and the `kiki-profile` skill writes the role to `$KIKI_HOME/agents/<role>.md` (default `~/.kiki/agents/`), leaving an existing file alone. Both templates set `model_alias: inherit`, so the role follows whatever model the parent agent is using, and leave `thinking_effort` unset — you can pin either role to a model later in Settings.
 
-The top-level [`skip_builtin_profile_installation`](../configuration/config-files.md#top-level-fields) setting skips installing named built-in templates under `agents/builtin/`. It does not disable or delete existing copies. To hide installed profiles from subagent discovery and dispatch, use `disabled_named_profiles`; the default main `agent` binding remains available.
+[`skip_builtin_profile_installation`](../configuration/config-files.md#top-level-fields) skips installing the named built-in templates under `agents/builtin/`, leaving copies that are already there. To hide installed profiles from discovery and dispatch, use `disabled_named_profiles` — the main `agent` binding stays available either way.
 
-## How to Invoke
+## How to invoke
 
-Sub-agents are scheduled automatically by the main Agent — based on task complexity, context consumption, and sub-task independence, they are dispatched at the right moment without the user having to specify one.
+The main agent dispatches sub-agents on its own as the work calls for it, and you can also ask for a specific one: "Use explore to map out the relevant files before making any changes."
 
-Each dispatch is presented in the terminal as an approval request (unless it matches an allow rule or YOLO mode is active), giving you a chance to review the task description. You can also instruct the main Agent directly in conversation to use a specific sub-agent, for example: "Use explore to map out the relevant files before making any changes."
-
-Sub-agents support running in the background: results are automatically returned to the main Agent upon completion, with no manual polling needed. You can also call back an existing sub-agent instance to continue the same task.
+Each dispatch appears as an approval request unless it matches an allow rule or YOLO mode is active, so you can read the task description before it runs. A sub-agent can run in the background and returns its result to the main agent on completion; you can also resume an existing sub-agent to continue the same task.
 
 ## Named child agents
 
-The default v2 engine (Kiki desktop and `kiki` CLI/TUI) gives the main `agent` profile three child-agent tools with no experiment flag: `AgentRun`, `AgentList`, and `AgentSend`. Built-in subagent profiles do not receive them. Each caller can list and message only the children it created directly; a grandchild or another caller's child is not a valid target.
+The main `agent` profile gets three child-agent tools with no experiment flag: `AgentRun`, `AgentList` and `AgentSend`. Built-in subagent profiles do not. Each caller sees only the children it created itself — a grandchild or another caller's child is not a valid target.
 
-`AgentRun` launches a new child or continues an existing one. Every call requires `prompt` and a short 3–5 word `description` for UI display. New launches can also set `profile` (when omitted, an explicitly configured `[subagent].default_profile` selects that profile; if the key is absent, the built-in general-purpose subagent prompt is used; an explicit blank value requires a target), `profile_file` (an explicit subagent role Markdown file, absolute or workspace-relative; it is a role definition, not a shared prompt template, and is mutually exclusive with `profile`, `route`, and `resume`), `route`, `name`, `background`, `model_alias`, and `effort`. The `allow_model_change` flag is meaningful only on `resume` with an explicit `model_alias`; it is required when that alias resolves to a different canonical model. Pass `name` when you expect to address the same child again; names must match `^[a-z0-9_]+$`, cannot be `root`, and stay unique for the session. To continue a direct child, set `resume` to its name or agent id; it rejects `name`, `profile`, `profile_file`, and `route`. Omit `effort` to keep the saved effort, or pass it to apply on the next idle run. Omit `model_alias` to keep the saved model; changing it to a different canonical model requires `allow_model_change: true`, while an alias resolving to the same canonical model is a no-op. Explicit `preferred_models`, `discouraged_models`, `preferred_efforts`, and route/caller-lease pins are soft: a hard-permitted executable override continues with a structured advisory. `allowed_models`, `deny_models`, and `allowed_efforts` are hard in every scope and reject violations. Machine `[subagent].deny_models`, missing or unsupported model capabilities, route identity, model-change confirmation, and executor/thread restrictions remain hard errors. An external executor that does not support changing a resumed thread binding returns an error instead of recreating the thread or executor. A new launch selects its model in order: concrete `model_alias` parameter → effective profile, route, or caller-lease pin → explicitly configured `[subagent].default_model`. With none of these sources, it fails with `model.not_configured` and no child is created. Effort resolves separately through tool `effort` → profile `thinking_effort` → the bound model's own default. An unknown `model_alias` is an error. Omitting `background` runs in background when the caller is main and waits in foreground when the caller is a subagent. Explicit `true` always selects background and explicit `false` always selects synchronous waiting; the same caller-based rule applies to `resume` and goal mode. Agent tasks time out after 2 hours by default; configure the global limit through `[subagent] timeout_ms` or `KIKI_SUBAGENT_TIMEOUT_MS` (`0` disables it), and print mode defaults to no timeout. There is no per-call timeout or arbitrary provider-parameter passthrough.
+`AgentRun` launches a new child or continues an existing one. Every call needs `prompt` and a short 3–5 word `description` for the UI. A new launch can also set:
 
-Background launch requires `TaskList`, `TaskOutput`, and `TaskStop`. When those tools are disabled, main's omitted `background` is rejected before launch, not changed to foreground; enable the tools or set `background:false` for a genuine same-turn dependency. During main foreground waiting, steer / Send now moves the child to background without cancelling it, allowing the next safe step to read the new input; completion still notifies the parent automatically. Ordinary queued messages do not release the wait. Detached children are not cancelled merely because the main turn stops; use `TaskStop` for explicit child cancellation. Subagents must settle their own dependencies before returning their final receipt. See the [`AgentRun` reference](../reference/tools.md#collaboration-tools).
+| Parameter | Notes |
+| --- | --- |
+| `profile` | Which subagent role to run. Omitted, an explicitly configured `[subagent].default_profile` applies; with no such key the built-in general-purpose subagent is used. An explicit blank value requires a target. |
+| `profile_file` | A subagent role Markdown file, absolute or workspace-relative. It is a role definition rather than a shared prompt template, and cannot be combined with `profile`, `route` or `resume`. |
+| `route` | A named route of the base profile. |
+| `name` | A handle for addressing this child again: `^[a-z0-9_]+$`, not `root`, unique within the session. |
+| `background` | Omitted, main runs it in the background and a subagent waits in the foreground. `true` and `false` force background and synchronous waiting respectively. |
+| `model_alias`, `effort` | Omitted, the saved or default values are kept. |
 
-For `AgentRun` model choices, a profile's menu is not exhaustive while `restrict_models_to_menu` is off (the default). When it is on, only the profile author's original default `model_alias` and `model_profiles` menu entries are selectable, subject to all other hard rules and execution capabilities. Route / caller-lease pins and explicit `model_alias` arguments cannot add candidates. An out-of-menu selection is rejected without falling back; `resume` and `allow_model_change: true` do not expand the frozen menu. See [Model menus and hard boundaries](./agent-profiles.md#model-menus-and-hard-boundaries).
+To continue a direct child, set `resume` to its name or agent id; it rejects `name`, `profile`, `profile_file` and `route`. `allow_model_change` only matters on `resume` with an explicit `model_alias` that resolves to a different canonical model.
 
-`profile_file` supplies a role definition directly, without preset registration or matching its file name against preset allow/deny lists. `allowed_subagents: []` still permits this path; `can_spawn_subagents: false` blocks all new children. Absolute or workspace-relative paths are accepted, and the real path after resolving links must remain inside an allowed directory.
+A new launch picks its model from the concrete `model_alias` parameter, then the effective profile, route or caller-lease pin, then an explicitly configured `[subagent].default_model`. With none of those it fails with `model.not_configured` and no child is created, and an unknown alias is an error. Effort resolves separately, from the tool call, the route, the caller lease, the profile, or the model itself — [the full order is below](#named-profile-routes-experimental). Omitted `model_alias` and `effort` on `resume` keep the saved binding; an alias resolving to the same canonical model is a no-op, and a different one needs `allow_model_change: true`.
 
-`AgentList` returns direct children. Default `include_finished=false` lists running children and children with no tracking task; pass `true` when you need children whose latest background task has already finished or failed. At most 50 entries are returned, running first.
+`preferred_models`, `discouraged_models`, `preferred_efforts` and route or caller-lease pins are soft: a hard-permitted override runs with a structured advisory. `allowed_models`, `deny_models` and `allowed_efforts` are hard in every scope. Machine `[subagent].deny_models`, unsupported model capabilities, route identity, a missing model-change confirmation and executor or thread restrictions are hard errors, and an external executor that cannot change a resumed thread binding returns an error rather than recreating the thread or executor.
 
-`AgentSend` queues a mailbox message that is delivered as early as possible: when the child is running, the message is steered into its active turn at the next step boundary; when the child is idle and resumable, it starts a new run with the message, whose completion notifies the parent like any other agent task. Address the child by `name` or agent id.
+Agent tasks time out after 2 hours by default; set the global limit with `[subagent] timeout_ms` or `KIKI_SUBAGENT_TIMEOUT_MS` (`0` disables it). Print mode has no timeout, and there is no per-call timeout or provider-parameter passthrough.
 
-`AgentNotify` runs in the opposite direction and is available only to subagents: it queues a fire-and-forget message in the parent agent's mailbox, injected into the parent's active turn at the next step boundary (or read when the parent next runs). The main agent has no parent and never receives this tool. The switch `[agents] notify_parent = false` in `config.toml` turns it off globally; it defaults to on.
+Background launch needs `TaskList`, `TaskOutput` and `TaskStop`. With those disabled, an omitted `background` from the main agent is rejected before launch rather than turned into a foreground wait — enable the tools, or pass `background: false` for a genuine same-turn dependency. While main waits in the foreground, steer or **Send now** moves the child to the background without cancelling it, so the next safe step can read the new input and the completion still notifies the parent. Ordinary queued messages do not release that wait. A child is not cancelled just because the main turn stops; use `TaskStop` to cancel one explicitly. See the [`AgentRun` reference](../reference/tools.md#collaboration-tools).
 
-## Peer-thread communication
+For `AgentRun` model choices, a profile's menu is a candidate list rather than a closed set while `restrict_models_to_menu` is off (the default). When it is on, only the profile author's default `model_alias` and `model_profiles` entries are selectable, and an out-of-menu pick is rejected rather than replaced. See [Model menus and hard boundaries](./agent-profiles.md#model-menus-and-hard-boundaries).
 
-Peer-thread communication lets the main Agent coordinate existing Kiki sessions on the same local host, including sessions in other workspaces. It is separate from the child-agent tools above and is disabled by default. After opting in, the four tools `ThreadList`, `ThreadRead`, `ThreadSend`, and `ThreadWait` are available on a session's main Agent. Subagents do not get them by default; a subagent can be given `ThreadList`, `ThreadRead`, and `ThreadWait` by naming them in its profile's `tools` list, while `ThreadSend` stays main-only because it sends under the parent session's peer identity. To create an independent session, main agents can use [`ThreadCreate`](../reference/tools.md#collaboration-tools) without enabling peer-thread communication.
+`profile_file` supplies a role definition directly, bypassing preset registration and preset allow/deny matching. `allowed_subagents: []` still permits this path, while `can_spawn_subagents: false` blocks all new children. Absolute or workspace-relative paths work, and the real path after resolving links must stay inside an allowed directory.
 
-A thread reference identifies a host, workspace, and session. `ThreadList` returns the references needed for later calls; `ThreadRead` reads completed main-Agent turns without resuming a cold session; `ThreadSend` derives the source from the current main-Agent session and durably accepts a peer-attributed message for another thread; and `ThreadWait` waits for activity from up to eight threads for at most 60 seconds. Messages cannot cross hosts.
+`AgentList` returns direct children. By default it lists running children and children with no tracking task; pass `include_finished: true` to also get children whose latest background task has already finished or failed. At most 50 entries come back, running ones first.
 
-True peer attribution requires the source thread's main Agent to call `ThreadSend`. REST and the `global.threads` Klient facade accept only target-addressed input and record it as user-origin, so an external client cannot claim a source thread.
+`AgentSend` queues a mailbox message: a running child has it steered into its active turn at the next step boundary, and an idle, resumable child starts a new run with it, whose completion notifies the parent like any other agent task. Address the child by `name` or agent id.
 
-Set `[thread_communication] enabled = true` in `config.toml` to opt in globally. Sending a message can resume a cold target session and consume model quota. Integrators can also persist an enable or disable override for an individual workspace; a workspace override cannot turn the feature on while the global switch is off. See [Server API](../server/rest-api.md#session-leases-and-peer-threads) for those interfaces.
+`AgentNotify` goes the other way and is available only to subagents: it queues a fire-and-forget message in the parent agent's mailbox, read at the parent's next step boundary or next run. The main agent has no parent and never receives it. `[agents] notify_parent = false` in `config.toml` turns it off globally; it is on by default.
 
-## Context Isolation and Resource Cost
+## Peer-thread communication
 
-Each sub-agent has a fully independent context window. It can only see the task description explicitly passed by the main Agent and cannot see the main Agent's conversation history. The sub-agent's own intermediate reasoning and tool call records do not flow back; only the final result appears in the main Agent's context.
+Peer-thread communication lets a main agent coordinate other Kiki sessions on the same local host, including sessions in other workspaces. It is separate from the child-agent tools above and is off by default. Once enabled, a session's main agent gets `ThreadList`, `ThreadRead`, `ThreadSend` and `ThreadWait`. Subagents do not get them by default; a subagent profile can name `ThreadList`, `ThreadRead` and `ThreadWait` in its `tools` list, while `ThreadSend` stays main-only because it sends under the parent session's peer identity. To create an independent session instead, main agents can use [`ThreadCreate`](../reference/tools.md#collaboration-tools) without enabling anything.
 
-This isolation provides two benefits:
+A thread reference identifies a host, workspace and session. `ThreadList` returns the references later calls need, `ThreadRead` reads completed main-agent turns without resuming a cold session, `ThreadSend` derives the source from the current main-agent session, and `ThreadWait` waits up to 60 seconds for activity from up to eight threads. Messages cannot cross hosts.
 
-- **The main Agent's context stays lean** and is not filled with large volumes of exploratory logs during long sessions.
-- **Multiple sub-agents can run in parallel** without interfering with each other.
+A message is recorded as coming from a peer only when the source thread's own main agent calls `ThreadSend`. REST and the `global.threads` Klient facade take target-addressed input only and record it as user-origin, so an external client cannot claim a source thread.
 
-Note that each sub-agent independently consumes model tokens. For simple tasks, there is no need to dispatch a sub-agent — the main Agent handles them more economically.
+Set `[thread_communication] enabled = true` in `config.toml` to opt in globally. Sending can resume a cold target session and consume model quota. A workspace can persist an enable or disable override, but it cannot turn the feature on while the global switch is off. See [Server API](../server/rest-api.md#session-leases-and-peer-threads) for those interfaces.
 
-## Permission Inheritance
+## Context Isolation and Resource Cost
+
+A sub-agent sees only the task description it was given, never the main agent's conversation, and only its final result comes back. Two things follow from that: the main context stays readable during a long session, and several sub-agents can run in parallel without interfering.
+
+Each sub-agent spends its own tokens, so a small task is cheaper to do in the main agent.
 
-Sub-agent permission rules are inherited from the main Agent: "always allow" rules that the main Agent has accepted via `/permission` or through an approval dialog automatically propagate to all sub-agents it dispatches, so sub-agents do not need to re-approve the same types of tool calls. The `AgentRun` tool itself is allowed by default, enabling the main Agent to delegate multiple times without interrupting the user.
+## Permission inheritance
 
-If you need a particular type of tool to be permanently unavailable inside sub-agents, tighten the corresponding permission rule on the main Agent.
+Sub-agents inherit the main agent's permission decisions: an "always allow" rule you accepted through `/permission` or an approval dialog applies to everything that agent dispatches, so the same tool call is not re-approved each time. `AgentRun` itself is allowed by default, so the main agent can delegate repeatedly without interrupting you.
 
-## Custom Agents
+To keep a tool permanently out of sub-agents, tighten the matching permission rule on the main agent.
 
-Beyond the shipped profiles, you can define your own agents as Markdown files. Each file describes one agent: the frontmatter (YAML metadata at the top of the file) declares its name, description, and tool access, and the file body is its system prompt. Custom agents can be delegated to as sub-agents — the main Agent discovers them automatically alongside the built-in ones — or selected as the main Agent at startup.
+## Custom agents
+
+Your own agents are Markdown files. The frontmatter declares the name, description and tool access; the body is the system prompt. Kiki discovers them next to the built-ins, and they can be dispatched as sub-agents or selected as the main agent at startup.
 
 ### Capability visibility
 
-The GUI's main-agent selector uses the effective profiles for the current workspace or working directory. Main profiles have `main: true`. A file overriding a built-in profile inherits its `main` value when omitted; an explicit `main: false` is preserved. `SYSTEM.md` therefore retains the default `agent` profile's main-agent status without extra frontmatter. Removing the default profile from subagent discovery does not remove its main binding or discard its effective file overrides. Other disabled profiles remain unavailable. See [Agent file format](#agent-file-format) for the field definitions.
+The GUI's main-agent selector lists the profiles effective for the current workspace or working directory. Main profiles carry `main: true`; a file that overrides a built-in inherits that value when it omits it, and an explicit `main: false` is kept. `SYSTEM.md` therefore stays a main-agent profile with no extra frontmatter, and hiding the default profile from subagent discovery does not remove its main binding or its file overrides. See [Agent file format](#agent-file-format) for the fields.
 
-In **Settings → Agents**, select a workspace to inspect its default main profile, effective source, and subagent capabilities. File-backed profiles can be edited at their displayed source; editing common fields in a legacy `SYSTEM.md` adds frontmatter while preserving the prompt body. A selected profile that later becomes unavailable stays visible with a diagnostic so you can choose another.
+In **Settings → Agents**, pick a workspace to inspect its default main profile, the source in effect, and the subagent capabilities. File-backed profiles can be edited where they are shown; editing a legacy `SYSTEM.md` adds frontmatter and keeps the prompt body. A selected profile that later becomes unavailable stays visible with a diagnostic, so you can pick another.
 
 ### Profile reloads and live sessions
 
-Agent files are watched and reloaded on change. A reload never breaks a live session: an agent already running or resumed keeps the prompt and constraint snapshot it was bound with, even if its profile is edited, made `private`, deleted, or becomes invalid. Frozen dispatch lists skip invalid targets instead of failing the whole conversation. Changes apply to **new** dispatches only — a new dispatch to a private or deleted profile fails with an explicit error. Restoring an old record whose profile is gone and has no recoverable binding snapshot falls back to the default profile with a warning; model, effort, and executor are still validated.
+Agent files are watched and reloaded on change, and a reload never breaks a live session: an agent already running or resumed keeps the prompt and constraint snapshot it was bound with, even if its profile is edited, made `private`, deleted or made invalid. Your edit therefore applies to **new** dispatches only, and dispatching to a private or deleted profile fails with an explicit error. A frozen dispatch list skips an invalid target instead of failing the whole turn. Restoring an old record whose profile is gone falls back to the default profile with a warning, after checking its model, effort and executor.
+
+### Choosing the engine and its profile
+
+The control at the left of the composer's status line answers one question — what runs this session — in one panel. Kiki itself is the first entry; each external engine follows, and under each engine sit that engine's own main profiles. The first row of every engine is that harness **as it is**: no Kiki profile, no Kiki prompt, no injected tools, and the harness's own model, effort and approval mode. Picking a profile under an engine takes both at once, so the two halves can never disagree.
+
+The model control beside it stays separate on purpose. A model is a choice *within* the engine you picked, not a third axis of the same question, and on a bare engine it belongs to the harness: Kiki reports what the session resolved without offering to change it.
+
+A new session applies its pick immediately. In a session that has already spoken, the change takes effect from your next message, and picking a different engine asks once first. The confirmation answers the two things you are actually unsure about: the new engine starts a context of its own — Kiki does not hand it the old conversation and does not resume the old engine's session — while the conversation itself stays in Kiki, complete and readable. A turn that is already running finishes on the current engine, and the chip marks the pick as pending until the next message carries it.
+
+**What Kiki adds when an engine runs** in **Settings → AI → External engines** sets the defaults for that engine across every session that does not override them: which Kiki tool groups and hooks the harness can reach, whether it can dispatch Kiki subagents, and how the profile prompt is delivered. Leaving everything there off is the same as choosing the bare row in the composer, so a harness you already trust runs exactly as its own CLI would.
+
+### Direct external execution
+
+A harness chooses the execution program; a profile is optional customization, and a model is a choice within that harness. With the main-agent [REST execution selection](../server/rest-api.md#sessions), omit `profile` to run the external program directly. Without session overrides or [harness defaults](../configuration/config-files.md#external-harness-defaults), Kiki sends no profile prompt, cognition, shared fields, memory, hooks or MCP tools and does not set model, effort, approval mode or Codex sandbox policy. Native execution without a profile keeps its existing Kiki defaults.
+
+Direct execution preserves the configured launch environment, home and working directory, but the program must resolve to the same executable and settings sources as the CLI you expect. An ACP adapter may launch an SDK-provided binary or a configured override instead of the CLI on PATH; omitting a profile does not make those programs identical. An unknown login observation alone does not prevent launch.
 
 ### External ACP profile delivery
 
-For an outbound ACP (Agent Client Protocol) executor, Kiki sends the frozen profile as a system prompt only when that harness is configured to accept the `session/new` extension `_meta.systemPromptOverride`. The built-in `grok-acp` executor enables this by default. Other ACP executors keep the profile in the first user-message preamble. To opt in a custom harness that supports the extension, add `profile_delivery = "system_prompt_override"` to its `[agent_executors.<id>]` entry in `config.toml`; do not enable it for a harness that ignores the extension, because Kiki then omits the user-message fallback.
+For an outbound ACP (Agent Client Protocol) executor, Kiki sends the frozen profile as a system prompt only when that harness accepts the `session/new` extension `_meta.systemPromptOverride`. The built-in `grok-acp` executor enables this; other ACP executors get the profile in the first user-message preamble. Add `profile_delivery = "system_prompt_override"` to a custom harness's `[agent_executors.<id>]` entry in `config.toml` to opt it in — only for a harness that honours the extension, since Kiki then omits the preamble fallback.
 
-The override applies when a **new remote session** is created, not on `session/resume` or `session/load`. An existing remote session keeps its original profile delivery mode, including when you change this executor setting. A new dispatch with a changed frozen profile starts a new remote session; if reconnecting fails and Kiki creates a new session instead, it sends the override again along with a bounded conversation handoff. Kiki does not send `_meta.rules` or `_meta.agentProfile` as part of this setting. Since a system-prompt override can replace a harness's default system prompt, only opt in when that replacement is appropriate for your harness.
+The override applies when a **new remote session** is created, not on `session/resume` or `session/load`, and an existing remote session keeps whichever mode it started with. Legacy profile-only dispatches include a bounded conversation handoff when a remote session must be recreated. The main-agent `execution` path does not send old Kiki history on a generation change or reconnect fallback. Because a system-prompt override can replace a harness's default system prompt, opt in only when that replacement suits the harness.
 
-The built-in `kimi-acp` executor forwards configured MCP servers to Kimi Code. Kimi CLI versions from `0.37.0` up to, but not including, `0.39.0` reject ACP stdio MCP servers; preflight warns that MCP tools will fail and recommends upgrading to `0.39.0` or newer. The warning does not block forwarding. If the version cannot be detected, Kiki forwards the servers without this version warning.
+For legacy profile-only bindings, the built-in `kimi-acp` executor forwards configured MCP servers to Kimi Code; the `execution` path does not automatically forward workspace MCP. Kimi CLI versions from `0.37.0` up to, but not including, `0.39.0` reject ACP stdio MCP servers, so preflight warns that MCP tools will fail and recommends upgrading to `0.39.0` or newer. The warning does not block forwarding, and an undetectable version is forwarded without it.
 
 ### External main-agent delegation
 
-An external executor can run as the main agent. To let it dispatch Kiki subagents, add `allow_kiki_subagents: true` to its profile and bind that profile to the main agent. The flag defaults to `false`; it does not enable delegation from external child agents.
+An external executor can run as the main agent. To let it dispatch Kiki subagents, add `allow_kiki_subagents: true` to its profile and bind that profile to the main agent. The main-agent `execution` path can also set it in session overrides or [harness defaults](../configuration/config-files.md#external-harness-defaults); an omitted profile field inherits those defaults. Without an explicit value it is `false`, and it does not enable delegation from external child agents.
 
-Kiki attaches its MCP tools (the bridge through which a harness calls Kiki) to the **existing session**, without creating a separate seat session. The harness must support local stdio MCP, and `kiki` must be available to its process. The profile's spawn switch, preset permissions and preferences, model constraints, and parent-notification policy still apply. Rebind the main profile after changing the flag; an existing binding retains its frozen snapshot. Disabling delegation on the bound main profile or closing the executor revokes its bridge.
+Kiki attaches its MCP tools (the bridge through which a harness calls Kiki) to the **existing session**, without creating a separate seat session. The harness must support local stdio MCP and have `kiki` on its path. The profile's spawn switch, preset permissions and preferences, model constraints and parent-notification policy still apply. Rebind the main profile after changing the flag — an existing binding keeps its frozen snapshot — and the bridge is revoked by disabling delegation or closing the executor.
 
-Child completion is queued back to the same main agent without blocking the child. If the main agent is busy, delivery waits until its turn settles; if it is idle, the queued receipt wakes it. Parent notifications use the same conversation and remain subject to `allow_parent_notify` and the configured notification policy.
+A child's completion is queued back to the same main agent without blocking the child: if the main agent is busy, delivery waits for its turn to settle; if it is idle, the receipt wakes it. Parent notifications use the same conversation and remain subject to `allow_parent_notify` and the configured notification policy.
 
 Codex app-server MCP tool calls can require a separate vendor approval, mapped to Kiki's persistent approval interaction. Manual or auto mode (`on-request`) lets you answer it. In Full access (YOLO), Kiki pre-approves only its attached `kiki-harness` MCP server at the Codex layer; Kiki's own capability and execution policies still govern those calls. Other MCP servers keep their approval policy, and the workspace-write sandbox is not widened.
 
-External interaction support depends on the harness's negotiated capabilities. ACP historical forks use `session/fork` when available; exact assistant-message positions additionally require the AIR fork-point extension supported by the Claude, Codex, or DeepSeek adapters. Unsupported positions use a new remote session with a bounded conversation handoff, never continue the source remote session. Codex and DeepSeek ACP form questions use Kiki's persistent question interaction; unsupported complex forms and URL-mode requests are declined. Grok's plan approval uses the persistent plan-review interaction. These mappings do not turn a harness's unsupported feature into a native one.
+What works with an external harness depends on the capabilities it negotiated. ACP historical forks use `session/fork` when available; an exact assistant-message position additionally needs the AIR fork-point extension supported by the Claude, Codex and DeepSeek adapters, and a position it cannot express starts a new remote session with a bounded conversation handoff. Codex and DeepSeek ACP form questions use Kiki's persistent question interaction, and complex forms or URL-mode requests they cannot express are declined. Grok's plan approval uses the persistent plan-review interaction.
 
 ### Kiki context in external main agents
 
@@ -114,7 +140,7 @@ allow_kiki_subagents: true
 kiki_context: [memory, board, cron, threads, history, hooks]
 ```
 
-The list defaults to absent (all context groups off); `[]` explicitly disables every group. Rebind the main profile after editing it. Tools are registered once when the bridge starts, so enabling a group does not rewrite a running harness's tool list. The bound profile's native tool policy and feature settings still apply; a disabled native tool is not exposed. Only external main agents can acquire this bridge.
+In legacy profile-only bindings, an absent list turns every group off. In the main-agent `execution` path, an omitted profile field inherits [harness defaults](../configuration/config-files.md#external-harness-defaults), and session overrides take priority; `[]` explicitly disables everything. Rebind the execution after editing it. Tools are registered once when the bridge starts, so a group you enable later is not added to a harness that is already running. The bound profile's tool policy and feature settings still apply. Only external main agents can acquire this bridge.
 
 | Group | MCP tools |
 | --- | --- |
@@ -125,26 +151,24 @@ The list defaults to absent (all context groups off); `[]` explicitly disables e
 | `history` | `kiki_history_search`, `kiki_history_read` |
 | `hooks` | Message-context injection; no extra model-callable tool |
 
-The tools use native Kiki parameters and execution policies, including approval, persona visibility, workspace access, memory review, and Plan mode restrictions. Calls are attributed to the existing main agent, not to a user write or a new seat session. The bridge token cannot access ordinary REST endpoints or select a different caller session. Native read tools advertise MCP read-only annotations. Vendor approval remains a separate layer from Kiki approval, except for the Codex Full access pre-approval described above.
+These tools use native Kiki parameters and execution policies, including approval, persona visibility, workspace access, memory review and Plan mode restrictions. Calls are attributed to the existing main agent — not to a user write, and not to a new seat session. The bridge token cannot reach ordinary REST endpoints or select a different caller session, and the native read tools advertise MCP read-only annotations. Vendor approval stays a separate layer from Kiki approval, except for the Codex Full access pre-approval above.
 
-`hooks` sends memory summaries and undelivered reminders/working notes through messages, not through a changing system prompt or tool schema. Identical content is deduplicated for the bridge's lifetime. Hook content is recorded with a `hook_result` origin in the Kiki transcript. Kiki creates only temporary process/session configuration; it does not edit the harness's global hook settings.
+`hooks` sends memory summaries and undelivered reminders and working notes as messages, rather than by rewriting the system prompt or the tool schema. Identical content is deduplicated for the bridge's lifetime, and hook content is recorded in the Kiki transcript with a `hook_result` origin. Kiki writes only temporary process or session configuration and does not edit the harness's global hook settings.
 
 | Harness | Injection |
 | --- | --- |
 | Claude ACP | Temporary command-hook settings through `session/new` metadata; `SessionStart` and `UserPromptSubmit` use `additionalContext`. |
 | Codex app-server / ACP | Temporary `hooks.json` definitions become per-process/session configuration with trust pinned only to those commands; `SessionStart` and `UserPromptSubmit` use `additionalContext`. |
-| Antigravity | Isolated `GEMINI_HOME` with `PreInvocation.injectSteps`; ACP hook loading and preservation of login through the isolated home are not yet verified against a runnable ACP server. |
-| Grok ACP | Native session-local ACP `Stop` callbacks inject `additionalContext`, without relying on plugin hook activation. Session-start and prompt-submit hooks cannot inject context, so Kiki retains its existing message preamble before tools. |
+| Antigravity | Isolated `GEMINI_HOME` with `PreInvocation.injectSteps`. |
+| Grok ACP | Native session-local ACP `Stop` callbacks inject `additionalContext`. Session-start and prompt-submit hooks cannot inject context, so Kiki keeps its message preamble before tools. |
 
-Claude and Codex `PreCompact` hooks prepare an auditable handoff snapshot but do not accept `additionalContext`; Kiki does not label that snapshot as injected. Claude's compact `SessionStart`, or Codex's next `UserPromptSubmit` after the preparation event, restores the state summaries. Antigravity and Grok do not provide a verified pre-compaction injection event. These hooks do not add idle wakeup support to a harness.
+Claude and Codex `PreCompact` hooks prepare an auditable handoff snapshot rather than injecting it, and the state summaries are restored at Claude's compact `SessionStart` or Codex's next `UserPromptSubmit`.
 
 ### Rebuilding a session context
 
-After editing prompt sources, open the profile selector in the session composer and choose **Rebuild context**. After confirmation, Kiki reloads the current profile, prompt-field overrides, Agent Skills, `AGENTS.md` instructions, and plugin prompt/session-start injections from disk, reconciles other runtime context injections, then uses the rebuilt snapshot for later requests. Conversation messages are preserved. The action is unavailable while a turn is running; wait for the session to become idle and try again.
+After editing prompt sources, open the profile selector in the session composer and choose **Rebuild context**. Kiki reloads the current profile, prompt-field overrides, Agent Skills, `AGENTS.md` instructions and plugin prompt or session-start injections from disk, reconciles the other runtime context injections, and uses the rebuilt snapshot for later requests. Conversation messages are preserved. The action is unavailable while a turn is running.
 
-Open **Dispatch capabilities** in settings, next to the new-session workspace selector, or in a session's right rail to inspect subagent profiles, routes, executors, and default model and thinking-effort sources. Default configuration validity and permission to launch are shown separately. The draft panel is a planning reference, not a real-time launch check.
-
-The session panel reflects the current agent's tool directory, including [Plan mode's read-only research restriction](../reference/tools.md#plan-mode) and launch refusal reasons. It does not check external provider health. If a selected model, profile, or thinking effort becomes unavailable, choose a valid value before sending; a loading state or catalog error alone does not invalidate a saved choice.
+**Dispatch capabilities** — next to the new-session workspace selector, or in a session's right rail — shows subagent profiles, routes, executors, and where the default model and thinking effort come from. Default-configuration validity and permission to launch are shown separately, and the panel reflects the current agent's tool directory, including [Plan mode's read-only research restriction](../reference/tools.md#plan-mode) and the reasons a launch would be refused. It does not check external provider health. If a model, profile or effort becomes unavailable, pick a valid value before sending; a loading state or catalog error alone does not invalidate a saved choice.
 
 ### Agent Locations
 
@@ -154,7 +178,7 @@ Kiki discovers agent files by scope; more specific scopes take higher priority:
 - `$KIKI_HOME/agents/` (default: `~/.kiki/agents/`)
 - `~/.agents/agents/`
 
-The Kiki-specific user agent directory moves with `KIKI_HOME`, while the generic `~/.agents/agents/` directory stays under the real OS home so it can be shared across tools.
+The Kiki-specific user agent directory moves with `KIKI_HOME`, while the generic `~/.agents/agents/` stays under the real OS home so other tools can share it.
 
 **Project level** (project root = the nearest directory containing `.git`, searching upward from the working directory):
 - `.kiki/agents/`
@@ -166,14 +190,14 @@ The Kiki-specific user agent directory moves with `KIKI_HOME`, while the generic
 extra_agent_dirs = ["~/team-agents", ".agents/team-agents"]
 ```
 
-Agent Markdown files under the user, project, and `extra_agent_dirs` roots are watched for filesystem changes. After an approximately 200 ms debounce, additions, edits, and deletions reload automatically, so a running session can dispatch a newly available role without `/reload` or a CLI restart. `$KIKI_HOME/SYSTEM.md` is watched the same way. An already-created `AgentRun` tool instance keeps a frozen snapshot of its displayed role descriptions, so that list can look stale, but dispatch resolution uses the reloaded profiles immediately.
+Agent Markdown files under the user, project and `extra_agent_dirs` roots are watched, and after roughly 200 ms additions, edits and deletions reload automatically — a running session can dispatch a newly added role without `/reload` or a restart. `$KIKI_HOME/SYSTEM.md` is watched the same way. An `AgentRun` tool instance keeps a frozen snapshot of the role descriptions it displays, so that list can look stale while dispatch resolution already uses the reloaded profiles.
 
 **Plugin level**: directories declared in an enabled plugin's manifest `agents` field (when omitted, the `agents/` directory under the plugin root is picked up automatically); see [Plugin Agents](./plugins.md#plugin-agents). Plugin definitions have lower priority than the user files, including installed built-in copies.
 
-**Built-in copies** are installed under `$KIKI_HOME/agents/builtin/` and loaded in the user scope. They are scanned after ordinary files in both user directories, so a same-name user definition always wins without `override: true`, regardless of filename order or when it was installed. Duplicate-name diagnostics identify both paths. A file loaded through `--agent-file` outranks every directory scope and applies to the current launch only. Separately, `$KIKI_HOME/SYSTEM.md` permanently overrides the default main agent's system prompt; its precedence interactions are covered below.
+**Built-in copies** are installed under `$KIKI_HOME/agents/builtin/` and loaded in the user scope after ordinary files in both user directories, so a same-name user definition always wins without `override: true`, whatever the filename order or install time. A duplicate-name diagnostic names both paths. A file loaded through `--agent-file` outranks every directory scope and applies to that launch only; `$KIKI_HOME/SYSTEM.md` separately overrides the default main agent's system prompt, as covered below.
 
 ::: warning Trust model
-Agent files are prompt configuration, and project-level files come from the repository itself — including repositories you have just cloned and do not trust yet. A project-scoped file can take over a built-in agent entirely: a file named `agent.md` can replace the **default main agent's whole system prompt**, and `general.md` can replace the default subagent type. This does not require `override: true`. Unlike `AGENTS.md` content — scoped instructions subordinate to system policy and your current request — an override file *is* the system prompt, and omitting `tools` adds no profile allowlist beyond the applicable runtime policy. Review `.kiki/agents/` and `.agents/agents/` in unfamiliar repositories with the same caution you would apply to scripts, before running Kiki inside them.
+Agent files are prompt configuration, and project-level files come from the repository itself — including one you have just cloned and do not trust yet. A project file named `agent.md` can replace the **default main agent's whole system prompt**, and `general.md` can replace the default subagent type, with no `override: true` needed. Unlike `AGENTS.md` content, which is scoped instructions subordinate to system policy and your current request, such a file *is* the system prompt. Review `.kiki/agents/` and `.agents/agents/` in an unfamiliar repository before running Kiki inside it.
 :::
 
 ### Agent File Format
@@ -200,7 +224,7 @@ disallowedTools:
 You are a strict code reviewer. Read the diff, then report findings grouped by severity…
 ```
 
-The model-list rejection and advisory behavior below describes **subagent bindings**. For the session's main agent, user selections override profile model and effort rules: hard violations only warn, while recommendations and default pins do not warn or block sending. Using a `main: true` profile through `AgentRun` still follows subagent rules. See [Model menus and hard boundaries](./agent-profiles.md#model-menus-and-hard-boundaries).
+Model-list rejection and advisories below describe **subagent bindings**. For a session's main agent your selection wins over profile rules: a hard violation only warns, and recommendations do not warn at all. A `main: true` profile dispatched through `AgentRun` still follows the subagent rules. See [Model menus and hard boundaries](./agent-profiles.md#model-menus-and-hard-boundaries).
 
 | Field | Required | Description |
 | --- | --- | --- |
@@ -241,13 +265,13 @@ The model-list rejection and advisory behavior below describes **subagent bindin
 | `spawn_constraints` | no | Rules inherited by descendants: hard `allowed_models`, `deny_models`, `allowed_efforts`, and `disallowed_tools`; soft `preferred_models`, `discouraged_models`, and `preferred_efforts`. Allowsets intersect and denials accumulate along the tree; pins cannot widen hard rules |
 | `private` | no | Hide this profile from dispatch and selection lists (`AgentRun`, Settings pickers). A private profile stays registered: agents already running or resumed on it keep working from their bound snapshot, while any **new** dispatch to it fails with an explicit "profile is private" error. Use it to retire a role without breaking live sessions |
 
-Use `preferred_subagents: [explore]` when you want a recommendation, not a closed role list. Preset permissions and preferences are independent of model and tool rules. Across a base profile, route, and caller lease, allowed sets intersect, denials accumulate, and `false` remains closed; the nearest explicit preference list replaces the earlier one. A `"*"` may share an `allowed_subagents` list with names and source/lease mappings: it leaves this layer open while retaining those mappings. Repeated bare names are ignored; two different mappings for the same alias are an error.
+Use `preferred_subagents: [explore]` for a recommendation rather than a closed role list. Across a base profile, a route and a caller lease, allowed sets intersect, denials accumulate, `false` stays closed, and the nearest explicit preference list replaces the earlier one. A `"*"` can share an `allowed_subagents` list with names and source or lease mappings: it leaves this layer open while keeping those mappings. Repeated bare names are ignored, and two different mappings for one alias are an error.
 
-`profile_file` directly supplies a new role definition, without registering it in the preset catalog. A file's `name` does not make it a same-name preset: preset allow/deny lists and same-name caller leases do not apply, and the caller's selectable preset list is not copied into the file child's own downstream rules. The file's own rules, inherited model/tool constraints, and workspace path checks still apply. Use `can_spawn_subagents: false` for a complete leaf, not `allowed_subagents: []`.
+`profile_file` supplies a new role definition without registering it in the preset catalog, and the file's `name` does not make it a same-name preset — preset allow/deny lists and same-name caller leases do not apply to it, and the caller's preset list is not copied into its downstream rules. The file's own rules, inherited model and tool constraints and workspace path checks still apply. Use `can_spawn_subagents: false` for a complete leaf rather than `allowed_subagents: []`.
 
-**Migration:** author fields `subagents` and `subagent_policy`, and host settings `main_dispatch_policy` and `subagent_dispatch_policy`, have been removed. Move advice-only role names to `preferred_subagents`; move real preset boundaries to `allowed_subagents` / `deny_subagents`; use `can_spawn_subagents: false` for an old leaf. Keep source and lease mappings under `allowed_subagents`. Saved bindings are upgraded without changing their role, model, prompt, or source snapshot. Structured edits preserve omitted fields; `null` removes a local declaration, while `[]` writes an explicit empty list.
+The old author fields `subagents` and `subagent_policy`, and the host settings `main_dispatch_policy` and `subagent_dispatch_policy`, have been removed. Move advice-only role names to `preferred_subagents`, real preset boundaries to `allowed_subagents` / `deny_subagents`, and a former leaf to `can_spawn_subagents: false`; source and lease mappings stay under `allowed_subagents`. Existing bindings are upgraded without changing their role, model, prompt or source snapshot, and a structured edit keeps the fields you did not mention — `null` removes a local declaration, `[]` writes an explicit empty list.
 
-`model_profiles` is a YAML list of mappings. A string, scalar, or mapping at the top level is invalid, because every entry needs an `alias`. `when` is optional; the rest of the fields are optional too. A matching entry's `auto_compact` overrides the profile's top-level value; both use integer tokens, never a percentage. Example:
+`model_profiles` is a YAML list of mappings, so every entry needs an `alias` — a bare string or mapping at the top level is invalid. Every other field is optional, and a matching entry's `auto_compact` overrides the profile's top-level value (both in integer tokens, never a percentage). Example:
 
 ```yaml
 model_profiles:
@@ -266,11 +290,11 @@ model_profiles:
       temperature: 0.2
 ```
 
-Match `model_profiles` by canonical model identity. Resolve the model alias configuration, including its `overrides`, first; then apply model alias → top-level profile → matching `model_profiles` entry. Merge `request_params` by key and use the last explicit `service_tier`. Treat `context_budget` and `max_completion_tokens` as limits: take the smallest declared value across layers, within the model's capacity and output cap. Omitting a limit adds no restriction. Only top-level `thinking_effort` requires the selected model to match the profile's default `model_alias`; other profile parameters are not conditional on that match.
+`model_profiles` is matched by canonical model identity. Resolve the model alias configuration, including its `overrides`, first; then apply model alias → top-level profile → matching `model_profiles` entry. `request_params` merge by key and the last explicit `service_tier` wins. Treat `context_budget` and `max_completion_tokens` as caps: the smallest declared value across layers applies, within the model's capacity and output limit. Omitting a cap adds no restriction. Only top-level `thinking_effort` requires the selected model to match the profile's default `model_alias`; other profile parameters do not.
 
-The model cognition overlay (`[models."<alias>".cognition]`) is the supported way to add per-model prompt text — `model_profiles.prompt_mode` and `prompt` extend the role body itself, while the alias cognition extends the model's system prompt.
+For per-model prompt text, `model_profiles.prompt_mode` and `prompt` extend the role body, while the model cognition overlay (`[models."<alias>".cognition]`) extends the model's system prompt.
 
-For subagent bindings, `allowed_models`, `deny_models`, and `allowed_efforts` are hard constraints everywhere they occur: profile, `spawn_constraints`, caller lease, and matching `model_profiles` entries. Allowsets intersect; denials accumulate. A violation returns `profile.constraint_violation` with the rule source, allowed/denied values, effective value, and binding-value source. Advisory dispatch, explicit pins, manual model/effort changes, and resume cannot widen these constraints. Machine `[subagent].deny_models` adds another hard boundary; route sidecars cannot declare model hard-list fields. External executor normalization is checked again against its actual effective model ID.
+For subagent bindings, `allowed_models`, `deny_models` and `allowed_efforts` are hard everywhere they appear: in the profile, `spawn_constraints`, a caller lease and matching `model_profiles` entries. Allowsets intersect and denials accumulate, and a violation returns `profile.constraint_violation` naming the rule source, the allowed and denied values, the effective value and where the binding value came from. An advisory, a pin, a manual model or effort change and `resume` cannot widen them. Machine `[subagent].deny_models` is one more hard boundary, route sidecars cannot declare model hard lists, and an external executor is rechecked against its effective model ID.
 
 ```yaml
 model_alias: fast-model
@@ -282,9 +306,9 @@ preferred_efforts: [high]
 discouraged_models: [review-model]
 ```
 
-Here `review-model` remains executable but carries an advisory; `heavy-model` is rejected. Lists never select a model: use a `model_alias` pin, dispatch parameter, or explicit `[subagent].default_model`.
+Here `review-model` stays executable with an advisory, and `heavy-model` is rejected. Lists never select a model — use a `model_alias` pin, a dispatch parameter or an explicit `[subagent].default_model`.
 
-If the default and per-model recipes already form the complete permitted menu, prefer making that menu the contract instead of maintaining a duplicate positive hard list:
+When the default and per-model recipes already form the complete permitted set, make that menu the contract instead of duplicating it as a hard list:
 
 ```yaml
 model_alias: fast-model
@@ -296,21 +320,21 @@ model_profiles:
 preferred_models: [fast-model]
 ```
 
-This permits the original default `fast-model` and the menu entry `review-model`, not arbitrary explicit overrides; other hard rules may further narrow them. Leave the switch off for recommendation-only menus and use `preferred_*` / `discouraged_models`. Use `allowed_models` / `deny_models` for independent budget, compliance, deployment, or descendant-tree boundaries. The switch defaults off and does not automatically migrate existing profiles. See [When to enable it](./agent-profiles.md#when-to-enable-it) for the three-scenario choice rule.
+This permits the default `fast-model` and the menu entry `review-model`, and nothing else; other hard rules may narrow them further. Keep the switch off for a recommendation-only menu and use `preferred_*` / `discouraged_models` there. Use `allowed_models` / `deny_models` for a budget, compliance, deployment or descendant-tree boundary of their own. See [When to enable it](./agent-profiles.md#when-to-enable-it) for the three-scenario rule.
 
-**Migration:** existing `allowed_models`, `deny_models`, and `allowed_efforts` now enforce their literal hard meaning; there is no legacy-soft mode. If a list was only advice, rename it to `preferred_models`, `discouraged_models`, or `preferred_efforts`, respectively, in every affected scope. Keep genuine hard boundaries and widen them only for intentional executable alternatives. Keep `model_profiles` candidates and default pins; migrate only advice fields within them, not the mechanism itself. A saved binding outside hard rules is rejected on resume: select a permitted value or revise the rule before retrying.
+`allowed_models`, `deny_models` and `allowed_efforts` enforce their literal hard meaning everywhere; there is no legacy soft mode. If one of your lists was only advice, rename it to `preferred_models`, `discouraged_models` or `preferred_efforts` in every scope where it appears, and keep real boundaries as they are. A saved binding outside the hard rules is rejected on resume — pick a permitted value or revise the rule, then retry.
 
-Built-in and user tools match by exact, case-sensitive name; entries starting with `mcp__` match MCP tools as globs. Three entry shapes never match anything and are reported with a warning when the profile takes effect: a wildcard outside an `mcp__` pattern (a bare `*` in `disallowedTools` disables nothing), an `mcp__` literal that is not a full `mcp__<server>__<tool>` name (`mcp__github` matches nothing — use `mcp__github__*` for the whole server), and a name no registered or built-in tool has (usually a typo, such as `read` instead of `Read`).
+Tool names match exactly and case-sensitively; entries starting with `mcp__` match MCP tools as globs. Three shapes match nothing and produce a warning when the profile takes effect: a wildcard outside an `mcp__` pattern (a bare `*` in `disallowedTools` disables nothing), an `mcp__` literal that is not a full `mcp__<server>__<tool>` name (`mcp__github` matches nothing — use `mcp__github__*` for the whole server), and a name no registered or built-in tool has, usually a typo such as `read` for `Read`.
 
-The body is the agent's system prompt, and it is rendered as a template each time the prompt is built: `${var}` placeholders substitute live context values — unknown variables stay verbatim, a bare `$` is never special, and a variable with no context value renders as an empty string. `${parent_prompt}` (alias `${base_prompt}`) embeds the implicit parent for this file: the effective default system prompt in an agent file, the built-in default inside `SYSTEM.md`, or the base profile in a route. `${builtin_prompt}` is always the built-in default, even when `SYSTEM.md` exists. If the file replaces the default prompt but should still honor instructions contributed by enabled plugins, place `${plugin_sections}` where those instructions should appear. The available variables are listed in the SYSTEM.md section below.
+The body is the agent's system prompt, rendered as a template each time the prompt is built: `${var}` placeholders substitute live context values, an unknown variable stays verbatim, a bare `$` is never special, and a variable with no value renders as an empty string. `${parent_prompt}` (alias `${base_prompt}`) embeds the implicit parent for this file: the effective default system prompt in an agent file, the built-in default inside `SYSTEM.md`, or the base profile in a route. `${builtin_prompt}` is always the built-in default, even when `SYSTEM.md` exists. If the file replaces the default prompt but should still honor instructions from enabled plugins, place `${plugin_sections}` where those belong. The full variable list is in the SYSTEM.md section below.
 
-Frontmatter keys are closed: a field Kiki does not recognize makes that file fail to load with a diagnostic naming the key, so remove or migrate unsupported keys (for example Claude Code's `model` or OpenCode's `mode`). The comma-separated `tools` form is accepted, and a missing `name` falls back to the file name, so a minimal file with `description` and a body loads.
+Frontmatter keys are closed: an unrecognized field makes the file fail to load with a diagnostic naming the key, so remove or migrate it (Claude Code's `model` and OpenCode's `mode`, for instance). The comma-separated `tools` form is accepted and a missing `name` falls back to the file name, so a minimal file with just a `description` and a body loads.
 
 ### Named profile routes (experimental)
 
-A named route specializes an existing Agent without creating a new permission identity. Enable discovery at startup with `[experimental] agent-profile-routes = true` in `config.toml`, or set `KIKI_EXPERIMENTAL_AGENT_PROFILE_ROUTES=1`.
+A named route specializes an existing agent without creating a new permission identity. Enable discovery at startup with `[experimental] agent-profile-routes = true` in `config.toml`, or set `KIKI_EXPERIMENTAL_AGENT_PROFILE_ROUTES=1`.
 
-Keep the base profile at `agents/<role>.md`. Put routes under `agents/.routes/<role>/<route>.md`; the canonical ID is `<role>.<route>`, with a lowercase hyphen/underscore-separated base profile and lowercase kebab-case route segments. For example, `agents/.routes/reviewer/ui-k3.md` defines `reviewer.ui-k3`:
+Keep the base profile at `agents/<role>.md` and put routes under `agents/.routes/<role>/<route>.md`, which gives the canonical id `<role>.<route>`. Route segments are kebab-case. For example, `agents/.routes/reviewer/ui-k3.md` defines `reviewer.ui-k3`:
 
 ```markdown
 ---
@@ -332,33 +356,33 @@ request_params:
 Focus on interaction regressions, accessibility, and visual consistency.
 ```
 
-The required fields are `id`, `profile`, `description`, and `prompt_mode`. Optional fields are `whenToUse` plus `model_alias`, `thinking_effort`, `service_tier`, `request_params`, `tools`, `disallowedTools`, `can_spawn_subagents`, `allowed_subagents`, `preferred_subagents`, and `deny_subagents`. Unlike ordinary Agent files, route frontmatter is strict. Unknown fields, invalid types, a path/ID/profile mismatch, duplicate IDs in one source, and incompatible model selectors cause only that sidecar to be skipped with a coded diagnostic; the base profile and sibling routes still load. Agent-file-only fields such as `model_profiles`, `allowed_models`, and `deny_models` are unknown here and skip the sidecar. A route may recommend a default `model_alias`. A preference mismatch produces an advisory, but the base profile's hard model and effort lists still reject violations; select a hard-permitted explicit override or revise the base rule.
+Required: `id`, `profile`, `description`, `prompt_mode`. Optional: `whenToUse`, `model_alias`, `thinking_effort`, `service_tier`, `request_params`, `tools`, `disallowedTools`, `can_spawn_subagents`, `allowed_subagents`, `preferred_subagents`, `deny_subagents`. Route frontmatter is strict, and an unknown field — including agent-file-only ones such as `model_profiles`, `allowed_models` and `deny_models` — skips that one sidecar with a coded diagnostic while the base profile and sibling routes still load. The same happens for a path, id or profile mismatch, a duplicate id in one source, or incompatible model selectors.
 
-`prompt_mode` always preserves the base prompt: `inherit` requires an empty body; `prepend` and `append` require a non-empty body and reject `${parent_prompt}` / `${base_prompt}`; `wrap` requires `${parent_prompt}` or `${base_prompt}` exactly once. There is no unguarded replace mode.
+`prompt_mode` always preserves the base prompt: `inherit` requires an empty body, `prepend` and `append` require a non-empty body and reject `${parent_prompt}` / `${base_prompt}`, and `wrap` requires `${parent_prompt}` or `${base_prompt}` exactly once. There is no unguarded replace mode.
 
-A route's `tools` and `disallowedTools` replace the corresponding base fields. Its `allowed_subagents` intersects the base set, `deny_subagents` accumulates, and `can_spawn_subagents: false` cannot be reopened; the nearest explicit `preferred_subagents` replaces the earlier preference. Omission inherits each field. `allowed_subagents: []` closes preset selection only; `can_spawn_subagents: false` makes a full leaf. Caller checks use the base role, so a route cannot introduce a preset role the caller could not dispatch.
+A route's `tools` and `disallowedTools` replace the base fields, its `allowed_subagents` intersects the base set, `deny_subagents` accumulates, and `can_spawn_subagents: false` cannot be reopened; the nearest explicit `preferred_subagents` replaces the earlier preference, and an omitted field inherits. `allowed_subagents: []` closes preset selection only. Caller checks use the base role, so a route cannot introduce a preset role the caller could not dispatch.
 
-An omitted request field inherits the base value. `service_tier: null` clears the base tier; another tier replaces it. `request_params: null` clears the base map; a mapping overlays scalar keys on it. A route-declared `model_alias` or `thinking_effort` is the route default. `AgentRun` may explicitly override either value only within all hard model and effort lists; an accepted child stays associated with the route, is marked detached, and records a structured advisory. If no override is supplied, a missing route model or an effort the selected provider/executor cannot perform remains a hard capability error.
+An omitted request field inherits the base value: `service_tier: null` clears the tier, `request_params: null` clears the map, and a mapping overlays scalar keys. A route-declared `model_alias` or `thinking_effort` is the route default, and `AgentRun` may override either only within the hard model and effort lists. With no override, a missing route model or an effort the provider cannot perform is a hard capability error.
 
-When enabled, `AgentRun` shows compact route entries filtered through the caller's base-role allowlist. Entries contain the route ID, base role, description/usage hint, model and effort defaults, and overridden field names—never the prompt body. Pass `route: reviewer.ui-k3`; omit `profile` to derive `reviewer`, or pass that matching base explicitly. A mismatch is a coded error. There is no automatic ranking or silent fallback.
+`AgentRun` lists route entries filtered through the caller's base-role allowlist, showing the route id, base role, description, model and effort defaults and the overridden field names — never the prompt body. Pass `route: reviewer.ui-k3`; omit `profile` to derive `reviewer`, or pass that matching base explicitly. A mismatch is a coded error, and there is no automatic ranking or silent fallback.
 
-Resume never reselects or switches a route. The journal stores the canonical base role and route ID with the rendered prompt, layered tool policy, denylist, subagent restriction, model/effort locks, service tier, and request parameters. Existing routed Agents therefore resume from their snapshot even if the flag is disabled or the sidecar changes, disappears, or becomes invalid; those changes affect only new dispatches. Old journals remain compatible.
+Resume never reselects or switches a route: the journal stores the canonical base role and route id with the rendered prompt, tool policy, denylist, subagent restriction, model and effort locks, service tier and request parameters. A routed agent therefore resumes from its snapshot even if the flag is later disabled or the sidecar changes; those changes affect only new dispatches.
 
-A newly spawned subagent selects its model in order: the concrete `model_alias` tool parameter → the pin on the effective profile, route, or caller lease → explicitly configured `[subagent].default_model`. With none of these sources, the spawn fails with `model.not_configured` and no child is created. The caller's model and the main-agent `default_model` are not silent fallbacks. Set `model_alias: inherit` in a profile, route, or caller lease to explicitly bind the caller's current resolved model. `AgentRun` rejects `model_alias: "inherit"`: specify a concrete configured model name, or omit the parameter to use the target default. With profile-, route-, or lease-configured inheritance, the caller's effective thinking effort follows too, unless an explicit tool `effort` or applicable `thinking_effort` pin on the profile, route, caller lease, or matching `model_profiles` entry takes priority. For other model selections, effort follows the existing precedence: explicit tool `effort` → matching `model_profiles` effort → profile `thinking_effort` when the bound model matches the profile pin (canonical identity) → the bound model's own default. An unknown concrete alias is an error whether it came from the dispatch or from a profile pin.
+A new child picks its model from the concrete `model_alias` parameter, then the pin on the effective profile, route or caller lease, then an explicitly configured `[subagent].default_model`; with none of them the spawn fails with `model.not_configured` and no child is created, and the caller's model is not a silent fallback. Set `model_alias: inherit` in a profile, route or caller lease to bind the caller's resolved model explicitly — `AgentRun` itself rejects `model_alias: "inherit"`, so pass a concrete name or omit the parameter. With configured inheritance the caller's effort follows too, unless a tool `effort` or an applicable `thinking_effort` pin takes priority; otherwise effort resolves as tool `effort` → the route's locked effort, or the caller lease's when the route pins none → matching `model_profiles` effort → profile `thinking_effort` when the bound model matches the profile pin → the bound model's own default. When none supplies an effort, a model known not to support thinking uses `off`; a thinking model without a resolvable default still needs an explicit effort. Unknown capabilities do not imply `off`, and an unknown alias is an error wherever it came from.
 
-On `AgentRun` resume the saved binding is kept when you omit both `model_alias` and `effort`. A `model_alias` that resolves to the same canonical model is a no-op. Changing only `effort` applies the new value to the next idle run and keeps the saved model. Changing `model_alias` to a different canonical model requires `allow_model_change: true`; when `effort` is also omitted in that case, the target model's own default effort is re-resolved from scratch — the previous effort is not carried over. `AgentRun` also rejects `model_alias: "inherit"` on resume; use a concrete model name for an explicit change, or omit it to keep the saved model. Explicit preferences and saved route/caller-lease pins produce advisories for a hard-permitted runnable resume. Profile, lease, matching model-profile and inherited hard rules are checked at resume admission; rejection leaves the saved binding unchanged. An explicit effort the provider cannot honor, machine model denial, executor thread-binding restrictions, and admission consistency checks also remain hard errors.
+On `resume`, omitting both `model_alias` and `effort` keeps the saved binding, and an alias resolving to the same canonical model is a no-op. Changing only `effort` applies it to the next idle run. Changing `model_alias` to a different canonical model needs `allow_model_change: true`, and with `effort` also omitted the target model's own default is re-resolved rather than carried over. Profile, lease, model-profile and inherited hard rules are checked at resume admission, and a rejection leaves the saved binding unchanged; an effort the provider cannot honor, a machine model denial and executor thread-binding restrictions are hard errors too.
 
-Omit `model_alias` and `effort` to use the selected target's defaults when launching a new child. The model catalog filters hard-permitted configured models and separately identifies preferences from the effective profile, lease, route, and model-profile candidates. A model listed for another target is not automatically preferred or allowed here. An executable override is accepted only inside every hard boundary. Pair `preferred_models` with a default `model_alias` to publish a preferred pool; retain `model_profiles` for per-model defaults and guidance. Route tier overrides, including `service_tier: null`, do not clear a configured model-level tier.
+Omit `model_alias` and `effort` to use the target's defaults for a new child. The model catalog lists hard-permitted configured models and marks the preferences coming from the effective profile, lease, route and model-profile entries; a model listed for another target is neither preferred nor allowed here. Pair `preferred_models` with a default `model_alias` to publish a preferred pool, and keep `model_profiles` for per-model defaults and guidance. A route's `service_tier`, including `service_tier: null`, does not clear a configured model-level tier.
 
-Native model governance compares canonical identities after resolving `[models]` aliases; external executors use effective model IDs. `allowed_models`, `deny_models`, and `allowed_efforts` are always hard, regardless of scope or dispatch policy. `preferred_models`, `discouraged_models`, `preferred_efforts`, route defaults, and caller-lease pins are soft; deviations are retained in the binding and summarized in the parent `AgentRun` result. See the [configuration reference](../configuration/config-files.md#subagent) for fields and validation rules.
+`allowed_models`, `deny_models` and `allowed_efforts` are always hard, whatever the scope. `preferred_models`, `discouraged_models`, `preferred_efforts`, route defaults and caller-lease pins are soft: a deviation is kept in the binding and summarized in the parent `AgentRun` result. See the [configuration reference](../configuration/config-files.md#subagent).
 
-A file with invalid content discovered in a directory is skipped with a warning and does not affect other files. A file passed explicitly via `--agent-file` must be valid — otherwise the CLI reports the error and exits.
+An invalid file found in a directory is skipped with a warning and does not affect the others. A file passed via `--agent-file` must be valid, or the CLI reports the error and exits.
 
 ::: warning Note
-`tools` and `disallowedTools` shape the tools shown to the model and are enforced again before execution. Preset allow/deny rules also filter the `AgentRun` catalog and are checked again before dispatch. The spawn switch additionally controls new Markdown-file children; continuing an existing child is exempt. Permission rules remain a separate control for operations that require approval.
+`tools` and `disallowedTools` shape what the model is shown and are enforced again before execution. Preset allow/deny rules also filter the `AgentRun` catalog and are checked again before dispatch, and `can_spawn_subagents: false` blocks new Markdown-file children while still allowing an existing child to be resumed. Permission rules remain a separate control for operations that need approval.
 :::
 
-When a custom agent runs as a dispatched subagent, Kiki prepends a short handoff notice: the last message is the complete deliverable for the caller. An independent host invocation (MCP / SDK) gets a different notice: there is no parent agent. Main-agent binds inject nothing. Put `${delegation_context}` in the body to place the notice; otherwise it is prepended. Set `delegation_notice: off` on the profile, or `[agents.delegation] sub = false` / `independent = false` in `config.toml`, to skip it. To replace the text, override `delegation.sub.notice` or `delegation.independent.notice` through [`PromptOverrides`](../configuration/config-files.md#prompt). The former delegation `.md` path values are no longer accepted; the boolean gates and `delegation_notice: off` always win over text overrides.
+A dispatched custom agent gets a short handoff notice prepended: its last message is the complete deliverable. An independent host invocation (MCP / SDK) gets a different notice, because there is no parent agent; a main-agent bind gets none. Put `${delegation_context}` in the body to place the notice yourself, or set `delegation_notice: off` (or `[agents.delegation] sub = false` / `independent = false` in `config.toml`) to skip it. Override `delegation.sub.notice` or `delegation.independent.notice` through [`PromptOverrides`](../configuration/config-files.md#prompt) to change its text; the boolean gates always win over a text override.
 
 ### Selecting the Main Agent
 
@@ -367,9 +391,9 @@ Two CLI flags select which agent drives a new session, in both print mode (`kiki
 - **`--agent <name>`**: Start the session with the named agent as the main Agent. The name can refer to a built-in agent or to any discovered file; an unknown name fails with an error listing the available agents.
 - **`--agent-file <path>`**: Load one agent file at the highest priority for this launch and start with it. The flag accepts exactly one file: it cannot be repeated, and it cannot be combined with `--agent`.
 
-Both flags only apply when starting a new session — neither can be combined with `--session`/`--continue`. The agent is bound at session creation, and resuming restores the bound agent automatically, so no flag is needed (or allowed) on resume.
+Both flags apply only when starting a new session — neither can be combined with `--session`/`--continue`. The agent is bound at creation, and resuming restores it automatically, so no flag is needed or allowed there.
 
-In print mode, an explicit `--model` takes precedence over the selected profile's `model_alias`. Without `--model`, the engine uses the profile pin first and `default_model` only when no profile model is set. A pinned profile therefore works without a global default; subagents do not use this main-agent default, but may use their explicit `[subagent].default_model`. A main-agent profile cannot pin `model_alias: inherit` even if `default_model` or `--model` is set: it has no caller to follow.
+In print mode an explicit `--model` beats the profile's `model_alias`. Without `--model`, the profile pin wins and `default_model` applies only when the profile sets no model, so a pinned profile works without a global default. Subagents do not use that main-agent default; they can use their own `[subagent].default_model`. A main-agent profile cannot pin `model_alias: inherit`, because it has no caller to follow.
 
 For example:
 
@@ -378,22 +402,22 @@ kiki --agent reviewer
 kiki -p --agent reviewer "Review the changes on this branch"
 ```
 
-These CLI flags select the startup session's profile; they do not change a resumed session. The GUI can request a main-profile switch when submitting the next prompt. The user's main-agent model choice takes priority over profile model rules: recommendations do not warn, and hard violations only show non-blocking warnings. A session created later in the same TUI process (for example via `/new`) starts with the default agent.
+These flags select the profile for a new session only; the GUI can request a main-profile switch when you submit the next prompt. A session created later in the same TUI process (with `/new`, for example) starts with the default agent. Your main-agent model choice takes priority over profile rules: recommendations do not warn and hard violations only show a non-blocking warning.
 
-For main-agent customization, reference `${parent_prompt}` or `${base_prompt}` in the body so the environment, workspace-instruction, Skill, and plugin injections already present in the effective default prompt stay in effect. `${builtin_prompt}` is the stock default even when `SYSTEM.md` exists. When you want to replace the default prompt but keep only plugin-contributed instructions, use `${plugin_sections}` instead. A body without `${parent_prompt}` / `${base_prompt}` or `${plugin_sections}` owns the entire prompt and excludes plugin instructions, which fits self-contained sub-agents.
+When you customize the main agent, reference `${parent_prompt}` or `${base_prompt}` in the body so the environment, workspace-instruction, Skill and plugin injections already in the effective default prompt stay in effect. `${builtin_prompt}` is the stock default even when `SYSTEM.md` exists, and `${plugin_sections}` keeps just the plugin-contributed instructions. A body with none of the three owns the whole prompt, which suits a self-contained sub-agent.
 
 ### Overriding the main agent's system prompt with SYSTEM.md
 
-To override the default main agent permanently — without passing `--agent` or `--agent-file` on every launch — write a `$KIKI_HOME/SYSTEM.md` file (default: `~/.kiki/SYSTEM.md`; it moves with `KIKI_HOME`). A missing or empty file has no effect. Read or parse failures produce a path-specific diagnostic and retain that file's last good profile, if one was loaded in this process; other agent files still reload. Malformed YAML after an opening `---` is never reinterpreted as a legacy prompt. Repair the file to replace the retained profile, or remove it to drop the override. Without a last good version, the invalid override is skipped. SYSTEM.md takes effect in every launch mode, including interactive TUI sessions.
+To replace the default main agent permanently — without passing `--agent` or `--agent-file` on every launch — write `$KIKI_HOME/SYSTEM.md` (default: `~/.kiki/SYSTEM.md`; it moves with `KIKI_HOME`). It takes effect in every launch mode, including interactive TUI sessions. A missing or empty file does nothing, and a file that fails to parse produces a path-specific diagnostic while the last good version of that file keeps working, so you can repair it and reload rather than losing the override. Malformed YAML after an opening `---` is never treated as a plain prompt. Removing the file drops the override.
 
-How the file is parsed depends on its first line:
+How it is parsed depends on the first line:
 
-- **Legacy body.** The file does not start with `---` followed by a YAML mapping. Only the prompt is replaced; description, tools, and the sub-agent allowlist stay on the built-in defaults. Frontmatter is not required or read.
-- **Upgraded profile.** The file starts with `---` and that fence parses as a YAML mapping. It loads as a normal agent file named `agent`, with `override` forced on. Omitted tool fields and child-role permissions inherit the built-in defaults. Declared preset permissions narrow that layer, while explicit recommendations replace inherited recommendations.
+- **Legacy body.** The file does not start with `---` followed by a YAML mapping. Only the prompt is replaced; description, tools and the sub-agent allowlist keep the built-in defaults.
+- **Upgraded profile.** The file starts with `---` and that fence parses as a YAML mapping. It loads as a normal agent file named `agent`, with `override` forced on. Omitted tool fields and child-role permissions inherit the built-in defaults; declared preset permissions narrow them, and explicit recommendations replace inherited ones.
 
-Explicit intent still outranks it: a project-scoped same-name agent file declaring `override: true` and any file passed via `--agent-file` take precedence, and selecting another agent with `--agent` bypasses it entirely. Within the user scope itself, SYSTEM.md wins over a same-name file discovered in the `agents/` directories.
+Explicit intent still outranks it: a project-scoped same-name agent file declaring `override: true` and any file passed via `--agent-file` take precedence, `--agent` bypasses it entirely, and within the user scope SYSTEM.md wins over a same-name file in `agents/`.
 
-An upgraded `SYSTEM.md` may declare `prompt_overrides` in its frontmatter. With `system_prompt_mode: inherit`, leave the body empty and Kiki keeps the built-in `agent` prompt while applying only those fields. A legacy or upgraded replacement body remains authoritative and shadows built-in `system.*` section overrides, while `system.shared` and the applicable delegation notice stay outside that body. The complete format and precedence are documented under [`prompt`](../configuration/config-files.md#prompt).
+An upgraded `SYSTEM.md` may declare `prompt_overrides` in its frontmatter. With `system_prompt_mode: inherit`, leave the body empty and Kiki keeps the built-in `agent` prompt while applying only those fields. A replacement body stays authoritative and shadows built-in `system.*` section overrides, while `system.shared` and the delegation notice stay outside it. The complete format and precedence are under [`prompt`](../configuration/config-files.md#prompt).
 
 Like the body of a regular agent file, SYSTEM.md is rendered as a template each time the prompt is built — `${var}` placeholders in the body are substituted from the live context:
 
@@ -413,7 +437,7 @@ Like the body of a regular agent file, SYSTEM.md is rendered as a template each
 | `${delegation_context}` | Position-based handoff notice; empty for the main agent |
 | `${plugin_sections}` | A complete Plugin Instructions block contributed by enabled plugins; empty when no enabled plugin contributes instructions |
 
-Unknown variables stay verbatim, a bare `$` is never special, and a variable with no context value renders as an empty string. Four pre-composed blocks — `${windows_notes}`, `${additional_dirs_section}`, `${skills_section}`, and `${plugin_sections}` — render the matching built-in prompt section, or an empty string when it does not apply. The built-in default prompt already includes `${plugin_sections}`, so do not add it again when `${base_prompt}` already expands to that prompt. The variables are enough to rebuild the skeleton of the built-in prompt, for example:
+Four pre-composed blocks — `${windows_notes}`, `${additional_dirs_section}`, `${skills_section}` and `${plugin_sections}` — render the matching built-in prompt section, or an empty string when it does not apply. The built-in default prompt already includes `${plugin_sections}`, so do not add it again when `${base_prompt}` expands to that prompt. The variables are enough to rebuild the skeleton of the built-in prompt:
 
 ```markdown
 You are Kiki, running at ${cwd} on ${os}.
@@ -427,20 +451,18 @@ ${plugin_sections}
 
 ## Instruction Files
 
-`AGENTS.md` supplies instructions within each file's stated directory scope. More specific files take precedence when those instructions conflict. They remain subordinate to system policy and your current request, and cannot change tool schemas, permissions, or host controls. Runtime snapshots deliver these scoped rules; memory remains reference data.
-
-Kiki loads `$KIKI_HOME/AGENTS.md` (default: `~/.kiki/AGENTS.md`) together with the workspace-root `AGENTS.md`. A root `.kiki/AGENTS.md` replaces the user-level file; the root `AGENTS.md` still applies. At session start, applicable files along the path from the project root to the working directory are included too. Filename matching is case-insensitive. Files above the project boundary, `~/.agents/AGENTS.md`, and the legacy `.kimi-code/AGENTS.md` path are not discovered.
+`AGENTS.md` supplies instructions within each file's stated directory scope, and a more specific file wins when two conflict. These stay subordinate to system policy and your current request: they cannot change tool schemas, permissions or host controls.
 
-When a permitted file tool reaches a different directory, Kiki checks that directory's ancestors for `AGENTS.md` and `.kiki/AGENTS.md`, without scanning unrelated subtrees. It supplies the complete current rules before a file-tool write that would otherwise miss them. That first write returns a retryable result without changing files; after reviewing the supplied rules, the agent can retry under the existing permission policy. This does not add a new user approval. Bash discovery uses recognizable paths and an explicit working directory; it does not inspect every path computed by a shell command.
+Kiki loads `$KIKI_HOME/AGENTS.md` (default: `~/.kiki/AGENTS.md`) together with the workspace-root `AGENTS.md`; a root `.kiki/AGENTS.md` replaces the user-level file while the root `AGENTS.md` still applies. At session start, applicable files along the path from the project root to the working directory are included too. Filename matching is case-insensitive. Files above the project boundary, `~/.agents/AGENTS.md` and the legacy `.kimi-code/AGENTS.md` path are not discovered.
 
-A full current rule already present in the runtime snapshot or a complete successful `Read` is not sent again just because another tool visits the directory. Partial or truncated reads do not count as complete coverage. Changed files, a different host, or removal of the relevant context can require a fresh disclosure. The initial directory listing is only a one-level sample; the agent uses `Glob` to explore further. Rule bodies are not shortened to fit that sample.
+When a permitted file tool reaches a different directory, Kiki checks that directory's ancestors for `AGENTS.md` and `.kiki/AGENTS.md`. The first write that would have missed those rules returns a retryable result without changing anything, so the agent can read the supplied rules and retry under the same permission policy — no extra approval. Rules already delivered in full, by the runtime snapshot or a complete successful `Read`, are not sent again just because another tool visits the directory; a truncated read does not count. The initial directory listing is a one-level sample, and the agent uses `Glob` to explore further.
 
-## Storage Location in the Session Directory
+## Storage in the session directory
 
-Sub-agent runtime state is persisted to the `agents/` subdirectory of the current session directory. Each sub-agent instance has its own directory, which contains a `wire.jsonl` file that records prompts, message history, and final state in chronological order. Background sub-agents also expose their lifecycle status through a `tasks/` subdirectory.
+Sub-agent runtime state is persisted to the `agents/` subdirectory of the current session directory. Each sub-agent instance has its own directory containing a `wire.jsonl` file with its prompts, message history and final state in chronological order, and background sub-agents also expose their lifecycle status under a `tasks/` subdirectory.
 
 ::: warning Note
-Session directories, wire files, and task records are all local debug materials that may contain user prompts, command output, repository paths, tool return values, or traces of credentials. Do not commit these files directly to public repositories, issues, or chat logs; redact sensitive information before sharing.
+Session directories, wire files and task records can contain prompts, command output, repository paths, tool return values or traces of credentials. Redact them before putting any of it in a public repository, an issue or a chat log.
 :::
 
 ## Next steps