← Reference

Control-plane channels

System ↔ agent communication via <cp:*> XML tags.

Full notes from the app

Rate-limited. Visible live in the control drawer, which shows each tag as the agent reads it. Outside text a channel carries (command output, a plugin's note, another agent's mail) writes a channel tag it holds as &lt;cp:, so it can neither end its channel nor pose as another; the chat shows that text as written.

33 entries · kcode 0.6.5097

33 shown
ChannelDirectionAttributesLimitWhat it carries
system→agent
<cp:permission-context>system→agent(none)60/min/sourceThe active permission mode, which reads outside the project need permission, none, or only those of a secret location, the first of which it names (permissions.secret_paths), and how many deny rules apply. In auto mode it names the first secret location, since calls there still need permission. Injected once per turn and again when the mode changes.
<cp:event-trigger>system→agentsource="…"60/min/sourceExternal event fired (file watcher, timer, app-bus). Used to wake the agent on schedule.
<cp:hook-fired>system→agentname="…" (+ target="…" session="…" on project hook fires)30/min/hookA hook that reports to the chat ran; a silent hook (every plugin handler) adds nothing to the model's next message. Project [[hooks]] fires emit it too: on the target session, recording the hook name, its declared target, and the resolved session, with a preview of the injected line, so /control shows why a turn started.
<cp:fs-change>system→agent(none)30/min globalExternal file-system change detected. Filters out self-tool writes: only third-party changes are emitted.
<cp:mcp-tools-changed>system→agentserver="…" added="N" removed="N" changed="N"noneA connected MCP server pushed notifications/tools/list_changed and the live re-list changed the session's tool registry: the body names the added, removed and changed qualified tool names so the agent plans against the real set (a no-op re-list emits nothing; a tool listed with a new description, schemas or annotations is named changed, and one whose new input schema no model can take is named removed).
<cp:shell-notice>system→agentkind="command-terminated|host-restarted|prompt"noneAsync shell notice: a command was terminated by a host crash (status indeterminate, never auto-reissued), the shell host restarted, or a command is blocked on an interactive prompt (answer via shell_write_stdin).
<cp:shell-exit>system→agentcommand, exec-id, exit-code, signal, terminated, stopped-bynoneA watched background command exited: the watch is armed by default for any bash command that backgrounds past its timeout, and stays opt-in via notify_on_exit: true on shell_spawn or a prompt-parked command. Its attributes name the command (its first line), its exec id and how it ended; the body is the command's output tail (ANSI-stripped, bounded), so the agent can act without a shell_output round-trip. Mid-turn it drains into the next round like any channel, and one that lands after the round's drain continues the turn; when the session is idle the daemon drives a wake turn on it, so a finished command always gets acted on: no polling; the wake's chat row names the command and how it ended (cargo build (e3) ended with exit code 0) and opens to the notice, its output shown as written. A watched command can also be LOST without an exit: a shell-host restart emits the same channel with terminated="<reason>" (result indeterminate, never reissued), and a session crash-respawn drains the dead incarnation's watch and drives a wake turn naming the lost commands, the agent reconciles instead of waiting on an exit that can never come. A command the user stopped from /jobs ended as requested: its notice carries stopped-by="user", which the system prompt says means don't restart it unless the user asks, and waits for the next round instead of waking the session or continuing a turn; a crash-respawn leaves it out of the lost commands.
<cp:plugin-inject>system→agentplugin="<name>"noneA plugin's kcode.inject(text) wake (the "inject" permission): the plugin-facing face of the eventsource wake path. The body is the plugin's injection text, which a wake's chat row opens to as written. Mid-turn it drains into the next round like any channel; when the session is idle the daemon drives a wake turn on it, so a plugin can wake its session (a tail watcher, a long-poll monitor) instead of waiting for the user. Empty injections are dropped.
<cp:context-usage>system→agentused="…" window="…" pct="…" compacts-at="…"noneThe live token budget (tokens used / model window / percent, and compacts-at: the token count at which an automatic compaction runs, absent when it is off), so an autonomous agent can see how full its context is. Emitted only when the fill crosses a band boundary measured against that trigger (comfortable below 70% of it, filling from 70%, nearly full from 90%; against the effective input budget when automatic compaction is off), not every round, since each emission is injected into the transcript. The body names the trigger count; nearly full says a compaction runs before one of the agent's next steps, or that it is off, with the nudge to finish the current step or call compact.
<cp:permission-denied>system→agenttool="…" reason-code="…" path="…"?noneA tool call was blocked by the permission layer. Carries the tool, the reason-code enum (from permissions::DenialKind), and the offending path when there is one, so the agent can adjust rather than retry blindly.
<cp:plan-mode>system→agentconstraint="read-only" round="…"nonePer-round reminder while an agent kind that runs in plan mode is working (permission_mode: plan: the planner, security-reviewer and advisor kinds): tool calls are limited to read-only operations (no edits, and a shell command runs only when it only reads) though the agent's own task list, timers and memories stay available, and the user executes the assembled plan.
<cp:tool-empty-output>system→agenttool="…"noneNudge fired when a tool returned an Ok outcome whose payload was null or empty: prompts the agent to verify the input or change approach rather than assume success.
<cp:turn-summary-missing>system→agentnoneonce per turnReminder queued when a streamed round completes with no <turn-summary> signal: the session's status line (its working strip and tile, or a subagent's live row) is built from it, so a silent round reads as a dead 'Working…'. Injected at the next round boundary (as a synthetic user message when no control plane is wired: headless/tests); a reminder, not an error.
<cp:agent-status-malformed>system→agentnoneonce per turnNote added when the agent's <agent-status> names no state, or one other than done or continue: kcode ends the turn there, keeps the reply as the turn's answer, and the note names the bad state. The chat shows it as a notice, and /control shows the bad status as written.
<cp:reply-cut-off>system→agentnoneeach cut-off, up to the retry schedule's attemptsNote added when a reply is cut off partway: the connection lost, the stream broken, or a stall once the reply had started. The text that arrived stays as the assistant message, and the note, right after it, names the failure and tells the model to carry on from where it stopped without repeating it, and to write again any tool call it was making (one cut off before any text arrived requests the reply again). The next round carries the reply on, and the turn's answer starts with the text that arrived. Cut-offs in a row count against the failure's retry schedule (agent_loop.provider_retry, or agent_loop.provider_overload_retry for an overloaded vendor); once they run out the turn ends with 'Provider still failing after N attempts: <error>. Resend to retry.' A core.provider.error intercept decides each one, with streamed set.
<cp:memory>system→agentop="…" scope="…" hit-count="…"?noneA memory save / delete / recall occurred. Carries the operation, the scope, and (on a recall) the hit-count, so the agent sees memory activity in-context.
<cp:memory-recall>system→agentcount="…" names="…"nonePer-turn auto-recall ([memory] auto_recall): the turn's input queried the memory store's ranking and the floor-passing top-k memories ride this block, name, scope, description, body, and the date it was written. Injected beside the user's message in round 1; auto-recalls don't stamp recency or raise <cp:memory> events. The count and names attributes name the memories it holds. The turn also saves a one-line 'Recalled N memories into context: a, b, c.' notice in the chat, after your message (a recall changes what the model reads, so it shows like a compaction; the long bodies stay in /control).
<cp:tool-suggestion>system→agenttools="…"one per messageThe tools the user named with @ in the message before it (@grep, @web_search), comma-separated in tools. Only names the turn offers the agent count, so an email address or a tool the session lacks adds nothing, and a message that names none gets no note. Sent after the typed prompt and after each queued message pulled into a running turn; the mentions stay in the message as typed. The system prompt tells the agent to treat it as a suggestion, not an order. Shown in /control.
<cp:compaction-start>system→agent(none)noneA compaction pass just started: emitted the moment the threshold check passes and the summarization LLM round-trip begins. The daemon fans it to subscribers as a persistent 'Compacting context…' transcript bubble (CommandReplyKind::Compaction, not a toast) and raises the tile to Working, so an idle session running a manual /compact shows both that it started and that it's still working. Paired with <cp:compaction> on completion.
<cp:compaction>system→agentstrategy="…" tokens-before="…" tokens-after="…" messages-summarized="…" messages-kept="…"noneA compaction pass completed, carrying the strategy, the before/after token counts, and how many messages the summary replaced and how many recent ones were kept verbatim (the body names them too, and the images the pass cleared). The daemon fans a 'Context compacted (strategy): before → after tokens (N messages summarized, M recent kept)' transcript bubble (CommandReplyKind::Compaction) and pushes a corrected usage report so the chat footer's token/context count drops to the post-compaction figure immediately. The summary reaches the model once, as the first message of the model projection; nothing is added to the system prompt.
<cp:subagent>system→agentstate="started|unawaited|finished|failed" id="…" kind="…" name="…"? started-by="agent|subagent|plugin|user"? rounds="…"? error="…"?noneDelegation lifecycle: a subagent the parent spawned started, finished (with its round count, final text, its answer to the spawn's output_schema and the checkout it kept its changes in), or failed (with an error summary). started-by names who started it (the session's agent, one of its subagents, a plugin or the user) and a start, finish or failure notice names the subagent's task. The start of a subagent a spawn tool started shows only on the /control timeline, since the spawn already told the agent. A finish whose result a tool call returned (spawn_subagent's, or one an await_subagent was waiting on) shows only on the /control timeline, so the agent reads each result once. rounds counts the child's provider rounds, taken from the child turn's usage, not the number of tokens it streamed. Surfaces work-in-flight to the parent. A subagent a plugin started (kcode.spawn_subagent) carries the name the plugin gave it, and its finish or failure wakes an idle session with the notice, since no turn waits on it: one the user stopped doesn't; the wake's chat row opens to the task and result formatted, as a reply is. So does an async subagent (spawn_subagent_async) the session's own agent started and no await_subagent is waiting on, and one whose spawn_subagent call the user stopped; one a subagent started reaches it only through await_subagent, since a subagent never reads the session's notices. The finish of a subagent the user started with /agent joins the agent's next round without waking the session. When the session crashes, the subagents still running stop with it, and the restart's wake turn names each one the agent knew of (any but a subagent's own) so it doesn't await a result that can never come. state="unawaited" names an async subagent whose result only await_subagent reads (still running, or finished with its result kept for an await) when the agent's turn would end, once, so the agent can await it by its id in that turn before the result is lost.
<cp:time>system→agentutc, local, (duration_ms on tool results), (origin on user-role messages), (hook on a hook's prompt), (trigger on a trigger's text)noneThe moment the message it trails was written, in UTC and in your local zone. Rides on the end of every message kcode authors (agent_loop.time_metadata, on by default) so the agent can read elapsed time off its own history. Two optional per-message attributes refine it: a tool result carries duration_ms (that call's own wall time, which the gap between two stamps can't isolate), and a user-role message carries origin (typed / queued / channel / nudge / plugin / hook / trigger) so the agent can tell fresh typed intent from a queued message that may be stale or already answered, from a project hook's prompt, which also carries hook, the hook's name, or from a kcode trigger's text, which also carries trigger, the trigger's name. Read-only: the agent never emits it.
<cp:mailbox>system→agentfrom, tounboundedA message from a named agent in this session arrived in the main agent's mailbox.
<cp:steer>system→agentfrom, sessionunboundedAnother session in this project sent instructions with manage_session's steer: from is its name and session its id. The agent reads it at its next round; an idle session wakes to it. Where it conflicts with the user's instructions, the user's win.
<cp:worktree-merged>system→agentslug, branch, commit, kindnoneA worktree session's branch was merged into this session's tree (the user ran /worktree merge). Emitted by the daemon into the receiving session: the body carries the diffstat and the worker's final report (its last assistant message), kind says squash or true merge. Queued for the agent's next round and shown live as a transcript bubble.
<cp:semantic-index>system→agentstate=ready|failed, ready=true|false, initial=true (startup report only)one initial state, then change-onlyThe project's semantic index is usable or a refresh/cache load failed. New sessions restore saved data without scanning source or loading a model and receive the current ready/failed state with initial=true. Missing caches remain lazy until the first query. Ready means a deferred search can be retried. Failure names the error and whether an older usable index remains. Queued for the next agent round; never starts a new turn in an idle session. Use text search or LSP while indexing instead of polling.
<cp:lsp-diagnostics>system→agentpath, countunboundedFresh LSP errors on a file the agent just edited or wrote (a post-edit digest; only from already-spawned servers, and only once the check the edit's save started, such as rust-analyzer's cargo check, has finished).
<cp:external-trigger>system→agentname, target, sessionunboundedA kcode trigger's text ran in this session: CI/cron/sidecar provenance for the turn, shown in /control. The text itself shows in the chat under a trigger · <name> label and reaches the agent stamped origin="trigger" with the trigger's name.
agent→system
<agent-status>agent→systemstate="done|continue"noneTurn-control signal inside <control-plane>, after its required <turn-summary> child. Use done when ending the turn, continue for another round without pending tool calls; omit it on a tool-call round. The first valid occurrence controls continuation and an invalid state hard-stops the turn. Signals are excluded from the model's replayed prose; original history retains the response. The done body is a short summary that shows only in /control: what a subagent hands back and kcode -p prints is the round's reply, and the body only when that round wrote no reply.
<goal-status>agent→systemstate="done|blocked"noneGoal exit declaration inside <control-plane>: done means every goal sub-task was verified; blocked names a required decision, credential or external dependency. The daemon disarms /goal nudges and posts the summary as a notification. Goal status does not end the turn; pair it with <agent-status state="done"> when ending. The system prompt and idle nudges share this contract. Invalid goal status never hard-stops a turn.
<compact>agent→systemtype="fact|learning|decision|request|response|tool"noneStructured turn summary preserved in history. Used by the compaction engine to build session digests.
<plan-revision>agent→systemfrom="…" to="…" reason="…"nonePlan-modification tracker. Preserved in history for an auditable trail.
<agent-thinking>agent→system(none)noneA brief decision summary inside <control-plane>: relevant evidence, a trade-off or the next step, not an internal reasoning transcript. Visible in the control pane and excluded from model-context replay.