@agfpd/iapeer 0.4.68 → 0.4.70

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 }
+}

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,200 @@
+// 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). VERIFIED LIVE (codex-cli 0.142.5, Unit 3): codex
+// fires `PreToolUse` (NOT PermissionRequest) for tool calls, with `tool_name:"Bash"` for shell exec +
+// `tool_input.command` = the full command; a PreToolUse `deny` HARD-BLOCKS the tool AND the
+// `permissionDecisionReason` reaches the model — even under `sandbox_mode=danger-full-access`
+// (permission_mode=bypassPermissions), so under the gated config the hook is the SOLE gate. `Bash`
+// confirmed live; `apply_patch` (the patch tool) per the codex hooks docs. The extra alternatives are a
+// forward-compatible superset (a future codex rename still matches) — harmless, never over-matches.
+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

@@ -1278,9 +1278,14 @@ const VERBS: ReadonlyArray<{ sig: string; desc: string }> = [
     desc: 'DARK (cutover Block 2): detach-persistent pty-supervisor PoC port; serves nothing on the live fleet (throwaway validation only)',
   },
   {
-    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: 'tray install|uninstall|render [--stream]|cmd <c> <peer>|approve <id>|deny <id> [reason]|status',
+    desc: 'the macOS menu-bar fleet dashboard (SwiftBar plugin) — first external Fleet API client; renders the approval queue (badge + Allow/Deny), 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
@@ -2537,6 +2542,23 @@ export async function runCli(argv: string[], env: NodeJS.ProcessEnv = process.en
             out(`${JSON.stringify(r.body)}\n`)
             return r.ok ? 0 : 1
           }
+          case 'approve':
+          case 'deny': {
+            // Tray click → resolve a pending approval over the unix-first fleet client (docs/17). The
+            // menu Allow/Deny items run these; the broker resolution is seen by every channel.
+            const id = positionals[1]
+            if (!id) return argErr(errOut, `usage: iapeer tray ${sub} <approval-id> [reason]`)
+            const reason = sub === 'deny' ? positionals.slice(2).join(' ') || undefined : undefined
+            let r: Awaited<ReturnType<typeof tray.trayResolveApproval>>
+            try {
+              r = await tray.trayResolveApproval(env, sub, id, reason)
+            } catch (e) {
+              errOut(`tray ${sub}: ${e instanceof Error ? e.message : String(e)}\n`)
+              return 1
+            }
+            out(`${JSON.stringify(r.body)}\n`)
+            return r.ok ? 0 : 1
+          }
           case 'install': {
             // Explicit activation verb: installs SwiftBar.app when absent
             // (owner-sanctioned) + launches, unless --plugin-only (file only).
@@ -2580,6 +2602,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):