@agfpd/iapeer 0.4.68 → 0.4.69

package/src/daemon/approvalslog.ts

@@ -0,0 +1,54 @@
+// Approval-broker durable log — the daemon's DURABLE trace of every human-approval
+// request it brokers (docs/17). Sibling to lifecycle.log / delivery.log / exits.log
+// under cfg.eventLogDir; tailed by the fleet-API SSE stream (fleetEventFiles), so the
+// `approval-request` / `approval-resolved` events reach every operator client (CLI,
+// tray, telegram) with at-least-once semantics — and a postmortem can reconstruct who
+// asked, what, and how it resolved after the in-memory queue is gone.
+//
+// What is logged: approval METADATA + a one-line `summary` of the action — NOT the full
+// multi-line content (a Write's whole body / a long diff would bloat the log). The full
+// human-readable content lives in the in-memory queue and is served by GET
+// /fleet/v1/approvals/<id>; the log carries enough to correlate + render a badge/line.
+//
+// Same rotation class as its siblings: written by OUR code → self-rotates via the shared
+// storage/rotatelog primitive. The dir is passed IN by the composition point, never
+// re-resolved from env — a falsy dir → no-op (library/test daemons stay hermetic).
+
+import { join } from 'path'
+import { DEFAULT_LOG_KEEP, DEFAULT_LOG_MAX_BYTES, appendRotatedEvent } from '../storage/rotatelog.ts'
+
+/** The approval-broker log inside `logDir` (sibling to lifecycle.log). */
+export function approvalsLogPath(logDir: string): string {
+  return join(logDir, 'approvals.log')
+}
+
+function envPosInt(raw: string | undefined, dflt: number): number {
+  const n = parseInt(raw ?? '', 10)
+  return Number.isFinite(n) && n > 0 ? n : dflt
+}
+
+export interface AppendApprovalOptions {
+  /** Reads the rotation knobs IAPEER_APPROVALS_LOG_MAX_BYTES / _KEEP. */
+  env?: NodeJS.ProcessEnv
+  /** Stamp the line with this epoch-ms. Default Date.now(). */
+  nowMs?: number
+}
+
+/**
+ * Append one approval event line into `logDir`/approvals.log. A falsy `logDir` is a
+ * no-op (the default for library/test daemons). Fully best-effort — never throws;
+ * logging must never fail an approval round-trip.
+ */
+export function appendApprovalEvent(
+  logDir: string | undefined,
+  fields: Record<string, string | number | undefined>,
+  opts: AppendApprovalOptions = {},
+): void {
+  if (!logDir) return
+  const env = opts.env ?? process.env
+  appendRotatedEvent(approvalsLogPath(logDir), fields, {
+    nowMs: opts.nowMs,
+    maxBytes: envPosInt(env.IAPEER_APPROVALS_LOG_MAX_BYTES, DEFAULT_LOG_MAX_BYTES),
+    keep: envPosInt(env.IAPEER_APPROVALS_LOG_KEEP, DEFAULT_LOG_KEEP),
+  })
+}

package/src/daemon/fleet.ts

@@ -42,6 +42,7 @@ import {
   isEphemeralPeer,
   isLaunchdManaged,
   loadLifecycleConfig,
+  peerApprovalMode,
   wakeOrSpawn,
   type LifecycleConfig,
 } from '../lifecycle/index.ts'
@@ -59,6 +60,8 @@ import {
 } from '../storage/rotatelog.ts'
 import { heartbeatAgeSecs, probeFullDiskAccess, readMemoryProvider, readVoiceProvider } from '../status/index.ts'
 import { deliveryLogPath } from './deliverylog.ts'
+import { approvalsLogPath } from './approvalslog.ts'
+import { ApprovalBroker } from './approvals.ts'
 import { callTool, type CallToolDeps } from './index.ts'
 
 /** The API generation baked into every snapshot (additive evolution within v1 —
@@ -93,6 +96,9 @@ export interface FleetPeer {
   wake_policy: 'warm' | 'ephemeral'
   /** Ephemeral peers only: pending serial-queue tasks across declared runtimes. */
   queue_depth?: number
