@agfpd/iapeer 0.4.67 → 0.4.69

package/src/approval/hook.ts

@@ -0,0 +1,193 @@
+// approval-hook — the blocking bridge from a runtime's PreToolUse hook to the daemon
+// approval broker (docs/17). Installed (gated peers only) as the `command` of a claude /
+// codex PreToolUse hook. On each matched tool call it: reads the runtime's hook JSON on
+// stdin, builds a human-readable approval request, POSTs it to the daemon (long-poll,
+// blocking until a human answers or the broker's default-deny timeout), and prints the
+// runtime hook decision JSON on stdout. claude and codex share the PreToolUse output
+// shape (`hookSpecificOutput.permissionDecision`), so ONE format serves both.
+//
+// FAIL-SAFE by construction: ANY failure (no PEER identity, daemon unreachable, malformed
+// response, client timeout) prints a DENY with a reason — a gated peer is never allowed to
+// act unapproved, and never hangs (the client timeout sits above the broker's).
+//
+// Pure helpers (parseHookInput / actionContent / formatHookDecision) are unit-tested;
+// runApprovalHook is the thin IO orchestration over the shared broker transport (brokerClient).
+
+import { type ApprovalDecision, requestApproval, resolveFleetBase } from './brokerClient.ts'
+
+function str(v: unknown): string {
+  return typeof v === 'string' ? v : v === undefined || v === null ? '' : JSON.stringify(v)
+}
+function firstLine(s: string): string {
+  const nl = s.indexOf('\n')
+  return (nl >= 0 ? s.slice(0, nl) : s).trim()
+}
+function clip(s: string, max: number): string {
+  return s.length > max ? `${s.slice(0, max)}\n…[+${s.length - max} chars]` : s
+}
+
+export interface ActionContent {
+  kind: 'tool' | 'plan'
+  content: string
+  summary: string
+}
+
+/** Turn a PreToolUse (tool_name, tool_input) into the human-readable content + summary the
+ *  broker shows in every channel. Covers the v1 nomenclature (docs/17 §2); an unknown tool
+ *  falls back to a pretty-printed tool_input so nothing is opaque. */
+export function actionContent(toolName: string, toolInput: Record<string, unknown> | undefined): ActionContent {
+  const ti = toolInput ?? {}
+  switch (toolName) {
+    case 'Bash': {
+      const cmd = str(ti.command)
+      const desc = str(ti.description)
+      return { kind: 'tool', content: desc ? `${cmd}\n\n# ${desc}` : cmd, summary: cmd || 'Bash' }
+    }
+    case 'Write': {
+      const fp = str(ti.file_path)
+      return { kind: 'tool', content: `Write ${fp}\n\n${clip(str(ti.content), 8000)}`, summary: `Write ${fp}` }
+    }
+    case 'Edit': {
+      const fp = str(ti.file_path)
+      return {
+        kind: 'tool',
+        content: `Edit ${fp}\n\n--- old\n${clip(str(ti.old_string), 3000)}\n+++ new\n${clip(str(ti.new_string), 3000)}`,
+        summary: `Edit ${fp}`,
+      }
+    }
+    case 'MultiEdit': {
+      const fp = str(ti.file_path)
+      const edits = Array.isArray(ti.edits) ? ti.edits : []
+      return { kind: 'tool', content: `MultiEdit ${fp} (${edits.length} edits)\n\n${clip(JSON.stringify(edits, null, 2), 6000)}`, summary: `MultiEdit ${fp} (${edits.length})` }
+    }
+    case 'NotebookEdit': {
+      const fp = str(ti.notebook_path)
+      return { kind: 'tool', content: `NotebookEdit ${fp}\n\n${clip(str(ti.new_source), 6000)}`, summary: `NotebookEdit ${fp}` }
+    }
+    case 'ExitPlanMode': {
+      const plan = str(ti.plan)
+      return { kind: 'plan', content: plan, summary: firstLine(plan) || 'plan' }
+    }
+    // codex patch application (tool_input carries the patch text)
+    case 'apply_patch':
+    case 'ApplyPatch': {
+      const patch = str(ti.input ?? ti.patch ?? ti)
+      return { kind: 'tool', content: clip(patch, 8000), summary: `apply_patch (${firstLine(patch) || 'diff'})` }
+    }
+    default: {
+      const body = clip(JSON.stringify(ti, null, 2), 6000)
+      return { kind: 'tool', content: `${toolName}\n\n${body}`, summary: toolName }
+    }
+  }
+}
+
+/** The two hook events we intercept. `PermissionRequest` (claude, and codex) fires ONLY when
+ *  the runtime's permission config DECIDED to prompt — the primary, matcher-free interceptor
+ *  (verified live 2.1.201: fires + suppresses the prompt + returns a decision, policy stays
+ *  100% at the runtime). `PreToolUse` fires on every matched tool (codex structural path). */
+export type HookEvent = 'PermissionRequest' | 'PreToolUse'
+
+export interface HookInput {
+  event: HookEvent
+  toolName: string
+  toolInput: Record<string, unknown> | undefined
+}
+
+/** Parse the runtime's hook stdin JSON. Throws on non-JSON / unknown event / missing tool_name
+ *  (the caller turns a throw into a fail-safe exit-2 deny, which both events honor). */
+export function parseHookInput(stdin: string): HookInput {
+  const raw = JSON.parse(stdin) as Record<string, unknown>
+  const evName = raw.hook_event_name
+  const event: HookEvent =
+    evName === 'PermissionRequest' ? 'PermissionRequest' : evName === 'PreToolUse' ? 'PreToolUse' : throwEvent(evName)
+  const toolName = raw.tool_name
+  if (typeof toolName !== 'string' || !toolName) throw new Error('hook stdin has no tool_name')
+  const toolInput =
+    raw.tool_input && typeof raw.tool_input === 'object' && !Array.isArray(raw.tool_input)
+      ? (raw.tool_input as Record<string, unknown>)
+      : undefined
+  return { event, toolName, toolInput }
+}
+function throwEvent(v: unknown): never {
+  throw new Error(`hook stdin has an unexpected hook_event_name "${String(v)}"`)
+}
+
+/** The decision JSON in the shape the given event accepts. A deny carries the reason to the
+ *  model. PermissionRequest uses `decision.behavior` (+ `message`); PreToolUse uses
+ *  `permissionDecision` (+ `permissionDecisionReason`) — both verified live 2.1.201 / codex 0.142.5. */
+export function formatHookDecision(d: ApprovalDecision, event: HookEvent): string {
+  if (event === 'PermissionRequest') {
+    return JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PermissionRequest',
+        decision: { behavior: d.decision, ...(d.decision === 'deny' && d.reason ? { message: d.reason } : {}) },
+      },
+    })
+  }
+  return JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: d.decision,
+      ...(d.decision === 'deny' && d.reason ? { permissionDecisionReason: d.reason } : {}),
+    },
+  })
+}
+
+export interface RunHookDeps {
+  env?: NodeJS.ProcessEnv
+  /** Injectable fetch (tests). Default global fetch. */
+  fetch?: typeof fetch
+  /** Injectable client timeout (tests). */
+  timeoutMs?: number
+}
+
+export interface HookRunResult {
+  /** Decision JSON for the runtime (empty on the exit-2 hard fail-safe). */
+  stdout: string
+  /** Reason fed to the model on the exit-2 path (empty otherwise). */
+  stderr: string
+  /** 0 = decision expressed in stdout JSON; 2 = hard fail-safe deny (both events honor it). */
+  exitCode: number
+}
+
+/**
+ * Full hook run: stdin JSON → broker → decision JSON in the shape the event accepts. Never
+ * throws. Two fail-safe layers: once the event is known, any downstream failure (no identity,
+ * daemon down, timeout, broker deny) returns an event-appropriate DENY JSON (exit 0, reason to
+ * the model); a stdin we cannot even parse (unknown event) returns exit 2 + stderr, which
+ * DENIES under BOTH PermissionRequest and PreToolUse — so a gated peer is never allowed
+ * unapproved and never hangs, even on a malformed hook payload.
+ */
+export async function runApprovalHook(stdin: string, deps: RunHookDeps = {}): Promise<HookRunResult> {
+  const env = deps.env ?? process.env
+  const doFetch = deps.fetch ?? fetch
+  const timeoutMs = deps.timeoutMs
+  let event: HookEvent
+  let toolName: string
+  let toolInput: Record<string, unknown> | undefined
+  try {
+    ;({ event, toolName, toolInput } = parseHookInput(stdin))
+  } catch (e) {
+    // Cannot determine the event → exit 2 denies in BOTH events (stderr → model).
+    return { stdout: '', stderr: `iapeer approval-hook: ${e instanceof Error ? e.message : String(e)} — denied fail-safe`, exitCode: 2 }
+  }
+  try {
+    const personality = env.PEER_PERSONALITY?.trim()
+    if (!personality) throw new Error('no PEER_PERSONALITY in the hook environment')
+    const runtime = env.PEER_RUNTIME?.trim() || 'claude'
+    const { kind, content, summary } = actionContent(toolName, toolInput)
+    const decision = await requestApproval(
+      resolveFleetBase(env),
+      { personality, runtime, kind, tool: toolName, content, summary },
+      { env, fetch: doFetch, timeoutMs },
+    )
+    return { stdout: formatHookDecision(decision, event), stderr: '', exitCode: 0 }
+  } catch (e) {
+    // Event known → event-appropriate DENY JSON (never allow-by-accident, never hang).
+    return {
+      stdout: formatHookDecision({ decision: 'deny', reason: `iapeer approval unavailable (${e instanceof Error ? e.message : String(e)}) — denied fail-safe` }, event),
+      stderr: '',
+      exitCode: 0,
+    }
+  }
+}

