Skip to main content
Kalam Documentation

Hooks

A hook is a fact. Kalam already did the thing. The worker cannot cancel it by returning a value. To change or consume a take, use an interceptor.

The host sends hooks the plugin is allowed to see as a JSON-RPC notification (no id):

{ "jsonrpc": "2.0", "method": "kalam.hook", "params": { "event": "dictation.delivered", "data": {} } }

params is tagged: event is the name, data is the payload. In @kalam/plugin-sdk this is the onHook argument.

Which permission delivers which event​

EventPermission
focus.changed, focus.sensitivefocus:read
system.idle_changedidle:read
dictation.started, dictation.heard, dictation.stopped, dictation.final, dictation.delivered, dictation.diverted, dictation.cancelled, dictation.faileddictation:observe
pill.slot_clickedpill:slot
stt.changed, llm.changed, profile.changednone

All listed hook events arrive over JSON-RPC. If a TypeScript helper from @kalam/plugin-sdk 0.1.0 only types the core dictation, focus, and idle hooks, cast or widen your handler parameter to read engine, profile, or slot click events.

Shared objects​

FocusSnapshot​

FieldTypeMeaning
process_namestringForeground process. Kept even when sensitive.
window_titlestringEmpty when sensitive is true.
exe_pathstring or nullExecutable path when the OS provided one.
window_idnumber or nullWindows HWND, macOS process id, or Linux X11 window id.
sensitivebooleanThe foreground app is on the sensitive list.
sourcelive or cachedLive OS query, or the last cached foreground.

EngineSnapshot​

Sent by stt.changed, llm.changed, and engine.current. Never includes an API key.

FieldTypeMeaning
slotstt, polish, or commandsWhich engine.
connectedbooleanThe slot can run.
placementlocal or cloudWhere it runs.
providerstringProvider id.
modelstringModel id.
profile_idstringActive profile.
reasonready, key_missing, or downloadPresent when the host has a reason. Omitted otherwise.

TakeDeliveryFact​

dictation.delivered uses this object as data (not nested under another key).

FieldTypeMeaning
takenumberSame id for every event in one hold.
outcomeinsert, clipboard_fallback, or reviewHow the text reached the speaker.
raw_textstring or omittedTranscript before polish. Omitted when the focus is sensitive.
final_textstring or omittedText after polish. Omitted when the focus is sensitive.
mode_idstringProfile used for the take.
duration_msnumberHold length.
word_countnumberWords in the text that was kept.
focusFocusSnapshotForeground at delivery.
context_sourcesstring arrayOmitted when empty.
history_entry_idstring or omittedHistory row, when one was written.

Event payloads​

Eventdata
focus.changed{ "focus": FocusSnapshot }
focus.sensitive{ "sensitive": boolean, "focus": FocusSnapshot }
system.idle_changed{ "state": "active" or "idle", "idle_secs": number, "focus": FocusSnapshot }
dictation.started{ "take": number }
dictation.heard{ "take": number, "text": string }
dictation.stopped{ "take": number }
dictation.final{ "take": number, "text": string } — raw final text, before polish
dictation.deliveredTakeDeliveryFact
dictation.diverted{ "take": number, "plugin_id": string, "interceptor_id": string }
dictation.cancelled{ "take": number }
dictation.failed{ "take": number, "can_retranscribe": boolean }
stt.changed{ "engine": EngineSnapshot }
llm.changed{ "engine": EngineSnapshot }
profile.changed{ "profile_id": string }
pill.slot_clicked{ "plugin_id": string, "slot_id": string, "action_id"?: string }

dictation.heard can repeat during one hold. Match on take if you join partial text to the final event.

A click on your Pill chip is also a request, kalam.pill.slot_click, with slot_id. Handle that in onPillSlotClick when you need a return value. The hook is the fact for every subscriber that holds pill:slot.

Config changed​

This is not a HookEvent. When someone saves plugin settings, the host sends:

{ "jsonrpc": "2.0", "method": "kalam.config_changed", "params": { "config": {} } }

definePlugin({ onConfigChanged }) receives that object. There is no id. Do not reply.