agent-director 0.11.0 → 0.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -16,32 +16,17 @@ Requires Bun >=1.0.21. The package ships pure JavaScript — there are
16
16
  optional platform dependencies. `bun add --ignore-scripts agent-director`
17
17
  is a no-op and installs the library with identical functionality.
18
18
 
19
- **You must separately install the CLI binary on the host.** The
20
- fastest path on a fresh machine is the one-liner published with the
21
- agent-director GitHub repo — it downloads the binary for your OS/arch
22
- from the [latest release](https://github.com/gabemahoney/agent-director/releases/latest)
23
- and sets up `~/.agent-director/`:
24
-
25
- ```sh
26
- curl -fsSL https://raw.githubusercontent.com/gabemahoney/agent-director/main/skills/install-agent-director/install.sh | bash -s -- --from-release
27
- ```
28
-
29
- `Client.create()` discovers the installed binary at construction time
30
- (either at `~/.agent-director/bin/agent-director` or anywhere on
31
- `$PATH`) and rejects if it cannot find one. Other supported install
32
- mechanisms — `install.sh --binary <path> --admin-binary <path>` with
33
- locally-staged artifacts, or any drop-in copy onto `$PATH` — are documented in the
34
- [repo README](https://github.com/gabemahoney/agent-director#install-the-cli).
19
+ Install the CLI separately using the [install guide](../../docs/install.md).
20
+ `Client.create()` finds it at the standard install path or on `$PATH`;
21
+ its version must meet the client floor.
35
22
 
36
23
  ## Supported platforms
37
24
 
38
25
  - `linux/x64` (Linux on x86_64)
39
26
  - `darwin/arm64` (Apple Silicon Mac)
40
27
 
41
- The library's published npm package admits installs on any host (no
42
- `os`/`cpu` restrictions on the library itself); the platform gate is
43
- the CLI binary's own platform coverage. The CLI must be installed
44
- separately per the platform list above.
28
+ Package installation may also succeed on `linux/arm64` and `darwin/x64`;
29
+ those are not supported CLI install hosts. See [Requirements](../../docs/install.md#requirements).
45
30
 
46
31
  ## Quick start
47
32
 
@@ -53,6 +38,9 @@ const v = await client.version({});
53
38
  console.log(v.version);
54
39
  ```
55
40
 
41
+ The `version` result is `{ version, commit, config_dir }`; `config_dir` is the
42
+ directory the CLI keeps its files in, `~/.config/agent-director` (unexpanded).
43
+
56
44
  Explicit `try/finally` (portable fallback):
57
45
 
58
46
  ```ts
@@ -65,70 +53,126 @@ try {
65
53
  }
66
54
  ```
67
55
 
68
- All constructor options are optional. Omitted fields fall back to the CLI binary's own three-tier default resolution (config.toml value, then hardcoded fallback such as `~/.agent-director/state.db`) — the CLI is the single source of truth for defaults. Tilde expansion (`~` → home directory) is handled automatically before paths are forwarded to the CLI subprocess. The `using` form calls `client.close()` automatically at block exit and requires Bun >=1.0.21 (or a TypeScript project with `"lib": ["ESNext.Disposable"]`).
56
+ All constructor options are optional. Omitted fields fall back to the CLI binary's own three-tier default resolution (config.toml value, then hardcoded fallback such as `~/.config/agent-director/state.db`) — the CLI is the single source of truth for defaults. The `using` form calls `client.close()` automatically at block exit and requires Bun >=1.0.21 (or a TypeScript project with `"lib": ["ESNext.Disposable"]`).
69
57
 
70
- `ClientOptions` overrides forward verbatim to the CLI subprocess as global flags:
58
+ `ClientOptions` overrides forward to the CLI subprocess as global flags:
71
59
 
72
60
  - `storePath` → `--store-path`
73
61
  - `home` → `--home`
74
62
  - `tmuxCommand` → `--tmux-command`
63
+ - `createIfMissing: false` → `--create-if-missing false` (`true` forwards nothing)
64
+
65
+ The paths are forwarded verbatim. The CLI, not the client, expands a `~` in
66
+ them, against `HOME` and nothing else (never the passwd entry's home). It applies `home` first, so with `home`
67
+ set, a `~/` in `storePath` or `tmuxCommand` resolves under `home`. With
68
+ `HOME` unset or empty, a `home` of `~` or `~/…` rejects every call with
69
+ `ErrInvalidFlags`, and with no `home` either, every call that opens the store
70
+ is refused with `ErrStoreOpen`, whatever `storePath` is, because the CLI cannot
71
+ expand its config path `~/.config/agent-director/config.toml`.
75
72
 
76
- Set them only when the consumer needs to override the CLI's default for that field.
73
+ Set them when the consumer needs to override that field's CLI default.
74
+
75
+ By default, the first call that opens the store creates it when it does not
76
+ exist (parent directories, file and schema). With `createIfMissing: false`,
77
+ such a call rejects with `ErrStoreOpen` (`database not initialized`) and
78
+ creates none of it; an existing store opens as usual, and calls that open no
79
+ store, such as `version`, are unaffected.
80
+
81
+ For spawning under another home or store, use
82
+ [Permissions](../../docs/permissions.md#one-spawn-under-another-home-or-store).
77
83
 
78
84
  ## Verb examples
79
85
 
80
- ### spawn
86
+ Shared CLI use is in [Usage](../../docs/usage.md).
81
87
 
82
- Launch a tracked Claude Code instance in a new tmux session.
88
+ A call that carries an old name of a renamed key (on any verb) throws
89
+ `ErrInvalidFlags` before the client starts any process; its description names
90
+ the new key.
83
91
 
84
- ```sh
85
- agent-director spawn --cwd ~/my-project
86
- ```
92
+ ### spawn
93
+
94
+ Launch a tracked agent in a new tmux session. A spawn names its agent, `"claude"` or `"codex"` (case-sensitive), in `agent` or through its template; with neither it throws `ErrAgentMissing`. An empty `agent` counts as not given.
87
95
 
88
96
  ```ts
89
- const result = await client.spawn({ cwd: "~/my-project" });
90
- console.log(result.claude_instance_id);
97
+ const result = await client.spawn({ cwd: "~/my-project", agent: "claude" });
98
+ console.log(result.instance_id);
91
99
  ```
92
100
 
101
+ The `SpawnResult` has `instance_id`, `pre_trust` and optional
102
+ `dropped_args?: string[]`. On a switching reuse, `dropped_args` contains
103
+ removed original argument tokens in argv order; it is omitted when empty.
104
+ The switch starts fresh and resumes nothing. Selector lists and reporting
105
+ rules are in the
106
+ [caller contract](../../docs/caller-contract.md#spawn-and-template-input-refusals).
107
+
108
+ Same-agent reuse retains current-life session history and subagent records;
109
+ switching agents starts another life, including when switching back.
110
+ `resume` continues only the recorded agent's latest reported session and
111
+ never selects an archived one. See [Usage](../../docs/usage.md#naming-the-agent)
112
+ and [Transcript recovery](../../docs/caller-contract.md#transcript-recovery).
113
+
93
114
  ### status
94
115
 
95
116
  Get the current lifecycle state of a Spawn.
96
117
 
97
- ```sh
98
- agent-director status --claude-instance-id <id>
99
- ```
100
-
101
118
  ```ts
102
- const result = await client.status({ claude_instance_id: "<id>" });
119
+ const result = await client.status({ instance_id: "<id>" });
103
120
  console.log(result.state);
104
121
  ```
105
122
 
123
+ With `[state] settle_ms` set in the CLI's `~/.config/agent-director/config.toml`,
124
+ `status`, `get` and `list` report the settled state: a state a hook wrote
125
+ shows only once it has held that long, the last settled state until then;
126
+ `ended`, `missing` and a state a verb wrote show at once, and `list`'s
127
+ `state` filter matches the settled state. Every verb that acts on a Spawn
128
+ judges its live state, which can be newer. The client adds no field and
129
+ no state value for it.
130
+
106
131
  ### list
107
132
 
108
133
  Query Spawns with optional filters.
109
134
 
110
- ```sh
111
- agent-director list --state waiting
112
- ```
113
-
114
135
  ```ts
115
136
  const result = await client.list({ state: ["waiting"] });
116
137
  for (const spawn of result.spawns) {
117
- console.log(spawn.claude_instance_id, spawn.state);
138
+ console.log(spawn.instance_id, spawn.state, spawn.agent);
118
139
  }
119
140
  ```
120
141
 
121
- ### sendKeys
142
+ Each row, like `get`'s result, carries `agent` (`"claude"` or `"codex"`), the agent the row runs.
122
143
 
123
- Send text to the agent's own pane, then one Enter to submit it. An empty
124
- `text` sends the Enter only, submitting what is already typed.
144
+ ### listSubagents
125
145
 
126
- ```sh
127
- agent-director send-keys --claude-instance-id <id> --text "what is 2+2?"
146
+ Read the subagent records across launches of one agent's current life, and
147
+ whether the agent is tracked. `subagent_id` is unique among the returned
148
+ records; earlier-life records remain stored but are hidden. See
149
+ [visibility and retention](../../docs/usage.md#read-an-agents-subagent-records).
150
+
151
+ ```ts
152
+ const result = await client.listSubagents({ instance_id: "<id>" });
153
+ console.log(result.tracked);
154
+ for (const sub of result.subagents) {
155
+ console.log(sub.subagent_id, sub.state, sub.subagent_type ?? "unknown type");
156
+ }
128
157
  ```
129
158
 
159
+ `tracked` is `false`, with `subagents` `[]`, for a `"codex"` agent (from its spawn, and after every `resume` or reuse of its id) and for a `"claude"` agent that predates subagent tracking (it becomes `true` when that agent is next resumed or its id is reused). `subagents` is never null; a field with no known value is `null`, and times are RFC 3339 UTC strings. The fields and values are described in [Read an agent's subagent records](../../docs/usage.md#read-an-agents-subagent-records).
160
+
161
+ ### sendKeys
162
+
163
+ Send text to the agent's own pane, then one Enter to submit it. An empty
164
+ or omitted `text` sends the Enter only, submitting what is already typed.
165
+ `no_enter: true` types the text without the Enter, and `key` sends one key
166
+ alone (`"Escape"`, `"Enter"`, `"Up"`, `"Down"`, `"Tab"`, or one character),
167
+ never followed by Enter. With `expect_pane_sha256` (the `pane_sha256` of
168
+ the `readPane` you looked at, with its `n_lines`), nothing is sent if the
169
+ pane changed since (`ErrPaneChanged`); on a relayed Spawn a match also
170
+ passes the dialog hold (`ErrDialogMaybeOpen`, see "Answering a request at
171
+ the pane" below). Pass it only for a pane a person or an LLM judged, never
172
+ from an automatic flow.
173
+
130
174
  ```ts
131
- await client.sendKeys({ claude_instance_id: "<id>", text: "what is 2+2?" });
175
+ await client.sendKeys({ instance_id: "<id>", text: "what is 2+2?" });
132
176
  ```
133
177
 
134
178
  Pass `allow_pending: true` to also allow a `pending` row: a launch (spawn,
@@ -139,30 +183,23 @@ still rejected. A `pending` row whose launch start or launch token is not record
139
183
  only a session an earlier launch left behind is found, gets
140
184
  `ErrSpawnNotInteractive` and nothing is sent.
141
185
 
142
- Send an empty string with `allow_pending: true` to press Enter and dismiss such
143
- a prompt:
144
-
145
- ```ts
146
- await client.sendKeys({
147
- claude_instance_id: "<id>",
148
- text: "",
149
- allow_pending: true,
150
- });
151
- ```
186
+ `liveness_note: "unreported"` means an alive agent has not reported since
187
+ launch. Action on a pending row belongs to the
188
+ [caller contract](../../docs/caller-contract.md#caller-contract).
152
189
 
153
190
  ### readPane
154
191
 
155
192
  Read the last N lines of the agent's own pane (default 25).
156
193
 
157
- ```sh
158
- agent-director read-pane --claude-instance-id <id> --n-lines 50
159
- ```
160
-
161
194
  ```ts
162
- const result = await client.readPane({ claude_instance_id: "<id>", n_lines: 50 });
163
- console.log(result.pane);
195
+ const result = await client.readPane({ instance_id: "<id>", n_lines: 50 });
196
+ console.log(result.pane, result.pane_sha256);
164
197
  ```
165
198
 
199
+ `pane_sha256` is the SHA-256 of exactly the bytes of `pane`; pass it back as
200
+ `sendKeys`' or `recordPaneAnswer`'s `expect_pane_sha256`, with the same
201
+ `n_lines`, when you act on what this pane shows.
202
+
166
203
  `readPane` has no state guard — it works on `pending`, `ended`, and `missing`
167
204
  rows as well as live ones. The `allow_pending` flag is accepted for symmetry
168
205
  with `sendKeys` but has no behavioral effect.
@@ -179,47 +216,167 @@ resolves with `kill_sent: false`; that is not verification that the agent
179
216
  exited. `kill` never changes the row's state: `find-missing` marks the row once
180
217
  its agent process is gone.
181
218
 
182
- ```sh
183
- agent-director kill --claude-instance-id <id>
184
- ```
185
-
186
219
  ```ts
187
- const { kill_sent } = await client.kill({ claude_instance_id: "<id>" });
220
+ const { kill_sent } = await client.kill({ instance_id: "<id>" });
188
221
  console.log(kill_sent);
189
222
  ```
190
223
 
191
224
  Errors to catch: `ErrTmuxKillFailed` and `ErrTmuxUnresponsive` (UNAVAILABLE:
192
- retry later), `ErrTmuxSessionConflict` (CONFLICT: a human must look),
193
- `ErrTmuxNotAvailable` (ENVIRONMENT: an operator must fix the environment) and
194
- `ErrSpawnNotFound`. None of these means the agent is dead. The caller must run
195
- as the same user and in the same tmux environment as the agents. See the "tmux
196
- transport" table under [Errors](#errors).
225
+ retry later), `ErrTmuxSessionConflict` (CONFLICT),
226
+ `ErrTmuxNotAvailable` (ENVIRONMENT) and
227
+ `ErrSpawnNotFound`. None of these proves exit. See the [caller contract](../../docs/caller-contract.md#caller-contract)
228
+ for the live-row sequence and finished-row limits.
229
+
230
+ ### pause
231
+
232
+ Shut down a `waiting` Spawn: type `/exit` in its pane and wait up to
233
+ `pause.timeout_seconds` for `ended`. A finished Spawn is a no-op. A live Codex
234
+ Spawn whose agent already exited with an end report resolves, in any live
235
+ state, having typed nothing, and its row is `ended`; otherwise any live state
236
+ but `waiting` throws `ErrSpawnNotPausable`. On a Codex Spawn
237
+ `pause` ends the row itself once the agent exits (see the
238
+ [caller contract](../../docs/caller-contract.md#when-a-codex-agent-exits)).
239
+
240
+ ```ts
241
+ await client.pause({ instance_id: "<id>" });
242
+ ```
243
+
244
+ `pause` is held like a `sendKeys` without `request_token` and without
245
+ `expect_pane_sha256`: on a Spawn with `relay_mode: "on"` it throws
246
+ `ErrSendKeysWhileRelayed`, `ErrRelayFallenBack` or `ErrDialogMaybeOpen`,
247
+ with the same `errDetails`, typing nothing and starting no wait, whenever
248
+ that `sendKeys` would. It takes no pane hash, so it stays held until the
249
+ agent's hooks prove each request gone (after a subagent's denied request, or on
250
+ a Codex Spawn an allowed one, until the agent ends). Stopping a held spawn and handling these refusals are in the
251
+ [caller contract](../../docs/caller-contract.md#permission-relay).
197
252
 
198
253
  ### makeTemplate
199
254
 
200
- Save a reusable spawn preset. Pass `overwrite: true` to atomically replace an existing template; omit the field to keep the default rejection on collision.
255
+ Save a reusable spawn preset. Pass `agent` to bake in the template's agent; a template with `agent_args` needs one. Pass `overwrite: true` to atomically replace an existing template; omit the field to keep the default rejection on collision.
201
256
 
202
- ```sh
203
- agent-director make-template --name dev --cwd /repos/widget --overwrite
257
+ ```ts
258
+ await client.makeTemplate({ name: "dev", cwd: "/repos/widget", agent: "claude", overwrite: true });
204
259
  ```
205
260
 
261
+ ### decide
262
+
263
+ Answer a relayed permission request of a Spawn launched with
264
+ `relay_mode: "on"`. `decide` records the verdict, waits at most 1 s for the
265
+ agent's relay hook to confirm it, and resolves with the request's
266
+ `delivery`.
267
+
206
268
  ```ts
207
- await client.makeTemplate({ name: "dev", cwd: "/repos/widget", overwrite: true });
269
+ const result = await client.decide({
270
+ instance_id: "<id>",
271
+ request_token: "<token>",
272
+ decision: "allow",
273
+ max_wait_ms: 2000, // at most your deadline minus 1 s
274
+ });
275
+ if (result.delivery === "not_confirmed") {
276
+ const later = await client.getPermission({ request_token: "<token>" });
277
+ console.log(later.delivery, later.confirm_by);
278
+ }
208
279
  ```
209
280
 
210
- ## Consumption
281
+ `"delivered"`: the relay hook confirmed the verdict before handing it to
282
+ the agent. `"not_confirmed"`: the relay hook has not confirmed the verdict;
283
+ `getPermission` exposes subsequent delivery and `confirm_by`. See the
284
+ [caller contract](../../docs/caller-contract.md#permission-relay) for
285
+ confirmation handling. `decision`
286
+ is the verdict recorded, not the outcome: read `delivery`. `max_wait_ms`
287
+ bounds the whole call, its reads and its write, and has no default; without
288
+ it `decide` can wait up to the store's busy timeout. `decide` rejects,
289
+ recording no verdict, with `ErrRelayFallenBack` when the request's relay
290
+ hook is gone and took no verdict, with `ErrStoreBusy` when `max_wait_ms`
291
+ ran out before the verdict was recorded, and with
292
+ `ErrNoOpenPermissionRequest` when no open request has that token or the
293
+ request is closed. Pane answers, retries and closed-request handling are
294
+ in the [caller contract](../../docs/caller-contract.md#permission-relay). The
295
+ `permission_requests` of `get` and of each `list` row carry the same
296
+ delivery fields, `pane_answer` and `pane_as` included, for requests that
297
+ still await an answer only; a row can read `waiting`, `working` or
298
+ `ask_user` while a request is still open, so follow the requests you track
299
+ with `getPermission`.
300
+ `decision_reason` is one of `"operator"`, `"timeout"`, `"find_missing"`,
301
+ `"ended"`, `"pane"`, `"pane_outside"` and `"tool_ran"`. For a reason you
302
+ do not know, read the recorded verdict from `decision` (`null` for a
303
+ `"pane_outside"` `"unknown"` claim) and the outcome from `delivery` and
304
+ `pane_answer`; never read a reason as a verdict.
305
+
306
+ `proven_gone_at` and `proven_gone_how` (`ProvenGoneHow`: `"tool_ran"`, its
307
+ tool ran (a Claude Spawn only); `"turn_end"`, the turn of the agent that asked
308
+ ended after it was written, which a Codex main agent's Interrupt also proves; or
309
+ `"agent_gone"`, the agent ended) say when and how the agent's
310
+ hooks showed the request's dialog gone; `"delivered"` and a pane answer are
311
+ agent-director's own records, not proof. `get`'s `unproven_requests` lists
312
+ every request not yet proven gone, each with `unproven_since`. A request
313
+ that reads `"delivered"` or closed at the pane can remain unproven; its dialog
314
+ may still be there. Handling is in the
315
+ [caller contract](../../docs/caller-contract.md#permission-relay).
316
+
317
+ ### Answering a request at the pane
318
+
319
+ `sendKeys` with a `request_token` answers a request at the pane.
320
+ The [caller contract](../../docs/caller-contract.md#permission-relay) owns
321
+ when to use a pane answer and how to judge the screen. Example:
211
322
 
212
- The supported consumption mode is Bun-runtime ESM:
323
+ ```ts
324
+ const seen = await client.readPane({ instance_id: "<id>" });
325
+ // having looked at seen.pane, the caller picks the key and the verdict it gives
326
+ await client.sendKeys({
327
+ instance_id: "<id>",
328
+ request_token: "<token>",
329
+ as: "deny",
330
+ key: "<key>",
331
+ expect_pane_sha256: seen.pane_sha256,
332
+ });
333
+ ```
213
334
 
214
- ```sh
215
- bun add agent-director
335
+ It sends exactly that key and no Enter, then records the request
336
+ `pane_answer` `"sent"` with `decision` your `as` and `decision_reason`
337
+ `"pane"`. `as`, `key` and `expect_pane_sha256` are required.
338
+ An `ErrInternal` whose `errDetails` is a `PaneKeySentDetails`
339
+ (`key_sent` `true`) means the key was sent but not recorded; hash use and
340
+ recovery are in the [caller contract](../../docs/caller-contract.md#permission-relay).
341
+ `recordPaneAnswer` records an answer made outside agent-director and types
342
+ nothing:
343
+
344
+ ```ts
345
+ try {
346
+ await client.recordPaneAnswer({
347
+ request_token: "<token>",
348
+ as: "unknown",
349
+ expect_pane_sha256: "<pane_sha256>",
350
+ });
351
+ } catch (e) {
352
+ if (e instanceof ErrClaimTooSoon) {
353
+ // errDetails is a ClaimTooSoonDetails here.
354
+ console.log("retry at", e.errDetails?.["not_before"]);
355
+ } else {
356
+ throw e;
357
+ }
358
+ }
216
359
  ```
217
360
 
361
+ `as` is the caller's claim; use `"unknown"` when the answer was not seen.
362
+ `ErrPaneChanged`, `ErrPaneAnswerInProgress`, `ErrClaimTooSoon` and
363
+ `ErrDialogMaybeOpen` carry structured facts in `errDetails`.
364
+ `recordPaneAnswer` types nothing; `sendKeys` with a request token sends one
365
+ key and records it. Delivery does not prove the dialog gone. See
366
+ [Permissions](../../docs/permissions.md) and the
367
+ [caller contract](../../docs/caller-contract.md#permission-relay) for the
368
+ complete pane-answer and held-agent procedures.
369
+
370
+ ## Consumption
371
+
372
+ The supported consumption mode is Bun-runtime ESM:
373
+
218
374
  ```ts
219
375
  import { Client } from "agent-director";
220
376
  ```
221
377
 
222
- The package uses `import.meta.resolve` and `import.meta.url` at runtime to locate the installed `package.json`. Bundling it through webpack or other bundlers that do not support these features is not supported.
378
+ Bundling without support for module-relative resource resolution is unsupported.
379
+ Use the package as Bun-runtime ESM.
223
380
 
224
381
  ## Versioning
225
382
 
@@ -232,8 +389,7 @@ The library version equals the agent-director release tag — released in lockst
232
389
  ## Minimum required CLI binary version
233
390
 
234
391
  The library declares the minimum CLI-binary version it requires on two
235
- surfaces, both backed by the same single source of truth shipped in the
236
- published npm package at `dist/version-floor.json`.
392
+ surfaces, available from the published package at `dist/version-floor.json`.
237
393
 
238
394
  **TS export (preferred for JS/TS consumers):**
239
395
 
@@ -248,8 +404,7 @@ if (binaryVersion === DEV_SENTINEL_VERSION) {
248
404
  ```
249
405
 
250
406
  `MIN_BINARY_VERSION` is a strict-SemVer-2.0 string (e.g. `0.7.0` or
251
- `0.7.0-rc1`). The value is inlined into the bundle at build time; no
252
- runtime file read. `DEV_SENTINEL_VERSION` is the literal `"0.0.0-dev"`
407
+ `0.7.0-rc1`). `DEV_SENTINEL_VERSION` is the literal `"0.0.0-dev"`
253
408
  — a dev-built CLI binary stamps this value and satisfies any floor by
254
409
  short-circuit. The library returns the binary's reported version
255
410
  verbatim — no leading-`v` stripping, no normalization. Consumers
@@ -265,21 +420,24 @@ jq -r .min_binary_version < node_modules/agent-director/dist/version-floor.json
265
420
  This pattern is part of the public contract. It does not require the
266
421
  agent-director CLI to be installed, does not spawn a JS runtime, and
267
422
  does not require any agent-director-specific environment setup — read
268
- the field from the file at the stable documented path. The `-r` flag
269
- returns a bare string suitable for shell comparison.
423
+ the field from the file at the stable documented path.
270
424
 
271
425
  ## Supported Bun versions
272
426
 
273
- Minimum: `>=1.0.21` (set in `engines.bun`). Tested on Bun 1.3.x as of this release. The `using` block syntax (Explicit Resource Management) requires Bun 1.0.21+.
427
+ Minimum: `>=1.0.21` (set in `engines.bun`). The `using` block syntax (Explicit Resource Management) requires Bun 1.0.21+.
274
428
 
275
429
  ## Errors
276
430
 
277
- Every error thrown by this package extends `AgentDirectorError`, so you can catch by subclass with `instanceof`:
431
+ Named client and CLI errors extend `AgentDirectorError`, so you can catch
432
+ by subclass with `instanceof`. Subprocess spawn failures can also surface
433
+ as their original errors: an unclassified `ENOENT` (neither the binary nor
434
+ the caller's cwd is verifiably gone) and every other spawn failure are
435
+ re-thrown unchanged. Keep a general fallback catch for these paths:
278
436
 
279
437
  ```ts
280
438
  import { Client, ErrSpawnNotFound } from "agent-director";
281
439
  try {
282
- await client.status({ claude_instance_id: "bogus" });
440
+ await client.status({ instance_id: "bogus" });
283
441
  } catch (e) {
284
442
  if (e instanceof ErrSpawnNotFound) {
285
443
  // recover
@@ -289,20 +447,24 @@ try {
289
447
  }
290
448
  ```
291
449
 
292
- The public typed-error surface falls into four groups. Every class named below is exported from the package entry point. The tables are self-sufficient for choosing what to catch; the raw generated catalog for the group-4 classes lives in [`../../pkg/api/errnames/catalog.json`](../../pkg/api/errnames/catalog.json).
293
-
294
- ### Realistic catch-site shortlist
295
-
296
- Most services only need to route on the "agent-director is sick" set. Alert on these six and let everything else propagate:
297
-
298
- - `ErrSystemInstallNotFound`
299
- - `ErrSystemInstallTooOld`
300
- - `ErrSystemInstallUnreachable`
301
- - `ErrCallerCwdUnreachable`
302
- - `ErrSystemInstallDisappeared`
303
- - `ErrCallTimeout`
304
-
305
- Everything else is either **programmer error** (bad arguments — fix the call site, do not retry) or a **normal operational signal** (an expected verb outcome you branch on, like "no such spawn" or "already decided"). `ErrConsumerSignal` sits in between: it is a runtime infrastructure failure, but a routine one during shutdown, so treat it as an operational signal rather than a page.
450
+ Every `AgentDirectorError` has `errName`, `errDescription` and `errDetails`:
451
+ the error envelope's optional `err_details` object, or `null`. Five errors
452
+ carry one, typed as exported interfaces: `ErrRelayFallenBack`
453
+ (`RelayFallenBackDetails`, with `OpenRequestFacts`), `ErrPaneAnswerInProgress`
454
+ (`PaneAnswerInProgressDetails`), `ErrClaimTooSoon` (`ClaimTooSoonDetails`),
455
+ `ErrPaneChanged` (`PaneChangedDetails`) and `ErrDialogMaybeOpen`
456
+ (`DialogMaybeOpenDetails`). So does the `ErrInternal` of a
457
+ pane answer whose key was sent but not recorded (`PaneKeySentDetails`:
458
+ `key_sent` `true` and `request_token`). Read facts from `errDetails`, never
459
+ from `errDescription`.
460
+
461
+ The public typed-error surface falls into four groups. Every class named below is exported from the package entry point. The tables are self-sufficient for choosing what to catch; the CLI error contract also applies to group 4.
462
+
463
+ For retry, escalation and shared CLI refusal handling see the
464
+ [caller contract](../../docs/caller-contract.md). Binary installation and
465
+ upgrade procedures are in [Installation](../../docs/install.md), and
466
+ human repairs in [Operator actions](../../docs/operator-actions.md).
467
+ The tables below describe the typed classes and their fields.
306
468
 
307
469
  ### 1. Library lifecycle
308
470
 
@@ -311,19 +473,19 @@ Raised by the client wrapper itself, independent of any agent-director binary.
311
473
  | Error | When it fires |
312
474
  |---|---|
313
475
  | `ErrClientClosed` | A verb was called on a `Client` after `close()`/disposal. Obtain a fresh handle with `Client.create()`. Programmer error. |
314
- | `ErrBunVersionTooOld` | The running Bun runtime is below the package's minimum. Upgrade Bun. Fires at construction. |
476
+ | `ErrBunVersionTooOld` | The running Bun runtime is below the package's minimum. Fires at construction. |
315
477
 
316
478
  ### 2. System install (agent-director binary)
317
479
 
318
- The "AD is sick" group. **Construction-time** errors are thrown by `Client.create()` / `resolveSystemBinary()` before any verb runs; **runtime** errors are thrown at verb-dispatch time on a client that constructed successfully.
480
+ **Construction-time** errors are thrown by `Client.create()` / `resolveSystemBinary()` before any verb runs; **runtime** errors are thrown at verb-dispatch time on a client that constructed successfully.
319
481
 
320
482
  | Error | Phase | When it fires |
321
483
  |---|---|---|
322
484
  | `ErrSystemInstallNotFound` | Construction | No agent-director binary was found in any checked location. Carries `checkedLocations`. |
323
485
  | `ErrSystemInstallTooOld` | Construction | A binary was found but its version is below the required floor. Carries `actualVersion`, `requiredVersion`, `binaryPath`. |
324
486
  | `ErrSystemInstallUnreachable` | Construction | A binary was found but failed the version probe (not executable, wrong arch, non-zero exit, killed). Carries `binaryPath`, `reason`, `diagnostic`, `exitCode`, `signal`. |
325
- | `ErrCallerCwdUnreachable` | Construction **and** runtime | `process.cwd()` does not resolve to a real directory. Thrown at construction if the cwd is already gone, or at the first verb call after the cwd disappears mid-flight. Carries `cwd`, `cause`. Restart your service from a valid directory. |
326
- | `ErrSystemInstallDisappeared` | Runtime | The binary path resolved at construction no longer exists at verb-dispatch (uninstalled or replaced mid-flight). Carries `verb`, `binaryPath`, `cause`. Re-install the binary, then create a new `Client`. |
487
+ | `ErrCallerCwdUnreachable` | Construction **and** runtime | `process.cwd()` does not resolve to a real directory. Thrown at construction if the cwd is already gone, or at the first verb call after the cwd disappears mid-flight. Carries `cwd`, `cause`. See [Installation](../../docs/install.md) for environment requirements. |
488
+ | `ErrSystemInstallDisappeared` | Runtime | The binary path resolved at construction no longer exists at verb-dispatch (uninstalled or replaced mid-flight). Carries `verb`, `binaryPath`, `cause`. Installation repair is owned by [Installation](../../docs/install.md). |
327
489
 
328
490
  ### 3. Per-call infrastructure
329
491
 
@@ -331,13 +493,13 @@ Thrown per verb call by the subprocess transport, not by the CLI's own validatio
331
493
 
332
494
  | Error | When it fires | Category |
333
495
  |---|---|---|
334
- | `ErrCallTimeout` | The subprocess did not complete within the configured per-call timeout. Carries `verb`, `elapsedMs`, `timeoutMs`. | Operational — include in your "AD is sick" alert set. |
496
+ | `ErrCallTimeout` | The subprocess did not complete within the configured per-call timeout. Carries `verb`, `elapsedMs`, `timeoutMs`. | Operational; see the caller contract. |
335
497
  | `ErrConsumerSignal` | The subprocess was killed by an OS signal (e.g. `SIGTERM`, `SIGINT`) before producing a result. Carries `verb`, `signal`. | Operational — routine during shutdown. |
336
- | `ErrUnknownErrorName` | The CLI returned an error envelope whose `err_name` this client version does not recognize (client older than the binary). Carries `unknownName`, `envelope`. | Programmer/version error — upgrade the client. |
498
+ | `ErrUnknownErrorName` | The CLI returned an error envelope whose `err_name` this client has no class for. This client has a class for every `err_name` the binary of its own version gives, so the binary is of a different version, most often a newer one. Carries `unknownName` (the real `err_name`) and `envelope`. | Version error; see [Installation](../../docs/install.md). |
337
499
 
338
500
  ### 4. Catalog-derived (CLI-side validation)
339
501
 
340
- These 42 classes are generated one-to-one from the shared `err_name` catalog ([`../../pkg/api/errnames/catalog.json`](../../pkg/api/errnames/catalog.json), the canonical source). They surface bad input or a verb's own state preconditions — almost all are either **programmer error** or a **normal operational signal**, so few catch sites need to name them individually. They are grouped by domain below.
502
+ These classes correspond to the shared CLI `err_name` contract. They surface bad input, a verb's own state preconditions, a config or store the CLI cannot open, or a failure of the CLI itself — almost all are either **programmer error** or a **normal operational signal**, so few catch sites need to name them individually. They are grouped by domain below.
341
503
 
342
504
  **cwd validation** (bad `cwd` argument to `spawn` — programmer error):
343
505
 
@@ -348,14 +510,19 @@ These 42 classes are generated one-to-one from the shared `err_name` catalog ([`
348
510
  | `ErrCwdNotFound` | `cwd` resolved to a path that does not exist on disk. |
349
511
  | `ErrCwdNotADirectory` | `cwd` resolved to a file (or other non-directory inode). |
350
512
 
351
- **spawn config validation** (bad `spawn` arguments — programmer error):
513
+ **spawn and template config validation** (bad `spawn` or `makeTemplate` arguments — programmer error):
352
514
 
353
515
  | Error | When it fires |
354
516
  |---|---|
355
517
  | `ErrRelayModeInvalid` | `relay_mode` was something other than `on` / `off` / empty. |
356
- | `ErrSpawnDeniedFlag` | `claude_args` contains a flag the supervisor must own (`--settings`, `--resume`, `--continue`, `--print`, `--output-format`). |
357
- | `ErrReservedEnvKey` | `extra_env` contains an `AGENT_DIRECTOR_*` key (reserved prefix). |
358
- | `ErrInstanceIdCollision` | Without `reuse_finished`, a row already exists for the supplied `claude_instance_id`, in any state. With `reuse_finished: true`, the row is live (`pending` included), or it changed or was removed after this spawn examined it (a lost race); nothing was changed. |
518
+ | `ErrSpawnDeniedFlag` | The `agent_args` of a `spawn` contain an argument the supervisor must own; nothing is written, and the description names it. A `"claude"` spawn always refuses `--settings`, `--output-format` and print (`--print`, `-p`, parsed clusters included). Session selectors and owned values are refused except on a verified finished-agent switch, where they are removed and the remainder is checked as for a plain spawn. Exact denied long names owned as option values always refuse. A `"codex"` spawn also refuses other Codex subcommands as the first word that is neither an option nor an option's value, `--remote`, `--remote-auth-token-env`, a `-c` / `--config` key at, above or under `hooks`, `tui.disable_paste_burst` or `features.hooks`, `--disable hooks`, and, while `disable_ask_user` is on, `--enable default_mode_request_user_input` and the question-tool keys. `resume` filters stored arguments without applying spawn's argument refusals; see [Pause and resume](../../docs/usage.md#pause-and-resume) for replay rules. The refused forms and argument recognition limits are in [Caller contract](../../docs/caller-contract.md#spawn-and-template-input-refusals). |
519
+ | `ErrAgentMissing` | `spawn` got no `agent` and its template names none; nothing is written. Pass `agent` (`"claude"` or `"codex"`), or put one in the template. |
520
+ | `ErrAgentInvalid` | `agent` is neither `"claude"` nor `"codex"` (the value is case-sensitive); nothing is written. |
521
+ | `ErrAgentArgsMismatch` | The template's `agent_args` are for another agent than the one this spawn resolves to, so they are not inherited; nothing is written. Spawn that agent, or pass this call's own non-empty `agent_args`, which replace the template's. |
522
+ | `ErrTemplateAgentMissing` | A template has `agent_args` and names no agent. From `makeTemplate` (`agent_args` without `agent`) and from a `spawn` that loads such a template; nothing is written. Give the template an `agent`, or remove its `agent_args`. |
523
+ | `ErrPermissionsUnsupported` | A `"codex"` spawn, or a `makeTemplate` with `agent: "codex"`, carries an `allow`, `deny` or `ask` entry; nothing is written. Drop the lists and set permission rules in the group's Codex folder, with Codex's own permission controls. |
524
+ | `ErrReservedEnvKey` | From `spawn`: an `extra_env` key (a template's included) is reserved or is not a valid env-var name; nothing is written or launched, and the description says which. Reserved: an `AGENT_DIRECTOR_*` key, or a key that sets `HOME` (`HOME` itself, or one such as `HOME=/x`), with any value, an empty one included. An `extra_env` `HOME` would send the agent's hook events to another agent-director store; set an absolute `CLAUDE_CONFIG_DIR` (a Claude Code agent) or `CODEX_HOME` (a Codex agent) to give the agent its own config. Not a valid name: the key is empty, or contains `=` or a NUL character; give each variable its own name as the key and its value as the value (`{ CLAUDE_CONFIG_DIR: "/cfg" }`, not `{ "CLAUDE_CONFIG_DIR=/cfg": "" }`). This client refuses an invalid key in the call's `extra_env` itself, before it runs the CLI. From `makeTemplate`: the template's `extra_env` has such a key, reserved or not a valid name, refused by spawn's own check; no template is written or replaced, so none is saved that `spawn` would refuse (this client refuses an invalid key itself, as for `spawn`). From `resume`: the row's stored `extra_env` has a key that sets `HOME` or is not a valid name (a row spawned before spawn refused it); nothing is written or launched. Shared repair and reuse handling is in [Spawn and template input refusals](../../docs/caller-contract.md#spawn-and-template-input-refusals); a fresh conversation has no memory of the old conversation. |
525
+ | `ErrInstanceIdCollision` | Without `reuse_finished`, a row already exists for the supplied `instance_id`, in any state. With `reuse_finished: true`, the row is live (`pending` included), or it changed or was removed after this spawn examined it (a lost race); nothing was changed. |
359
526
 
360
527
  **tmux session naming** (bad `tmux_session_name` — programmer error):
361
528
 
@@ -369,13 +536,13 @@ These 42 classes are generated one-to-one from the shared `err_name` catalog ([`
369
536
 
370
537
  | Error | When it fires |
371
538
  |---|---|
372
- | `ErrSpawnNotFound` | No spawn row matches the supplied `claude_instance_id`. |
539
+ | `ErrSpawnNotFound` | No spawn row matches the supplied `instance_id`. |
373
540
  | `ErrSpawnNotInteractive` | The target spawn is not in a live interactive state (`waiting`/`working`/`ask_user`/`check_permission`); `pending`, `ended`, and `missing` are rejected. With `allow_pending: true`, `sendKeys` allows a `pending` row but delivers keys only to a session started by the row's current launch: a `pending` row with no launch start or launch token recorded, or where only a session an earlier launch left behind is found, is still refused and nothing is sent. |
374
541
  | `ErrSpawnNotPausable` | The target spawn is not in a pausable (`waiting`) state. |
375
- | `ErrPauseTimeout` | The spawn did not reach `ended` within `pause.timeout_seconds` after `/exit`. Retry the pause; the agent may still be running. |
376
- | `ErrSpawnNotResumable` | `resume` applies only to a finished (`ended`/`missing`) spawn. A live spawn is refused because its agent is running. A `pending` spawn is refused too: it is a launch (spawn, reuse or resume) in progress whose agent has not reported in, a resumed row included. Also returned when the row changed after `resume` examined it; nothing is written. |
377
- | `ErrNoSessionId` | The spawn has no `claude_session_id` (killed before its first SessionStart), so there is nothing to resume — spawn the same `claude_instance_id` again with `reuse_finished: true`, which starts with no memory of the old conversation. |
378
- | `ErrJsonlMissing` | The resume JSONL could not be located at any candidate path — spawn the same `claude_instance_id` again with `reuse_finished: true`, which starts with no memory of the old conversation. |
542
+ | `ErrPauseTimeout` | The spawn did not reach `ended` within `pause.timeout_seconds` after `/exit`. The agent may still be running; see [Caller contract](../../docs/caller-contract.md). |
543
+ | `ErrSpawnNotResumable` | `resume` applies only to a finished (`ended`/`missing`) spawn. A live spawn is refused because its agent is running. A `pending` spawn is refused too: it is a launch (spawn, reuse or resume) in progress whose agent has not reported in, a resumed row included. Abandoned or failed launch handling is owned by [Caller contract](../../docs/caller-contract.md) and [Maintenance](../../docs/maintenance.md). Also returned when the row changed after `resume` examined it; nothing is written. |
544
+ | `ErrNoSessionId` | The spawn has no `session_id` (killed before its first SessionStart, or a spawn's or reuse's launch that never reported in and that `find-missing` marked `missing`), so there is nothing to resume; recourse contract: spawn the same `instance_id` again with `reuse_finished: true` and the row's `agent` (`get` shows it), which starts with no memory of the old conversation. See [Caller contract](../../docs/caller-contract.md) for the recovery procedure. |
545
+ | `ErrJsonlMissing` | The current session's resume JSONL could not be located at any candidate path (for a Codex agent, only its current recorded path; older sessions are never tried); recourse contract: spawn the same `instance_id` again with `reuse_finished: true` and the row's `agent` (`get` shows it), which starts with no memory of the old conversation. See [Caller contract](../../docs/caller-contract.md) for the recovery procedure. |
379
546
  | `ErrListInvalidLabel` | A `list` label filter could not be parsed as `key=value`. |
380
547
  | `ErrProbeUnsupported` | No verb returns it: `find-missing` no longer reads process environments, the only path that returned it. The name stays catalogued (and listed for `find-missing`) so the client still maps it. |
381
548
 
@@ -384,10 +551,10 @@ These 42 classes are generated one-to-one from the shared `err_name` catalog ([`
384
551
  | Error | Class | When it fires |
385
552
  |---|---|---|
386
553
  | `ErrTmuxNotAvailable` | ENVIRONMENT | The `tmux` binary is not on PATH or refuses to execute, the tmux socket is not accessible to this user, or its per-user socket directory cannot be used (`spawn` then writes nothing). `kill`, `resume`, `readPane`, `sendKeys` and `pause` return it too: tmux could not be run, the socket is not accessible to this user, or this is not the tmux server the agent was launched on. |
387
- | `ErrTmuxSessionCreate` | LAUNCH FAILURE | The session could not be created or labelled; the new row stays `pending`. After tmux answers "duplicate session", `spawn` returns it only when the session holding the requested name was gone by the re-lookup; the new row is then ended (the error says if it was not), and the error names the instance id (a minted one included) and the retry: spawn that `claude_instance_id` again with `reuse_finished: true` once the name is free (if the row was not ended, once `get` shows it `ended` or `missing`), since a plain `spawn` of the id collides with its row. From `resume`, the session could not be created or labelled, or after "duplicate session" no session held the name when it was looked up again; the row is restored to `ended` or `missing` (the error says if it was not). A name found held is never this error. |
388
- | `ErrTmuxUnresponsive` | UNAVAILABLE (transient) | tmux did not answer in time, or gave a reply agent-director does not recognise. From `spawn`'s or `resume`'s session-creating call: the session may have been created and the row stays `pending`; do not retry until `get` shows the row `ended` or `missing`; then a `spawn` of an explicit `claude_instance_id` is retried with `reuse_finished: true`, since a plain `spawn` of the id collides with its finished row. From a plain `spawn` after "duplicate session": the re-lookup could not be read, or more than one session's name matches the requested name; the new row is ended (the error says if it was not) and the error names the retry with `reuse_finished: true`, as for `ErrTmuxSessionCreate`. From `resume`'s check before the launch, with nothing written: the row's own session or agent process appears to still be stopping or still starting, tmux's answer could not be read, or more than one session's name matches the row's session name; retry later. After "duplicate session" at the create, the same cases, and the row is restored (the error says if it was not). From `kill`: the lookup or the pane listing could not be read (nothing was done), or a kill was sent, the agent process could not be checked and the follow-up lookup could not be read (the kill may or may not have taken effect); retry later with backoff. From `readPane`, `sendKeys` and `pause`: tmux did not answer usably; after a timed-out send the keys (or `/exit`) may have been delivered. Where `sendKeys`' text may be typed, the error names the next step instead of "retry later", because the same call would type the text a second time: after a timed-out text call, `readPane` and, if the text is typed, `sendKeys` with empty `text`, otherwise the same `sendKeys`; after a failed or timed-out Enter, `sendKeys` with empty `text`, which submits it. A `pause` is retried later as it is: before typing `/exit` it clears the line the agent's cursor is on, so an `/exit` the failed `pause` left typed is not doubled. |
389
- | `ErrTmuxSessionConflict` | CONFLICT (permanent until a human looks) | A tmux session conflict that needs a human. From `spawn` with an explicit `claude_instance_id` that has no row: a session of this store still labelled with that id is left over from an earlier life, or labels conflict; nothing is written. From a plain `spawn` whose requested tmux session name is already held (tmux answered "duplicate session"): the holder is a session left over from an earlier life of this id, another row's session, a session of another agent-director store, or one with no valid instance id, or labels conflict; the new row is ended (the error says if it was not) and the error names the blocking session. Another row's or another store's session is another agent and is never ended; the holding session is never read or typed into. From `resume` of a finished row, before anything is written and with no session touched: a session holds the row's session name (another row's session, a session of another agent-director store, or one with no valid instance id), a session is left over from an earlier life of this id, the row's own old session (or its agent process still running with no session) is past the stopping window and the starting-session bound, or labels conflict; the error names the blocking session. After "duplicate session" at the create, the same cases, and the row is restored (the error says if it was not). None of these means the agent is dead. From `kill` on a live row: the session found is not this launch's session (it carries the label of an earlier launch with this row's own id), or labels conflict; no kill was sent. From `readPane`, `sendKeys` and `pause`: the agent's pane was not found, a session an earlier launch left behind is there (for `readPane`, more than one; for `sendKeys`, on a live row), or labels conflict; nothing was read or sent. See "Operator actions" in the agent-director README. |
390
- | `ErrTmuxKillFailed` | UNAVAILABLE | `kill` only: the agent process still runs after `kill`. A kill was sent and the agent process, or another process in a pane of the agent's session, still ran after the kill exit wait (`kill_exit_wait_ms`); or the process cannot be checked and its labelled session is still there; or no session or pane of this launch was found while the agent process runs, so no kill was sent. Retry `kill` later; never `delete` the row. |
554
+ | `ErrTmuxSessionCreate` | LAUNCH FAILURE | The session could not be created or labelled. A plain launch normally stays `pending`; a duplicate-name re-lookup finding no holder ends its new row. Resume and reuse attempt a guarded restore after a non-timeout failure; the description reports whether it applied. |
555
+ | `ErrTmuxUnresponsive` | UNAVAILABLE | tmux did not answer usably, or a launch still appears to be starting or stopping. A timed-out launch stays `pending`; after a timed-out send, keys may have been delivered. See the [caller contract](../../docs/caller-contract.md#caller-contract) before retrying. |
556
+ | `ErrTmuxSessionConflict` | CONFLICT | A held name, a session left over from an earlier life (an earlier launch), conflicting labels, or the agent pane was not found. The description names the blocker and whether a new row was ended or a prior row restored. Nothing is sent to a conflicting session. Human repair is owned by [Operator actions](../../docs/operator-actions.md). |
557
+ | `ErrTmuxKillFailed` | UNAVAILABLE | `kill` only: the agent process still runs after `kill`. A kill was sent and the agent process, or another process in a pane of the agent's session, still ran after the kill exit wait (`kill_exit_wait_ms`); or the process cannot be checked and its labelled session is still there; or no session or pane of this launch was found while the agent process runs, so no kill was sent. Retry and refusal handling is owned by [Caller contract](../../docs/caller-contract.md). |
391
558
  | `ErrTmuxSendKeys` | GONE | `sendKeys` and `pause`: the row's session or pane is not there. |
392
559
  | `ErrTmuxCaptureFailed` | GONE | `readPane`: the row's session or pane is not there. |
393
560
 
@@ -397,12 +564,18 @@ Only a GONE error means the row's session is not there (for `kill`, GONE is succ
397
564
 
398
565
  | Error | When it fires |
399
566
  |---|---|
400
- | `ErrSendKeysWhileRelayed` | `send-keys` was attempted against a spawn sitting on a `check_permission` row with `relay_mode=on`. |
567
+ | `ErrSendKeysWhileRelayed` | A `sendKeys` or `pause` while a relay hook may still answer a request. Nothing was sent. The message distinguishes an undecided request from a recorded verdict still being delivered; see the [caller contract](../../docs/caller-contract.md#permission-relay). |
568
+ | `ErrRelayFallenBack` | A request's relay hook is gone and acked no verdict, with no pane answer recorded through agent-director: no answer from the relay reached the agent. Thrown by `decide` on that request, within seconds of the hook's end (after the request's `confirm_by` when agent-director cannot check the hook's process); no verdict was recorded, the caller's is kept as the request's `attempted_decision`. Thrown by a `sendKeys` without `request_token`, and by `pause`, while any request of the spawn is so; nothing was sent. `errDetails` is a `RelayFallenBackDetails`: the request's facts, the spawn's `state` and its other `open_requests`. Pane-answer handling is owned by [Permission relay](../../docs/caller-contract.md#permission-relay); the relevant API methods are `sendKeys` with `request_token` and `recordPaneAnswer`. For a request recorded by an older binary, `decide` throws it once the request's record is still open 2 s after its relay window ended (a call from 1 s before the window ends first waits for that instant, at most 3 s), and only while the spawn is still in `check_permission` with no other open request and none recorded after this one, otherwise `ErrNoOpenPermissionRequest`. |
569
+ | `ErrDialogMaybeOpen` | A `sendKeys` without `request_token` and without `expect_pane_sha256`, or a `pause`, on a spawn with `relay_mode=on`, while a permission request of the spawn is not proven gone by the agent's hooks (a Claude agent's tool's PostToolUse, the main agent's end of turn after it (on a Codex Spawn, its `Stop` or Interrupt), or the agent's end), whatever agent-director's records say of it (`"delivered"`, a pane answer, `recordPaneAnswer`); nothing was sent. `errDetails` is a `DialogMaybeOpenDetails`: the oldest such request with its facts and `unproven_since`, the spawn's `state` and its other `unproven_requests`. Retry, escalation and pane-hash handling are owned by [Permission relay](../../docs/caller-contract.md#permission-relay). A subagent's denied request holds until the agent ends, and on a Codex Spawn so does an allowed one. `pause` takes no hash; stopping a held Spawn is covered by [Caller contract](../../docs/caller-contract.md). |
570
+ | `ErrPaneChanged` | `sendKeys` or `recordPaneAnswer` with `expect_pane_sha256`: the agent's pane no longer has that hash; nothing was sent or recorded. `errDetails` (`PaneChangedDetails`) never carries the new hash; shared pane handling is in [Permission relay](../../docs/caller-contract.md#permission-relay). |
571
+ | `ErrPaneAnswerInProgress` | A pane answer or `recordPaneAnswer` while another sender still owns the request. Nothing was sent or recorded; `errDetails` is `PaneAnswerInProgressDetails`. |
572
+ | `ErrClaimTooSoon` | `recordPaneAnswer` before the request's relay hook has been gone 2 s, or while it may still answer the request; nothing was recorded. `errDetails` is `ClaimTooSoonDetails`, with `not_before` (`null` only while the hook is seen running); retry handling is in [Permission relay](../../docs/caller-contract.md#permission-relay). |
401
573
  | `ErrRelayModeOff` | `decide` was called on a spawn whose `relay_mode` is not `on`. |
402
- | `ErrInvalidDecision` | `--decision` was neither `allow` nor `deny`. |
574
+ | `ErrInvalidDecision` | `decision` was neither `allow` nor `deny`. |
403
575
  | `ErrMissingRequestToken` | `decide` was called with an empty `request_token`. |
404
- | `ErrNoOpenPermissionRequest` | No open permission-request row matches the `(instance_id, request_token)` pair (or it was already decided). |
405
- | `ErrAlreadyDecided` | A permission-request row exists but has already been decided; first decide wins. |
576
+ | `ErrNoOpenPermissionRequest` | No open permission-request row matches the `(instance_id, request_token)` pair. `decide` also throws it, recording nothing, for an open request of a spawn that is `ended` or `missing`: such a request is closed; see [Permission relay](../../docs/caller-contract.md#permission-relay) for handling. It throws it too for a request closed with its spawn (when its agent ended it, or `find-missing` or `pause` moved a Codex row to `ended`, `decision_reason` `"ended"` for an undecided one, or when `find-missing` marked it `missing`) before the request's relay hook confirmed a verdict recorded on it, `find-missing`'s own deny excepted, whether or not the spawn was resumed since: the request stays closed, `get` and `list` no longer show it, and `getPermission` reads its `delivery` as for any request (`"delivered"` only if its relay hook confirmed). Pane handling is owned by [Permission relay](../../docs/caller-contract.md#permission-relay). A pane answer (`sendKeys` with `request_token`) and `recordPaneAnswer` throw it for such a closed request too, nothing sent or recorded. For a request recorded by an older binary, `decide` also throws it when the request's record is still open 2 s after its relay window ended but the spawn has left `check_permission`, has recorded a later request, or has another request open: the request's dialog may have closed, and a pane answer to a closed dialog is typed into the agent's prompt; see [Permission relay](../../docs/caller-contract.md#permission-relay) for handling. `send-keys` does not apply this check. |
577
+ | `ErrAlreadyDecided` | A permission-request row exists but has already been decided; first decide wins. This includes a request the relay hook denied when its time ran out (`getPermission` returns `decision_reason` `"timeout"`); the hook recorded that deny with its confirmation before returning it to the agent, so there is nothing to answer at the pane. It also includes a request `find-missing` denied when it marked the spawn `missing` (`decision_reason` `"find_missing"`), and one closed at the pane (`pane_answer` `"sent"`, `"outside"` or `"tool_ran"`, with a `decision` or, for an `"unknown"` claim, none): `decide` on it records nothing, not even `attempted_decision`. A pane answer or `recordPaneAnswer` on a request its relay hook confirmed, or one already closed at the pane, throws it too. |
578
+ | `ErrStoreBusy` | `decide` was called with `max_wait_ms`, and the bound ran out, during its reads or its write, before its verdict was recorded: another agent-director process held the store that long (or, for a request recorded by an older binary, `decide` would have had to wait past the bound for the end of its relay window). Nothing was recorded; retry handling is in [Caller contract](../../docs/caller-contract.md). Once the verdict is recorded, `decide` never throws it: a bound reached while it waits for the relay hook's confirmation resolves with `delivery` `"not_confirmed"`. Without `max_wait_ms`, `decide` never throws it. A pane answer (`sendKeys` with `request_token`) or `recordPaneAnswer` throws it when the store's write lock was not taken within its busy timeout; nothing was sent or recorded; retry handling is in [Caller contract](../../docs/caller-contract.md). |
406
579
  | `ErrPermissionRequestNotFound` | No permission-request row exists for the supplied `request_token`. |
407
580
  | `ErrAmbiguousRequest` | `request_token` was empty and more than one open request exists for the spawn. |
408
581
 
@@ -412,15 +585,35 @@ Only a GONE error means the row's session is not there (for `kill`, GONE is succ
412
585
  |---|---|
413
586
  | `ErrTemplateNameUnsafe` | A template name fails the safety check (path traversal, absolute path, hidden name, or trivial garbage). |
414
587
  | `ErrTemplateNotFound` | The named template `.toml` does not exist on disk. |
415
- | `ErrTemplateMalformed` | A template file exists but fails schema validation (unknown keys, wrong types, bad enums). |
416
- | `ErrTemplateExists` | `make-template` target already exists; the verb never overwrites. |
588
+ | `ErrTemplateMalformed` | A template file exists but fails schema validation (unknown keys, an `agent` other than `claude` or `codex`, the old name of the `agent_args` key, wrong types, bad enums, or one key set under names that differ only in letter case, such as `RELAY_MODE` and `relay_mode`). `makeTemplate` also throws it, before writing anything, for an `agent` that is not exactly `claude` or `codex`. |
589
+ | `ErrTemplateExists` | `make-template` target already exists and `overwrite` is not `true`. |
417
590
 
418
591
  **misc**:
419
592
 
420
593
  | Error | When it fires |
421
594
  |---|---|
422
- | `ErrInvalidFlags` | CLI flag parsing rejected the invocation, or `spawn` was given an explicit `claude_instance_id` containing an ASCII control character (0x00–0x1f or 0x7f). |
595
+ | `ErrInvalidFlags` | CLI flag parsing rejected the invocation; a call carried an old name of a renamed key (thrown before any process starts, naming the new key); `spawn` was given an explicit `instance_id` containing an ASCII control character (0x00–0x1f or 0x7f); `readPane`'s `n_lines` or `list`'s `limit` is negative (0 or omitted gives the default: 25 lines, no cap); `decide` was given a negative `max_wait_ms`; `sendKeys` was given params that do not fit together (a pane answer without `as`, `key` or `expect_pane_sha256` or with `text`; `key` with a non-empty `text`; `no_enter` with neither; `as` without `request_token`; a `key` that is neither a named key nor one character; a malformed hash); or `recordPaneAnswer` was given an `as` other than `"allow"`, `"deny"` or `"unknown"`, or a missing or malformed hash. Nothing was changed, sent or recorded. |
596
+
597
+ **CLI setup** (the CLI could not load its config or open its store, so no verb ran — operational):
598
+
599
+ | Error | When it fires |
600
+ |---|---|
601
+ | `ErrConfigMalformed` | The CLI refused its config file, `~/.config/agent-director/config.toml`: it cannot be read, does not parse as TOML, or sets a value agent-director refuses (for example a negative `[pause] timeout_seconds`). The description names the file and why: the parse error, or every refused key with its value and the values it allows. Every call that opens the store fails this way until an operator fixes the file. See the caller contract for handling. |
602
+ | `ErrStoreOpen` | The CLI could not open its store; the description says what failed. This includes `HOME` unset or empty with no `home` option (`api: expand config path: …`): every call that opens the store is then refused, whatever `storePath` is. With `createIfMissing: false` it includes a store that does not exist (`database not initialized`); nothing was created. It says nothing about any agent. |
603
+ | `ErrSchemaMismatch` | The CLI refused to open its store: the store was written by a newer agent-director than the binary (`found user_version=<N>, want <M>`), or it has no valid store id. The description says which. Nothing was written, and every call that opens the store fails this way until an operator acts: a newer store needs the agent-director release that wrote it. See Operator actions for recovery. It says nothing about any agent. |
604
+ | `ErrSchemaMigrationRequired` | The CLI refused to open its store: the store is older than the binary and must be migrated first. The description gives both schema versions. Nothing was written, and every call that opens the store fails this way until an administrator migrates the store; no call through this client can. See the caller contract for handling. It says nothing about any agent. |
605
+ | `ErrOldLayout` | The CLI refused to open its store: it was about to open the default store (no `storePath`, and no `[store] db_path` in its config file), no store exists in `~/.config/agent-director`, and the old directory exists. Nothing was created, and every call that opens the store fails this way until an operator runs this release's `install.sh`. See the caller contract for handling. It says nothing about any agent. |
606
+
607
+ **CLI itself** (the CLI failed, or does not know the verb, rather than refusing the call's input or state):
608
+
609
+ | Error | When it fires |
610
+ |---|---|
611
+ | `ErrInternal` | A CLI failure with no more specific name. Its description reports what failed and whether anything changed. A pane answer whose key was sent but not recorded carries `PaneKeySentDetails` with `key_sent: true`; see the [caller contract](../../docs/caller-contract.md#permission-relay). |
612
+ | `ErrJSONMarshal` | The verb ran and succeeded, but the CLI could not write its JSON result, so the result is lost and whatever the call changes was changed (a `spawn` launched its agent). A bug in agent-director. Check with `get`, `status` or `list` before you repeat a call that changes something. |
613
+ | `ErrUnknownVerb` | The binary does not know the called verb. No verb ran; binary and client versions differ. See [Installation](../../docs/install.md). |
614
+ | `ErrTrailWrite` | Only the CLI's internal `trail-emit` command gives it, when it cannot write its trail event. No method of this client runs `trail-emit`, so a call through this client does not get it. |
423
615
 
424
- ## Architecture
616
+ ## See also
425
617
 
426
- See [`../../docs/architecture.md`](../../docs/architecture.md) for the internal design. Dedicated subsections cover: Client lifecycle, the subprocess call recipe, Per-platform packaging, Error mapping, TS smoke-test harness, and TS envelope-diff regression.
618
+ [Caller contract](../../docs/caller-contract.md), [Permissions](../../docs/permissions.md)
619
+ and [Installation](../../docs/install.md) own shared procedures.