+  /** Human-approval mode (docs/17-approval): `yolo` (default — bypass + auto-confirm
+   *  circuit-breakers) or `gated` (blocking runtime approvals routed to a human). */
+  approval_mode: 'yolo' | 'gated'
 }
 
 export interface FleetHost {
@@ -163,6 +169,9 @@ export function buildFleetSnapshot(
     if (ephemeral) {
       for (const s of r.runtimes) queueDepth += ephemeralQueueDepth(cfg, buildProcessAddress(s.runtime, r.personality))
     }
+    // Approval mode from the LOCAL profile (same source as ephemeral); a read hiccup →
+    // the safe `yolo` default (peerApprovalMode swallows it).
+    const approvalMode = peerApprovalMode(r.cwd)
     return {
       personality: r.personality,
       description: r.description,
@@ -176,6 +185,7 @@ export function buildFleetSnapshot(
       launchd_managed: isLaunchdManaged(r.personality, env),
       wake_policy: ephemeral ? ('ephemeral' as const) : ('warm' as const),
       ...(ephemeral ? { queue_depth: queueDepth } : {}),
+      approval_mode: approvalMode,
     }
   })
   const mem = readMemoryProvider(env)
@@ -217,6 +227,9 @@ export function fleetEventFiles(cfg: LifecycleConfig): Array<{ path: string; src
     { path: lifecycleLogPath(cfg.eventLogDir), src: 'lifecycle' },
     { path: deliveryLogPath(cfg.eventLogDir), src: 'delivery' },
     { path: exitLogPath(cfg.eventLogDir), src: 'exits' },
+    // Human-approval broker events (docs/17): approval-request / approval-resolved.
+    // A pre-approval daemon simply never writes this file (readLogTail tolerates absence).
+    { path: approvalsLogPath(cfg.eventLogDir), src: 'approvals' },
   ]
 }
 
