← 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.
8 entries · kcode 0.4.0
8 shown
| Event | Payload | Fires when | Used for |
|---|---|---|---|
| permissions.mode_changed | PermissionModeChangedEvent | Mode flip via /permissions, ask resolution, or persistent state reload. | 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), the turn lifecycle (core.app.turn-started/core.app.turn-finished/core.app.turn-error), 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), 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 (Area 2). kcode owns core.*; each plugin owns plugin.<id>.*. The loop fires core.turn.start/end, core.round.start/end, core.tool.pre/post/error, core.provider.request/response/error, core.compaction.gate; the daemon fires core.session.start/stop/fork; the subagent runner fires core.subagent.pre/post; the event sources fire core.fs.change, core.timer.tick, and the core.app.* family (turn-started/finished/error, assistant-output, tool-started/finished, subagent-started/finished). Plugins watch via kcode.on_event("core.<…>", …); a plugin can never emit into core.*. | The named attach-point contract every plugin hook, [[hooks]] entry, and the /control drawer dispatches on — one dotted name 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> so the /control drawer shows each hook run and its error summary. |
| 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/signal + output tail, or a LOST/indeterminate notice); the daemon wakes an idle session on it, the loop continues a turn it lands in (cascade rule 5), and the daemon counts outstanding watches for keep-awake. |