1# zot extensions
2
3zot can be extended with custom slash commands by running an external
4program as a subprocess and exchanging newline-delimited JSON over
5its stdin/stdout. Extensions can be written in **any language** that
6can read and write JSON lines from stdio — Go, TypeScript, Python,
7Rust, shell with `jq`, anything.
8
9Four phases shipped so far:
10
11- **Phase 1**: slash commands + chat notifications.
12- **Phase 2**: tools the LLM can call.
13- **Phase 3**: lifecycle event subscriptions + tool-call interception
14  for guardrail extensions.
15- **Phase 4**: interactive extension-owned panels rendered inside zot.
16- **Theme-only extensions**: ship `theme.json` without launching a
17  subprocess. See [themes.md](themes.md).
18
19## Quick start
20
21The simplest extension is a script that prints a hello frame, reads
22commands, and prints responses. Here's the whole thing in **Python**,
23no SDK required:
24
25```python
26#!/usr/bin/env python3
27# $ZOT_HOME/extensions/hello-py/hello.py
28import json, sys
29
30def emit(obj):
31    sys.stdout.write(json.dumps(obj) + "\n")
32    sys.stdout.flush()
33
34emit({"type":"hello","name":"hello-py","version":"1.0.0","capabilities":["commands"]})
35
36for line in sys.stdin:
37    msg = json.loads(line)
38    if msg["type"] == "hello_ack":
39        emit({"type":"register_command","name":"hellopy","description":"say hi (python)"})
40        emit({"type":"ready"})
41    elif msg["type"] == "command_invoked":
42        emit({"type":"command_response","id":msg["id"],"action":"prompt",
43              "prompt": "Greet me very briefly in one sentence."})
44    elif msg["type"] == "shutdown":
45        emit({"type":"shutdown_ack"})
46        break
47```
48
49Drop it in a directory with this `extension.json`:
50
51```json
52{
53  "name": "hello-py",
54  "version": "1.0.0",
55  "exec": "./hello.py",
56  "language": "python",
57  "enabled": true
58}
59```
60
61`exec` is required for protocol extensions. If an extension only ships
62`theme.json` or `themes/theme.json`, no `exec` is required and zot does
63not spawn a subprocess. A skill-only bundle may instead provide a `skills`
64array and is also never spawned.
65
66`chmod +x hello.py`, install:
67
68```bash
69zot ext install ./hello-py
70```
71
72Restart `zot`, type `/hellopy`, the agent greets you. Done.
73
74## Built-in extensions
75
76**zot ships with no extensions installed by default.** A fresh `zot install` (or `go install`) gives you a clean agent. Extensions are entirely opt-in: you install (or `--ext` for one run) only the ones you want.
77
78The `examples/extensions/` directory in the repo is reference code, not a default install set. To use any of those:
79
80```bash
81# go-based examples need a build first
82cd path/to/zot/examples/extensions/hello && go build -o hello .
83
84# install (copies to $ZOT_HOME/extensions/hello/)
85zot ext install path/to/zot/examples/extensions/hello
86
87# or load straight from the repo for one zot session
88zot --ext path/to/zot/examples/extensions/hello
89```
90
91Nothing is auto-installed and nothing reaches out to the network without your explicit action.
92
93## Layout & discovery
94
95zot scans two directories on startup, in this order:
96
971. **Project-local**: `./.zot/extensions/<name>/extension.json`
982. **Global**: `$ZOT_HOME/extensions/<name>/extension.json`
99
100A project-local extension with the same name wins over a global one.
101When `XDG_STATE_HOME` is set on any platform, `$ZOT_HOME` defaults to
102`$XDG_STATE_HOME/zot`. Otherwise it defaults to `~/Library/Application Support/zot/`
103on macOS, `~/.local/state/zot` on Linux, or `%LOCALAPPDATA%\zot` on Windows.
104
105Because each extension owns its own directory, the recommended place
106for extension state is inside that directory itself (for example
107`todos.json`, `settings.json`, or an auth/cache file used only by that
108extension). The host also passes this path back in `hello_ack` as
109`extension_dir` / `data_dir` so runtime code does not need to guess it.
110
111Each extension owns its own subdirectory. The `extension.json`
112manifest tells zot how to launch it:
113
114```json
115{
116  "name": "weather",
117  "version": "1.0.0",
118  "exec": "./weather",
119  "args": ["--mode", "daemon"],
120  "language": "go",
121  "description": "current weather for any city",
122  "enabled": true
123}
124```
125
126| field | meaning |
127|---|---|
128| `name` | required. how zot identifies the extension; must match what's sent in the `hello` frame. |
129| `version` | optional. shown in `zot ext list`. |
130| `exec` | required. path to the executable (relative to the manifest). |
131| `args` | optional. extra argv passed to `exec`. |
132| `language` | optional. informational only (`go`, `python`, `typescript`, ...). |
133| `description` | optional. shown in `zot ext list`. |
134| `skills` | optional. directories (recursively scanned) or direct `SKILL.md` paths, relative to the manifest. |
135| `enabled` | optional, defaults to `true`. set to `false` to disable without removing. |
136
137## Lifecycle
138
1391. **Discovery**: zot reads every `extension.json` in the search dirs.
1402. **Spawn**: enabled extensions are launched as subprocesses. stderr
141   redirects to `$ZOT_HOME/logs/ext-<name>.log` (one file per
142   extension, append-mode).
1433. **Hello handshake**: the extension's first stdout frame must be
144   `hello`; zot replies with `hello_ack` containing the protocol
145   version, the active provider/model/cwd, and the extension's own
146   data directory so it can persist files beside its manifest.
1474. **Registration**: after receiving `hello_ack`, the extension sends
148   `register_command`, `register_tool`, and subscription frames, then
149   sends `ready`. First-come-first-served: a name already taken by a
150   built-in or by a previously-loaded extension is silently shadowed
151   (logged in the extension's own log file).
1525. **Runtime**: after `ready`, zot dispatches `command_invoked` frames
153   when the user runs a registered command; the extension responds
154   with `command_response`. Extensions can also push `notify` frames
155   during runtime. Panel-capable extensions may open an interactive
156   panel, receive key events, and push redraws while the panel is
157   focused.
1586. **Shutdown**: when zot exits, it sends `shutdown` and waits up to
159   2s for the extension to send `shutdown_ack`. Holdouts are
160   SIGTERM'd, then SIGKILL'd.
161
162A crashing extension does not bring down zot. The slash command it
163owned simply stops working until the extension is fixed and zot is
164restarted.
165
166## Wire format
167
168All frames are one JSON object per line. Top-level `type` is the
169discriminator. Optional `id` correlates request frames with their
170responses. The canonical startup order is `hello`, `hello_ack`,
171registration frames, then `ready`. Do not send `notify`, logs, or any
172other stdout frame before `hello`.
173
174### Extension → host
175
176#### `hello` (required, first frame)
177
178```json
179{"type":"hello","name":"weather","version":"1.0.0",
180 "capabilities":["commands","tools","panels"]}
181```
182
183#### `register_command`
184
185```json
186{"type":"register_command","name":"weather",
187 "description":"current weather for a city"}
188```
189
190Command names are matched case-insensitively. zot sends `command_invoked.name` using the canonical spelling registered here. Registrations that differ only by case conflict, and the first registration remains active.
191
192#### `register_tool`
193
194Registers a tool the LLM can call. `schema` is a JSON Schema object
195describing the tool's args (the same shape Anthropic and OpenAI accept).
196
197```json
198{"type":"register_tool","name":"weather",
199 "description":"Get the current weather for a city.",
200 "schema":{
201   "type":"object",
202   "properties":{"city":{"type":"string"}},
203   "required":["city"]
204 }}
205```
206
207Tool names live in the same namespace as built-in tools (`read`,
208`write`, `edit`, `bash`, `skill`). Conflicts are silently shadowed by
209the built-in.
210
211Set `"deferred": true` to register a tool without advertising its definition initially. A loader tool can activate registered deferred tools by returning their names in `activate_tools`:
212
213```json
214{"type":"tool_result","id":"...",
215 "content":[{"type":"text","text":"Enabled weather lookup"}],
216 "activate_tools":["weather"]}
217```
218
219On Kimi K3's OpenAI-compatible routes, zot places newly activated schemas at the tool-result position using Kimi's native deferred-tool format. Other models receive the complete active tool list on the next request. Unknown names are ignored. The Go extension SDK exposes `DeferredTool` and `ToolResult.ActivateTools` for the same protocol.
220
221#### `ready`
222
223Sentinel telling zot "all initial registrations are flushed". Send it
224right after your last `register_*` frame so the host can build the
225agent's tool registry without racing the registration window.
226
227```json
228{"type":"ready"}
229```
230
231#### `tool_result`
232
233Reply to a `tool_call` from the host. `content[]` is a list of
234message blocks; each block is `{"type":"text","text":"..."}` or
235`{"type":"image","mime_type":"image/png","data":"<base64>"}`. Set
236`is_error: true` to mark the call as failed. `activate_tools` can name
237registered deferred tools that become available after this result.
238
239```json
240{"type":"tool_result","id":"...",
241 "content":[{"type":"text","text":"Berlin: 16°C, fog"}]}
242```
243
244#### `subscribe`
245
246Declares which lifecycle events the extension wants to observe and
247which it wants to intercept. Send once after `hello`, before `ready`.
248
249```json
250{"type":"subscribe",
251 "events":["session_start","turn_start","tool_call","tool_confirmation_requested","turn_end","assistant_message"],
252 "intercept":["tool_call","turn_start","assistant_message"]}
253```
254
255Recognised event names: `session_start`, `session_end`, `user_prompt_submit`,
256`turn_start`, `turn_end`, `tool_call`, `tool_result`,
257`tool_confirmation_requested`, `permission_decision`, `assistant_message`,
258`pre_compact`, `post_compact`, `subagent_start`, `subagent_stop`.
259The new lifecycle events are observational only; adding them to `intercept`
260does not make them blocking hooks. See [Lifecycle payloads](#lifecycle-payloads).
261
262`tool_confirmation_requested` fires only when zot is about to wait for
263interactive approval. Calls running in yolo mode, calls covered by a
264remembered approval, and calls blocked before confirmation do not emit it.
265The event includes `tool_id`, `tool_name`, and the short `tool_preview`
266shown in the confirmation dialog.
267
268Interceptable events:
269
270- `before_agent_start`: inspect and replace the complete system prompt before
271  the first model call. See [System prompt replacement](#system-prompt-replacement).
272- `tool_call`: block the call (model sees `reason` as the tool
273  error) or rewrite args via `modified_args`.
274- `turn_start`: block the turn before the model is called. Useful
275  for rate-limiting and business-hour gates. `reason` is shown to
276  the user as a status line. No rewrite supported.
277- `assistant_message`: suppress the message via `block`, or rewrite
278  the user-visible text via `replace_text`. The model's original
279  text stays in the transcript so the model sees what it actually
280  said on subsequent turns.
281
282#### System prompt replacement
283
284Subscribe with `{"type":"subscribe","intercept":["before_agent_start"]}`.
285After prompt assembly (including context files, skills, and extension tools),
286zot sends a request before the first agent model call:
287
288```json
289{"type":"event_intercept","id":"start-1","event":"before_agent_start","session_id":"session-123","agent_run_id":"run-456","cwd":"/work/repo","provider":"anthropic","model":"claude-opus-4-7","system_prompt":"The complete current system prompt"}
290```
291
292Reply with an exact replacement:
293
294```json
295{"type":"event_intercept_response","id":"start-1","system_prompt":"The complete replacement system prompt"}
296```
297
298No trimming, merging, or appending is performed by the host. `""` intentionally
299removes the prompt; omission leaves it unchanged. `block` does not block startup.
300Extensions run serially in successful load order (explicit extensions first,
301then discovery); each receives the previous extension's result.
302
303The result remains stable across normal user messages, retries, and tool-loop
304steps. The event runs again after a model change, conversation clear, session
305change, or explicit prompt rebuild/reset (including interactive extension reload).
306Rebuilds start from the unmodified base prompt, not the last extension result.
307If a prompt rebuild/reset occurs while a hook is waiting, zot discards that
308preparation's result and runs the chain again against the current base prompt,
309even when the reset keeps the same text. The new pass has a new `agent_run_id`.
310Cancellation stops preparation without committing a pending replacement.
311`session_start` remains a separate one-way setup notification.
312
313`session_id` is the persisted conversation ID when available, otherwise a
314runtime-local ID. `agent_run_id` identifies one preparation pass and changes
315on each rebuild. It is shared by all extensions in that pass.
316
317Each extension has a five-second deadline including the request pipe write.
318Invalid/non-string values, malformed responses, crashes, and timeouts preserve
319the current prompt and produce an extension log diagnostic and host warning.
320An omitted value is a normal no-op. The encoded `system_prompt` response value
321is limited to 1 MiB; complete transport frames are limited to 4 MiB. Exceeding
322the frame limit disconnects the extension's read loop. A blocked request write
323closes its input pipe to release the writer. Other subscribed extensions still
324run unless the user cancels startup.
325
326Supported in interactive, print, JSON, and RPC modes. RPC warnings use
327`ext_notify`. Subscribed extensions see the entire prompt, including private
328context-file instructions. This feature is not a security boundary and does
329not change tool permissions or validate the safety of replacement instructions.
330
331#### `event_intercept_response`
332
333Reply to an `event_intercept` from the host. All fields default to
334"allow, pass through unmodified".
335
336| field | meaning |
337|---|---|
338| `block` | `true` refuses the action. For `tool_call`, `reason` is shown to the model; for `turn_start` / `assistant_message`, `reason` is shown to the user. |
339| `reason` | refusal text (on block) or pass-through note. |
340| `modified_args` | for `tool_call`: rewritten JSON args the tool will actually see. Must be a valid JSON object. Ignored when `block` is true. |
341| `replace_text` | for `assistant_message`: replaces the user-visible text. The model's original output still lives in the transcript. Ignored when `block` is true. |
342| `system_prompt` | for `before_agent_start`: exact string replacement, including an empty string. Omission keeps the current prompt. |
343
344Missing the response within 5s is treated as "allow, unchanged". For
345`before_agent_start`, this deadline also includes the request write; legacy
346interceptors start the timeout after writing the request. When multiple
347extensions subscribe to the same event, they're consulted serially;
348the first `block` wins for the blocking events and rewrites (args / text)
349chain. `before_agent_start` follows the non-blocking replacement rules above.
350
351```json
352{"type":"event_intercept_response","id":"...",
353 "block":true,"reason":"refused: matches danger pattern \"rm -rf\""}
354
355{"type":"event_intercept_response","id":"...",
356 "modified_args":{"command":"echo GUARDED: ls"}}
357
358{"type":"event_intercept_response","id":"...",
359 "replace_text":"[redacted]"}
360```
361
362#### `command_response` (reply to `command_invoked`)
363
364```json
365{"type":"command_response","id":"...","action":"prompt",
366 "prompt":"Show today's weather for Berlin in one line."}
367```
368
369`action` is one of:
370
371- `"prompt"` — submits `prompt` as a fresh user message; the agent
372  runs a turn against it.
373- `"insert"` — inserts `insert` into the editor at the cursor without
374  submitting.
375- `"display"` — appends `display` to the chat as a one-shot styled
376  note. No model call, nothing written to the transcript.
377- `"open_panel"` — opens an extension-owned interactive panel inside
378  zot. The panel content lives in `open_panel`.
379- `"noop"` — the extension handled it itself (e.g. it pushed
380  `notify` frames or kicked off background work). zot doesn't change
381  the UI in response.
382
383Example:
384
385```json
386{"type":"command_response","id":"...","action":"open_panel",
387 "open_panel":{
388   "id":"todos-main",
389   "title":"Todos",
390   "lines":["□ ship panel api","✓ persist state"],
391   "footer":"↑/↓ navigate - a add - x complete - esc close"
392 }}
393```
394
395If `error` is non-empty, zot renders it as a red status line
396regardless of `action`.
397
398#### `submit` (one-way, any time)
399
400Submits text as a user prompt in the interactive host. If the agent is
401idle, zot starts a turn immediately. If a turn is already running, zot
402queues the prompt behind it using the same queue path as typed input.
403Empty or whitespace-only text is ignored.
404
405```json
406{"type":"submit","text":"Summarize the selected workspace."}
407```
408
409In print / JSON / RPC modes this frame is ignored because there is no
410interactive editor or prompt queue.
411
412#### `panel_render` (one-way, while a panel is open)
413
414Pushes a fresh frame for an already-open panel.
415
416```json
417{"type":"panel_render","panel_id":"todos-main",
418 "title":"Todos",
419 "lines":["□ ship panel api","✓ persist state"],
420 "footer":"↑/↓ navigate - a add - x complete - esc close"}
421```
422
423#### `panel_close`
424
425Closes a previously-open panel.
426
427```json
428{"type":"panel_close","panel_id":"todos-main"}
429```
430
431#### `notify` (one-way, any time)
432
433```json
434{"type":"notify","level":"info",
435 "message":"refreshed cache (12 entries)"}
436```
437
438`level` is one of `info`, `success`, `warn`, `error`. The note shows
439up below the transcript with the extension's name in brackets. Notes
440are one-shot: they clear automatically when the user sends their next
441prompt (and on `esc` / `/clear`).
442
443#### `clear_notes` (one-way, any time)
444
445Removes every note this extension previously pushed via `notify` /
446`display`. Use it for transient status lines (e.g. an approval prompt)
447so they do not stack up; notes from other extensions are untouched.
448
449```json
450{"type":"clear_notes"}
451```
452
453In `--mode rpc`, this surfaces to the host as an `ext_clear_notes`
454event (alongside `ext_notify` / `ext_display`).
455
456#### `shutdown_ack`
457
458Sent in response to `shutdown`. Extension should exit promptly after.
459
460### Host → extension
461
462#### `hello_ack`
463
464```json
465{"type":"hello_ack","protocol_version":1,
466 "zot_version":"0.0.7","provider":"anthropic",
467 "model":"claude-opus-4-7","cwd":"/Users/pat/Developer/zot",
468 "extension_dir":"/Users/pat/Developer/zot/.zot/extensions/todos",
469 "data_dir":"/Users/pat/Developer/zot/.zot/extensions/todos"}
470```
471
472Sent immediately after `hello`. Wait for this frame before sending
473registrations if they depend on host metadata. The extension can use
474these fields to decide which commands to register (e.g. only register
475a Python tool on macOS, only register a model-specific shortcut for
476opus, etc.). `cwd` is the user's project directory; the extension
477process itself runs from the extension directory, so do not use
478`os.Getwd()` or `process.cwd()` when you need the project path.
479`extension_dir` / `data_dir` are where the extension should persist
480its own state (for example `todos.json`, cached metadata, or auth
481tokens scoped to that extension).
482
483#### `command_invoked`
484
485```json
486{"type":"command_invoked","id":"...",
487 "name":"weather","args":"berlin"}
488```
489
490`args` is everything the user typed after the command name, trimmed.
491
492#### `tool_call`
493
494Sent when the LLM invokes a tool the extension registered. `args` is
495the parsed JSON object the model produced; the extension is
496responsible for validating/coercing it.
497
498```json
499{"type":"tool_call","id":"...","name":"weather",
500 "args":{"city":"Berlin"}}
501```
502
503Reply with `tool_result` within the host's tool timeout (default 60s).
504Missing the timeout surfaces an error to the model and the call is
505marked as failed.
506
507#### `event`
508
509Lifecycle notification for events the extension subscribed to via
510`subscribe`. One-way, no response expected. Fields are additive under protocol
511version 1. Clients must tolerate unknown fields and event names.
512
513```json
514{"type":"event","event":"turn_start","step":1}
515{"type":"event","event":"tool_call",
516 "tool_id":"...","tool_name":"read","tool_args":{"path":"foo.go"}}
517{"type":"event","event":"tool_confirmation_requested",
518 "tool_id":"...","tool_name":"read","tool_preview":"foo.go"}
519{"type":"event","event":"turn_end","stop":"end_turn"}
520```
521
522### Lifecycle payloads
523
524Notifications include `session_id`, `cwd`, and a monotonically increasing
525`sequence` scoped to the extension manager's lifetime. Sequence numbers span
526all notifications, not just an extension's subscriptions, so gaps do not by
527themselves indicate lost delivery. They reset when zot restarts. Correlate tool
528outcomes with `(session_id, tool_id)`, compaction with `compaction_id`, and swarm
529runs with `agent_run_id`. These are payload identifiers, not request/reply IDs.
530
531| Event | Additional payload | Meaning |
532|---|---|---|
533| `session_start` | No additional fields | An active conversation opens |
534| `session_end` | `reason` | The active conversation closes |
535| `user_prompt_submit` | `text`, optional `queued`, `image_count` | Model input accepted, before appending or queueing |
536| `turn_start` | `step` | A model step begins |
537| `turn_end` | `stop`, optional `error` | A model response attempt finishes, before client tool execution |
538| `tool_call` | `tool_id`, `tool_name`, `tool_args` | The model's original proposed call |
539| `tool_confirmation_requested` | `tool_id`, `tool_name`, `tool_preview` | Interactive approval is about to be requested |
540| `permission_decision` | `tool_id`, `tool_name`, `decision`, `source`, `stage`, optional `reason` | An approval or policy decision was resolved |
541| `tool_result` | `tool_id`, `tool_name`, `tool_args`, `status`, `executed`, `result` | A client tool call reached a terminal outcome |
542| `assistant_message` | `text` | Visible assistant text |
543| `pre_compact` | `compaction_id`, `message_count`, `token_estimate` | A compaction attempt begins |
544| `post_compact` | Same counts and ID, `status`, optional `error` | A compaction attempt finishes, including failure |
545| `subagent_start` | `agent_id`, `agent_run_id`, `name` | A local swarm runner starts or resumes |
546| `subagent_stop` | Same identity, `status`, optional `error` | That local swarm runner returns |
547
548#### Prompt submission
549
550`text` is the input handed to the agent after host preprocessing, not raw editor
551keystrokes. This includes extension-generated prompts and queued follow-ups.
552Queued input emits once at acceptance with `queued:true`, not again at
553consumption; it can subsequently be withdrawn without reaching the model.
554Image bytes are not included; `image_count` reports attached images. An
555image-only prompt may omit `text`. Slash commands that do not submit model
556input, transcript replay, compaction summaries, and internal image mirrors do
557not emit this event.
558
559#### Tool outcomes and permission decisions
560
561```json
562{"type":"event","event":"tool_result","session_id":"session-1","cwd":"/work","sequence":12,"tool_id":"call-1","tool_name":"bash","tool_args":{"command":"go test ./..."},"status":"completed","executed":true,"result":{"content":[{"type":"text","text":"ok"}],"is_error":false}}
563```
564
565`status` is `completed`, `failed`, `blocked`, `cancelled`, or `timed_out`.
566Failures include unknown tools, panics, and tool error results. Guards and
567built-in jail/manifest policy refusals are `blocked`. Cancellation and timeout
568classification uses typed execution errors or explicit tool outcome metadata,
569not error-message matching. A custom tool that reports only `is_error` without
570such metadata is classified as `failed`.
571
572`tool_args` contains effective arguments, including accepted interceptor
573rewrites and the empty-argument default `{}`. For a call refused before
574execution, it contains the last proposed arguments instead. If the arguments
575are malformed JSON, `tool_args_raw` contains their raw text and `tool_args` is
576omitted, so the outcome remains a valid protocol frame. `executed` means
577`Tool.Execute` was entered, not that a side effect occurred or was rolled back.
578A tool-local policy refusal can therefore be `blocked` with `executed:true`.
579Pending calls cancelled before execution still receive terminal results.
580Provider-executed server tools do not receive client `tool_result` events.
581
582`result.content` uses text and base64 image blocks. Observation payloads have a
583256 KiB combined text/base64/MIME-data budget and a 128-block limit. Text may be
584shortened at a UTF-8 boundary; oversized images and unsupported block types are
585omitted. `result.truncated:true` marks any omission. Tool execution, the model's
586result, and the persisted transcript are not truncated by this observation
587limit. Private `Details` and tool activation metadata are not exported.
588
589```json
590{"type":"event","event":"permission_decision","session_id":"session-1","tool_id":"call-1","tool_name":"bash","decision":"approved","source":"user","stage":"pre_execution"}
591```
592
593`decision` is `approved`, `denied`, or `cancelled`. `source` is `user`,
594`remembered`, `policy`, or `yolo`. Automatic approval is represented by an
595approved decision with its source, not a separate decision value. Guard
596refusals, preview failures, and no available confirmer use `policy`.
597
598A `pre_execution` approval does not bypass tool-local checks. If a tool later
599refuses access, an additional denied decision with `source:"policy"` and
600`stage:"tool_execution"` precedes its blocked result. These events cannot grant
601permission or override a refusal. Calls cancelled before checking permission
602or rejected as unknown tools can have a result without a permission decision.
603Existing mode-specific confirmation behavior is unchanged, including modes
604that do not support interactive approval.
605
606#### Session, compaction, and swarm boundaries
607
608Sessions use the persisted conversation ID when available, otherwise a
609runtime-generated ID. Interactive and RPC sessions start when initialized;
610single-shot/headless sessions start when the agent first emits an observation.
611Switching conversations emits the old session's end before the new start.
612Current end reasons are `shutdown`, `session_switch`, and `cwd_change`.
613`session_end` is emitted at most once per activation on these graceful paths.
614Switching models or clearing messages does not close the active conversation.
615Reloading extensions does not close the session or replay earlier events.
616
617Every compaction attempt emits a matching `post_compact`, including empty
618transcripts, failures, and cancellation. Status is `completed`, `failed`,
619`cancelled`, or `timed_out`. Post counts describe the resulting in-memory
620transcript; they do not assert that persistence succeeded. Token estimates
621count serialized text bytes divided by four, not exact provider usage or image
622tokens. The events do not let extensions modify the summary.
623
624Swarm events are emitted by the parent supervisor, including resumed tasks.
625`session_id` identifies the task's parent conversation, even if the active
626conversation later changes. `agent_id` survives resume; `agent_run_id` is fresh
627for each local runner invocation and pairs start with stop. `name` currently
628uses the agent ID. Stop statuses are `completed`, `failed`, `cancelled`, and
629`timed_out`. Merely loading detached agents from disk does not replay lifecycle
630events. Cancellation requests do not emit stop until the runner returns. On
631interactive shutdown zot waits up to two seconds for local runners before
632closing extensions; unresponsive runners may not produce a final notification.
633
634#### Ordering, delivery, and privacy
635
636For a normal client tool step, the observable sequence is:
637
638```text
639user_prompt_submit
640turn_start
641assistant_message / tool_call
642turn_end
643synchronous tool interception
644tool_confirmation_requested (when needed)
645permission_decision
646tool execution
647tool_result
648next turn_start (if continuing)
649```
650
651This preserves the existing meaning of `turn_end`: it ends the model response,
652not the tool batch. Multiple calls are announced before the batch executes;
653each client call then gets its own permission and result events. Retries,
654blocked turns, queued prompts, and concurrent swarm tasks can add or interleave
655events; do not assume a globally linear workflow from the example alone.
656
657Frames are serialized per extension, including notifications and interception
658requests. Notification enqueue does not wait for the subprocess. Each
659extension has a bounded outbound queue (256 frames or 16 MiB of queued bytes,
660plus one in-flight frame); overflow disconnects it rather than silently dropping
661an event and continuing. Synchronous writes are bounded to five seconds.
662Graceful shutdown attempts to drain queued frames, including `session_end`,
663before sending `shutdown`, within the shutdown grace period.
664
665Delivery is best-effort, not a durable or exactly-once audit log. There is no
666acknowledgement, replay, or crash recovery for notifications. A crash, forced
667termination, slow consumer, or broken pipe can prevent delivery. The protocol's
6684 MiB frame limit still applies. Slow event handlers can delay later
669interception requests, so extension handlers should hand lengthy work to their
670own bounded queue. Existing interception response and failure policies remain
671unchanged.
672
673Prompts, effective tool arguments, outputs, paths, and error text may contain
674secrets or private data. Only subscribe to content-bearing events you need.
675There is no automatic secret redaction; subscriptions are not an extension
676security sandbox. This surface is available where zot loads an extension
677manager (interactive, print/stream/JSON, RPC, and swarm-child modes). It does
678not add extension loading to other hosts or change the RPC client event schema.
679
680#### `event_intercept`
681
682Sent when zot wants to give the extension a chance to block, modify,
683or annotate a lifecycle event before it happens. Reply with
684`event_intercept_response` within 5s; missing the deadline is
685treated as "allow".
686
687Payload fields depend on the event:
688
689```json
690// tool_call: includes the tool id, name, and parsed args
691{"type":"event_intercept","id":"...","event":"tool_call",
692 "tool_id":"...","tool_name":"bash",
693 "tool_args":{"command":"rm -rf /tmp/foo"}}
694
695// turn_start: includes the step number
696{"type":"event_intercept","id":"...","event":"turn_start",
697 "step":3}
698
699// assistant_message: includes the assembled text
700{"type":"event_intercept","id":"...","event":"assistant_message",
701 "text":"here is your api key: sk-ant-..."}
702```
703
704#### `panel_key`
705
706Sent while an extension-owned panel is focused. `key` is a normalized
707name (`up`, `down`, `left`, `right`, `enter`, `esc`, `tab`, `pageup`,
708`pagedown`, `home`, `end`, `backspace`, `delete`, `rune`). For
709`key:"rune"`, `text` carries the typed character.
710
711```json
712{"type":"panel_key","panel_id":"todos-main","key":"down"}
713{"type":"panel_key","panel_id":"todos-main","key":"rune","text":"x"}
714```
715
716#### `panel_close`
717
718Sent when the user closes the focused panel from zot (for example with
719Esc or Ctrl+C). The extension should treat this as the panel lifetime
720ending and stop sending `panel_render` updates for that `panel_id`.
721
722```json
723{"type":"panel_close","panel_id":"todos-main"}
724```
725
726#### `shutdown`
727
728Sent during graceful zot exit (or `/reload-ext` once that lands).
729Reply with `shutdown_ack` and then exit.
730
731## Managing extensions from the CLI
732
733```
734zot ext list                    list installed extensions and their state
735zot ext doctor                  diagnose load, registration, and conflict issues
736zot ext install <path|git-url>  copy / clone into $ZOT_HOME/extensions/
737zot ext remove <name>           delete an extension directory
738zot ext enable <name>           re-enable a disabled extension
739zot ext disable <name>          disable without removing
740zot ext logs <name> [-f]        cat / tail the extension's stderr
741```
742
743`zot ext doctor` runs the same discovery path as zot startup, but reports
744what happened instead of changing the fail-soft runtime behavior. It shows
745manifest errors, disabled or shadowed extensions, subprocess load errors,
746ready/auto-ready status, registered commands/tools, registration conflicts,
747warnings, and each extension's stderr log path.
748
749`zot ext install <path>` does a recursive copy; `<git-url>` does a
750shallow clone. Both validate that the destination contains an
751`extension.json` and roll back if not.
752
753## Loading an extension for one run
754
755For iteration on a working copy, skip the install + reload cycle
756and load straight from disk for one zot session:
757
758```
759zot --ext ./my-extension        # short form: -e ./my-extension
760zot --ext ./a -e ./b            # repeatable
761```
762
763`--ext` paths take precedence over installed extensions of the same
764name, so you can shadow an installed copy with a work-in-progress
765version without uninstalling first. Nothing is copied or persisted;
766the extension dies with zot like any other subprocess.
767
768## SDKs
769
770Writing the wire protocol by hand is fine for one-off scripts, but
771for anything bigger the SDKs handle the boilerplate.
772
773### Go — `packages/agent/ext`
774
775```go
776package main
777
778import (
779    "encoding/json"
780    "github.com/patriceckhart/zot/packages/agent/ext"
781)
782
783func main() {
784    e := ext.New("hello", "1.0.0")
785
786    // Slash command
787    e.Command("hello", "say hi", func(args string) ext.Response {
788        return ext.Prompt("Greet me in one short sentence.")
789    })
790
791    // LLM-callable tool
792    e.Tool("weather", "Current weather for a city.",
793        json.RawMessage(`{"type":"object","properties":{"city":{"type":"string"}},"required":["city"]}`),
794        func(args json.RawMessage) ext.ToolResult {
795            var in struct{ City string `json:"city"` }
796            json.Unmarshal(args, &in)
797            return ext.TextResult(in.City + ": sunny")
798        })
799
800    // Optional: register project-specific commands after hello_ack.
801    e.OnHello(func(host ext.HostInfo) {
802        if host.CWD != "" {
803            e.Command("cwd", "show the current project directory", func(args string) ext.Response {
804                return ext.Display(host.CWD)
805            })
806        }
807    })
808
809    e.Run()
810}
811```
812
813Build with `go build -o hello .`, drop the binary + an `extension.json`
814into `$ZOT_HOME/extensions/hello/`.
815
816`OnHello` is optional. Use it when configuration or registrations need
817host metadata such as `HostInfo.CWD`, `Provider`, `Model`, `ZotVersion`,
818`ExtensionDir`, or `DataDir`. The SDK sends `hello`, waits for
819`hello_ack`, runs `OnHello`, announces registrations, then sends `ready`.
820
821The SDK has five interceptor hooks, all optional:
822
823```go
824// e is the *ext.Extension returned by ext.New(...).
825
826// Replace the complete prompt once per session or explicit rebuild.
827// Return nil to keep it, or a pointer to "" to remove it entirely.
828e.InterceptBeforeAgentStart(func(event ext.BeforeAgentStartEvent) *string {
829    prompt := event.SystemPrompt + "\nUse the project's preferred coding style."
830    return &prompt
831})
832
833// Refuse calls or rewrite args before they run.
834e.InterceptToolCall(func(tool string, args json.RawMessage) (bool, string) {
835    if tool == "bash" { /* inspect args, return false, reason */ }
836    return true, ""
837})
838
839// Richer variant: returns ToolCallDecision so you can also rewrite
840// args via ModifiedArgs.
841e.InterceptToolCallX(func(tool string, args json.RawMessage) ext.ToolCallDecision {
842    return ext.ToolCallDecision{
843        ModifiedArgs: json.RawMessage(`{"command":"echo GUARDED"}`),
844    }
845})
846
847// Block the next turn before the model is called.
848e.InterceptTurnStart(func(step int) ext.TurnStartDecision {
849    if time.Now().Hour() < 9 { return ext.TurnStartDecision{Block: true, Reason: "outside business hours"} }
850    return ext.TurnStartDecision{}
851})
852
853// Scrub or rewrite the assistant's final text before the user sees it.
854e.InterceptAssistantMessage(func(text string) ext.AssistantMessageDecision {
855    return ext.AssistantMessageDecision{
856        ReplaceText: strings.ReplaceAll(text, "SECRET", "[redacted]"),
857    }
858})
859```
860
861See:
862- `examples/extensions/hello/` — slash commands
863- `examples/extensions/clock/` — slash commands in plain Node, no SDK
864- `examples/extensions/weather/` — LLM-callable tool
865- `examples/extensions/guard/` — event subscriptions + tool-call
866  interception (refuses dangerous bash patterns)
867- `examples/extensions/todo/` — interactive persistent panel + tool
868- `examples/extensions/scratchpad/` — source-run TypeScript commands + tool
869
870### Hot reload
871
872Type `/reload-ext` in the TUI to tear down every running extension
873subprocess, re-read the manifests from disk, and respawn the set.
874The agent's tool registry is rebuilt automatically, so freshly-
875registered extension tools become callable without restarting zot.
876Useful while developing an extension: edit, save, `/reload-ext`,
877done. Explicit `--ext` paths are remembered and reloaded alongside
878discovered extensions. The temporary reload status reports each load
879error in red, including its message, and dismisses itself after five
880seconds. Extension failures from startup and `/reload-ext` remain in the
881scrolling chat until a successful reload or `/clear`, without being sent to
882the model or saved in the session transcript. Subprocess startup and
883handshake errors identify the extension and its directory, configured executable,
884and declared language (if present), along with the original error and stderr log
885path when the log was opened. Manifest errors also identify the extension
886directory. Multiline diagnostics preserve their line breaks in both the temporary
887status and scrolling chat.
888If a subprocess exits before sending `hello`, the error also reports its exit
889status or terminating signal.
890
891### TypeScript / Python
892
893These SDKs aren't in the main repo yet; the wire format is small
894enough that a `~30 line` raw script gets you started in either
895language. See the [Quick start](#quick-start) Python example for the
896shape. SDK packages will land in follow-up commits.
897
898## Security
899
900Extensions run with **the user's full filesystem and network
901permissions**. Treat installing an extension the same as installing
902any other binary on your machine.
903
904`zot ext install <git-url>` clones from any URL you give it. There's
905no sandbox in v1; if you need isolation, install only extensions you
906trust or run zot under your platform's sandboxing tool (`bwrap` /
907`sandbox-exec` / AppContainer).
908
909## Roadmap
910
911Phase 1 (shipped):
912- [x] subprocess lifecycle + hello handshake
913- [x] `register_command` + `command_invoked`
914- [x] `notify` + `clear_notes`
915- [x] `zot ext` CLI
916
917Phase 2 (shipped):
918- [x] `register_tool` + `tool_call` + `tool_result`
919- [x] `ready` sentinel for safe agent-registry build timing
920- [x] tool result attribution surfaces extension name in details
921
922Phase 3 (shipped):
923- [x] event subscriptions (`session_start`, `turn_start`, `turn_end`,
924      `tool_call`, `assistant_message`)
925- [x] tool-call interception (block before execution)
926
927Phase 4 (shipped):
928- [x] interception for `turn_start` and `assistant_message` (in
929      addition to `tool_call`)
930- [x] modify tool args mid-flight via `modified_args`
931- [x] rewrite user-visible assistant text via `replace_text`
932- [x] `/reload-ext` slash command (hot-reload without restarting zot)
933
934Future (no firm timeline):
935- [ ] TypeScript and Python SDK packages (currently the wire format
936      is stable enough to hand-roll, see the Python quick-start)
937- [ ] HTTP / WebSocket transport variants (today: subprocess stdio)
938- [ ] per-extension permission scopes (today: full user privileges)