@@ -432,6 +445,8 @@ export interface FleetHandlerOptions {
   ops?: FleetOps
   /** Injectable tailer poll interval (tests). */
   pollMs?: number
+  /** Injectable approval broker (tests — e.g. a short timeout). Default: a fresh one. */
+  broker?: ApprovalBroker
 }
 
 export type FleetHandler = (
@@ -451,6 +466,9 @@ export function buildFleetHandler(opts: FleetHandlerOptions = {}): FleetHandler
   const startedAtMs = Date.now()
   const files = fleetEventFiles(cfg)
   const tailer = new FleetEventTailer(files, opts.pollMs)
+  // The approval broker — one per daemon; the ASK side (POST /approvals long-poll) and
+  // the ANSWER side (GET/POST /approvals/*) are all interfaces to this one queue.
+  const broker = opts.broker ?? new ApprovalBroker({ logDir: cfg.eventLogDir, env })
   let opsPromise: Promise<FleetOps> | undefined
   const getOps = (): Promise<FleetOps> => {
     if (opts.ops) return Promise.resolve(opts.ops)
@@ -533,6 +551,72 @@ export function buildFleetHandler(opts: FleetHandlerOptions = {}): FleetHandler
         if (result.isError) return sendJson(res, 502, { error: text })
         return sendJson(res, 200, { from: caller.address, result: safeParse(text) })
       }
+      // ── approvals — the human-approval broker surface (docs/17) ────────────
+      if (path === '/fleet/v1/approvals') {
+        if (method === 'GET') {
+          return sendJson(res, 200, { api: FLEET_API_VERSION, version: IAPEER_VERSION, ts: new Date().toISOString(), approvals: broker.list() })
+        }
+        if (method === 'POST') {
+          // The gated peer's hook BLOCKS here (long-poll): enqueue + await a decision.
+          let body: Record<string, unknown>
+          try {
+            body = await readBody(req)
+          } catch (e) {
+            return sendJson(res, 400, { error: e instanceof Error ? e.message : String(e) })
+          }
+          if (typeof body.personality !== 'string' || !body.personality || typeof body.tool !== 'string' || typeof body.content !== 'string') {
+            return sendJson(res, 400, { error: 'approval request needs {personality, runtime, tool, content} (+ optional kind/summary/title/approvers)' })
+          }
+          const { id, decision } = broker.request({
+            personality: body.personality,
+            runtime: typeof body.runtime === 'string' ? body.runtime : 'claude',
+            kind: typeof body.kind === 'string' ? body.kind : 'tool',
+            tool: body.tool,
+            content: body.content,
+            summary: typeof body.summary === 'string' ? body.summary : undefined,
+            title: typeof body.title === 'string' ? body.title : undefined,
+            approvers: Array.isArray(body.approvers) ? body.approvers.filter((a): a is string => typeof a === 'string') : undefined,
+          })
+          // No idle-socket kill during the (≤ broker-timeout) hold; cancel default-deny
+          // if the asking hook's transport dies before an answer (drop it from the queue).
+          res.setTimeout?.(0)
+          let settled = false
+          const onClose = (): void => {
+            if (!settled) broker.cancel(id)
+          }
+          req.on('close', onClose)
+          const d = await decision
+          settled = true
+          return sendJson(res, 200, { id, ...d })
+        }
+        return sendJson(res, 405, { error: 'method not allowed — GET|POST /fleet/v1/approvals' })
+      }
+      const apMatch = /^\/fleet\/v1\/approvals\/([^/]+)(?:\/(approve|deny))?$/.exec(path)
+      if (apMatch) {
+        const id = decodeURIComponent(apMatch[1]!)
+        const action = apMatch[2]
+        if (!action) {
+          if (method !== 'GET') return sendJson(res, 405, { error: 'method not allowed — GET /fleet/v1/approvals/<id>' })
+          const item = broker.get(id)
+          if (!item) return sendJson(res, 404, { error: `no pending approval "${id}"` })
+          return sendJson(res, 200, { api: FLEET_API_VERSION, version: IAPEER_VERSION, ts: new Date().toISOString(), approval: item })
+        }
+        if (method !== 'POST') return sendJson(res, 405, { error: 'method not allowed — POST /fleet/v1/approvals/<id>/(approve|deny)' })
+        let body: Record<string, unknown> = {}
+        try {
+          body = await readBody(req)
+        } catch {
+          /* empty/invalid body is fine — approve/deny carry only optional fields */
+        }
+        const by = typeof body.approver === 'string' ? body.approver : undefined
+        const via = typeof body.via === 'string' ? body.via : 'cli'
+        const ok =
+          action === 'approve'
+            ? broker.resolve(id, { decision: 'allow', reason: typeof body.reason === 'string' ? body.reason : undefined }, { by, via })
+            : broker.resolve(id, { decision: 'deny', reason: typeof body.reason === 'string' ? body.reason : 'denied by human' }, { by, via })
+        if (!ok) return sendJson(res, 404, { error: `no pending approval "${id}" (already resolved, expired, or unknown)` })
+        return sendJson(res, 200, { id, action, ok: true })
+      }
       return sendJson(res, 404, {
         error: `unknown fleet endpoint ${method} ${path}`,
         endpoints: [
@@ -541,6 +625,10 @@ export function buildFleetHandler(opts: FleetHandlerOptions = {}): FleetHandler
           'GET /fleet/v1/events?replay=N',
           'POST /fleet/v1/peers/<peer>/(wake|stop|start|new|refresh|interrupt|compact)',
           'POST /fleet/v1/send',
+          'GET /fleet/v1/approvals',
+          'POST /fleet/v1/approvals (hook long-poll)',
+          'GET /fleet/v1/approvals/<id>',
+          'POST /fleet/v1/approvals/<id>/(approve|deny)',
         ],
       })
     } catch (e) {

package/src/identity/index.ts

@@ -56,6 +56,14 @@ import {
  *  Enum (not bool) to leave room for future policies. */
 export type WakePolicy = 'ephemeral'
 
+/** Per-peer human-approval mode (foundation lifecycle-owned; docs/17-approval).
+ *  `yolo` (default, absent) = current fleet behavior — runtime bypass flag + the
+ *  supervisor auto-confirms circuit-breakers. `gated` = launch WITHOUT bypass, the
+ *  runtime's blocking approval requests are routed to a human through the daemon
+ *  approval broker. Only `gated` is persisted (yolo = field absent, byte-identical to
+ *  a never-toggled profile — mirrors wake_policy). */
+export type ApprovalMode = 'yolo' | 'gated'
+
 export interface PeerProfile {
   personality: string
   runtime: Runtime
@@ -69,6 +77,9 @@ export interface PeerProfile {
   interfaces?: PeerInterfaces
   /** Per-peer wake policy (lifecycle-owned). Absent = normal warm-on-demand. */
   wake_policy?: WakePolicy
+  /** Per-peer human-approval mode (lifecycle-owned). Absent = `yolo` (default). Only
+   *  `gated` is persisted; see ApprovalMode. */
+  approval_mode?: ApprovalMode
 }
 
 // Write shape: intelligence/description optional so a caller can write a profile
@@ -241,9 +252,19 @@ export function readPeerProfile(cwd: string = process.cwd()): PeerProfile | null
     // Wake policy — only the known enum value is honored; anything else → omitted
     // (treated as normal warm-on-demand, never throws on an unknown future value).
     ...(obj.wake_policy === 'ephemeral' ? { wake_policy: 'ephemeral' as const } : {}),
+    // Approval mode — only `gated` is persisted/honored; absent / `yolo` / unknown →
+    // omitted (treated as the default `yolo`, never throws on an unknown future value).
+    ...(obj.approval_mode === 'gated' ? { approval_mode: 'gated' as const } : {}),
   }
 }
 
+/** The effective approval mode of a profile: `gated` iff persisted, else the default
+ *  `yolo`. The ONE place the "absent ⇒ yolo" default lives — every reader (launch,
+ *  supervisor, fleet snapshot, CLI) resolves the mode through this, never re-derives it. */
+export function approvalModeOf(profile: PeerProfile | null | undefined): ApprovalMode {
+  return profile?.approval_mode === 'gated' ? 'gated' : 'yolo'
+}
+
 /**
  * Atomically write peer-profile.json, preserving fields the foundation does not
  * own (e.g. persistent-peer's initial_prompt/aliases section) via a raw read-
@@ -375,6 +396,13 @@ function writePeerProfileMerged(path: string, profile: PeerProfileWrite): void {
   if (typeof profile.initial_prompt === 'string' && profile.initial_prompt) {
     merged.initial_prompt = profile.initial_prompt
   }
+  // Approval mode (lifecycle-owned toggle). `gated` persists the field; `yolo` REMOVES
+  // it (default = absence, so a gated→yolo flip restores a byte-identical pristine
+  // profile — the toggle idempotency invariant). An ABSENT approval_mode in the write
+  // (any non-toggle writer: verify --fix, rename, re-provision) preserves the existing
+  // value verbatim via `...existing` — a caller that does not own the toggle never flips it.
+  if (profile.approval_mode === 'gated') merged.approval_mode = 'gated'
+  else if (profile.approval_mode === 'yolo') delete merged.approval_mode
   writeFileAtomic(path, `${JSON.stringify(merged, null, 2)}\n`)
 }
 

package/src/identity/profileStandard.ts

@@ -115,6 +115,9 @@ export function validateProfileStandard(raw: unknown, cwd: string): ProfileIssue
   if (obj.wake_policy !== undefined && obj.wake_policy !== 'ephemeral') {
     issues.push({ severity: 'warn', field: 'wake_policy', message: `unknown value "${String(obj.wake_policy)}" — only 'ephemeral' is honored` })
   }
+  if (obj.approval_mode !== undefined && obj.approval_mode !== 'gated' && obj.approval_mode !== 'yolo') {
+    issues.push({ severity: 'warn', field: 'approval_mode', message: `unknown value "${String(obj.approval_mode)}" — only 'gated'|'yolo' honored (absent = yolo default)` })
+  }
 
   // Owner sections — well-typed only; foundation never restructures them.
   if (obj.interfaces !== undefined && (typeof obj.interfaces !== 'object' || obj.interfaces === null || Array.isArray(obj.interfaces))) {

package/src/launch/adapters/claude.ts

@@ -23,7 +23,7 @@
 import { homedir } from 'os'
 import { join } from 'path'
 import { readdirSync, realpathSync, statSync } from 'fs'
-import type { ControlCommand, ControlPlan, LaunchAdapterConfig, LaunchSpec, RuntimeAdapter } from '../types.ts'
+import type { ApprovalMode, ControlCommand, ControlPlan, LaunchAdapterConfig, LaunchSpec, RuntimeAdapter } from '../types.ts'
 import { lastTimestampedEntryMs } from './transcriptTail.ts'
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -129,6 +129,46 @@ function dangerousRmDetail(pane: string): string {
   return [cmd && `cmd=${JSON.stringify(cmd)}`, target && `target=${JSON.stringify(target)}`].filter(Boolean).join(' ') || '(unparsed)'
 }
 
+// Standard command-approval prompt (claude 2.1.201 — the NO-RULE-MATCH passthrough / file-access "ask")
+// needles. This is the prompt a peer sees when it is NOT in bypass — i.e. GATED mode, OR a yolo peer
+// whose bypass the runtime disabled mid-session (the `tengu_disable_bypass_permissions_mode` feature
+// gate / `disableBypassPermissionsMode` setting). Under GENUINE bypass this prompt never surfaces (only
+// the dangerous-rm breaker does — verified from the 2.1.201 permission-gate: bypass auto-allows every
+// `ask` except "Dangerous rm/rmdir operation"). The live render (captured via a nested pty, default
+// mode) is a THREE-option select — "❯ 1. Yes / 2. Yes, and <don't ask again | always allow …> / 3. No"
+// under "Do you want to proceed?" — which is what distinguishes it from the dangerous-rm breaker's
+// TWO-option "1. Yes / 2. No". Split-literal (В40): a peer reviewing this adapter must not self-trigger.
+const ORG_POLICY_APPROVAL = 'organization requires ' + 'approval' // MCP org-restriction — NEVER auto-pressed
+const BASH_CMD_HEADER = 'Bash' + ' command'
+/** FULL-signature + position match for the LIVE standard command-approval prompt. Returns true ONLY for
+ *  the 3-option layout with the bottom-most `❯` cursor on "1. Yes" — so a mere QUOTE of the prompt (ready
+ *  composer `❯` below) never matches. Two hard exclusions satisfy the owner's NARROW-matcher rule:
+ *    · org-policy ("Your organization requires approval for this tool", an MCP restriction) → excluded,
+ *      the owner's org rule is HUMAN-only and must never be auto-pressed;
+ *    · the dangerous-rm breaker → handled by its own taxonomy (checked first in blockingConfirm), and
+ *      structurally excluded here anyway (it is a 2-option "2. No", never "2. Yes," + "3. No"). */
+function isCommandApprovalPrompt(pane: string): boolean {
+  if (!pane.includes(RM_PROCEED)) return false // shares "Do you want to proceed?" with the rm breaker
+  if (pane.includes(ORG_POLICY_APPROVAL)) return false // org-policy → never auto-Yes
+  if (isDangerousRmPrompt(pane)) return false // its own taxonomy owns this pane
+  // 3-option standard layout: option 2 is a "Yes," variant + option 3 is "No" (the rm breaker is
+  // 2-option "1. Yes / 2. No", so it fails BOTH tests — no overlap).
+  if (!/(^|\n)\s*2\.\s*Yes/.test(pane)) return false
+  if (!/(^|\n)\s*3\.\s*No\b/.test(pane)) return false
+  // live-modal position gate: the bottom-most `❯` row must sit on "1. Yes".
+  let lastCursorRow = ''
+  for (const line of pane.split(/\r?\n/)) if (line.includes('❯')) lastCursorRow = line
+  return /❯\s*1\.\s*Yes\b/.test(lastCursorRow)
+}
+/** Best-effort trace of the command the approval prompt guarded — the first non-blank line under the
+ *  "Bash command" block header. Mirrors dangerousRmDetail's post-hoc audit purpose. */
+function commandApprovalDetail(pane: string): string {
+  const lines = pane.split(/\r?\n/)
+  const hi = lines.findIndex(l => l.trim() === BASH_CMD_HEADER)
+  if (hi >= 0) for (let j = hi + 1; j < lines.length; j++) { const t = lines[j].trim(); if (t) return `cmd=${JSON.stringify(t)}` }
+  return '(unparsed)'
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Transcript activity proxy + resume uuid (lifecycle port, claude slug fix)
 // ─────────────────────────────────────────────────────────────────────────────
@@ -228,9 +268,16 @@ export const claudeAdapter: RuntimeAdapter = {
    * NO currency — no marketplace/install/update on this path.
    */
   buildArgv(spec: LaunchSpec, cfg: LaunchAdapterConfig): string[] {
+    // Human-approval mode (docs/17). yolo (default) = '--dangerously-skip-permissions'
+    // (headless bypass, current fleet behavior). gated = NO bypass + an EXPLICIT
+    // '--permission-mode default' so the base is deterministic (never inherits an
+    // acceptEdits/bypass defaultMode from settings): the runtime's permission layer is
+    // active as a fail-SAFE backstop, and the separately-installed PreToolUse hook is
+    // the primary interceptor (it fires regardless of mode — verified live 2.1.201).
+    const gated = spec.approvalMode === 'gated'
     return [
       cfg.claudeBin,
-      '--dangerously-skip-permissions',
+      ...(gated ? ['--permission-mode', 'default'] : ['--dangerously-skip-permissions']),
       '--disallowedTools',
       'AskUserQuestion',
       '--add-dir',
@@ -329,18 +376,30 @@ export const claudeAdapter: RuntimeAdapter = {
   },
 
   /**
-   * Dangerous-rm/rmdir circuit-breaker (RuntimeAdapter.blockingConfirm). Unlike the fullscreen nag
-   * (benign upsell → DECLINE), this guard sits ABOVE `--dangerously-skip-permissions` and hangs a
-   * headless peer forever with no human to answer. Owner decision (Артур, 04.07): auto-press YES —
-   * peers run on bypass, so this only restores the pre-2.1.x status quo, and a hang is real recurring
-   * harm. The default cursor is already on "1. Yes" (verified live), so ['1','Enter'] is the explicit,
-   * position-robust affirmative. Returns the class tag + a one-line command/target trace so the
-   * supervisor logs a post-hoc audit line. NB deliberately NOT a "smart" safe-decline/escalation — that
-   * lands later on the vault idea "Human-approval подтверждения действий пира через Telegram-кнопки".
+   * Blocking-confirm circuit-breaker (RuntimeAdapter.blockingConfirm). Unlike the fullscreen nag
+   * (benign upsell → DECLINE), these guards hang a headless peer forever with no human to answer.
+   * Owner decision (Артур, 04.07): auto-press YES — peers run on bypass, so this only restores the
+   * pre-2.1.x status quo, and a hang is real recurring harm. Two signatures are matched, most-specific
+   * first, each with its own taxonomy so the supervisor's audit log and (later) the human-approval
+   * broker can tell them apart:
+   *   1. 'dangerous-rm' — the rm/rmdir breaker that sits ABOVE `--dangerously-skip-permissions` (the
+   *      ONLY prompt that surfaces under genuine bypass). Default cursor on "1. Yes" (verified live).
+   *   2. 'command-approval' — the STANDARD 3-option approval prompt, surfaced when the peer is NOT in
+   *      bypass: gated mode, or a yolo peer whose bypass the runtime disabled mid-session (feature gate
+   *      / setting). Auto-Yes keeps a yolo peer alive; a gated peer is routed to the human broker by the
+   *      supervisor (Unit 4, mode-aware). Org-policy ("Your organization requires approval for this
+   *      tool") is EXCLUDED by the matcher — the owner's org rule is never auto-pressed.
+   * Both AFFIRM with ['1','Enter'] (the position-robust affirmative — cursor already on "1. Yes"); the
+   * DECLINE keys differ by layout: dangerous-rm is a 2-option "1.Yes/2.No" → ['2','Enter']; command-
+   * approval is a 3-option "1.Yes/2.Yes,…/3.No" → ['3','Enter']. The supervisor presses `keys` (yolo
+   * auto-Yes / gated-approved) or `denyKeys` (gated-denied / broker fail-safe). Each carries a one-line
+   * command/target trace for the audit + broker content. NB deliberately NOT a "smart" safe-decline —
+   * the gated human-approval path lands via the daemon broker (docs/17, Unit 4).
    */
-  blockingConfirm(pane: string): { keys: string[]; taxonomy: string; detail: string } | null {
-    if (!isDangerousRmPrompt(pane)) return null
-    return { keys: ['1', 'Enter'], taxonomy: 'dangerous-rm', detail: dangerousRmDetail(pane) }
+  blockingConfirm(pane: string): { keys: string[]; denyKeys: string[]; taxonomy: string; detail: string } | null {
+    if (isDangerousRmPrompt(pane)) return { keys: ['1', 'Enter'], denyKeys: ['2', 'Enter'], taxonomy: 'dangerous-rm', detail: dangerousRmDetail(pane) }
+    if (isCommandApprovalPrompt(pane)) return { keys: ['1', 'Enter'], denyKeys: ['3', 'Enter'], taxonomy: 'command-approval', detail: commandApprovalDetail(pane) }
+    return null
   },
 
   /**
@@ -350,12 +409,20 @@ export const claudeAdapter: RuntimeAdapter = {
    *   - '❯' (U+276F) — the TUI input-prompt glyph, present only at the ready
    *     input row, never in the splash art (claude-start.sh:357-360).
    *   - 'bypass permissions on' — the banner --dangerously-skip-permissions
-   *     emits once booted past the splash.
+   *     emits once booted past the splash (YOLO mode only).
    *   - none of the boot dialogs present (a dialog row can also carry '❯').
+   *
+   * GATED (docs/17): the peer launches WITHOUT --dangerously-skip-permissions, so the
+   * 'bypass permissions on' banner is ABSENT (verified live 2.1.201 — the no-bypass
+   * ready pane is '❯ Try "edit <filepath> to…"', no banner). The ready signal is then
+   * the composer '❯' with every boot dialog cleared. This branch is evaluated ONLY at
+   * BOOT (waitHostReady / the boot-driver), before any tool runs — so a mid-session
+   * '❯'-bearing modal (dangerous-rm / nag) cannot false-positive it.
    */
-  isInputReady(pane: string): boolean {
+  isInputReady(pane: string, mode?: ApprovalMode): boolean {
     if (anyBootDialog(pane)) return false
-    return pane.includes('❯') && pane.includes('bypass permissions on')
+    if (!pane.includes('❯')) return false
+    return mode === 'gated' ? true : pane.includes('bypass permissions on')
   },
 
   /**

package/src/launch/adapters/codex.ts

@@ -43,7 +43,7 @@ import { homedir } from 'os'
 import { join } from 'path'
 import { readdirSync, realpathSync, statSync } from 'fs'
 import { codexSessionCwd, lastTimestampedEntryMs } from './transcriptTail.ts'
-import type { ControlCommand, ControlPlan, LaunchAdapterConfig, LaunchSpec, RuntimeAdapter } from '../types.ts'
+import type { ApprovalMode, ControlCommand, ControlPlan, LaunchAdapterConfig, LaunchSpec, RuntimeAdapter } from '../types.ts'
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Boot dialog markers (watcher.codexUpdate/DirTrust/HooksReview, 253-261)
@@ -199,6 +199,13 @@ export const codexAdapter: RuntimeAdapter = {
    * NO currency — no marketplace/install/update on this path.
    */
   buildArgv(spec: LaunchSpec, cfg: LaunchAdapterConfig): string[] {
+    // Human-approval mode (docs/17). yolo (default) = the YOLO bypass flag (current
+    // fleet behavior). gated = NO bypass + `-c approval_policy=on-request` (the model
+    // asks before acting → the PreToolUse/PermissionRequest hook intercepts) with
+    // `-c sandbox_mode=danger-full-access` — gated gates APPROVALS, it does NOT add a
+    // sandbox (workspace-write would sever the loopback-MCP send_to_peer + vault writes;
+    // sandboxing is a separate axis, not v1). Session-scoped `-c`, never a host-config edit.
+    const gated = spec.approvalMode === 'gated'
     return [
       cfg.codexBin,
       ...(spec.resume ? ['resume', '--last'] : []),
@@ -208,7 +215,9 @@ export const codexAdapter: RuntimeAdapter = {
       ...(spec.systemPromptFile
         ? ['-c', `model_instructions_file=${spec.systemPromptFile}`]
         : []),
-      '--dangerously-bypass-approvals-and-sandbox',
+      ...(gated
+        ? ['-c', 'approval_policy=on-request', '-c', 'sandbox_mode=danger-full-access']
+        : ['--dangerously-bypass-approvals-and-sandbox']),
       ...(spec.extraArgs ?? []),
     ]
   },
@@ -261,7 +270,9 @@ export const codexAdapter: RuntimeAdapter = {
    * composer, and the ready-gate still verifies a real model turn (activity
    * mtime advance) before declaring READY.
    */
-  isInputReady(pane: string): boolean {
+  // mode is accepted for interface parity but ignored: codex's ready marker (the '› '
+  // composer arrow) is the same whether or not it launched with the YOLO bypass flag.
+  isInputReady(pane: string, _mode?: ApprovalMode): boolean {
     if (pane.includes('Press enter to continue')) return false
     return pane.split(/\r?\n/).some(line => line.trimStart().startsWith('› '))
   },

package/src/launch/index.ts

@@ -202,7 +202,7 @@ export const launch: LaunchFn = async (
       // the SAME shape as the tmux boot/deliver/ready-gate below, with host equivalents.
       const baselineMtime = adapter.newestActivityMtime(cwd) ?? 0
       const isReady = await waitHostReady(
-        { identity, logDir: cfg.logDir, adapter, bootDeadlineSecs: cfg.bootDeadlineSecs, paneLogStartByte, env },
+        { identity, logDir: cfg.logDir, adapter, bootDeadlineSecs: cfg.bootDeadlineSecs, paneLogStartByte, approvalMode: spec.approvalMode, env },
         sleep,
       )
       if (!isReady) return fail(identity, 'never-became-ready (hosted: supervisor input surface not ready)')

package/src/launch/ptyHost.ts

@@ -19,7 +19,7 @@ import { parseSessionName } from '../core/socket.ts'
 import type { TmuxRuntime } from '../core/constants.ts'
 import { paneLogViewport } from './readyGateModel.ts'
 import type { LaunchInvocation } from './invocation.ts'
-import type { RuntimeAdapter } from './types.ts'
+import type { ApprovalMode, RuntimeAdapter } from './types.ts'
 
 /** Match the tmux launch geometry (index.ts new-session -x 220 -y 50) so the served child + the
  *  pane-log model render at the same size launch reads readiness at. */
@@ -154,7 +154,7 @@ export async function startPtyHost(b: {
  * 2 s cadence + bootDeadline.
  */
 export async function waitHostReady(
-  b: { identity: string; logDir: string; adapter: RuntimeAdapter; bootDeadlineSecs: number; paneLogStartByte?: number; env?: NodeJS.ProcessEnv },
+  b: { identity: string; logDir: string; adapter: RuntimeAdapter; bootDeadlineSecs: number; paneLogStartByte?: number; approvalMode?: ApprovalMode; env?: NodeJS.ProcessEnv },
   sleep: (ms: number) => Promise<void>,
 ): Promise<boolean> {
   const log = `${b.logDir}/${b.identity}.log`
@@ -168,7 +168,7 @@ export async function waitHostReady(
     await sleep(2000)
     if (!hostSessionAlive(b.identity, b.env)) return false
     const view = await paneLogViewport(log, HOST_COLS, HOST_ROWS, b.paneLogStartByte ?? 0)
-    if (view && b.adapter.isInputReady(view)) return true
+    if (view && b.adapter.isInputReady(view, b.approvalMode)) return true
   }
   return false
 }

package/src/launch/types.ts

@@ -14,8 +14,13 @@
 // be implemented independently against a known contract.
 
 import type { Intelligence, Runtime } from '../core/constants.ts'
+import type { ApprovalMode } from '../identity/index.ts'
 import type { PublicPeerSummary } from '../registry/index.ts'
 
+// Re-export so the adapters (which already import their contract types from here) get
+// ApprovalMode from ONE place rather than reaching into identity directly.
+export type { ApprovalMode }
+
 export type { PublicPeerSummary } from '../registry/index.ts'
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -159,6 +164,12 @@ export interface LaunchSpec {
    *  less throwaway may omit it, but an adapter that declares requiresIntelligence
    *  then refuses (cannot confirm the required nature). */
   intelligence?: Intelligence
+  /** Human-approval mode (docs/17): `yolo` (default/omitted) launches with the
+   *  runtime bypass flag (current fleet behavior); `gated` launches WITHOUT bypass
+   *  and swaps in the gated permission/approval config, so the runtime's blocking
+   *  requests route to a human via the daemon broker (a PreToolUse hook, installed
+   *  separately at toggle time, is the interceptor). buildArgv reads it. */
+  approvalMode?: ApprovalMode
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -307,17 +318,25 @@ export interface RuntimeAdapter {
    * settings, or flag disables it). A headless peer has no human to press 1/2, so it HANGS forever
    * (live-observed on a verification session). Owner decision (Артур, 04.07): auto-press YES — peers
    * already run on bypass, so this only restores the pre-2.1.x status quo; a hang is real recurring
-   * harm. Return `{keys, taxonomy, detail}` (the affirmative keys + a class tag + a one-line trace of
-   * WHAT was approved) so the supervisor can press it AND leave a post-hoc log; else null. Match the
-   * FULL signature + cursor position so ordinary content mentioning the phrase never fires. Optional
-   * (codex/router omit it). tui only. FUTURE: replace blind-YES with human approval via Telegram —
-   * see the vault idea "Human-approval подтверждения действий пира через Telegram-кнопки".
+   * harm. Return `{keys, denyKeys, taxonomy, detail}` (the AFFIRMATIVE keys + the taxonomy-specific
+   * DECLINE keys + a class tag + a one-line trace of WHAT was approved) so the supervisor can press
+   * YES on a yolo peer AND leave a post-hoc log, OR route the confirm to the human broker on a gated
+   * peer and press the decision (Unit 4 — allow→keys, deny→denyKeys). `denyKeys` differs by taxonomy
+   * because the modal layouts differ (dangerous-rm is a 2-option "1.Yes/2.No" → `['2','Enter']`;
+   * command-approval is a 3-option "1.Yes/2.Yes,…/3.No" → `['3','Enter']`) — the adapter owns that
+   * layout knowledge, not the supervisor. Match the FULL signature + cursor position so ordinary
+   * content mentioning the phrase never fires; else null. Optional (codex/router omit it). tui only.
+   * Human-approval lands via the daemon broker (docs/17); the vault idea is "Human-approval
+   * подтверждения действий пира через Telegram-кнопки".
    */
-  blockingConfirm?(pane: string): { keys: string[]; taxonomy: string; detail: string } | null
+  blockingConfirm?(pane: string): { keys: string[]; denyKeys: string[]; taxonomy: string; detail: string } | null
 
   /** Is the input surface ready for the first message? (tui: ready marker present
-   *  AND startup dialogs gone). Router runtimes return true (no input surface). */
-  isInputReady(pane: string): boolean
+   *  AND startup dialogs gone). Router runtimes return true (no input surface).
+   *  `mode` (default yolo) lets a runtime whose READY marker differs by approval mode
+   *  pick the right one — claude's yolo ready banner ('bypass permissions on') is
+   *  absent under gated (launched WITHOUT --dangerously-skip-permissions). */
+  isInputReady(pane: string, mode?: ApprovalMode): boolean
 
   /** Newest activity-proxy FILE mtime — used by the READY-GATE (it waits for ANY transcript write past
    *  baseline = "the model produced its first turn"). NOT for idle accounting: a live session re-saves

package/src/lifecycle/index.ts

@@ -28,7 +28,7 @@ import { buildProcessAddress, buildSocketPath, parseSessionName } from '../core/
 import { err, ok, type Result } from '../core/errors.ts'
 import { capPaneLogs } from '../launch/cmdlog.ts'
 import { resolveGlobalRoot } from '../storage/index.ts'
-import { readPeerProfile, resolveIdentity } from '../identity/index.ts'
+import { approvalModeOf, readPeerProfile, resolveIdentity, type ApprovalMode } from '../identity/index.ts'
 import {
   ephemeralQueueDepth,
   listQueuedIdentities,
@@ -600,6 +600,18 @@ export function isEphemeralPeer(cwd: string): boolean {
   }
 }
 
+/** The effective human-approval mode of the peer at `cwd` — `gated` iff its profile
+ *  persists it, else the default `yolo`. A profile read hiccup → `yolo` (safe default:
+ *  the current-fleet behavior; never gates a peer we cannot read). The single cwd-level
+ *  reader the launch/supervisor/fleet paths call (default lives in approvalModeOf). */
+export function peerApprovalMode(cwd: string): ApprovalMode {
+  try {
+    return approvalModeOf(readPeerProfile(cwd))
+  } catch {
+    return 'yolo'
+  }
+}
+
 /**
  * Decide resume vs fresh on a wake (TARGET redesign). Branch order:
  *   1. argsResume === false (folder-launch `iapeer <runtime>`) → FRESH.
@@ -1112,6 +1124,9 @@ export async function wakeOrSpawn(args: WakeArgs, deps: WakeDeps = {}): Promise<
       // Carry the peer's nature so the launch primitive can enforce an adapter's
       // intelligence gate (telegram requires natural). From the registry record.
       intelligence: peer.intelligence,
+      // Human-approval mode from the LOCAL profile (docs/17): drives the runtime
+      // bypass flag + gated permission/approval config in buildArgv. Default yolo.
+      approvalMode: peerApprovalMode(cwd),
     }
     const launchCfg: LaunchConfig = {
       claudeBin: cfg.claudeBin,