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
| Event | Permission |
|---|---|
focus.changed, focus.sensitive | focus:read |
system.idle_changed | idle:read |
dictation.started, dictation.heard, dictation.stopped, dictation.final, dictation.delivered, dictation.diverted, dictation.cancelled, dictation.failed | dictation:observe |
pill.slot_clicked | pill:slot |
stt.changed, llm.changed, profile.changed | none |
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
| Field | Type | Meaning |
|---|---|---|
process_name | string | Foreground process. Kept even when sensitive. |
window_title | string | Empty when sensitive is true. |
exe_path | string or null | Executable path when the OS provided one. |
window_id | number or null | Windows HWND, macOS process id, or Linux X11 window id. |
sensitive | boolean | The foreground app is on the sensitive list. |
source | live or cached | Live OS query, or the last cached foreground. |
EngineSnapshot
Sent by stt.changed, llm.changed, and engine.current. Never includes an API key.
| Field | Type | Meaning |
|---|---|---|
slot | stt, polish, or commands | Which engine. |
connected | boolean | The slot can run. |
placement | local or cloud | Where it runs. |
provider | string | Provider id. |
model | string | Model id. |
profile_id | string | Active profile. |
reason | ready, key_missing, or download | Present when the host has a reason. Omitted otherwise. |
TakeDeliveryFact
dictation.delivered uses this object as data (not nested under another key).
| Field | Type | Meaning |
|---|---|---|
take | number | Same id for every event in one hold. |
outcome | insert, clipboard_fallback, or review | How the text reached the speaker. |
raw_text | string or omitted | Transcript before polish. Omitted when the focus is sensitive. |
final_text | string or omitted | Text after polish. Omitted when the focus is sensitive. |
mode_id | string | Profile used for the take. |
duration_ms | number | Hold length. |
word_count | number | Words in the text that was kept. |
focus | FocusSnapshot | Foreground at delivery. |
context_sources | string array | Omitted when empty. |
history_entry_id | string or omitted | History row, when one was written. |
Event payloads
| Event | data |
|---|---|
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.delivered | TakeDeliveryFact |
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.