← Reference
Events and hooks
Internal events surfaced on the event bus.
Full notes from the app
Subscribers include the control drawer, the EventLog, metrics exporters, and user hooks.
9 entries · kcode 0.6.5097
9 shown
| Event | Payload | Fires when | Used for |
|---|---|---|---|
| core.semantic.started / core.semantic.ready / core.semantic.failed | { root, kind, status, initial } | A project semantic refresh starts, a new or cached generation becomes searchable, or refresh fails. After plugins load, a new session receives the current ready/failed state with initial=true; later changes carry false. An unchanged refresh does not duplicate the ready event. | Observe-only hooks for every session in that checkout, including Lua kcode.on_event handlers. Initial catch-up is local to the new session, not repeated to existing sessions. Contains status and diagnostic errors, never indexed source or query text. Separate ready/failed notices inform the agent at its next round. |
| permissions.mode_changed | PermissionModeChangedEvent | A mode change: /permissions, the launch flags, or a session coming back live in the mode its row records. | Refreshes permission-context channel; drives status-bar indicator. |
| channel.emitted | ChannelEmittedEvent | Any <cp:*> system→agent or agent→system emission. | Control-plane pane live view; EventLog persistence. |
| channel.dropped | ChannelDroppedEvent | Rate-limit cap hit on event-trigger, hook-fired, or fs-change. | Observability: surfaces dropped-counter in /stats and the control-plane footer. |
| triggers.fired | TriggerFiredEvent | A session event source fired: core.fs.change (project watcher, gitignore-filtered), core.timer.tick (config eventsource_timer.crons, or a plugin-owned schedule, manifest [triggers] / kcode.on_cron, fired from source plugin-timer with {owner, name, schedule} and Observe intent, in one open session for the app, for each project or for each session as its fires_per says), the turn lifecycle (core.app.turn-started/core.app.turn-finished/core.app.turn-error/core.app.turn-interrupted-user/core.app.turn-interrupted-agent: each turn end fires one of the last four, and a turn ended by its own session stopping fires none), tool activity (core.app.tool-started/core.app.tool-finished: every tool-registry invocation publishes a start/finish pair, Observe intent), subagent lifecycle (core.app.subagent-started/core.app.subagent-finished: every spawn, name-correlated, the finished fire carrying the child's answer; Observe intent), what a session waits on (core.app.waits-changed: fired by the daemon when a permission ask or a question opens, is answered or is dropped; Observe intent), a session's attention (core.app.attention-changed: fired by the daemon when a session goes idle, starts working, needs your input or shows an error; Observe intent), a webhook (webhook:<name>: an authenticated POST to the loopback listener or a kcode trigger fire, data {name, text, json?}, Observe intent), or a plugin emission (kcode.emit → kind plugin.<emitter>.<kind>, source plugin:<emitter>, Observe intent). | Matches registered hooks (including Lua kcode.on_event handlers) and routes to <cp:event-trigger> (fs fires surface as <cp:fs-change> instead; Observe-intent fires are hook-only, never agent-visible). |
| core.* | TriggerFiredEvent (kind = core.<area>.<event>) | The one owned event namespace. kcode owns core.*; each plugin owns plugin.<id>.*. The runtime fires core.prompt.build once per session build (start, resume, reload); the loop fires core.command.pre/post (around a turn a slash command produced: the client names the command on the wire), core.input.submit (for a typed turn on a session transcript, not a wake turn, not a delegated child's), core.model.select, core.turn.start/end, core.round.start/end, core.context.build, core.tool.pre/post/error, core.shell.pre, core.provider.request/response/error, core.continuation.decide, core.compaction.gate, core.compaction.summarize; the daemon fires core.session.start/stop/fork; the subagent runner fires core.subagent.pre/post; the agent's run_command fires core.command.pre/post around a prompt command it names; the skill runner fires core.skill.pre/post around a skill run, the agent's run_skill or a user's /<name>; the semantic index fires core.semantic.started/ready/failed; the event sources fire core.fs.change, core.timer.tick, and the core.app.* family (turn-started/finished/error/interrupted-user/interrupted-agent, assistant-output, tool-started/finished, subagent-started/finished, job-finished); the daemon fires core.app.waits-changed, core.app.attention-changed and core.app.presence-changed. One copy per session: each session loads its own copy of every plugin, on its own event bus, so a plugin's handlers hear only that session's events, core.app.* included, and no copy sees every session's; the copies share only the plugin's kv keys: the user scope for a user plugin, the project scope for a project one. One payload per point: each point carries one set of fields, a handler reads them as the event's data (ev.data.summary in Lua), and the watch fire and the intercept call of a loop point carry the same fields (triggers_framework::payloads) (core.prompt.build {session_id, sections, order}) the system prompt as named sections (sections maps a name to its text, order lists the names in assembly order), fired by agent-runtime once when the session's stack is built and never mid-session; session_id is empty on the headless path, which builds its stack before a session exists; core.input.submit {session_id, text} (what the user submitted, as typed, fired before the model is chosen; core.model.select {session_id, model, prompt, effort, delegated, agent_name}) the turn as it is about to start, before core.turn.start; delegated marks a subagent's turn; core.turn.start {session_id, model}; core.turn.end {session_id, model, tokens_in, tokens_out, elapsed_ms, rounds}; core.round.start / core.round.end {session_id, round}; core.context.build {session_id, round, model, messages}, the messages the next request will carry, one {id, role, content, synthetic, call_id, is_error, tool_calls, images} each, fired before the request point and only when a plugin intercepts or watches it; core.provider.request {session_id, round, model, max_tokens, temperature, effort, thinking, stop_sequences, tools} (the call as it goes on the wire; core.provider.response {session_id, round, model, ttfb_ms, total_ms, input_tokens, output_tokens, tool_calls, stop_reason}; core.provider.error {session_id, round, model, error, attempt, max_attempts, streamed, action, delay_ms}) the loop's own decision (retry after delay_ms, or stop) rides in the payload, max_attempts is the cap of the failure's retry schedule (agent_loop.provider_retry, or agent_loop.provider_overload_retry for an overloaded vendor), streamed marks a failure after the reply started (reply text, a tool call or the stop reason: thinking starts no reply, and usage counts and empty tokens show nothing): a reply cut off partway, which a retry carries on in a new round; core.tool.pre {session_id, round, call_id, tool, args}; call_id is the model's id for the call, the same on the call's core.shell.pre and on its core.tool.post or core.tool.error, so a plugin can match a result to its call when a round runs several at once; a plugin's or a script skill's kcode.run_tool call has none; core.shell.pre {session_id, round, call_id, tool, command, argv?}, the shell command a call of kcode's own bash, shell_spawn or shell_proceed is about to run (a proceed runs its plan's command; an abort runs none), fired after the core.tool.pre chain and before the permission check; a plugin's own tool named bash fires none; a plugin's kcode.exec fires it too, for every other plugin's handlers, with tool = kcode.exec, round 0, no call_id, command the program and its arguments quoted as a shell would read them, and argv, the list itself (the one field only an exec carries; core.tool.post {session_id, round, call_id, tool, args, content, is_error}; core.tool.error {session_id, round, call_id, tool, args, content}) args as the call ran with them; core.continuation.decide {session_id, round, tool_calls, last_text, vote, reason} (after every round; tool_calls is how many tool calls the round made; core.compaction.gate {session_id, round, before_messages, used_tokens, trigger_tokens, deferrals, max_deferrals}) fired only when a pass is due; core.compaction.summarize {session_id, messages, conversation, previous_summary, instructions, required_sections}, the Summary pass as it is about to run (the serialized messages being summarized, the earlier summary on a repeat pass, the user's /compact text, the template's section headings case-folded), built and fired only when a plugin watches or provides it; core.subagent.pre {session_id, id, kind, name, prompt, model, effort} (the spawn as requested, fired before the child is registered; core.subagent.post {session_id, id, kind, name, model, success, rounds, error}) once per pre, a refused spawn included; core.command.pre {session_id, command, args, by, text}, a prompt command about to run: its name, the text after it as typed, who ran it (by = user for a slash command the client expanded, fired by the loop before core.input.submit; agent for the model's run_command) and the expanded prompt; core.command.post {session_id, command, args, by, applied, error}, once per pre: applied says the prompt was handed on (a prompt command has no return value), a veto posts applied: false with its text; core.skill.pre {session_id, skill, args, by, inputs}, a skill run as requested, before its state home and lock are taken, who ran it (by = user or agent) and the text that filled $ARGUMENTS and $n (args (what the user typed, or the agent's arguments) empty for a skill with typed inputs); core.skill.post {session_id, skill, args, by, success, error}, once per pre: a guide skill counts as run when its guide reaches the model (a user's /<name> once its prompt passes core.input.submit, whose veto posts success: false), a script skill by its outcome, a refused run posts success: false with the reason. The watch-only points carry: core.session.start {session_id, project_root}; core.session.fork {session_id, child_session_id} (fired on the session the fork was made from; core.session.stop {session_id}) once for each run that fired core.session.start, when it is stopped, crashes or the app quits; a crashed session's restart is a new run with its own start; core.fs.change {path, kind}, path relative to the project, kind one of created, modified, removed, renamed, attribute_changed; core.timer.tick {cron_expr, job_id} from an eventsource_timer.crons entry (source timer), or {owner, name, schedule} from a plugin's own schedule (source plugin-timer); core.app.turn-started {session_id, model, agent}, agent the subagent that ran the turn, null for the session's own agent, as in every core.app.turn-* event; core.app.turn-finished {session_id, tokens_input, tokens_output, elapsed_ms, agent}; core.app.turn-error {session_id, summary, agent} (summary is the error's text; a stopped turn is no error; core.app.turn-interrupted-user {session_id, agent}) the user stopped the turn with Esc; core.app.turn-interrupted-agent {session_id, by_session_id, by_name, agent}, another session's agent stopped it, and by_name is that session's title or folder name; core.app.assistant-output {session_id, text} (one settled assistant message; core.app.tool-started {session_id, tool, args_preview, agent}) args_preview is a shortened copy of the arguments, agent the subagent that made the call, null for the session's own agent; core.app.tool-finished {session_id, tool, outcome, took_ms, error, agent}; outcome is ok, error or cancelled, error the error's text or null; core.app.subagent-started {id, kind, name, session_id, prompt_preview}; core.app.subagent-finished {id, kind, name, session_id, success, final_text, rounds, error} (name pairs it with its start, final_text is the child's answer; core.app.job-finished {session_id, id, owner, ok, text, error}) a job a plugin started with kcode.jobs.start ended: id is the id the call returned, owner the plugin, ok whether the job ran to its end, text its answer as far as it got and error why it failed or stopped (null when ok); only the plugin that started the job hears it, and a job fires no core.app.subagent-started or subagent-finished; core.app.waits-changed {session_id, waits}, what the session waits on the user for changed: waits lists each open permission ask and question, oldest first, as {what, request_id, tool, agent, summary, since_unix_ms}; what is permission or question, request_id stays the same while the prompt waits, tool is the tool a permission ask is for (null for a question), agent the subagent that asked (null for the session's own agent and for kcode), and summary the ask's first line or the question, at most 200 characters; an empty waits means the session waits on nothing now, and a fire that would list the same waits is not sent; core.app.attention-changed {session_id, from, to}, how urgently the session wants the user's eyes changed: from and to are each idle, working, needs-input or error, as the session's tile shows it, needs-input while a permission ask or a question waits, error after a failed turn, working while a turn, a /compact or one of its subagents runs; a session goes live idle, and a fire whose to would equal from is not sent; core.app.presence-changed {session_id, app_focused, in_view, idle, idle_seconds, screen_locked}; whether the user is at the Mac or sees the session changed, its fields as kcode.presence() gives them: while a plugin of some session watches the point the daemon reads the Mac every session_daemon.presence_poll_ms (1000), and checks again when a window reports what it shows or closes; the first reading after a plugin starts to watch is no change, and a change of idle_seconds alone is none; the core.semantic.* fields are listed with their own entry. What a plugin may do at each point is catalogued (triggers_framework::names::CoreEvent): every live point can be watched (kcode.on / kcode.on_event), core.app.presence-changed only with the presence grant on top of hooks and core.app.job-finished only with the jobs grant, a watch there without it fails the load naming the grant; fourteen can be intercepted (kcode.intercept), core.command.pre (veto; the command does not run: the user's slash-command turn ends before any provider call with The plugin "<name>" blocked the command: <reason>, the agent's run_command fails naming the plugin; rewrite text, the prompt the turn runs or the instructions the agent follows; command, args, by are read-only, so one handler gates both callers and tells them apart by by), core.skill.pre (veto: the run is refused before it starts, and a user's /<name> turn ends before any provider call with the reason in the chat; rewrite inputs, validated against the skill's schema after the rewrite, then executed; skill, args and by are read-only), core.input.submit (veto (the turn ends before any provider call, with the reason in the chat; rewrite text) the prompt the turn runs on and the user message the transcript records; kcode.on_input is the short form, in the same chain: a string or {text=…} rewrites, {veto=…} vetoes), core.prompt.build (rewrite sections and order only: replace, append to, drop or add a named section and place it; control-plane only grows, a section set to nothing is refused, a rewrite that breaks a rule is refused whole; no veto; the one point that needs a grant beyond hooks, prompt, and a plugin without it cannot attach there), core.context.build (rewrite messages only: cut a tool result's content to a short note, edit or drop a user or system message, insert a user message the model alone reads; an assistant message's content is ignored, an assistant or tool message may not be dropped, a kept message may not be emptied, nothing moves, and a rewrite that breaks a rule is refused whole; no veto, the request point right after carries the turn-level veto), core.provider.request (veto; rewrite max_tokens, temperature, effort, thinking, stop_sequences, tools: model is read-only, tools may only drop names, the rewritten ceiling and effort are re-clamped to the model, and a change the provider's call leaves out, a ChatGPT sign-in sends no max_tokens, temperature, stop_sequences or thinking, the other OpenAI-style providers no thinking, and on Claude the effort sets thinking and can change max_tokens, is named once per session, with the plugin and the field, as a warning in agentloop.log and an error in the plugin's Activity), core.provider.error (veto (the turn ends with the reason; rewrite action = retry/fallback/stop, delay_ms, model) a fallback names another model the rest of the turn runs on, a retry or stop keeps the model that failed, only stop is left on the last attempt, a reply cut off partway (streamed) is decided the same way, a fallback to a model no connected provider serves is refused, and a rewrite that breaks a rule is refused whole), core.tool.pre (veto; rewrite args; kcode.on_tool is the short form of a gate here, veto only, and the point covers a plugin's own kcode.run_tool call and a script skill's too, watched with round 0), core.shell.pre (veto only: the command does not run, and the model, or the plugin or script skill whose run_tool made the call, reads which plugin refused it and why, as a plugin's kcode.exec does; one gate covers every way kcode runs a command, where a gate on bash alone misses shell_spawn and a shell_proceed that runs its plan; a plugin's or a script skill's kcode.run_tool meets it with round 0), core.tool.post (veto; rewrite content, is_error), core.tool.error (rewrite content only: the error text the model reads; no veto, the failure already happened), core.continuation.decide (veto = stop; rewrite vote = continue/stop, reason), core.compaction.gate (veto only: puts the due automatic pass off, at most compaction.max_deferrals times in a row, then it runs regardless; overflow recovery never consults the gate), core.subagent.pre (veto: the spawn fails before the child is registered, and core.subagent.post still reports it with success: false; rewrite prompt, kind, model, effort; a rewritten kind must be a registered kind and the child takes its tools and permission mode, a rewritten model is a catalogue label or id a connected provider serves and JSON null, kcode.null from Lua, since a nil field is an absent key and leaves the field as it was. Clears it so the child inherits the session's, id/name/session_id are read-only); a rewrite of any other field is ignored and logged. A rewrite lands on the payload key by key: the fields the handler returns replace those fields and the ones it leaves out stay, so the next plugin in the chain and the loop read a whole payload, an args-only rewrite at core.tool.pre cannot strip tool from the next plugin's gate. Three are provide slots (kcode.provide: one plugin answers, the project plugin before the user plugin before the built-in, then by name): core.model.select (answer model: the model the turn runs on; a name no connected provider serves is refused), core.continuation.decide (answer vote, reason: the same ballot the intercept form rewrites, consulted after every round; a stop ends the turn whatever the round did, and a continue counts only on a round that would otherwise stop), core.compaction.summarize (answer summary (used verbatim, the model is not called) or instructions: weighed beside the user's /compact text; watch and provide only, no intercept). Every catalogued point fires. A handler that attaches where it would never run: a watch-only point as an intercept, a point with no slot as a provide, an unknown name, a retired pre-rename name (turn-finished, file-changed, cron-fire, …), or an intercept at any plugin.* event, fails the plugin's load naming the fix, and kcode plugins validate reports the same error. A plugin that loads once for the app (loads_per = "app") hears, with hooks and "sessions.all", every session's core.app.* events but core.app.presence-changed and core.app.job-finished, each event's data naming its session under session (id, project_root, project, title), and no other core.* point but its own core.timer.tick. Plugins can never emit into core.*. The loop's own points are never rate-capped; only the outside sources (core.fs.change, core.timer.tick) fall under triggers_framework.rate_limits. | The named attach-point contract every plugin hook, [[hooks]] entry, and the /control drawer dispatches on: one dotted name per point, one payload per point, replacing the ad-hoc kebab-case kinds. |
| triggers.hook_completed | HookCompletedEvent | A trigger hook (e.g. a Lua on_event handler) finished running, cleanly or with an error. | Routed to <cp:hook-fired> when the hook reports to the chat, so the /control drawer shows the run and its error summary; a silent hook's run (every plugin handler's) is not routed. |
| shell.notice | ShellNoticeEvent | A shell command was terminated by a host crash, the shell host restarted, or a command is blocked on an interactive prompt. | Routed to the <cp:shell-notice> channel so the agent sees the notice in-context. |
| shell.watch_exit | ShellWatchExitEvent | A watched background command exits (bash backgrounds are watched by default; shell_spawn watches are armed with notify_on_exit: true) or the command is lost to a shell-host restart (the terminated field carries the reason). One-shot per watch. | Routed onto the <cp:shell-exit> channel (exit code or signal and the output tail, or terminated for a loss); the daemon wakes an idle session on it, the loop continues a turn it lands in, and the daemon counts outstanding watches for keep-awake. |