@agfpd/iapeer 0.4.68 → 0.4.70

package/docs/15-fleet-api.md

@@ -55,8 +55,14 @@ The full fleet state. The peer rows are produced by the **same in-process functi
       "last_active_ms": 1751731100000,
       "attached": true,
       "launchd_managed": false,
-      "wake_policy": "warm"
+      "wake_policy": "warm",
+      "approval_mode": "yolo"
     }
+  ],
+  "approvals": [
+    { "id": "a1", "personality": "boris", "runtime": "claude", "kind": "circuit-breaker",
+      "tool": "dangerous-rm", "summary": "rm -rf /tmp/x",
+      "content": "cmd=\"rm -rf /tmp/x\" target=\"/tmp/x\"", "createdMs": 1751731100000, "expiresMs": 1751731400000 }
   ]
 }
 ```
@@ -68,11 +74,13 @@ Field notes:
 - `attached` — any runtime attached (peer-level convenience).
 - `launchd_managed` — launchd owns this peer's lifecycle (H4): the daemon never wakes/reaps it, and wake/stop/start commands are guarded accordingly.
 - `wake_policy` — `warm` (default: wake-on-message, idle-reap, resume) or `ephemeral` (stateless worker: serial task queue, die-after-reply).
+- `approval_mode` — the peer's human-approval mode (docs/17-approval): `yolo` (default — launched with the runtime bypass flag, the supervisor auto-confirms circuit-breakers) or `gated` (launched without bypass; the runtime's blocking approval requests are routed to a human through the daemon approval broker). Additive field; a pre-approval daemon omits it — clients MUST treat its absence as `yolo`.
 - `queue_depth` — ephemeral peers only: pending tasks across the peer's serial queues.
 - `host.memory` / `host.voice` — the provider slots (`null` = empty slot); `heartbeatAgeSecs: null` with a non-null slot = provider declared but its daemon isn't heartbeating.
 - `host.fda` — Full Disk Access of the binary: `true` / `false` / `null` (undeterminable).
 - The daemon answering **is** the health signal: there is no `healthy` boolean. A dashboard that cannot reach any advertised address should render the daemon as down (this is also why a purely API-fed dashboard is insufficient when the daemon itself is broken — the built-in TUI keeps its direct in-process read path for exactly that case).
 - The peer's **LLM model is deliberately absent**: the effective model of a live session is not an observable registry fact (static launch pins exist, but reporting a pin as «the model» would lie under runtime auto-switching). If it ever becomes observable, it will appear as an additive field.
+- `approvals` (top-level, docs/17-approval) — the pending human-approval queue, the SAME items `GET /fleet/v1/approvals` returns, carried in the snapshot so a client that already re-fetches `/snapshot` on every event renders the queue with no extra call. **ADDITIVE + OMITTED when the queue is empty** — a client MUST treat its absence as an empty queue (the same rule as `approval_mode`). Each item: `id` (broker id, the target of `POST /fleet/v1/approvals/<id>/(approve|deny)`), `personality` + `runtime` (whose action), `kind` (`tool`|`plan`|`question`|`circuit-breaker`), `tool` (the tool / breaker name), `summary` (a one-line badge string), `content` (the FULL verbatim action — command / diff / plan; criterion #7), `createdMs` / `expiresMs`. The broker's item is a superset — unknown extra fields (`title`, `approvers`) MUST be ignored (obligation 2).
 
 ## GET /fleet/v1/peers/&lt;personality&gt;
 
@@ -132,7 +140,7 @@ What the headline states look like on the stream: a peer **waking** is `ev=wake`
 
 `from` is optional: a full `<runtime>-<personality>`, or a bare personality (its default runtime). Default: the **single natural-intelligence peer** of the registry — a GUI-originated message is the human's. With zero or several natural peers the request is refused (`400`) with an instruction to pass `from`.
 
-Not part of the API, deliberately: **attach** (a terminal handoff — a client opens the system terminal with `iapeer attach <peer>`), registry/host **admin verbs** (`create`/`remove`/`update`/`uninstall` — will be added when a client actually needs them), **approve** (no approval broker exists yet; it will arrive as new endpoints + `ev` kinds under this same contract).
+Not part of the *command* API, deliberately: **attach** (a terminal handoff — a client opens the system terminal with `iapeer attach <peer>`), registry/host **admin verbs** (`create`/`remove`/`update`/`uninstall` — will be added when a client actually needs them). The **human-approval broker** now lives under `/fleet/v1/approvals*` (`GET` the queue / one item, `POST /<id>/(approve|deny)`) with the `approval-request` / `approval-resolved` SSE `ev` kinds and the `approvals` snapshot field above — the full contract is **docs/17-approval**.
 
 Errors are always `{"error": "…"}` with an honest status: `400` malformed request, `401` bearer required, `404` unknown peer/endpoint, `405` wrong method, `502` the verb itself failed, `500` internal.
 

package/docs/16-tray.md

@@ -16,10 +16,13 @@ activation that also installs SwiftBar.app when it is absent.
 
 ## What you see
 
-- **Menu bar:** an antenna glyph + the count of peers with a live session. When no
-  advertised daemon address answers, a red warning triangle instead (the daemon is down —
-  a purely API-fed dashboard cannot show a broken daemon any other way; the built-in TUI
-  keeps its direct read path for that case, see [15](15-fleet-api.md)).
+- **Menu bar:** an antenna glyph + the count of peers with a live session. When one or more
+  **human-approval** requests are pending, the menu bar instead shows a **red `N.circle.fill`
+  badge** (the iOS-notification look — a red circle with the count) so the owner sees an
+  awaiting request at a glance. When no advertised daemon address answers, a red warning
+  triangle instead (the daemon is down — a purely API-fed dashboard cannot show a broken
+  daemon any other way; the built-in TUI keeps its direct read path for that case, see
+  [15](15-fleet-api.md)).
 - **Dropdown:** a host header (`iapeer <version> · up <uptime>`) and the memory/voice
   provider heartbeats, then one row per peer:
   - `<peer>  <runtime><glyph> …  <age>` with the same glyph semantics as the CLI —
@@ -36,6 +39,16 @@ activation that also installs SwiftBar.app when it is absent.
     peers (telegram / notifier, `🔒`) are not pty-attachable** — their rows are plain status
     lines. Lifecycle actions (Wake / Stop / Start / New / Interrupt / Refresh / Compact) live
     in the **Manage** submenu, each a `POST /fleet/v1/peers/<peer>/<cmd>` via `iapeer tray cmd`.
+- **Pending approvals (docs/17):** when the queue is non-empty, the **top of the dropdown** shows
+  each pending request **expanded, with no extra clicks** — a header (`<peer> · <tool>`), the
+  **verbatim action content** (the command / diff / plan, monospace, capped for the menu; the FULL
+  content stays in `iapeer approvals`), then **Allow** / **Deny** items directly below. Clicking runs
+  `iapeer tray approve|deny <id>` in the background → the broker resolves → the stream re-renders (the
+  badge clears). The peer with a pending request is **highlighted in the fleet list** (a `⚠` prefix, a
+  red `🔴N` count, the row painted red) so the owner sees *which* peer is waiting. This channel is
+  **always on** — the approval queue is reflected whenever it is non-empty, independent of everything
+  else; an empty queue shows no section and no badge. (A true *pulse* animation is not possible in a
+  static SwiftBar menu — the highlight + badge is its equivalent.)
 
 The list updates itself: the plugin is **streamable** — it subscribes to the event stream
 and re-fetches the snapshot on every change (a peer waking, an operator stop/start, a
@@ -54,6 +67,7 @@ whole dashboard twice.
 | `iapeer tray uninstall` | Remove the plugin file and refresh SwiftBar. **Never touches the fleet** — the daemon, TUI and delivery keep running; SwiftBar.app is left installed (it may host other plugins). |
 | `iapeer tray render [--stream]` | Print the SwiftBar plugin output. `--stream` is the streamable loop the plugin runs; the one-shot form is the poll fallback and the test surface. |
 | `iapeer tray cmd <command> <peer> [runtime]` | POST a fleet command (`wake`/`stop`/`start`/`new`/`refresh`/`interrupt`/`compact`) — the menu's lifecycle actions call this. |
+| `iapeer tray approve <id>` · `iapeer tray deny <id> [reason]` | Resolve a pending human-approval (docs/17) — `POST /fleet/v1/approvals/<id>/(approve\|deny)` over the same unix-first fleet client. The menu's Allow/Deny items call these; the single-queue invariant means the resolution is seen by every channel (CLI, telegram). |
 | `iapeer tray status` | Read-only: is the fleet API up (from `router.json`), is SwiftBar installed and where is its plugin dir, is the plugin file present. Repairs nothing. |
 
 ## How it is wired

package/docs/17-approval.md

@@ -0,0 +1,128 @@
+# 17 — Human approval
+
+A peer can run in one of two **approval modes**. In `yolo` (the default — every peer today) the agent acts autonomously: the runtime is launched with its bypass flag and nothing asks a human before a tool runs. In `gated` the peer is launched **without** bypass, and every blocking approval the runtime would raise is routed to a **human** through the daemon's approval broker — a Telegram button, a tray click, or `iapeer approve` on the CLI. The human's `allow`/`deny` (with a reason) flows back into the runtime and the tool proceeds or is refused.
+
+This is a **normative contract**. The approval broker is the daemon's, the fleet endpoints and `ev` kinds below are the surface that operator faces (CLI, tray, the Telegram runtime) are written against — not the daemon source. The interception facts (which runtime event fires, in which shape) are pinned to **Claude Code 2.1.201** and **codex-cli 0.142.5**, taken from the live binaries + current runtime docs.
+
+`gated` means **«ask before acting»**, not «sandboxed». It removes the bypass so blocking questions surface; it does **not** add an OS sandbox (a separate axis, not in v1). On codex, gated is explicitly `approvals ON + sandbox OFF` (see the toggle table).
+
+## The approval-mode toggle
+
+### Profile field
+
+A foundation-owned lifecycle field in `peer-profile.json`, next to `wake_policy` / `initial_prompt`:
+
+```json
+{ "approval_mode": "gated" }
+```
+
+`"yolo" | "gated"`, **default `yolo`**. Only `gated` is persisted — writing `yolo` **removes** the field (so a `gated→yolo→gated` round-trip is byte-identical, and the whole fleet keeps behaving exactly as before this feature existed). The one place the «absent ⇒ yolo» default lives is `approvalModeOf(profile)`; every reader (launch, supervisor, fleet snapshot, CLI) resolves through it and never re-derives it. The mode appears in the fleet snapshot as the additive `approval_mode` field (docs/15) by reading the local profile — a pre-approval daemon omits it and clients MUST treat its absence as `yolo`.
+
+### Launch surfaces the flip touches
+
+The bypass is a **launch argument**, different per runtime, and the mode is a coordinated operation over **all** the surfaces that argument implies. iapeer owns the launch, so completeness is on the foundation.
+
+**claude** (Option D — a matcher-free `PermissionRequest` hook; verified live 2.1.201):
+
+| # | Surface | yolo | gated |
+|---|---|---|---|
+| C1 | argv `--dangerously-skip-permissions` | present | **removed** |
+| C2 | argv permission-mode | (bypass) | `--permission-mode default` (explicit — never inherits an acceptEdits/bypass defaultMode) |
+| C3 | ready-gate marker `isInputReady` | needs the `bypass permissions on` banner | banner is **absent** → the marker is mode-aware (composer `❯` + boot dialogs cleared), else the peer never becomes ready and the wake fails |
+| C4 | boot-dialog «Bypass Permissions mode» accept | appears (first bypass) | not shown (no bypass) |
+| C5 | `PermissionRequest` hook in `<cwd>/.claude/settings.json` | **absent** (0 overhead, byte-identical to today) | **installed** — matcher-free (see below), `command = iapeer approval-hook` |
+| C6 | allow-rule for the peer's own MCP tool (`permissions.allow: ["mcp__iapeer__send_to_peer"]`) | not needed (bypass) | **needed** — else default-mode gates the peer's own IAP channel and it hangs on `send_to_peer` |
+| C7 | supervisor circuit-breaker (dangerous-rm, above the permission layer) | auto-Yes + audit log | **routed to a human** through the broker |
+| C8 | argv `--disallowedTools AskUserQuestion` | stays | stays in v1 (see Limitations) |
+
+**Why matcher-free `PermissionRequest`, not `PreToolUse`.** `PermissionRequest` fires **only when the runtime's permission config decided to prompt** — a call not covered by an allow/deny rule. So the policy of *what to ask* stays 100% at the runtime: a user tunes it with ordinary permission rules (a tool in `permissions.allow` is never asked → the hook never fires → auto-allowed). No class matcher to drift, no new tool slipping through, no hang. iapeer only seeds the hook + the one allow-rule for the peer's own MCP tool.
+
+**codex** (`PreToolUse` hook — verified live, codex-cli 0.142.5):
+
+| # | Surface | yolo | gated |
+|---|---|---|---|
+| X1 | argv `--dangerously-bypass-approvals-and-sandbox` | present | **removed** |
+| X2 | argv approval/sandbox | (bypass) | `-c approval_policy=on-request -c sandbox_mode=danger-full-access` — approvals **ON**, sandbox **OFF** (so loopback-MCP `send_to_peer` + writes to the memory vault outside cwd still work; `workspace-write` would cut the network and external paths). Session-scoped via `-c`, not host config. |
+| X3 | `PreToolUse` hook `<cwd>/.codex/hooks.json` + trust pre-seed in `~/.codex/config.toml [hooks.state]` | **absent** | **installed + trusted** (`preSeedCodexHooksTrust`; an untrusted codex hook is silently skipped) |
+| X4 | codex cwd-trust `[projects."<cwd>"] trust_level="trusted"` | pre-trusted (both modes) | pre-trusted (matters more with approvals active) |
+| X5 | ready-gate `isInputReady` (`›` composer) | mode-independent | unchanged |
+
+The codex hook is matched by tool-name regex `^(Bash|Shell|shell|local_shell|exec|apply_patch|ApplyPatch)$` — the coarse class matcher lives on the runtime's own `hooks.json` (the user tunes it as ordinary runtime config).
+
+### Idempotency and the application moment
+
+- **argv surfaces** (C1–C2, C8, X1–X2) are computed from the mode on every launch — structurally idempotent, no accumulation.
+- **settings.json / hooks.json** (C5–C6, X3) are add-on-gated / remove-on-yolo with a no-clobber merge, keyed on the stable `approval-hook` marker: our block is written deterministically and removed cleanly (an emptied `hooks.PermissionRequest` / `PreToolUse` array is dropped, an emptied `hooks` / `permissions` object is dropped, foreign hooks/rules untouched). A `gated→yolo→gated` round-trip restores the pre-install bytes.
+- **codex trust** (X3–X4) reuses the already-idempotent `preSeedCodexHooksTrust` / `removeCodexHooksTrustUnder`.
+
+All surfaces are read/applied **at session start**. A **live session keeps its launched mode** until the next fresh session — exactly like an agentic peer picking up new doctrine lazily on its next wake. The toggle (1) persists `approval_mode`, (2) idempotently brings the settings/hooks surfaces to the mode, (3) does **not** touch the live session. To apply immediately, start a fresh session (`iapeer approval-mode <peer> <mode> --now`, or `iapeer new`/`refresh`).
+
+## Interception mechanism
+
+Both runtimes carry a Claude-compatible **hook** system that intercepts an approval programmatically and returns `allow`/`deny` + a reason + the structured action content. That is the primary mechanism. **pty screen-scrape is a backstop for one class only** — claude's `dangerous-rm` circuit-breaker, which sits *above* the permission layer and no hook can see.
+
+- **claude `PermissionRequest`** — stdin carries `{tool_name, tool_input, …}`; the hook prints `{"hookSpecificOutput":{"hookEventName":"PermissionRequest","decision":{"behavior":"allow|deny","message":"…"}}}`. A `deny` carries `message` to the model. Fires only on prompt-worthy calls.
+- **codex `PreToolUse`** — same stdin shape; prints `{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow|deny","permissionDecisionReason":"…"}}`. `exit 2` (+ stderr) also denies. Verified live (0.142.5): codex fires `PreToolUse` (not `PermissionRequest`) for tool calls with `tool_name:"Bash"` for shell; a `deny` hard-blocks the tool and the reason reaches the model even under `sandbox_mode=danger-full-access` — so under the gated config (danger-full-access + on-request → `permission_mode=bypassPermissions`) the hook is the SOLE gate.
+- **supervisor circuit-breaker** — claude's `dangerous-rm`/`rmdir` guard (and the standard command-approval prompt a no-bypass session shows) is a TUI select the hook never sees. The pty supervisor reads it off its authoritative model and, under gated, POSTs it to the broker (below); under yolo it auto-presses YES with an audit line.
+
+The hook binary is the `iapeer approval-hook` subcommand: it reads the runtime's hook JSON on stdin, resolves `PEER_PERSONALITY`/`PEER_RUNTIME` from its session env and the daemon URL from `router.json`, POSTs a blocking request to the broker, and prints the runtime-appropriate decision JSON.
+
+## Nomenclature v1 and content per action (criterion «what is being approved»)
+
+In every channel a human sees the **concrete content** of the action, not just the tool name.
+
+**claude** — `Bash` → full command (+ description); `Edit` → file + old/new; `Write` → file + content; `ExitPlanMode` → the plan text; `dangerous-rm` circuit-breaker → the full prompt + the rm command + target (pane-scraped, not structured).
+
+**codex** — `Bash`/`exec` → the command; `apply_patch` → the patch/diff; escalations (shell/net/MCP) via `PermissionRequest` → tool + input + human-readable description.
+
+An unknown tool falls back to a pretty-printed `tool_input`, so nothing is opaque.
+
+**Limitations (not hidden):**
+
+1. **claude `AskUserQuestion` is not hookable** — no permission-check, not a `PreToolUse` event. It stays suppressed by `--disallowedTools AskUserQuestion` in v1 (a deliberate owner decision, not a gap to close; re-enabling is only on the owner's explicit request).
+2. **codex MCP-elicitation** delivers content only on screen, not via a structured hook — rare, not covered in v1.
+3. **codex has no plan-mode approval** — the «plan» class exists only on claude (an asymmetry, not a missing feature).
+
+## The broker (single source of truth)
+
+The approval queue lives **in the daemon** (the always-on process). Every channel that asks (the runtime hook, the supervisor breaker) and every channel that answers (CLI, tray, the Telegram runtime) is an interface to this one queue: a decision from any face resolves the request everywhere. In-memory + ephemeral — pending requests do **not** survive a daemon restart (the blocking hook connection breaks → the hook fails safe to deny); the durable `approvals.log` is the audit trace, not a recovery store.
+
+Flow: the gated peer's hook (or the supervisor breaker) blocks on `POST /fleet/v1/approvals` → the broker enqueues, emits `approval-request` (to `approvals.log` → SSE), and holds the connection → a face answers via `POST /fleet/v1/approvals/<id>/(approve|deny)` → the promise resolves, the daemon writes the runtime hook JSON back, the tool proceeds or is blocked with the reason.
+
+**Fail-safety — every failure direction is `deny`:** broker unreachable, daemon restarted mid-wait (connection breaks), requester disconnect, unknown id, and the per-request timeout all resolve to deny. This is the engineering basis for removing the bypass under gated: with no bypass, «no decision» degrades to the runtime's own permission prompt (a blocked TUI), **not** an auto-run — so a supervision fault is safe, never permissive. (Under a *retained* bypass a hook timeout would auto-run — exactly the harm gated exists to prevent.)
+
+**Timeouts (ordered so the broker's default-deny always wins):** the broker default-deny is **300 s** (`IAPEER_APPROVAL_TIMEOUT_MS`); the hook client's fetch ceiling is **600 s**; the installed runtime hook `timeout` is **900 s**. So the broker answers (or default-denies) first, the client aborts second, and the runtime only kills the hook last. A timeout is delivered to the model as `deny` with `reason="approval timed out (default-deny)"`.
+
+## Fleet API
+
+The approval surface is served on both daemon listeners under `/fleet/v1`, same auth and client obligations as the rest of the Fleet API (docs/15). It adds a fourth durable log, `approvals.log`, to the SSE tail — clients MUST ignore unknown `ev` kinds (obligation 1), which is exactly how `approval-request` / `approval-resolved` were reserved.
+
+**Events** (compact logfmt line → SSE JSON; the full content is *not* in the event — read the queue for it):
+
+- `approval-request` — `id, personality, runtime, kind, tool, summary, created, expires, approvers`.
+- `approval-resolved` — `id, personality, runtime, decision (allow|deny), reason, by (approver), via (cli|tray|telegram|timeout|disconnect), latencyMs`.
+
+**Endpoints:**
+
+| Method + path | Purpose |
+|---|---|
+| `GET /fleet/v1/approvals` | list pending requests (full items) |
+| `GET /fleet/v1/approvals/<id>` | one pending request, full `content` (the multi-line diff / plan / command) |
+| `POST /fleet/v1/approvals/<id>/approve` | `{approver?}` → allow |
+| `POST /fleet/v1/approvals/<id>/deny` | `{reason?, approver?}` → deny (reason to the model) |
+| `POST /fleet/v1/approvals` | the **blocking long-poll** the asking hook/breaker holds: `{personality, runtime, kind, tool, content, summary?}` → `{id, decision, reason?}` |
+
+`kind` is the taxonomy tag (`tool` | `plan` | `question` | `circuit-breaker`; free-form-tolerant). So the SSE/badge stays light while the full content is available in every channel through the two `GET`s.
+
+## CLI
+
+- `iapeer approvals [--json]` — the pending queue: personality · runtime · kind · **the verbatim command/content** · age · id.
+- `iapeer approve <id> [--approver <peer>]` — allow.
+- `iapeer deny <id> [reason] [--approver <peer>]` — deny with a reason (delivered to the model).
+- `iapeer approval-mode <peer> [gated|yolo] [--now]` — read the current mode (omit the mode), or flip it: persists the field, idempotently brings the runtime surfaces to the mode, and reports the application moment. `--now` also starts a fresh session so the mode takes effect immediately.
+
+`approve` / `deny` / `approvals` reach the in-daemon broker over the Fleet API (like the tray), not in-process — the queue lives in the live daemon.
+
+## Compatibility
+
+Additive within `/fleet/v1` (docs/15): the `approval-*` endpoints and `ev` kinds grow the surface without a version bump. A pre-approval daemon simply omits `approval_mode` from the snapshot and serves no `/approvals` endpoints; a client feature-detects by the presence of the field / a `200` from `GET /fleet/v1/approvals`.

package/docs/README.md

@@ -78,6 +78,7 @@ The sections are layered: from "install and use" to "understand the architecture
 - [14 — Configuration and logs](14-configuration-and-logs.md) — environment variables, logs, diagnostics
 - [15 — Fleet API](15-fleet-api.md) — the daemon's HTTP surface for operator clients (dashboards, tray apps, scripts): snapshot, event stream, commands
 - [16 — Tray](16-tray.md) — the macOS menu-bar fleet dashboard (SwiftBar plugin), the first external Fleet API client
+- [17 — Human approval](17-approval.md) — per-peer gated/yolo mode: routing a runtime's blocking approvals to a human through the daemon broker (hook interception, the broker, Fleet API + CLI)
 
 ## Status
 

package/docs/ru/15-fleet-api.md

@@ -57,6 +57,11 @@ HTTP-поверхность демона для **операторских кл
       "launchd_managed": false,
       "wake_policy": "warm"
     }
+  ],
+  "approvals": [
+    { "id": "a1", "personality": "boris", "runtime": "claude", "kind": "circuit-breaker",
+      "tool": "dangerous-rm", "summary": "rm -rf /tmp/x",
+      "content": "cmd=\"rm -rf /tmp/x\" target=\"/tmp/x\"", "createdMs": 1751731100000, "expiresMs": 1751731400000 }
   ]
 }
 ```
@@ -73,6 +78,7 @@ HTTP-поверхность демона для **операторских кл
 - `host.fda` — Full Disk Access бинаря: `true` / `false` / `null` (неопределимо).
 - Сам факт ответа демона **и есть** сигнал здоровья: булева `healthy` нет. Дашборд, не достучавшийся ни до одного объявленного адреса, обязан рисовать демона лежачим (поэтому же дашборд, питающийся только API, недостаточен, когда сломан сам демон — встроенный TUI сохраняет прямой in-process путь чтения ровно на этот случай).
 - **LLM-модель пира отсутствует намеренно**: эффективная модель живой сессии — не наблюдаемый факт реестра (статические пины запуска существуют, но выдавать пин за «модель» — врать при рантаймном автопереключении). Станет наблюдаемой — появится аддитивным полем.
+- `approvals` (top-level, docs/17-approval) — очередь ожидающих human-approval, ТЕ ЖЕ item'ы, что отдаёт `GET /fleet/v1/approvals`, в снапшоте — чтобы клиент, уже перефетчащий `/snapshot` на каждое событие, рендерил очередь без доп. вызова. **АДДИТИВНО + ОПУСКАЕТСЯ при пустой очереди** — клиент ОБЯЗАН трактовать отсутствие как пустую очередь (то же правило, что `approval_mode`). Поля item: `id` (broker-id, цель `POST /fleet/v1/approvals/<id>/(approve|deny)`), `personality` + `runtime` (чьё действие), `kind` (`tool`|`plan`|`question`|`circuit-breaker`), `tool` (имя инструмента / breaker'а), `summary` (однострочник для бейджа), `content` (ПОЛНОЕ дословное действие — команда / диф / план; крит №7), `createdMs` / `expiresMs`. Item брокера — суперсет: неизвестные лишние поля (`title`, `approvers`) ОБЯЗАНЫ игнорироваться (обязательство 2).
 
 ## GET /fleet/v1/peers/&lt;personality&gt;
 
@@ -132,7 +138,7 @@ GET /fleet/v1/events?replay=50
 
 `from` опционален: полный `<runtime>-<personality>` или голая personality (её default-рантайм). По умолчанию — **единственный natural-intelligence пир** реестра: сообщение из GUI принадлежит человеку. При нуле или нескольких natural-пирах запрос отклоняется (`400`) с указанием передать `from`.
 
-Не входит в API, намеренно: **attach** (передача терминала — клиент открывает системный терминал с `iapeer attach <peer>`), реестровые/хостовые **admin-verb'ы** (`create`/`remove`/`update`/`uninstall` — добавятся, когда появится клиент с реальной потребностью), **approve** (брокера подтверждений ещё не существует; он придёт новыми эндпоинтами + видами `ev` в рамках этого же контракта).
+Не входит в *командный* API, намеренно: **attach** (передача терминала — клиент открывает системный терминал с `iapeer attach <peer>`), реестровые/хостовые **admin-verb'ы** (`create`/`remove`/`update`/`uninstall` — добавятся, когда появится клиент с реальной потребностью). **Брокер human-approval** теперь живёт под `/fleet/v1/approvals*` (`GET` очередь / один item, `POST /<id>/(approve|deny)`) с видами SSE `approval-request` / `approval-resolved` и полем `approvals` в снапшоте выше — полный контракт в **docs/17-approval**.
 
 Ошибки — всегда `{"error": "…"}` с честным статусом: `400` некорректный запрос, `401` требуется bearer, `404` неизвестный пир/эндпоинт, `405` не тот метод, `502` сам verb упал, `500` внутренняя.
 

package/docs/ru/16-tray.md

@@ -15,8 +15,10 @@ SwiftBar.app, если его нет.
 
 ## Что видно
 
-- **Меню-бар:** глиф-антенна + число пиров с живой сессией. Если ни один объявленный адрес
-  демона не отвечает — красный треугольник (демон недоступен; чисто API-дашборд иначе не
+- **Меню-бар:** глиф-антенна + число пиров с живой сессией. Когда есть ожидающие запросы
+  **human-approval**, меню-бар вместо этого показывает **красный бейдж `N.circle.fill`** (iOS-look —
+  красный круг с числом), чтобы владелец сразу видел ожидающий запрос. Если ни один объявленный
+  адрес демона не отвечает — красный треугольник (демон недоступен; чисто API-дашборд иначе не
   покажет сломанный демон — встроенный TUI держит прямой путь чтения для этого случая, см.
   [15](15-fleet-api.md)).
 - **Выпадашка:** шапка хоста (`iapeer <версия> · up <аптайм>`) и хартбиты провайдеров памяти
@@ -34,6 +36,15 @@ SwiftBar.app, если его нет.
     (telegram / notifier, `🔒`) не pty-аттачатся** — их строки просто статус. Lifecycle-действия
     (Wake / Stop / Start / New / Interrupt / Refresh / Compact) — в подменю **Manage**, каждое —
     `POST /fleet/v1/peers/<peer>/<cmd>` через `iapeer tray cmd`.
+- **Ожидающие подтверждения (docs/17):** когда очередь непуста, **вверху выпадашки** каждый
+  ожидающий запрос показан **раскрытым, без доп. кликов** — заголовок (`<peer> · <tool>`),
+  **дословное содержимое действия** (команда / диф / план, моноширинно, усечено для меню; ПОЛНОЕ
+  содержимое — в `iapeer approvals`), затем пункты **Allow** / **Deny** прямо под ним. Клик запускает
+  `iapeer tray approve|deny <id>` в фоне → брокер резолвит → стрим ре-рендерит (бейдж гаснет). Пир с
+  ожидающим запросом **выделен в списке флота** (префикс `⚠`, красный счётчик `🔴N`, строка красная),
+  чтобы владелец видел, *какой* пир ждёт. Канал **always-on** — очередь отражается всегда, когда
+  непуста, независимо от прочего; пустая очередь — ни секции, ни бейджа. (Настоящая *пульс*-анимация в
+  статичном SwiftBar-меню невозможна — highlight + бейдж это её эквивалент.)
 
 Список обновляется сам: плагин **streamable** — подписан на поток событий и перечитывает
 снапшот на каждое изменение (пробуждение пира, стоп/старт оператором, смерть), склеивая
@@ -51,6 +62,7 @@ SwiftBar.app, если его нет.
 | `iapeer tray uninstall` | Удалит файл плагина и обновит SwiftBar. **Флот не трогает** — демон, TUI и доставка живут; SwiftBar.app остаётся (может держать другие плагины). |
 | `iapeer tray render [--stream]` | Печатает вывод плагина SwiftBar. `--stream` — streamable-цикл, который крутит плагин; одноразовая форма — поллинг-фолбэк и тест-поверхность. |
 | `iapeer tray cmd <command> <peer> [runtime]` | POST fleet-команды (`wake`/`stop`/`start`/`new`/`refresh`/`interrupt`/`compact`) — lifecycle-пункты меню зовут это. |
+| `iapeer tray approve <id>` · `iapeer tray deny <id> [reason]` | Резолв ожидающего human-approval (docs/17) — `POST /fleet/v1/approvals/<id>/(approve\|deny)` через тот же unix-first fleet-клиент. Пункты Allow/Deny меню зовут это; инвариант единой очереди — резолв виден каждому каналу (CLI, telegram). |
 | `iapeer tray status` | Только чтение: жив ли fleet API (из `router.json`), установлен ли SwiftBar и где его каталог плагинов, на месте ли файл плагина. Ничего не чинит. |
 
 ## Как устроено

package/docs/ru/17-approval.md

@@ -0,0 +1,128 @@
+# 17 — Подтверждение человеком
+
+Пир работает в одном из двух **режимов подтверждения**. В `yolo` (режим по умолчанию — сегодня так у всего флота) агент действует автономно: рантайм запускается со своим bypass-флагом, и ничто не спрашивает человека перед выполнением инструмента. В `gated` пир запускается **без** bypass, и каждый блокирующий вопрос-подтверждение, который поднял бы рантайм, уходит **человеку** через брокер подтверждений в демоне — кнопкой в Telegram, кликом в трее или командой `iapeer approve`. Решение человека `allow`/`deny` (с причиной) возвращается в рантайм, и инструмент либо исполняется, либо отклоняется.
+
+Это **нормативный контракт**. Брокер подтверждений живёт в демоне; fleet-эндпоинты и типы событий `ev` ниже — это поверхность, под которую пишутся операторские клиенты (CLI, трей, telegram-рантайм), а не исходники демона. Факты перехвата (какое событие рантайма фаярит, в какой форме) закреплены за **Claude Code 2.1.201** и **codex-cli 0.142.5** — сняты с живых бинарей и актуальных доков рантаймов.
+
+`gated` значит **«спрашивать перед действием»**, а не «в песочнице». Он убирает bypass, чтобы блокирующие вопросы всплывали; он **не** добавляет OS-песочницу (отдельная ось, не в v1). На codex gated явно есть `аппрувы ВКЛ + песочница ВЫКЛ` (см. таблицу тумблера).
+
+## Тумблер режима
+
+### Поле профиля
+
+Foundation-owned lifecycle-поле в `peer-profile.json`, рядом с `wake_policy` / `initial_prompt`:
+
+```json
+{ "approval_mode": "gated" }
+```
+
+`"yolo" | "gated"`, **дефолт `yolo`**. Персистится только `gated` — запись `yolo` **удаляет** поле (поэтому круг `gated→yolo→gated` байт-в-байт, а весь флот остаётся ровно таким, каким был до появления этой фичи). Единственное место, где живёт дефолт «отсутствует ⇒ yolo», — `approvalModeOf(profile)`; каждый читатель (запуск, супервизор, fleet-снапшот, CLI) резолвит через него и никогда не переопределяет. В fleet-снапшот режим попадает аддитивным полем `approval_mode` (docs/15) чтением локального профиля — pre-approval-демон его опускает, и клиенты ОБЯЗАНЫ трактовать отсутствие как `yolo`.
+
+### Поверхности запуска, которых касается флип
+
+Bypass — это **аргумент запуска**, у каждого рантайма свой, и режим есть согласованная операция над **всеми** поверхностями, которые этот аргумент подразумевает. iapeer владеет запуском, поэтому полнота списка — за фундаментом.
+
+**claude** (вариант D — matcher-free хук `PermissionRequest`; проверено живьём 2.1.201):
+
+| # | Поверхность | yolo | gated |
+|---|---|---|---|
+| C1 | argv `--dangerously-skip-permissions` | присутствует | **убран** |
+| C2 | argv permission-mode | (bypass) | `--permission-mode default` (явно — не наследует acceptEdits/bypass defaultMode) |
+| C3 | ready-gate маркер `isInputReady` | нужен баннер `bypass permissions on` | баннера **НЕТ** → маркер mode-aware (composer `❯` + сняты boot-диалоги), иначе пир никогда не станет ready и wake проваливается |
+| C4 | boot-диалог «Bypass Permissions mode» accept | появляется (первый bypass) | не появляется (нет bypass) |
+| C5 | хук `PermissionRequest` в `<cwd>/.claude/settings.json` | **отсутствует** (0 оверхеда, байт-в-байт как сегодня) | **установлен** — matcher-free (см. ниже), `command = iapeer approval-hook` |
+| C6 | allow-rule собственного MCP-инструмента пира (`permissions.allow: ["mcp__iapeer__send_to_peer"]`) | не нужен (bypass) | **нужен** — иначе default-mode гейтит сам IAP-канал пира, и он виснет на `send_to_peer` |
+| C7 | супервизор: circuit-breaker (dangerous-rm, выше permission-слоя) | авто-Yes + аудит-лог | **маршрут человеку** через брокер |
+| C8 | argv `--disallowedTools AskUserQuestion` | остаётся | остаётся в v1 (см. Лимитации) |
+
+**Почему matcher-free `PermissionRequest`, а не `PreToolUse`.** `PermissionRequest` фаярит **только когда permission-конфиг рантайма решил спросить** — вызов, не покрытый allow/deny-правилом. Значит политика *что спрашивать* остаётся на 100% у рантайма: юзер настраивает её обычными permission-правилами (инструмент в `permissions.allow` не спрашивается никогда → хук не фаярит → авто-allow). Нет матчера классов, который дрейфует, нет проскакивающего нового инструмента, нет зависания. iapeer лишь сеет хук + одно allow-правило для собственного MCP-инструмента пира.
+
+**codex** (хук `PreToolUse` — проверено живьём, codex-cli 0.142.5):
+
+| # | Поверхность | yolo | gated |
+|---|---|---|---|
+| X1 | argv `--dangerously-bypass-approvals-and-sandbox` | присутствует | **убран** |
+| X2 | argv approval/sandbox | (bypass) | `-c approval_policy=on-request -c sandbox_mode=danger-full-access` — аппрувы **ВКЛ**, песочница **ВЫКЛ** (чтобы loopback-MCP `send_to_peer` и запись в vault-память вне cwd работали; `workspace-write` отрезал бы сеть и внешние пути). Session-scoped через `-c`, не хост-конфиг. |
+| X3 | хук `PreToolUse` `<cwd>/.codex/hooks.json` + trust-preseed в `~/.codex/config.toml [hooks.state]` | **отсутствует** | **установлен + доверен** (`preSeedCodexHooksTrust`; недоверенный codex-хук молча пропускается) |
+| X4 | codex cwd-trust `[projects."<cwd>"] trust_level="trusted"` | pre-trusted (обе моды) | pre-trusted (при активных аппрувах важнее) |
+| X5 | ready-gate `isInputReady` (composer `›`) | mode-независим | без изменений |
+
+codex-хук матчится по регекспу имён инструментов `^(Bash|Shell|shell|local_shell|exec|apply_patch|ApplyPatch)$` — грубый матчер классов живёт на собственном `hooks.json` рантайма (юзер правит как обычный рантайм-конфиг).
+
+### Идемпотентность и момент применения
+
+- **argv-поверхности** (C1–C2, C8, X1–X2) вычисляются из моды на каждом запуске — идемпотентны структурно, накопления нет.
+- **settings.json / hooks.json** (C5–C6, X3) — add при gated / remove при yolo, no-clobber merge, ключ по стабильному маркеру `approval-hook`: наш блок дописывается детерминированно и удаляется дочиста (опустевший массив `hooks.PermissionRequest` / `PreToolUse` снимается, опустевший объект `hooks` / `permissions` снимается, чужие хуки/правила не трогаются). Круг `gated→yolo→gated` восстанавливает pre-install байты.
+- **codex trust** (X3–X4) переиспользует уже идемпотентные `preSeedCodexHooksTrust` / `removeCodexHooksTrustUnder`.
+
+Все поверхности читаются/применяются **на старте сессии**. **Живая сессия держит свою запущенную моду** до следующей фреш-сессии — ровно как агентик-пир лениво подхватывает новую доктрину на следующем wake. Тумблер: (1) персистит `approval_mode`, (2) идемпотентно приводит settings/hooks-поверхности к моде, (3) НЕ трогает живую сессию. Чтобы применить сразу — подними фреш-сессию (`iapeer approval-mode <peer> <mode> --now`, или `iapeer new`/`refresh`).
+
+## Механизм перехвата
+
+У обоих рантаймов есть Claude-совместимая **hook-система**, которая перехватывает подтверждение программно и возвращает `allow`/`deny` + причину + структурное содержимое действия. Это первичный механизм. **Экранный pty-скрейп — бэкстоп только для одного класса** — claude-circuit-breaker `dangerous-rm`, который живёт *выше* permission-слоя и не виден ни одному хуку.
+
+- **claude `PermissionRequest`** — на stdin `{tool_name, tool_input, …}`; хук печатает `{"hookSpecificOutput":{"hookEventName":"PermissionRequest","decision":{"behavior":"allow|deny","message":"…"}}}`. `deny` доносит `message` до модели. Фаярит только на вопрос-достойных вызовах.
+- **codex `PreToolUse`** — тот же shape stdin; печатает `{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow|deny","permissionDecisionReason":"…"}}`. `exit 2` (+ stderr) тоже отклоняет. Проверено живьём (0.142.5): codex фаярит `PreToolUse` (не `PermissionRequest`) на tool-вызовах с `tool_name:"Bash"` для shell; `deny` жёстко блокирует тул и причина доходит до модели даже под `sandbox_mode=danger-full-access` — так что под gated-конфигом (danger-full-access + on-request → `permission_mode=bypassPermissions`) хук — ЕДИНСТВЕННЫЙ гейт.
+- **супервизор circuit-breaker** — гард `dangerous-rm`/`rmdir` claude (и стандартный command-approval-промпт, который показывает no-bypass-сессия) — это TUI-селект, невидимый хуку. pty-супервизор читает его со своей авторитетной модели и под gated POSTит брокеру (ниже); под yolo авто-жмёт YES с аудит-строкой.
+
+Хук-бинарь — сабкоманда `iapeer approval-hook`: читает hook-JSON рантайма со stdin, резолвит `PEER_PERSONALITY`/`PEER_RUNTIME` из session-env и URL демона из `router.json`, POSTит блокирующий запрос брокеру и печатает рантайм-специфичный JSON решения.
+
+## Номенклатура v1 и содержимое на точке перехвата (критерий «что подтверждается»)
+
+В любом канале человек видит **конкретное содержимое** действия, а не только имя инструмента.
+
+**claude** — `Bash` → полная команда (+ описание); `Edit` → файл + old/new; `Write` → файл + содержимое; `ExitPlanMode` → текст плана; circuit-breaker `dangerous-rm` → полный текст промпта + rm-команда + target (pane-скрейп, не структурно).
+
+**codex** — `Bash`/`exec` → команда; `apply_patch` → патч/диф; эскалации (shell/сеть/MCP) через `PermissionRequest` → инструмент + input + человекочитаемое описание.
+
+Неизвестный инструмент падает на pretty-print `tool_input`, так что непрозрачного нет ничего.
+
+**Лимитации (не замалчиваю):**
+
+1. **claude `AskUserQuestion` не перехватывается хуком** — у него нет permission-check и он не событие `PreToolUse`. В v1 остаётся заглушённым через `--disallowedTools AskUserQuestion` (осознанное решение владельца, не дыра к закрытию; возврат — только по его явному запросу).
+2. **codex MCP-elicitation** отдаёт содержимое только на экране, не структурным хуком — редко, в v1 не покрывается.
+3. **у codex нет plan-mode-аппрува** — класс «план» существует только у claude (асимметрия, не отсутствие фичи).
+
+## Брокер (единый источник истины)
+
+Очередь подтверждений живёт **в демоне** (always-on процесс). Каждый канал, который спрашивает (хук рантайма, breaker супервизора), и каждый, который отвечает (CLI, трей, telegram-рантайм), — интерфейс к этой одной очереди: решение из любого канала гасит запрос везде. In-memory + эфемерна — ожидающие запросы **не** переживают рестарт демона (блокирующее соединение хука рвётся → хук fail-safe в deny); durable `approvals.log` — аудит-след, не хранилище восстановления.
+
+Путь: хук gated-пира (или breaker супервизора) блокируется на `POST /fleet/v1/approvals` → брокер кладёт в очередь, эмитит `approval-request` (в `approvals.log` → SSE) и держит соединение → канал отвечает `POST /fleet/v1/approvals/<id>/(approve|deny)` → промис резолвится, демон пишет обратно hook-JSON, инструмент исполняется или блокируется с причиной.
+
+**Fail-safety — все направления отказа = `deny`:** брокер недоступен, демон рестартнул при ожидании (соединение рвётся), requester-дисконнект, неизвестный id и таймаут per-request — всё резолвится в deny. Это инженерное основание уборки bypass под gated: без bypass «нет решения» деградирует к собственному permission-промпту рантайма (блокирующий TUI), а **не** к авто-run — сбой перехвата безопасен, никогда не пермиссивен. (Под *сохранённым* bypass хук-таймаут = авто-run — ровно тот вред, ради которого gated существует.)
+
+**Таймауты (упорядочены так, чтобы default-deny брокера всегда выигрывал):** брокер default-deny — **300 с** (`IAPEER_APPROVAL_TIMEOUT_MS`); потолок fetch хук-клиента — **600 с**; `timeout` установленного хука рантайма — **900 с**. Так брокер отвечает (или default-денит) первым, клиент абортится вторым, а рантайм убивает хук последним. Таймаут доносится модели как `deny` с `reason="approval timed out (default-deny)"`.
+
+## Fleet API
+
+Поверхность подтверждений отдаётся на обоих листенерах демона под `/fleet/v1`, с той же авторизацией и обязательствами клиента, что и остальной Fleet API (docs/15). Добавляет четвёртый durable-лог `approvals.log` в SSE-тейл — клиенты ОБЯЗАНЫ игнорить неизвестные `ev` (обязательство 1), ровно так зарезервированы `approval-request` / `approval-resolved`.
+
+**События** (компактная logfmt-строка → SSE JSON; полное содержимое НЕ в событии — читай очередь):
+
+- `approval-request` — `id, personality, runtime, kind, tool, summary, created, expires, approvers`.
+- `approval-resolved` — `id, personality, runtime, decision (allow|deny), reason, by (approver), via (cli|tray|telegram|timeout|disconnect), latencyMs`.
+
+**Эндпоинты:**
+
+| Метод + путь | Назначение |
+|---|---|
+| `GET /fleet/v1/approvals` | список ожидающих (полные item'ы) |
+| `GET /fleet/v1/approvals/<id>` | один ожидающий, полный `content` (многострочный диф / план / команда) |
+| `POST /fleet/v1/approvals/<id>/approve` | `{approver?}` → allow |
+| `POST /fleet/v1/approvals/<id>/deny` | `{reason?, approver?}` → deny (причина к модели) |
+| `POST /fleet/v1/approvals` | **блокирующий long-poll**, который держит спрашивающий хук/breaker: `{personality, runtime, kind, tool, content, summary?}` → `{id, decision, reason?}` |
+
+`kind` — таксономический тег (`tool` | `plan` | `question` | `circuit-breaker`; терпим к свободной форме). Так бейдж/SSE остаётся лёгким, а полное содержимое доступно в каждом канале через два `GET`.
+
+## CLI
+
+- `iapeer approvals [--json]` — очередь ожидающих: personality · runtime · kind · **дословная команда/содержимое** · возраст · id.
+- `iapeer approve <id> [--approver <peer>]` — одобрить.
+- `iapeer deny <id> [reason] [--approver <peer>]` — отклонить с причиной (доносится модели).
+- `iapeer approval-mode <peer> [gated|yolo] [--now]` — прочитать текущую моду (опустить моду) или флипнуть: персистит поле, идемпотентно приводит рантайм-поверхности к моде и сообщает момент применения. `--now` дополнительно поднимает фреш-сессию, чтобы мода вступила сразу.
+
+`approve` / `deny` / `approvals` достают до in-daemon брокера по Fleet API (как трей), не in-process — очередь живёт в живом демоне.
+
+## Совместимость
+
+Аддитивно в рамках `/fleet/v1` (docs/15): эндпоинты и `ev` `approval-*` растят поверхность без бампа версии. Pre-approval-демон просто опускает `approval_mode` в снапшоте и не отдаёт эндпоинтов `/approvals`; клиент feature-детектит по наличию поля / `200` от `GET /fleet/v1/approvals`.

package/docs/ru/README.md

@@ -78,6 +78,7 @@ iapeer send assistant --message "привет, ты на связи?"
 - [14 — Конфигурация и журналы](14-конфигурация-и-журналы.md) — переменные окружения, журналы, диагностика
 - [15 — Fleet API](15-fleet-api.md) — HTTP-поверхность демона для операторских клиентов (дашборды, tray-приложения, скрипты): снапшот, поток событий, команды
 - [16 — Трей](16-tray.md) — дашборд флота в меню-баре macOS (плагин SwiftBar), первый внешний клиент Fleet API
+- [17 — Подтверждение человеком](17-approval.md) — режим gated/yolo на пира: маршрутизация блокирующих подтверждений рантайма человеку через брокер демона (перехват хуком, брокер, Fleet API + CLI)
 
 ## Статус
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agfpd/iapeer",
-  "version": "0.4.68",
+  "version": "0.4.70",
   "description": "Run Claude Code and Codex CLI as local background agents that message each other, wake on demand, and share one memory.",
   "license": "Apache-2.0",
   "author": "agfpd",

package/src/approval/brokerClient.ts

@@ -0,0 +1,92 @@
+// brokerClient — the shared client transport for the human-approval broker (docs/17). Both the
+// runtime hook (approval/hook.ts, the ASK side of a gated peer's PreToolUse/PermissionRequest) and the
+// supervisor circuit-breaker (supervisor/approvalRoute.ts, Unit 4 — the pty-scrape ASK side above the
+// permission layer) POST a blocking approval request to the daemon's `/fleet/v1/approvals` and await a
+// human decision. Factoring the request/response contract into ONE place (headers, optional H8 bearer,
+// abort-timeout, throw-on-non-200) makes the two callers behave IDENTICALLY by construction — the same
+// parity-by-one-source discipline as buildLaunchInvocation.
+//
+// Dependency-light on purpose: fetch + a router.json path resolver (readFileSync + pluginStateDir). The
+// supervisor daemon dynamic-imports this into its detached @xterm process, so it must never pull the
+// central router / transport graph.
+
+import { readFileSync } from 'fs'
+import { join } from 'path'
+import { pluginStateDir } from '../storage/index.ts'
+
+export interface ApprovalDecision {
+  decision: 'allow' | 'deny'
+  reason?: string
+}
+
+/** The request body POST /fleet/v1/approvals accepts (broker.request input; docs/17 §2).
+ *  `kind` is the taxonomy tag (tool | plan | question | circuit-breaker); the hook sends tool/plan,
+ *  the supervisor breaker sends circuit-breaker. */
+export interface ApprovalRequestBody {
+  personality: string
+  runtime: string
+  kind: string
+  tool: string
+  content: string
+  summary: string
+}
+
+/** Resolve the daemon fleet base URL (origin-form, no path) from router.json's `tcp` field, else the
+ *  well-known loopback default. TCP loopback is always served (the daemon dual-listens), so a client
+ *  never needs the unix socket. */
+export function resolveFleetBase(env: NodeJS.ProcessEnv = process.env): string {
+  try {
+    const routerJson = join(pluginStateDir('iapeer', { env }), 'router.json')
+    const parsed = JSON.parse(readFileSync(routerJson, 'utf8')) as { tcp?: unknown }
+    if (typeof parsed.tcp === 'string' && parsed.tcp) return parsed.tcp.replace(/\/mcp\/?$/, '')
+  } catch {
+    /* no router.json → default below */
+  }
+  const port = env.IAPEER_PORT?.trim() || '8765'
+  return `http://127.0.0.1:${port}`
+}
+
+/** Client-side hold ceiling — comfortably ABOVE the broker's default-deny timeout (300 s) so the
+ *  broker's answer always arrives first; if the daemon is dead the fetch aborts and the caller fails
+ *  safe to deny. */
+export const APPROVAL_FETCH_TIMEOUT_MS = 600_000
+
+export interface RequestApprovalDeps {
+  env?: NodeJS.ProcessEnv
+  /** Injectable fetch (tests). Default global fetch. */
+  fetch?: typeof fetch
+  /** Injectable client timeout (tests). */
+  timeoutMs?: number
+}
+
+/**
+ * POST a blocking approval request and await the human's decision. Long-poll: the daemon holds the
+ * connection until a face answers or the broker's default-deny timeout fires, then returns
+ * `{ id, decision, reason? }`. THROWS on any transport failure (daemon unreachable, abort/timeout,
+ * non-200) — the CALLER owns the fail-safe (both the hook and the supervisor deny on a throw). A
+ * normalized decision comes back: allow carries no reason; deny always carries one.
+ */
+export async function requestApproval(base: string, body: ApprovalRequestBody, deps: RequestApprovalDeps = {}): Promise<ApprovalDecision> {
+  const env = deps.env ?? process.env
+  const doFetch = deps.fetch ?? fetch
+  const timeoutMs = deps.timeoutMs ?? APPROVAL_FETCH_TIMEOUT_MS
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), timeoutMs)
+  ;(timer as { unref?: () => void }).unref?.()
+  try {
+    const headers: Record<string, string> = { 'content-type': 'application/json' }
+    const bearer = env.IAPEER_BEARER_TOKEN?.trim()
+    if (bearer) headers.authorization = `Bearer ${bearer}`
+    const resp = await doFetch(`${base}/fleet/v1/approvals`, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    })
+    if (!resp.ok) throw new Error(`daemon returned ${resp.status}`)
+    const data = (await resp.json()) as ApprovalDecision
+    return data.decision === 'allow' ? { decision: 'allow' } : { decision: 'deny', reason: data.reason || 'denied' }
+  } finally {
+    clearTimeout(timer)
+  }
+}