package/src/approval/install.ts

@@ -0,0 +1,194 @@
+// approval install — the RUNTIME-CONFIG surfaces the gated toggle brings up/down (docs/17
+// §1). The PreToolUse interceptor + the coarse tool-class matcher live on the runtime's OWN
+// hook config (claude: <cwd>/.claude/settings.json hooks.PreToolUse[].matcher; codex:
+// <cwd>/.codex/hooks.json matcher) — so the user tunes WHICH classes are gated as ordinary
+// runtime config; iapeer only SEEDS the default on flip-to-gated (seed-if-absent) and REMOVES
+// its whole block on flip-to-yolo. Idempotent both ways: a gated→yolo→gated round-trip is
+// byte-identical (no accumulation, no half-states) — the toggle invariant.
+//
+// Also installed for gated claude: an allow-rule for the peer's OWN MCP tool
+// (mcp__iapeer__send_to_peer) so a gated peer's IAP channel is never itself gated (a
+// no-bypass session would otherwise prompt on it and hang).
+
+import { existsSync, mkdirSync, readFileSync, rmSync } from 'fs'
+import { dirname, join } from 'path'
+import { writeFileAtomic } from '../storage/index.ts'
+import { claudeSettingsPath } from '../launch/nativeMemory.ts'
+import { iapeerBinPath } from '../install/index.ts'
+import { readPeerProfile, writePeerProfileAtomic, type ApprovalMode } from '../identity/index.ts'
+import { preSeedCodexHooksTrust, removeCodexHooksTrustUnder, type HooksTrustOutcome } from '../launch/codexHooksTrust.ts'
+
+// claude gated uses a matcher-FREE PermissionRequest hook (docs/17, Option D — verified live
+// 2.1.201): PermissionRequest fires ONLY when the runtime's permission config DECIDED to prompt
+// (a tool call not covered by an allow/deny rule), so the policy of "what to ask" stays 100% at
+// the runtime — the user tunes it with ordinary permission rules (a tool in permissions.allow is
+// never asked → the hook never fires → auto-allowed). No class matcher, no drift, no hang: a new
+// tool the runtime prompts for is intercepted the same way. iapeer only seeds the hook + the
+// allow-rule for its own MCP tool (else the runtime would prompt on the peer's own IAP channel).
+/** codex tool-name regex (codex PreToolUse path — structural, live-verify pending). */
+export const CODEX_APPROVAL_MATCHER = '^(Bash|Shell|shell|local_shell|exec|apply_patch|ApplyPatch)$'
+/** The peer's own IAP tool — allow-listed so a gated peer's send_to_peer is not itself gated. */
+export const IAPEER_MCP_ALLOW = 'mcp__iapeer__send_to_peer'
+/** Runtime hook timeout (seconds): ABOVE the broker default-deny (300) + the hook client fetch
+ *  ceiling (600) so the broker/human answers before the runtime kills the hook. */
+const HOOK_TIMEOUT_SECS = 900
+
+/** The `command` string the runtime runs per matched tool call (the installed binary). */
+export function approvalHookCommand(env: NodeJS.ProcessEnv = process.env): string {
+  return `${iapeerBinPath(env)} approval-hook`
+}
+
+function isIapeerGroup(group: unknown): boolean {
+  const hooks = (group as { hooks?: unknown })?.hooks
+  return (
+    Array.isArray(hooks) &&
+    hooks.some(h => typeof (h as { command?: unknown })?.command === 'string' && (h as { command: string }).command.includes('approval-hook'))
+  )
+}
+
+function iapeerClaudeGroup(env: NodeJS.ProcessEnv): Record<string, unknown> {
+  // Matcher-free: PermissionRequest already fires only on prompt-worthy calls (Option D).
+  return { hooks: [{ type: 'command', command: approvalHookCommand(env), timeout: HOOK_TIMEOUT_SECS }] }
+}
+
+function readJsonObject(path: string): Record<string, unknown> | null {
+  if (!existsSync(path)) return {}
+  try {
+    const raw = JSON.parse(readFileSync(path, 'utf8')) as unknown
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null // refuse to clobber a non-object
+    return raw as Record<string, unknown>
+  } catch {
+    return null
+  }
+}
+
+// ── claude (project settings.json) ───────────────────────────────────────────
+
+/** Seed the gated PreToolUse hook + MCP allow-rule into <cwd>/.claude/settings.json
+ *  (seed-if-absent, no-clobber merge). Returns the path, or null on a refusal/error. */
+export function installClaudeApproval(cwd: string, env: NodeJS.ProcessEnv = process.env): string | null {
+  const path = claudeSettingsPath(cwd)
+  const obj = readJsonObject(path)
+  if (obj === null) return null
+  // hooks.PermissionRequest — push OUR group iff absent (respect a user-added one).
+  const hooks = (obj.hooks && typeof obj.hooks === 'object' && !Array.isArray(obj.hooks) ? obj.hooks : {}) as Record<string, unknown>
+  const pre = (Array.isArray(hooks.PermissionRequest) ? hooks.PermissionRequest : []) as unknown[]
+  if (!pre.some(isIapeerGroup)) pre.push(iapeerClaudeGroup(env))
+  hooks.PermissionRequest = pre
+  obj.hooks = hooks
+  // permissions.allow — allow-list the peer's own MCP tool (idempotent).
+  const perms = (obj.permissions && typeof obj.permissions === 'object' && !Array.isArray(obj.permissions) ? obj.permissions : {}) as Record<string, unknown>
+  const allow = (Array.isArray(perms.allow) ? perms.allow : []) as unknown[]
+  if (!allow.includes(IAPEER_MCP_ALLOW)) allow.push(IAPEER_MCP_ALLOW)
+  perms.allow = allow
+  obj.permissions = perms
+  mkdirSync(dirname(path), { recursive: true })
+  writeFileAtomic(path, `${JSON.stringify(obj, null, 2)}\n`, 0o644)
+  return path
+}
+
+/** Remove OUR gated hook + MCP allow-rule, cleaning up any structures we emptied so a
+ *  gated→yolo flip restores the pre-install bytes (foreign hooks/rules preserved). */
+export function removeClaudeApproval(cwd: string): string | null {
+  const path = claudeSettingsPath(cwd)
+  if (!existsSync(path)) return null
+  const obj = readJsonObject(path)
+  if (obj === null) return null
+  const hooks = obj.hooks as Record<string, unknown> | undefined
+  if (hooks && Array.isArray(hooks.PermissionRequest)) {
+    hooks.PermissionRequest = (hooks.PermissionRequest as unknown[]).filter(g => !isIapeerGroup(g))
+    if ((hooks.PermissionRequest as unknown[]).length === 0) delete hooks.PermissionRequest
+    if (Object.keys(hooks).length === 0) delete obj.hooks
+  }
+  const perms = obj.permissions as Record<string, unknown> | undefined
+  if (perms && Array.isArray(perms.allow)) {
+    perms.allow = (perms.allow as unknown[]).filter(r => r !== IAPEER_MCP_ALLOW)
+    if ((perms.allow as unknown[]).length === 0) delete perms.allow
+    if (Object.keys(perms).length === 0) delete obj.permissions
+  }
+  writeFileAtomic(path, `${JSON.stringify(obj, null, 2)}\n`, 0o644)
+  return path
+}
+
+// ── codex (project hooks.json + trust pre-seed) ──────────────────────────────
+
+export function codexHooksJsonPath(cwd: string): string {
+  return join(cwd, '.codex', 'hooks.json')
+}
+
+/** Write <cwd>/.codex/hooks.json with the gated PreToolUse group (seed-if-absent merge) and
+ *  pre-seed its trust in ~/.codex/config.toml (else codex silently SKIPS an untrusted hook). */
+export function installCodexApproval(cwd: string, env: NodeJS.ProcessEnv = process.env): { path: string; trust?: HooksTrustOutcome } | null {
+  const path = codexHooksJsonPath(cwd)
+  const obj = readJsonObject(path)
+  if (obj === null) return null
+  const hooks = (obj.hooks && typeof obj.hooks === 'object' && !Array.isArray(obj.hooks) ? obj.hooks : {}) as Record<string, unknown>
+  const pre = (Array.isArray(hooks.PreToolUse) ? hooks.PreToolUse : []) as unknown[]
+  if (!pre.some(isIapeerGroup)) {
+    pre.push({ matcher: CODEX_APPROVAL_MATCHER, hooks: [{ type: 'command', command: approvalHookCommand(env), timeout: HOOK_TIMEOUT_SECS }] })
+  }
+  hooks.PreToolUse = pre
+  obj.hooks = hooks
+  mkdirSync(dirname(path), { recursive: true })
+  writeFileAtomic(path, `${JSON.stringify(obj, null, 2)}\n`, 0o644)
+  const trust = preSeedCodexHooksTrust(path, env)
+  return { path, trust }
+}
+
+/** Remove the codex gated hook (drop OUR group; delete the file if it becomes empty) and its
+ *  trust state under this cwd. */
+export function removeCodexApproval(cwd: string, env: NodeJS.ProcessEnv = process.env): string | null {
+  const path = codexHooksJsonPath(cwd)
+  removeCodexHooksTrustUnder(cwd, env)
+  if (!existsSync(path)) return null
+  const obj = readJsonObject(path)
+  if (obj === null) return null
+  const hooks = obj.hooks as Record<string, unknown> | undefined
+  if (hooks && Array.isArray(hooks.PreToolUse)) {
+    hooks.PreToolUse = (hooks.PreToolUse as unknown[]).filter(g => !isIapeerGroup(g))
+    if ((hooks.PreToolUse as unknown[]).length === 0) delete hooks.PreToolUse
+    if (Object.keys(hooks).length === 0) delete obj.hooks
+  }
+  // If nothing but our block was there, drop the file entirely (pristine restore).
+  if (Object.keys(obj).length === 0) {
+    rmSync(path, { force: true })
+    return path
+  }
+  writeFileAtomic(path, `${JSON.stringify(obj, null, 2)}\n`, 0o644)
+  return path
+}
+
+// ── the toggle: profile field + per-runtime surfaces (docs/17 §1) ─────────────
+
+export interface ApprovalToggleResult {
+  mode: ApprovalMode
+  surfaces: string[]
+}
+
+/**
+ * Flip a peer's approval mode: persist the profile field AND bring every PERSISTENT runtime
+ * surface to the mode (idempotent). The argv/ready-gate surfaces are NOT touched here — they
+ * are computed at launch from the profile field, so a LIVE session keeps its launched mode
+ * until the next fresh session (the explicit application moment). Throws if the cwd has no
+ * peer profile.
+ */
+export function setApprovalMode(cwd: string, mode: ApprovalMode, env: NodeJS.ProcessEnv = process.env): ApprovalToggleResult {
+  const profile = readPeerProfile(cwd)
+  if (!profile) throw new Error(`no peer profile at ${cwd}`)
+  writePeerProfileAtomic(cwd, { ...profile, approval_mode: mode })
+  const surfaces = [`profile: approval_mode=${mode}`]
+  for (const rt of profile.runtimes) {
+    if (rt === 'claude') {
+      if (mode === 'gated') surfaces.push(`claude: ${installClaudeApproval(cwd, env) ? 'PermissionRequest hook + MCP allow-rule installed' : 'settings write SKIPPED (non-object)'}`)
+      else surfaces.push(`claude: ${removeClaudeApproval(cwd) ? 'hook + allow-rule removed' : 'nothing to remove'}`)
+    } else if (rt === 'codex') {
+      if (mode === 'gated') {
+        const r = installCodexApproval(cwd, env)
+        surfaces.push(`codex: ${r ? `hooks.json installed + trust ${r.trust?.state ?? '?'}` : 'hooks.json write SKIPPED'}`)
+      } else {
+        surfaces.push(`codex: ${removeCodexApproval(cwd, env) ? 'hooks.json + trust removed' : 'trust cleared (no hooks.json)'}`)
+      }
+    }
+  }
+  return { mode, surfaces }
+}

