@agfpd/iapeer 0.4.67 → 0.4.69

package/docs/15-fleet-api.md

@@ -55,7 +55,8 @@ 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"
     }
   ]
 }
@@ -68,6 +69,7 @@ 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).

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 — structural; live-verify pending):
+
+| # | 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.
+- **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/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` — структурно; живая верификация ожидается):
+
+| # | Поверхность | 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) тоже отклоняет.
+- **супервизор 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.67",
+  "version": "0.4.69",
   "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)
+  }
+}

package/src/approval/cli.ts

@@ -0,0 +1,118 @@
+// approval CLI — the operator faces of the approval broker (docs/17 §5), all thin clients
+// of the daemon fleet-API (the queue lives in the daemon; these reach it over HTTP, like the
+// tray). `approval-hook` is the runtime-installed bridge; `approvals`/`approve`/`deny` are the
+// host answer channel; `approval-mode` is the per-peer gated/yolo toggle.
+
+import { resolveFleetBase } from './brokerClient.ts'
+import { setApprovalMode } from './install.ts'
+import { readPeersIndex } from '../registry/index.ts'
+import { readPeerProfile, approvalModeOf, type ApprovalMode } from '../identity/index.ts'
+
+function authHeaders(env: NodeJS.ProcessEnv): Record<string, string> {
+  const bearer = env.IAPEER_BEARER_TOKEN?.trim()
+  return { 'content-type': 'application/json', ...(bearer ? { authorization: `Bearer ${bearer}` } : {}) }
+}
+
+interface PendingApprovalRow {
+  id: string
+  personality: string
+  runtime: string
+  kind: string
+  tool: string
+  summary: string
+  content: string
+  createdMs: number
+  expiresMs: number
+}
+
+function ageStr(ms: number, nowMs: number): string {
+  const s = Math.max(0, Math.floor((nowMs - ms) / 1000))
+  return s < 60 ? `${s}s` : s < 3600 ? `${Math.floor(s / 60)}m` : `${Math.floor(s / 3600)}h`
+}
+
+/** `iapeer approvals [--json]` — the pending queue. Each row carries the VERBATIM action
+ *  content (a Bash command shown in full — boris's CLI acceptance criterion). */
+export async function approvalsList(json: boolean, env: NodeJS.ProcessEnv): Promise<{ text: string; code: number }> {
+  const base = resolveFleetBase(env)
+  let rows: PendingApprovalRow[]
+  try {
+    const resp = await fetch(`${base}/fleet/v1/approvals`, { headers: authHeaders(env) })
+    if (!resp.ok) return { text: `approvals: daemon returned ${resp.status}\n`, code: 1 }
+    rows = ((await resp.json()) as { approvals: PendingApprovalRow[] }).approvals
+  } catch (e) {
+    return { text: `approvals: cannot reach daemon (${e instanceof Error ? e.message : String(e)})\n`, code: 1 }
+  }
+  if (json) return { text: `${JSON.stringify(rows, null, 2)}\n`, code: 0 }
+  if (rows.length === 0) return { text: 'no pending approvals\n', code: 0 }
+  const now = Date.now()
+  const lines = [`${rows.length} pending approval(s):`]
+  for (const r of rows) {
+    lines.push(`  ${r.id}  ${r.personality}/${r.runtime}  [${r.kind}:${r.tool}]  ${ageStr(r.createdMs, now)} ago`)
+    lines.push(`      ${r.summary}`) // verbatim command / file / plan-line
+  }
+  lines.push('', 'approve: iapeer approve <id>   ·   deny: iapeer deny <id> [reason]')
+  return { text: `${lines.join('\n')}\n`, code: 0 }
+}
+
+/** `iapeer approve <id>` / `iapeer deny <id> [reason]` — resolve a pending request. The
+ *  decision propagates to whichever channel is waiting (the blocking hook) and clears it
+ *  everywhere. `approver` (default: the single natural peer) records who answered. */
+export async function resolveApproval(
+  id: string,
+  action: 'approve' | 'deny',
+  opts: { reason?: string; approver?: string },
+  env: NodeJS.ProcessEnv,
+): Promise<{ text: string; code: number }> {
+  const base = resolveFleetBase(env)
+  const approver = opts.approver ?? defaultApprover(env)
+  const body: Record<string, unknown> = { via: 'cli', ...(approver ? { approver } : {}), ...(opts.reason ? { reason: opts.reason } : {}) }
+  try {
+    const resp = await fetch(`${base}/fleet/v1/approvals/${encodeURIComponent(id)}/${action}`, {
+      method: 'POST',
+      headers: authHeaders(env),
+      body: JSON.stringify(body),
+    })
+    if (resp.status === 404) return { text: `no pending approval "${id}" (already resolved, expired, or unknown)\n`, code: 1 }
+    if (!resp.ok) return { text: `${action}: daemon returned ${resp.status}\n`, code: 1 }
+    return { text: `${action === 'approve' ? 'approved' : 'denied'} ${id}${opts.reason ? ` (${opts.reason})` : ''}\n`, code: 0 }
+  } catch (e) {
+    return { text: `${action}: cannot reach daemon (${e instanceof Error ? e.message : String(e)})\n`, code: 1 }
+  }
+}
+
+/** The default approver: the registry's single natural-intelligence peer (the owner). null
+ *  when zero/several — then the answer is recorded without a `by`. */
+function defaultApprover(env: NodeJS.ProcessEnv): string | undefined {
+  try {
+    const natural = readPeersIndex({ env }).peers.filter(p => p.intelligence === 'natural')
+    return natural.length === 1 ? natural[0]!.personality : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/** `iapeer approval-mode <peer> [gated|yolo]` — read (no mode) or flip the toggle. Flipping
+ *  persists the field + brings the runtime surfaces to the mode; a live session keeps its
+ *  launched mode until a fresh session (the application moment). */
+export function approvalModeCli(peer: string, mode: ApprovalMode | undefined, env: NodeJS.ProcessEnv): { text: string; code: number } {
+  const rec = readPeersIndex({ env }).peers.find(p => p.personality === peer)
+  if (!rec) return { text: `unknown peer "${peer}"\n`, code: 1 }
+  if (!mode) {
+    let current: ApprovalMode = 'yolo'
+    try {
+      current = approvalModeOf(readPeerProfile(rec.cwd))
+    } catch {
+      /* unreadable → yolo */
+    }
+    return { text: `${peer}: approval_mode=${current}\n`, code: 0 }
+  }
+  let result
+  try {
+    result = setApprovalMode(rec.cwd, mode, env)
+  } catch (e) {
+    return { text: `approval-mode: ${e instanceof Error ? e.message : String(e)}\n`, code: 1 }
+  }
+  const lines = [`${peer} → approval_mode=${mode}`, ...result.surfaces.map(s => `  · ${s}`)]
+  lines.push('', 'applies on the peer\'s NEXT fresh session — run `iapeer new ' + peer + '` to apply now.')
+  return { text: `${lines.join('\n')}\n`, code: 0 }
+}