package/src/cli/index.ts

@@ -1281,6 +1281,11 @@ const VERBS: ReadonlyArray<{ sig: string; desc: string }> = [
     sig: 'tray install|uninstall|render [--stream]|cmd <c> <peer>|status',
     desc: 'the macOS menu-bar fleet dashboard (SwiftBar plugin) — first external Fleet API client; install activates it (installs SwiftBar when absent). See docs/16.',
   },
+  { sig: 'approval-mode <peer> [gated|yolo]', desc: 'read/flip a peer\'s human-approval mode (docs/17): yolo=current bypass; gated=blocking runtime approvals routed to a human. Persists + brings runtime surfaces to the mode; applies on next fresh session' },
+  { sig: 'approvals [--json]', desc: 'list pending human-approval requests (verbatim action content); the host answer channel to the daemon broker' },
+  { sig: 'approve <id>', desc: 'approve a pending request — the decision clears it in every channel' },
+  { sig: 'deny <id> [reason]', desc: 'deny a pending request; the reason reaches the model' },
+  { sig: 'approval-hook', desc: '(runtime-installed) PreToolUse bridge: stdin hook JSON → broker → decision JSON. Not run by hand' },
 ]
 
 /** Greedy word-wrap to `width` columns. A token longer than `width` keeps its own
@@ -2580,6 +2585,48 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
             )
         }
       }
+      case 'approval-hook': {
+        // (runtime-installed, docs/17) the PreToolUse bridge: stdin = the runtime's hook JSON,
+        // stdout = the decision JSON (EXACTLY — the runtime parses it), blocking on the broker.
+        // Never run by hand. Fail-safe: any error prints a DENY (expressed in JSON, exit 0).
+        const { runApprovalHook } = await import('../approval/hook.ts')
+        const stdin = await Bun.stdin.text()
+        const r = await runApprovalHook(stdin, { env })
+        if (r.stdout) out(`${r.stdout}\n`)
+        if (r.stderr) errOut(`${r.stderr}\n`)
+        return r.exitCode
+      }
+      case 'approvals': {
+        const { approvalsList } = await import('../approval/cli.ts')
+        const r = await approvalsList(flags.json === true, env)
+        out(r.text)
+        return r.code
+      }
+      case 'approve':
+      case 'deny': {
+        const id = positionals[0]
+        if (!id) return argErr(errOut, `${verb} needs an id — usage: iapeer ${verb} <id>${verb === 'deny' ? ' [reason]' : ''} (list: iapeer approvals)`)
+        const { resolveApproval } = await import('../approval/cli.ts')
+        const reason = verb === 'deny' ? positionals.slice(1).join(' ') || undefined : undefined
+        const approver = typeof flags.approver === 'string' ? flags.approver : undefined
+        const r = await resolveApproval(id, verb, { reason, approver }, env)
+        out(r.text)
+        return r.code
+      }
+      case 'approval-mode': {
+        const peer = positionals[0]
+        if (!peer) return argErr(errOut, 'approval-mode needs a peer — usage: iapeer approval-mode <peer> [gated|yolo] [--now]')
+        const modeArg = positionals[1]
+        if (modeArg && modeArg !== 'gated' && modeArg !== 'yolo') return argErr(errOut, 'approval-mode: mode must be gated | yolo (omit to read the current mode)')
+        const { approvalModeCli } = await import('../approval/cli.ts')
+        const r = approvalModeCli(peer, modeArg as 'gated' | 'yolo' | undefined, env)
+        out(r.text)
+        if (r.code === 0 && modeArg && flags.now === true) {
+          const o = await newPeer(peer, undefined, { env })
+          out(`applied now: fresh session (${o.action})\n`)
+        }
+        return r.code
+      }
       default: {
         // `iapeer <runtime>` (launch) — folder-launch the cwd's peer, ALWAYS fresh. On a TTY this is
         // the human "start a fresh session and work in it" verb (parallel to `attach`, which resumes):

package/src/daemon/approvals.ts

@@ -0,0 +1,202 @@
+// Approval broker — the in-daemon queue that is the SINGLE SOURCE OF TRUTH for
+// human-approval requests (docs/17). Every channel (the runtime hook that ASKS, and
+// the CLI / tray / telegram faces that ANSWER) is an interface to THIS one queue: a
+// decision from any face resolves the request everywhere (the owner's invariant).
+//
+// Flow: a gated peer's PreToolUse hook blocks and POSTs /fleet/v1/approvals → the fleet
+// handler calls broker.request(...) and awaits the returned promise (long-poll) → the
+// broker enqueues, emits `approval-request` (approvals.log → SSE), and holds the promise
+// → a face calls broker.resolve(id, …) (via POST /fleet/v1/approvals/<id>/approve|deny)
+// → the promise resolves, the fleet handler writes the runtime hook JSON back, the tool
+// proceeds or is blocked with the reason. A per-request timeout resolves default-DENY so
+// a peer never hangs. Every failure direction is deny (fail-safe): timeout, requester
+// disconnect, unknown id.
+//
+// In-memory + ephemeral: pending requests do NOT survive a daemon restart (the blocking
+// hook connection breaks on restart → the hook fails safe to deny). The durable
+// approvals.log is the audit/observability trace, not a recovery store.
+
+import { appendApprovalEvent } from './approvalslog.ts'
+
+/** v1 taxonomy of intercepted blocking requests (docs/17 §2). Free-form-tolerant. */
+export type ApprovalKind = 'tool' | 'plan' | 'question' | 'circuit-breaker'
+
+export interface ApprovalRequestInput {
+  personality: string
+  runtime: string
+  /** Taxonomy tag (tool | plan | question | circuit-breaker | …). */
+  kind: ApprovalKind | string
+  /** The specific tool / breaker name, e.g. `Bash`, `Edit`, `dangerous-rm`. */
+  tool: string
+  /** FULL human-readable content of the action — the command, the diff, the plan text,
+   *  the circuit-breaker prompt. Shown to the human in every channel (criterion #7). */
+  content: string
+  /** One-line summary for the SSE event / badge (default: the first line of content). */
+  summary?: string
+  /** Short title, e.g. "boris · Bash" (default: "<personality> · <tool>"). */
+  title?: string
+  /** nature-peers who may answer (informational in v1 — same-uid faces are trusted). */
+  approvers?: string[]
+}
+
+export interface PendingApproval extends ApprovalRequestInput {
+  id: string
+  summary: string
+  title: string
+  approvers: string[]
+  createdMs: number
+  expiresMs: number
+}
+
+export interface ApprovalDecision {
+  decision: 'allow' | 'deny'
+  reason?: string
+}
+
+export interface ResolveMeta {
+  /** The approver who answered (a nature-peer personality). */
+  by?: string
+  /** The channel that answered: cli | tray | telegram | timeout | disconnect. */
+  via?: string
+}
+
+interface Entry {
+  item: PendingApproval
+  resolve: (d: ApprovalDecision) => void
+  timer: ReturnType<typeof setTimeout>
+}
+
+export interface ApprovalBrokerOptions {
+  /** cfg.eventLogDir — approvals.log lives here (falsy → no durable log, hermetic). */
+  logDir?: string
+  env?: NodeJS.ProcessEnv
+  /** Per-request default-deny timeout. Default IAPEER_APPROVAL_TIMEOUT_MS or 300 s.
+   *  MUST stay below the runtime hook's own timeout (claude/codex default 600 s) so the
+   *  broker's default-deny wins before the runtime kills the hook (fail-safe ordering). */
+  timeoutMs?: number
+  /** Injectable clock (tests). Default Date.now. */
+  now?: () => number
+}
+
+const DEFAULT_TIMEOUT_MS = 300_000
+
+function envPosInt(raw: string | undefined, dflt: number): number {
+  const n = parseInt(raw ?? '', 10)
+  return Number.isFinite(n) && n > 0 ? n : dflt
+}
+
+function firstLine(s: string): string {
+  const nl = s.indexOf('\n')
+  return (nl >= 0 ? s.slice(0, nl) : s).trim()
+}
+
+export class ApprovalBroker {
+  private readonly pending = new Map<string, Entry>()
+  private counter = 0
+  private readonly logDir?: string
+  private readonly env: NodeJS.ProcessEnv
+  private readonly timeoutMs: number
+  private readonly now: () => number
+
+  constructor(opts: ApprovalBrokerOptions = {}) {
+    this.logDir = opts.logDir
+    this.env = opts.env ?? process.env
+    this.timeoutMs = opts.timeoutMs ?? envPosInt(this.env.IAPEER_APPROVAL_TIMEOUT_MS, DEFAULT_TIMEOUT_MS)
+    this.now = opts.now ?? Date.now
+  }
+
+  /** Enqueue a request and return its id + a promise that resolves when a face answers
+   *  or the timeout fires (default-deny). The caller (fleet handler) awaits `decision`
+   *  and MUST call `cancel(id)` if its transport dies before the promise settles. */
+  request(input: ApprovalRequestInput): { id: string; decision: Promise<ApprovalDecision> } {
+    const id = `a${++this.counter}`
+    const createdMs = this.now()
+    const expiresMs = createdMs + this.timeoutMs
+    const summary = (input.summary?.trim() || firstLine(input.content) || input.tool).slice(0, 240)
+    const title = input.title?.trim() || `${input.personality} · ${input.tool}`
+    const approvers = input.approvers ?? []
+    const item: PendingApproval = { ...input, id, summary, title, approvers, createdMs, expiresMs }
+    let resolve!: (d: ApprovalDecision) => void
+    const decision = new Promise<ApprovalDecision>(res => {
+      resolve = res
+    })
+    const timer = setTimeout(
+      () => this.settle(id, { decision: 'deny', reason: 'approval timed out (default-deny)' }, { via: 'timeout' }),
+      this.timeoutMs,
+    )
+    ;(timer as { unref?: () => void }).unref?.()
+    this.pending.set(id, { item, resolve, timer })
+    appendApprovalEvent(
+      this.logDir,
+      {
+        ev: 'approval-request',
+        id,
+        personality: input.personality,
+        runtime: input.runtime,
+        kind: input.kind,
+        tool: input.tool,
+        summary,
+        created: createdMs,
+        expires: expiresMs,
+        approvers: approvers.join(',') || undefined,
+      },
+      { env: this.env, nowMs: createdMs },
+    )
+    return { id, decision }
+  }
+
+  /** All pending requests, oldest first (GET /fleet/v1/approvals + `iapeer approvals`). */
+  list(): PendingApproval[] {
+    return [...this.pending.values()].map(e => e.item).sort((a, b) => a.createdMs - b.createdMs)
+  }
+
+  /** One pending request by id (GET /fleet/v1/approvals/<id> — full content). */
+  get(id: string): PendingApproval | undefined {
+    return this.pending.get(id)?.item
+  }
+
+  /** Answer a request from a face. Returns false iff the id is unknown (already resolved,
+   *  expired, or never existed) — the caller reports 404. */
+  resolve(id: string, decision: ApprovalDecision, meta: ResolveMeta = {}): boolean {
+    if (!this.pending.has(id)) return false
+    this.settle(id, decision, meta)
+    return true
+  }
+
+  /** Requester transport died before an answer — settle default-deny + drop from the
+   *  queue so it does not linger (the asking hook is gone; the tool call is aborted). */
+  cancel(id: string, reason = 'requester disconnected'): boolean {
+    if (!this.pending.has(id)) return false
+    this.settle(id, { decision: 'deny', reason }, { via: 'disconnect' })
+    return true
+  }
+
+  /** Pending count (badge/metrics). */
+  size(): number {
+    return this.pending.size
+  }
+
+  private settle(id: string, decision: ApprovalDecision, meta: ResolveMeta): void {
+    const entry = this.pending.get(id)
+    if (!entry) return
+    clearTimeout(entry.timer)
+    this.pending.delete(id)
+    const nowMs = this.now()
+    appendApprovalEvent(
+      this.logDir,
+      {
+        ev: 'approval-resolved',
+        id,
+        personality: entry.item.personality,
+        runtime: entry.item.runtime,
+        decision: decision.decision,
+        reason: decision.reason,
+        by: meta.by,
+        via: meta.via,
+        latencyMs: nowMs - entry.item.createdMs,
+      },
+      { env: this.env, nowMs },
+    )
+    entry.resolve(decision)
+  }
+}