@phnx-labs/agents-cli 1.20.74 → 1.20.77

package/dist/lib/feed-post.js

@@ -0,0 +1,204 @@
+/**
+ * Agent status posts — deliberate progress messages into the activity stream.
+ *
+ * Surface: `agents feed post <text>` (agent-callable; humans watch via
+ * `agents feed` / `agents activity` / `agents events --module activity`).
+ *
+ * Identity is automatic: session id, agent, cwd, launch/pid/tmux provenance
+ * are resolved from the process environment and the per-pid launch registry
+ * (`lib/session/pid-registry.ts`). The agent only authors free-form text —
+ * no domain-specific flags (tickets, URLs, tracks).
+ *
+ * Storage: append-only activity log as a `status.posted` milestone. Does NOT
+ * open a feed block (blocks remain "needs you" state only).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { spawnSync } from 'child_process';
+import { appendActivityEvent, } from './activity.js';
+import { machineId } from './machine-id.js';
+import { isValidMailboxId } from './mailbox.js';
+import { listPidSessionEntries, readPidSessionEntry, } from './session/pid-registry.js';
+/** Soft cap so a runaway agent can't flood the activity lane with essays. */
+export const STATUS_POST_MAX_CHARS = 500;
+/**
+ * Resolve who is posting. Order:
+ *  1. Explicit --session flag
+ *  2. Env: AGENT_SESSION_ID / AGENTS_SESSION_ID / basename(AGENTS_MAILBOX_DIR)
+ *  3. Env AGENT_LAUNCH_ID → match in pid registry
+ *  4. Walk parent PIDs from startPid (default process.ppid) through by-pid registry
+ */
+export function resolvePostIdentity(input) {
+    const env = input.env ?? process.env;
+    const readEntry = input.readEntry ?? readPidSessionEntry;
+    const listEntries = input.listEntries ?? listPidSessionEntries;
+    const getParent = input.getParentPid ?? parentPidOf;
+    const envSession = firstValidId([
+        input.sessionId,
+        env.AGENT_SESSION_ID,
+        env.AGENTS_SESSION_ID,
+        mailboxIdFromEnv(env),
+    ]);
+    const launchId = env.AGENT_LAUNCH_ID?.trim() || undefined;
+    let registry;
+    if (launchId) {
+        registry = listEntries().find((e) => e.launchId === launchId);
+    }
+    if (!registry) {
+        const start = input.startPid ?? (typeof process.ppid === 'number' ? process.ppid : undefined);
+        if (start && start > 1) {
+            registry = walkPidRegistry(start, getParent, readEntry);
+        }
+    }
+    // Prefer env session (explicit + managed run), fill gaps from registry.
+    const sessionId = envSession ?? registry?.sessionId;
+    if (!sessionId || !isValidMailboxId(sessionId))
+        return undefined;
+    const mailboxFromEnv = mailboxIdFromEnv(env);
+    const mailboxId = mailboxFromEnv && isValidMailboxId(mailboxFromEnv)
+        ? mailboxFromEnv
+        : sessionId;
+    return {
+        sessionId,
+        mailboxId,
+        host: machineIdFromEnv(env),
+        runtime: env.AGENTS_RUNTIME?.trim() || 'headless',
+        agent: env.AGENTS_AGENT_NAME?.trim()
+            || registry?.agent
+            || detectAgentKind(env),
+        cwd: input.cwd
+            ?? (env.AGENTS_CWD?.trim() || registry?.cwd || process.cwd()),
+        pid: registry?.pid,
+        launchId: launchId || registry?.launchId,
+        terminalId: env.AGENT_TERMINAL_ID?.trim() || registry?.terminalId,
+        tmuxPane: env.TMUX_PANE?.trim() || registry?.tmuxPane,
+    };
+}
+function firstValidId(candidates) {
+    for (const raw of candidates) {
+        const id = (raw ?? '').trim();
+        if (id && isValidMailboxId(id))
+            return id;
+    }
+    return undefined;
+}
+function mailboxIdFromEnv(env) {
+    const dir = env.AGENTS_MAILBOX_DIR?.trim();
+    if (!dir)
+        return undefined;
+    const base = path.basename(dir.replace(/[/\\]+$/, ''));
+    return base || undefined;
+}
+/** Walk up to 16 ancestors looking for a by-pid registry entry with a session. */
+export function walkPidRegistry(startPid, getParent, readEntry) {
+    let pid = startPid;
+    const seen = new Set();
+    let firstHit;
+    for (let i = 0; i < 16 && pid && pid > 1 && !seen.has(pid); i++) {
+        seen.add(pid);
+        const entry = readEntry(pid);
+        if (entry) {
+            if (entry.sessionId && isValidMailboxId(entry.sessionId))
+                return entry;
+            if (!firstHit)
+                firstHit = entry;
+        }
+        pid = getParent(pid);
+    }
+    // Entry without sessionId still carries agent/cwd/launchId — usable when
+    // session id comes from env.
+    return firstHit;
+}
+/** Best-effort parent pid of `pid` (Linux /proc, else `ps`). */
+export function parentPidOf(pid) {
+    if (!Number.isInteger(pid) || pid <= 1)
+        return undefined;
+    if (process.platform === 'linux') {
+        try {
+            const status = fs.readFileSync(`/proc/${pid}/status`, 'utf8');
+            const m = status.match(/^PPid:\s*(\d+)/m);
+            if (m) {
+                const pp = Number(m[1]);
+                return Number.isInteger(pp) && pp > 0 ? pp : undefined;
+            }
+        }
+        catch {
+            /* fall through */
+        }
+    }
+    try {
+        const r = spawnSync('ps', ['-o', 'ppid=', '-p', String(pid)], {
+            encoding: 'utf8',
+            timeout: 1000,
+        });
+        if (r.status === 0) {
+            const pp = Number((r.stdout || '').trim());
+            return Number.isInteger(pp) && pp > 0 ? pp : undefined;
+        }
+    }
+    catch {
+        /* best-effort */
+    }
+    return undefined;
+}
+export function normalizeStatusText(text) {
+    const collapsed = text.replace(/\s+/g, ' ').trim();
+    if (!collapsed)
+        return '';
+    if (collapsed.length <= STATUS_POST_MAX_CHARS)
+        return collapsed;
+    return `${collapsed.slice(0, STATUS_POST_MAX_CHARS - 1)}…`;
+}
+/**
+ * Append a `status.posted` milestone for the calling agent.
+ * Throws if text is empty or session identity cannot be resolved.
+ */
+export function postFeedStatus(input) {
+    const detail = normalizeStatusText(input.text);
+    if (!detail) {
+        throw new Error('Status text is empty. Usage: agents feed post "what just happened"');
+    }
+    const identity = resolvePostIdentity(input);
+    if (!identity) {
+        throw new Error('No session id. Run from an agents-cli session '
+            + '(AGENT_SESSION_ID / AGENTS_MAILBOX_DIR / pid registry), or pass --session <id>.');
+    }
+    const event = {
+        ts: input.ts ?? new Date().toISOString(),
+        event: 'status.posted',
+        sessionId: identity.sessionId,
+        mailboxId: identity.mailboxId,
+        host: identity.host,
+        runtime: identity.runtime,
+        cwd: identity.cwd,
+        agent: identity.agent,
+        tool: 'feed.post',
+        detail,
+        ...(identity.pid !== undefined ? { pid: identity.pid } : {}),
+        ...(identity.launchId ? { launchId: identity.launchId } : {}),
+        ...(identity.terminalId ? { terminalId: identity.terminalId } : {}),
+        ...(identity.tmuxPane ? { tmuxPane: identity.tmuxPane } : {}),
+    };
+    appendActivityEvent(event, input.activityRoot);
+    return {
+        event: {
+            v: 1,
+            tier: 'milestone',
+            ...event,
+        },
+    };
+}
+function machineIdFromEnv(env) {
+    const raw = env.AGENTS_SYNC_MACHINE_ID || undefined;
+    if (raw) {
+        return raw.split('.')[0].trim().toLowerCase().replace(/[^a-z0-9_-]/g, '-') || 'unknown';
+    }
+    return machineId();
+}
+function detectAgentKind(env) {
+    if (env.CLAUDECODE === '1')
+        return 'claude';
+    if (env.CODEX_CI || env.CODEX_HOME)
+        return 'codex';
+    return 'agent';
+}

package/dist/lib/feed.d.ts

@@ -172,7 +172,7 @@ export declare function removeBlock(blockId: string, root?: string): boolean;
  * Embedded so it ships with the compiled CLI and can be installed to the
  * CLI-writable user hooks dir without a separate file in the npm tarball.
  */
-export declare const FEED_PUBLISH_HOOK_SCRIPT = "#!/usr/bin/env python3\n\"\"\"Publish and clear open-block records for `agents feed`.\n\nThe manifest invokes this script for top-level AskUserQuestion calls, waiting\nnotifications, question answers, and session lifecycle events. One atomic file\nper session means a new block replaces the previous block. Answer/resume/stop\nevents remove it so `agents feed` only lists decisions that are still open.\n\nSub-agent gate: when the PreToolUse payload carries `agent_type`, this is a\nTask/Agent subagent -- skip. Only the top-level agent publishes. Verified on\nClaude Code 2.1.170 (2026-07).\n\nFail-open: ANY error is swallowed so a feed hiccup never blocks a tool call.\n\"\"\"\nimport os\nimport sys\nimport json\nimport re\nimport socket\nimport tempfile\nfrom datetime import datetime, timezone\n\nWAITING_NOTIFICATION_TYPES = {\n    \"permission_prompt\",\n    \"idle_prompt\",\n    \"elicitation_dialog\",\n}\nCLEAR_EVENTS = {\n    \"PostToolUse\",\n    \"Stop\",\n    \"SessionEnd\",\n}\n\n\ndef read_json(path):\n    try:\n        with open(path) as f:\n            return json.load(f)\n    except Exception:\n        return None\n\n\ndef write_json(path, value):\n    dir_name = os.path.dirname(path)\n    os.makedirs(dir_name, exist_ok=True)\n    fd, tmp = tempfile.mkstemp(dir=dir_name, suffix=\".tmp\")\n    try:\n        with os.fdopen(fd, \"w\") as f:\n            json.dump(value, f, indent=2)\n        os.replace(tmp, path)\n    except Exception:\n        try:\n            os.unlink(tmp)\n        except Exception:\n            pass\n\n\ndef main():\n    raw = sys.stdin.read()\n    try:\n        payload = json.loads(raw) if raw.strip() else {}\n    except Exception:\n        return\n\n    # Sub-agent gate.\n    if payload.get(\"agent_type\"):\n        return\n\n    session_id = payload.get(\"session_id\", \"\")\n    if not session_id:\n        return\n\n    safe_session_id = re.sub(r\"[^A-Za-z0-9._-]\", \"-\", session_id)\n    block_id = f\"block-{safe_session_id}\"\n    home = os.environ.get(\"HOME\") or os.path.expanduser(\"~\")\n    feed_dir = os.path.join(home, \".agents\", \".history\", \"feed\")\n    answered_dir = os.path.join(feed_dir, \"answered\")\n    asks_dir = os.path.join(feed_dir, \"asks\")\n    target = os.path.join(feed_dir, f\"{block_id}.json\")\n    hook_event = payload.get(\"hook_event_name\", \"PreToolUse\")\n\n    if hook_event in CLEAR_EVENTS:\n        try:\n            os.unlink(target)\n        except FileNotFoundError:\n            pass\n        except Exception:\n            pass\n        # Also clear the answered marker so a future question for this session\n        # is not permanently locked.\n        try:\n            os.unlink(os.path.join(answered_dir, f\"{block_id}.json\"))\n        except FileNotFoundError:\n            pass\n        except Exception:\n            pass\n        return\n\n    # Terminal answers (human typed in the TUI) record an answered marker and\n    # remove the block file so the feed stops showing it within one poll cycle.\n    # The marker stays behind so a concurrent surface cannot double-answer.\n    if hook_event == \"UserPromptSubmit\":\n        os.makedirs(answered_dir, exist_ok=True)\n        marker = os.path.join(answered_dir, f\"{block_id}.json\")\n        try:\n            fd = os.open(marker, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o644)\n            record = {\n                \"answeredAt\": datetime.now(timezone.utc).isoformat(),\n                \"answeredFrom\": \"terminal\",\n            }\n            with os.fdopen(fd, \"w\") as f:\n                json.dump(record, f, indent=2)\n        except FileExistsError:\n            pass\n        except Exception:\n            pass\n        # Remove the visible block so the feed drops the answered question.\n        try:\n            os.unlink(target)\n        except FileNotFoundError:\n            pass\n        except Exception:\n            pass\n        return\n\n    notification_type = None\n    if hook_event == \"Notification\":\n        notification_type = payload.get(\"notification_type\", \"\")\n        if notification_type not in WAITING_NOTIFICATION_TYPES:\n            return\n        # Claude emits a generic permission notification after presenting an\n        # AskUserQuestion. Keep the structured questions and options already\n        # published for this session instead of replacing them with that less\n        # useful notification text.\n        try:\n            with open(target) as existing_file:\n                existing = json.load(existing_file)\n            if existing.get(\"kind\") == \"question\":\n                return\n        except Exception:\n            pass\n        message = payload.get(\"message\", \"\")\n        if not message:\n            return\n        normalized_questions = [{\n            \"text\": message,\n            \"header\": payload.get(\"title\") or notification_type.replace(\"_\", \" \").title(),\n            \"multiSelect\": False,\n        }]\n        kind = \"notification\"\n    else:\n        tool_input = payload.get(\"tool_input\", {})\n        questions = tool_input.get(\"questions\", [])\n        if not questions:\n            return\n        normalized_questions = []\n        for q in questions:\n            if not isinstance(q, dict):\n                continue\n            question = {\n                \"text\": q.get(\"question\", q.get(\"header\", \"\")),\n                \"header\": q.get(\"header\"),\n                \"multiSelect\": q.get(\"multiSelect\", False),\n            }\n            raw_opts = q.get(\"options\", [])\n            if raw_opts:\n                question[\"options\"] = [\n                    {\"label\": o.get(\"label\", \"\"), \"description\": o.get(\"description\")}\n                    for o in raw_opts\n                    if isinstance(o, dict)\n                ]\n            normalized_questions.append(question)\n        if not normalized_questions:\n            return\n        kind = \"question\"\n\n    # Identity from env (set by agents-cli at spawn).\n    mailbox_id = os.path.basename(\n        os.environ.get(\"AGENTS_MAILBOX_DIR\", \"\").rstrip(\"/\")\n    ) or session_id\n\n    now_iso = datetime.now(timezone.utc).isoformat()\n    stats_path = os.path.join(asks_dir, f\"{safe_session_id}.json\")\n    stats = read_json(stats_path) or {}\n    recent = stats.get(\"recentAskTimestamps\") if isinstance(stats, dict) else []\n    if not isinstance(recent, list):\n        recent = []\n    recent.append(now_iso)\n    # Keep enough history for rolling one-hour needy detection without unbounded\n    # per-session files. The TypeScript reader applies the exact time window.\n    recent = recent[-200:]\n    write_json(stats_path, {\n        \"sessionId\": session_id,\n        \"mailboxId\": mailbox_id,\n        \"firstAskAt\": stats.get(\"firstAskAt\") or now_iso,\n        \"lastAskAt\": now_iso,\n        \"totalAskCount\": int(stats.get(\"totalAskCount\") or 0) + 1,\n        \"recentAskTimestamps\": recent,\n    })\n\n    hostname = os.environ.get(\"AGENTS_SYNC_MACHINE_ID\") or socket.gethostname()\n    host = hostname.split(\".\")[0].strip().lower()\n    host = re.sub(r\"[^a-z0-9_-]\", \"-\", host) or \"unknown\"\n\n    runtime = os.environ.get(\"AGENTS_RUNTIME\", \"headless\")\n\n    block = {\n        \"blockId\": block_id,\n        \"sessionId\": session_id,\n        \"mailboxId\": mailbox_id,\n        \"host\": host,\n        \"runtime\": runtime,\n        \"ts\": now_iso,\n        \"questions\": normalized_questions,\n        \"kind\": kind,\n    }\n    if notification_type:\n        block[\"notificationType\"] = notification_type\n\n    # Optional multi-operator control metadata passed by the agent in the\n    # AskUserQuestion tool_input. Defaults keep the existing behavior.\n    controls = payload.get(\"tool_input\", {}) if hook_event != \"Notification\" else {}\n    block_class = controls.get(\"blockClass\") if isinstance(controls, dict) else None\n    if block_class in (\"approval\", \"decision\"):\n        block[\"blockClass\"] = block_class\n    consequence = controls.get(\"consequence\") if isinstance(controls, dict) else None\n    if consequence:\n        block[\"consequence\"] = consequence\n    allowed = controls.get(\"allowedOperators\") if isinstance(controls, dict) else None\n    if isinstance(allowed, list):\n        block[\"allowedOperators\"] = [str(a) for a in allowed]\n    timeout = controls.get(\"timeoutMinutes\") if isinstance(controls, dict) else None\n    if isinstance(timeout, (int, float)) and timeout > 0:\n        block[\"timeoutMinutes\"] = int(timeout)\n    safe_default = controls.get(\"safeDefault\") if isinstance(controls, dict) else None\n    if isinstance(safe_default, str):\n        block[\"safeDefault\"] = safe_default\n    cost = controls.get(\"costOfDelay\") if isinstance(controls, dict) else None\n    if cost in (\"low\", \"medium\", \"high\"):\n        block[\"costOfDelay\"] = cost\n\n    # Publishing a new question clears any stale answered marker from the\n    # previous question in this session.\n    try:\n        os.unlink(os.path.join(answered_dir, f\"{block_id}.json\"))\n    except FileNotFoundError:\n        pass\n    except Exception:\n        pass\n\n    # Python's expanduser() ignores HOME on Windows, while agents-cli honors a\n    # HOME override on every platform. Use the same anchor so hooks and the CLI\n    # always read/write one feed store (including temp-home and sandbox runs).\n    os.makedirs(feed_dir, exist_ok=True)\n\n    fd, tmp = tempfile.mkstemp(dir=feed_dir, suffix=\".tmp\")\n    try:\n        with os.fdopen(fd, \"w\") as f:\n            json.dump(block, f, indent=2)\n        os.replace(tmp, target)\n    except Exception:\n        try:\n            os.unlink(tmp)\n        except Exception:\n            pass\n\n\nif __name__ == \"__main__\":\n    try:\n        main()\n    except Exception:\n        pass  # fail open\n";
+export declare const FEED_PUBLISH_HOOK_SCRIPT = "#!/usr/bin/env python3\n\"\"\"Publish and clear open-block records for `agents feed`.\n\nThe manifest invokes this script for top-level AskUserQuestion calls, waiting\nnotifications, question answers, and session lifecycle events. One atomic file\nper session means a new block replaces the previous block. Answer/resume/stop\nevents remove it so `agents feed` only lists decisions that are still open.\n\nSub-agent gate: when the PreToolUse payload carries `agent_type`, this is a\nTask/Agent subagent -- skip. Only the top-level agent publishes. Verified on\nClaude Code 2.1.170 (2026-07).\n\nFail-open: ANY error is swallowed so a feed hiccup never blocks a tool call.\n\"\"\"\nimport os\nimport sys\nimport json\nimport re\nimport socket\nimport tempfile\nfrom datetime import datetime, timezone\n\nWAITING_NOTIFICATION_TYPES = {\n    \"permission_prompt\",\n    \"idle_prompt\",\n    \"elicitation_dialog\",\n}\nCLEAR_EVENTS = {\n    \"PostToolUse\",\n    \"Stop\",\n    \"SessionEnd\",\n}\n# Codex emits a PermissionRequest event (not Claude's Notification) when it\n# blocks on an approval prompt. Claude never fires PermissionRequest, so the\n# same script handles both: PermissionRequest maps to an approval-class block\n# with a high cost-of-delay so 'agents feed --dispatch' pages it as urgent.\n\n\ndef read_json(path):\n    try:\n        with open(path) as f:\n            return json.load(f)\n    except Exception:\n        return None\n\n\ndef write_json(path, value):\n    dir_name = os.path.dirname(path)\n    os.makedirs(dir_name, exist_ok=True)\n    fd, tmp = tempfile.mkstemp(dir=dir_name, suffix=\".tmp\")\n    try:\n        with os.fdopen(fd, \"w\") as f:\n            json.dump(value, f, indent=2)\n        os.replace(tmp, path)\n    except Exception:\n        try:\n            os.unlink(tmp)\n        except Exception:\n            pass\n\n\ndef main():\n    raw = sys.stdin.read()\n    try:\n        payload = json.loads(raw) if raw.strip() else {}\n    except Exception:\n        return\n\n    # Sub-agent gate.\n    if payload.get(\"agent_type\"):\n        return\n\n    session_id = payload.get(\"session_id\", \"\")\n    if not session_id:\n        return\n\n    safe_session_id = re.sub(r\"[^A-Za-z0-9._-]\", \"-\", session_id)\n    block_id = f\"block-{safe_session_id}\"\n    home = os.environ.get(\"HOME\") or os.path.expanduser(\"~\")\n    feed_dir = os.path.join(home, \".agents\", \".history\", \"feed\")\n    answered_dir = os.path.join(feed_dir, \"answered\")\n    asks_dir = os.path.join(feed_dir, \"asks\")\n    target = os.path.join(feed_dir, f\"{block_id}.json\")\n    hook_event = payload.get(\"hook_event_name\", \"PreToolUse\")\n\n    if hook_event in CLEAR_EVENTS:\n        # A matcher-less PostToolUse clear (registered for Codex so an approved\n        # tool clears its approval card) must NOT wipe an open AskUserQuestion\n        # while an unrelated tool runs mid-question -- those are cleared only by\n        # the AskUserQuestion-matched PostToolUse. So on PostToolUse, keep a\n        # 'question' block; approval/notification blocks clear once the tool runs.\n        if hook_event == \"PostToolUse\":\n            try:\n                with open(target) as existing_file:\n                    existing = json.load(existing_file)\n                if existing.get(\"kind\") == \"question\" and payload.get(\"tool_name\") != \"AskUserQuestion\":\n                    return\n            except Exception:\n                pass\n        try:\n            os.unlink(target)\n        except FileNotFoundError:\n            pass\n        except Exception:\n            pass\n        # Also clear the answered marker so a future question for this session\n        # is not permanently locked.\n        try:\n            os.unlink(os.path.join(answered_dir, f\"{block_id}.json\"))\n        except FileNotFoundError:\n            pass\n        except Exception:\n            pass\n        return\n\n    # Terminal answers (human typed in the TUI) record an answered marker and\n    # remove the block file so the feed stops showing it within one poll cycle.\n    # The marker stays behind so a concurrent surface cannot double-answer.\n    if hook_event == \"UserPromptSubmit\":\n        os.makedirs(answered_dir, exist_ok=True)\n        marker = os.path.join(answered_dir, f\"{block_id}.json\")\n        try:\n            fd = os.open(marker, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o644)\n            record = {\n                \"answeredAt\": datetime.now(timezone.utc).isoformat(),\n                \"answeredFrom\": \"terminal\",\n            }\n            with os.fdopen(fd, \"w\") as f:\n                json.dump(record, f, indent=2)\n        except FileExistsError:\n            pass\n        except Exception:\n            pass\n        # Remove the visible block so the feed drops the answered question.\n        try:\n            os.unlink(target)\n        except FileNotFoundError:\n            pass\n        except Exception:\n            pass\n        return\n\n    notification_type = None\n    codex_approval = False\n    if hook_event == \"Notification\":\n        notification_type = payload.get(\"notification_type\", \"\")\n        if notification_type not in WAITING_NOTIFICATION_TYPES:\n            return\n        # Claude emits a generic permission notification after presenting an\n        # AskUserQuestion. Keep the structured questions and options already\n        # published for this session instead of replacing them with that less\n        # useful notification text.\n        try:\n            with open(target) as existing_file:\n                existing = json.load(existing_file)\n            if existing.get(\"kind\") == \"question\":\n                return\n        except Exception:\n            pass\n        message = payload.get(\"message\", \"\")\n        if not message:\n            return\n        normalized_questions = [{\n            \"text\": message,\n            \"header\": payload.get(\"title\") or notification_type.replace(\"_\", \" \").title(),\n            \"multiSelect\": False,\n        }]\n        kind = \"notification\"\n    elif hook_event == \"PermissionRequest\":\n        # Codex approval prompt. The payload mirrors PreToolUse (tool_name,\n        # tool_input) but carries no questions -- Codex is asking to run a tool,\n        # not asking the operator a multiple-choice question. Publish it as a\n        # notification-kind approval block naming the tool so the feed and the\n        # phone notifier can surface it, and so the Factory extension can bridge\n        # it to a VS Code notification.\n        tool_name = payload.get(\"tool_name\") or \"a tool\"\n        tool_input = payload.get(\"tool_input\", {})\n        command = \"\"\n        if isinstance(tool_input, dict):\n            command = (\n                tool_input.get(\"command\")\n                or tool_input.get(\"cmd\")\n                or tool_input.get(\"path\")\n                or \"\"\n            )\n            if isinstance(command, list):\n                command = \" \".join(str(c) for c in command)\n        detail = f\": {command}\" if command else \"\"\n        normalized_questions = [{\n            \"text\": f\"Codex needs approval to run {tool_name}{detail}\",\n            \"header\": \"Approval needed\",\n            \"multiSelect\": False,\n        }]\n        kind = \"notification\"\n        notification_type = \"permission_prompt\"\n        codex_approval = True\n    else:\n        tool_input = payload.get(\"tool_input\", {})\n        questions = tool_input.get(\"questions\", [])\n        if not questions:\n            return\n        normalized_questions = []\n        for q in questions:\n            if not isinstance(q, dict):\n                continue\n            question = {\n                \"text\": q.get(\"question\", q.get(\"header\", \"\")),\n                \"header\": q.get(\"header\"),\n                \"multiSelect\": q.get(\"multiSelect\", False),\n            }\n            raw_opts = q.get(\"options\", [])\n            if raw_opts:\n                question[\"options\"] = [\n                    {\"label\": o.get(\"label\", \"\"), \"description\": o.get(\"description\")}\n                    for o in raw_opts\n                    if isinstance(o, dict)\n                ]\n            normalized_questions.append(question)\n        if not normalized_questions:\n            return\n        kind = \"question\"\n\n    # Identity from env (set by agents-cli at spawn).\n    mailbox_id = os.path.basename(\n        os.environ.get(\"AGENTS_MAILBOX_DIR\", \"\").rstrip(\"/\")\n    ) or session_id\n\n    now_iso = datetime.now(timezone.utc).isoformat()\n    stats_path = os.path.join(asks_dir, f\"{safe_session_id}.json\")\n    stats = read_json(stats_path) or {}\n    recent = stats.get(\"recentAskTimestamps\") if isinstance(stats, dict) else []\n    if not isinstance(recent, list):\n        recent = []\n    recent.append(now_iso)\n    # Keep enough history for rolling one-hour needy detection without unbounded\n    # per-session files. The TypeScript reader applies the exact time window.\n    recent = recent[-200:]\n    write_json(stats_path, {\n        \"sessionId\": session_id,\n        \"mailboxId\": mailbox_id,\n        \"firstAskAt\": stats.get(\"firstAskAt\") or now_iso,\n        \"lastAskAt\": now_iso,\n        \"totalAskCount\": int(stats.get(\"totalAskCount\") or 0) + 1,\n        \"recentAskTimestamps\": recent,\n    })\n\n    hostname = os.environ.get(\"AGENTS_SYNC_MACHINE_ID\") or socket.gethostname()\n    host = hostname.split(\".\")[0].strip().lower()\n    host = re.sub(r\"[^a-z0-9_-]\", \"-\", host) or \"unknown\"\n\n    runtime = os.environ.get(\"AGENTS_RUNTIME\", \"headless\")\n\n    block = {\n        \"blockId\": block_id,\n        \"sessionId\": session_id,\n        \"mailboxId\": mailbox_id,\n        \"host\": host,\n        \"runtime\": runtime,\n        \"ts\": now_iso,\n        \"questions\": normalized_questions,\n        \"kind\": kind,\n    }\n    if notification_type:\n        block[\"notificationType\"] = notification_type\n\n    # A Codex PermissionRequest is a real approval gate: mark it approval-class\n    # with a high cost-of-delay so 'agents feed --dispatch' classifies it urgent\n    # (isPhoneUrgent gates on costOfDelay >= phoneNotifyThreshold, default\n    # 'medium') and pages the phone. A plain 'deny' is the safe default.\n    if codex_approval:\n        block[\"blockClass\"] = \"approval\"\n        block[\"costOfDelay\"] = \"high\"\n        block[\"safeDefault\"] = \"deny\"\n\n    # Optional multi-operator control metadata passed by the agent in the\n    # AskUserQuestion tool_input. Defaults keep the existing behavior. A Codex\n    # PermissionRequest carries tool ARGS in tool_input (command/path), not\n    # operator controls, so it is excluded here -- its class/cost is stamped\n    # above from codex_approval.\n    controls = payload.get(\"tool_input\", {}) if hook_event not in (\"Notification\", \"PermissionRequest\") else {}\n    block_class = controls.get(\"blockClass\") if isinstance(controls, dict) else None\n    if block_class in (\"approval\", \"decision\"):\n        block[\"blockClass\"] = block_class\n    consequence = controls.get(\"consequence\") if isinstance(controls, dict) else None\n    if consequence:\n        block[\"consequence\"] = consequence\n    allowed = controls.get(\"allowedOperators\") if isinstance(controls, dict) else None\n    if isinstance(allowed, list):\n        block[\"allowedOperators\"] = [str(a) for a in allowed]\n    timeout = controls.get(\"timeoutMinutes\") if isinstance(controls, dict) else None\n    if isinstance(timeout, (int, float)) and timeout > 0:\n        block[\"timeoutMinutes\"] = int(timeout)\n    safe_default = controls.get(\"safeDefault\") if isinstance(controls, dict) else None\n    if isinstance(safe_default, str):\n        block[\"safeDefault\"] = safe_default\n    cost = controls.get(\"costOfDelay\") if isinstance(controls, dict) else None\n    if cost in (\"low\", \"medium\", \"high\"):\n        block[\"costOfDelay\"] = cost\n\n    # Publishing a new question clears any stale answered marker from the\n    # previous question in this session.\n    try:\n        os.unlink(os.path.join(answered_dir, f\"{block_id}.json\"))\n    except FileNotFoundError:\n        pass\n    except Exception:\n        pass\n\n    # Python's expanduser() ignores HOME on Windows, while agents-cli honors a\n    # HOME override on every platform. Use the same anchor so hooks and the CLI\n    # always read/write one feed store (including temp-home and sandbox runs).\n    os.makedirs(feed_dir, exist_ok=True)\n\n    fd, tmp = tempfile.mkstemp(dir=feed_dir, suffix=\".tmp\")\n    try:\n        with os.fdopen(fd, \"w\") as f:\n            json.dump(block, f, indent=2)\n        os.replace(tmp, target)\n    except Exception:\n        try:\n            os.unlink(tmp)\n        except Exception:\n            pass\n\n\nif __name__ == \"__main__\":\n    try:\n        main()\n    except Exception:\n        pass  # fail open\n";
 /** Manifest entry for the feed-publish hook, matching the ManifestHook shape. */
 export declare const FEED_PUBLISH_HOOK_MANIFEST: {
     name: string;
@@ -188,6 +188,12 @@ export declare const FEED_NOTIFICATION_HOOK_MANIFEST: {
     script: string;
     timeout: number;
 };
+export declare const FEED_PERMISSION_HOOK_MANIFEST: {
+    name: string;
+    events: string[];
+    script: string;
+    timeout: number;
+};
 export declare const FEED_ANSWERED_HOOK_MANIFEST: {
     name: string;
     events: string[];

package/dist/lib/feed.js

@@ -348,6 +348,10 @@ CLEAR_EVENTS = {
     "Stop",
     "SessionEnd",
 }
+# Codex emits a PermissionRequest event (not Claude's Notification) when it
+# blocks on an approval prompt. Claude never fires PermissionRequest, so the
+# same script handles both: PermissionRequest maps to an approval-class block
+# with a high cost-of-delay so 'agents feed --dispatch' pages it as urgent.
 
 
 def read_json(path):
@@ -398,6 +402,19 @@ def main():
     hook_event = payload.get("hook_event_name", "PreToolUse")
 
     if hook_event in CLEAR_EVENTS:
+        # A matcher-less PostToolUse clear (registered for Codex so an approved
+        # tool clears its approval card) must NOT wipe an open AskUserQuestion
+        # while an unrelated tool runs mid-question -- those are cleared only by
+        # the AskUserQuestion-matched PostToolUse. So on PostToolUse, keep a
+        # 'question' block; approval/notification blocks clear once the tool runs.
+        if hook_event == "PostToolUse":
+            try:
+                with open(target) as existing_file:
+                    existing = json.load(existing_file)
+                if existing.get("kind") == "question" and payload.get("tool_name") != "AskUserQuestion":
+                    return
+            except Exception:
+                pass
         try:
             os.unlink(target)
         except FileNotFoundError:
@@ -442,6 +459,7 @@ def main():
         return
 
     notification_type = None
+    codex_approval = False
     if hook_event == "Notification":
         notification_type = payload.get("notification_type", "")
         if notification_type not in WAITING_NOTIFICATION_TYPES:
@@ -466,6 +484,34 @@ def main():
             "multiSelect": False,
         }]
         kind = "notification"
+    elif hook_event == "PermissionRequest":
+        # Codex approval prompt. The payload mirrors PreToolUse (tool_name,
+        # tool_input) but carries no questions -- Codex is asking to run a tool,
+        # not asking the operator a multiple-choice question. Publish it as a
+        # notification-kind approval block naming the tool so the feed and the
+        # phone notifier can surface it, and so the Factory extension can bridge
+        # it to a VS Code notification.
+        tool_name = payload.get("tool_name") or "a tool"
+        tool_input = payload.get("tool_input", {})
+        command = ""
+        if isinstance(tool_input, dict):
+            command = (
+                tool_input.get("command")
+                or tool_input.get("cmd")
+                or tool_input.get("path")
+                or ""
+            )
+            if isinstance(command, list):
+                command = " ".join(str(c) for c in command)
+        detail = f": {command}" if command else ""
+        normalized_questions = [{
+            "text": f"Codex needs approval to run {tool_name}{detail}",
+            "header": "Approval needed",
+            "multiSelect": False,
+        }]
+        kind = "notification"
+        notification_type = "permission_prompt"
+        codex_approval = True
     else:
         tool_input = payload.get("tool_input", {})
         questions = tool_input.get("questions", [])
@@ -535,9 +581,21 @@ def main():
     if notification_type:
         block["notificationType"] = notification_type
 
+    # A Codex PermissionRequest is a real approval gate: mark it approval-class
+    # with a high cost-of-delay so 'agents feed --dispatch' classifies it urgent
+    # (isPhoneUrgent gates on costOfDelay >= phoneNotifyThreshold, default
+    # 'medium') and pages the phone. A plain 'deny' is the safe default.
+    if codex_approval:
+        block["blockClass"] = "approval"
+        block["costOfDelay"] = "high"
+        block["safeDefault"] = "deny"
+
     # Optional multi-operator control metadata passed by the agent in the
-    # AskUserQuestion tool_input. Defaults keep the existing behavior.
-    controls = payload.get("tool_input", {}) if hook_event != "Notification" else {}
+    # AskUserQuestion tool_input. Defaults keep the existing behavior. A Codex
+    # PermissionRequest carries tool ARGS in tool_input (command/path), not
+    # operator controls, so it is excluded here -- its class/cost is stamped
+    # above from codex_approval.
+    controls = payload.get("tool_input", {}) if hook_event not in ("Notification", "PermissionRequest") else {}
     block_class = controls.get("blockClass") if isinstance(controls, dict) else None
     if block_class in ("approval", "decision"):
         block["blockClass"] = block_class
@@ -604,6 +662,15 @@ export const FEED_NOTIFICATION_HOOK_MANIFEST = {
     script: '10-feed-publish.py',
     timeout: 5,
 };
+// Codex fires PermissionRequest (not Claude's Notification) when it blocks on an
+// approval prompt. The same script handles it, publishing a high-cost approval
+// block so the feed dispatch pages the phone. PermissionRequest has no matcher.
+export const FEED_PERMISSION_HOOK_MANIFEST = {
+    name: 'feed-publish-permission',
+    events: ['PermissionRequest'],
+    script: '10-feed-publish.py',
+    timeout: 5,
+};
 export const FEED_ANSWERED_HOOK_MANIFEST = {
     name: 'feed-clear-answered',
     events: ['PostToolUse'],
@@ -644,28 +711,51 @@ export function ensureFeedPublishHook(userAgentsDir = getUserAgentsDir()) {
         }
         const desiredHooks = {
             'feed-publish': {
-                agents: ['claude'],
+                agents: ['claude', 'codex'],
                 events: ['PreToolUse'],
                 matcher: 'AskUserQuestion',
                 script: '10-feed-publish.py',
                 timeout: 5,
             },
             'feed-publish-notification': {
-                agents: ['claude'],
+                agents: ['claude', 'codex'],
                 events: ['Notification'],
                 matcher: 'permission_prompt|idle_prompt|elicitation_dialog',
                 script: '10-feed-publish.py',
                 timeout: 5,
             },
+            // Codex-specific approval gate: Codex emits PermissionRequest (Claude does
+            // not), so this hook is where a blocked Codex agent surfaces to the feed.
+            'feed-publish-permission': {
+                agents: ['claude', 'codex'],
+                events: ['PermissionRequest'],
+                script: '10-feed-publish.py',
+                timeout: 5,
+            },
             'feed-clear-answered': {
-                agents: ['claude'],
+                agents: ['claude', 'codex'],
                 events: ['PostToolUse'],
                 matcher: 'AskUserQuestion',
                 script: '10-feed-publish.py',
                 timeout: 5,
             },
+            // Matcher-less PostToolUse clear: after Codex runs an approved tool, the
+            // approval card is stale, so clear it. Codex-only on purpose -- Claude
+            // never fires PermissionRequest, so it has no approval card to clear here,
+            // and a matcher-less PostToolUse for Claude would (1) re-run the script on
+            // every tool completion and (2) wipe Claude's notification-kind blocks
+            // (permission_prompt/idle_prompt/elicitation_dialog) the moment any later
+            // tool runs, instead of letting them persist to Stop/SessionEnd like they
+            // did before RUSH-2039. Registering it for codex alone keeps Claude's
+            // card lifetime exactly as it was.
+            'feed-clear-permission': {
+                agents: ['codex'],
+                events: ['PostToolUse'],
+                script: '10-feed-publish.py',
+                timeout: 5,
+            },
             'feed-clear-lifecycle': {
-                agents: ['claude'],
+                agents: ['claude', 'codex'],
                 events: ['Stop', 'UserPromptSubmit', 'SessionEnd'],
                 script: '10-feed-publish.py',
                 timeout: 5,

package/dist/lib/fleet/apply.d.ts

@@ -11,6 +11,30 @@ import type { DeviceProfile } from '../devices/registry.js';
 import type { DeviceDesired, DeviceProbe, DeviceDiff, FleetAction, FleetPlan, AuthFilePayload } from './types.js';
 /** Strip a version suffix from an agent spec: `claude@latest` -> `claude`. */
 export declare function agentIdOf(spec: string): string;
+/**
+ * The explicit pinned version of a spec, or undefined for an id-level spec.
+ * `claude@2.1.170` -> `2.1.170`; `claude`, `claude@latest`, `claude@oldest`, and
+ * `claude@all` all return undefined (the label channels install-latest / are
+ * expanded upstream, so they diff at id granularity, not per-version).
+ */
+export declare function pinnedVersion(spec: string): string | undefined;
+/** True when any spec in the roster pins an explicit version (needs a version probe). */
+export declare function rosterNeedsVersions(desired: DeviceDesired[]): boolean;
+/**
+ * Expand any `<agent>@all` spec into one pinned spec per version installed on the
+ * source, so `--agent claude@all` replicates THIS machine's exact version set.
+ * `versionsOf` returns the source's installed versions for an agent id. Every
+ * other spec passes through unchanged; the result is de-duplicated in order.
+ * Throws if `@all` names an agent with no installed versions here (nothing to
+ * replicate — a clear misconfig, not a silent no-op).
+ */
+export declare function expandAllSpecs(specs: string[], versionsOf: (id: string) => string[]): string[];
+/**
+ * Parse `agents view --json` (the all-agents array form) into a map of agent id
+ * -> installed version strings. Tolerant: returns undefined on any parse failure
+ * so a version-pinned spec falls back to id-level presence rather than crashing.
+ */
+export declare function parseInstalledVersions(stdout: string): Record<string, string[]> | undefined;
 /** Source-side auth availability, computed once from `snapshotAuth`. */
 export interface SourceAuth {
     /** Agent ids the source has a readable, propagatable credential file for. */
@@ -37,8 +61,14 @@ export interface DiffContext {
 }
 /** Pure: desired vs probed -> per-device diff + flat action list. */
 export declare function diffFleet(desired: DeviceDesired[], probes: Map<string, DeviceProbe>, ctx: DiffContext): FleetPlan;
-/** Probe one device: reachability + agents-cli version + installed agent ids. */
-export declare function probeDevice(device: DeviceProfile): DeviceProbe;
+export interface ProbeOptions {
+    /** Also fetch per-agent installed versions (one extra `agents view --json`
+     * round-trip). Enable only when the plan has a version-pinned spec. */
+    withVersions?: boolean;
+}
+/** Probe one device: reachability + agents-cli version + installed agent ids
+ * (and, when `withVersions`, the installed version strings per agent). */
+export declare function probeDevice(device: DeviceProfile, opts?: ProbeOptions): DeviceProbe;
 export interface ApplyStep {
     kind: FleetAction['kind'];
     ok: boolean;

package/dist/lib/fleet/apply.js

@@ -17,6 +17,76 @@ import { isPropagatableAgent, KEYCHAIN_BOUND_ON_MAC, buildAuthBundle, } from './
 export function agentIdOf(spec) {
     return spec.split('@')[0].trim();
 }
+/**
+ * The explicit pinned version of a spec, or undefined for an id-level spec.
+ * `claude@2.1.170` -> `2.1.170`; `claude`, `claude@latest`, `claude@oldest`, and
+ * `claude@all` all return undefined (the label channels install-latest / are
+ * expanded upstream, so they diff at id granularity, not per-version).
+ */
+export function pinnedVersion(spec) {
+    const at = spec.indexOf('@');
+    if (at < 0)
+        return undefined;
+    const v = spec.slice(at + 1).trim();
+    if (!v || v === 'latest' || v === 'oldest' || v === 'all')
+        return undefined;
+    return v;
+}
+/** True when any spec in the roster pins an explicit version (needs a version probe). */
+export function rosterNeedsVersions(desired) {
+    return desired.some((d) => d.agents.some((s) => pinnedVersion(s) !== undefined));
+}
+/**
+ * Expand any `<agent>@all` spec into one pinned spec per version installed on the
+ * source, so `--agent claude@all` replicates THIS machine's exact version set.
+ * `versionsOf` returns the source's installed versions for an agent id. Every
+ * other spec passes through unchanged; the result is de-duplicated in order.
+ * Throws if `@all` names an agent with no installed versions here (nothing to
+ * replicate — a clear misconfig, not a silent no-op).
+ */
+export function expandAllSpecs(specs, versionsOf) {
+    const out = [];
+    for (const spec of specs) {
+        const at = spec.indexOf('@');
+        const label = at >= 0 ? spec.slice(at + 1).trim() : '';
+        if (label !== 'all') {
+            out.push(spec);
+            continue;
+        }
+        const id = agentIdOf(spec);
+        const versions = versionsOf(id);
+        if (versions.length === 0) {
+            throw new Error(`--agent ${spec}: no ${id} versions installed on this machine to replicate.`);
+        }
+        for (const v of versions)
+            out.push(`${id}@${v}`);
+    }
+    return [...new Set(out)];
+}
+/**
+ * Parse `agents view --json` (the all-agents array form) into a map of agent id
+ * -> installed version strings. Tolerant: returns undefined on any parse failure
+ * so a version-pinned spec falls back to id-level presence rather than crashing.
+ */
+export function parseInstalledVersions(stdout) {
+    try {
+        const arr = JSON.parse(stdout);
+        if (!Array.isArray(arr))
+            return undefined;
+        const out = {};
+        for (const a of arr) {
+            if (a && typeof a.agent === 'string' && Array.isArray(a.versions)) {
+                out[a.agent] = a.versions
+                    .map((v) => v?.version)
+                    .filter((v) => typeof v === 'string');
+            }
+        }
+        return out;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Can we propagate `agent`'s login to a target on `targetPlatform`? False when
  * the agent has no portable file, the source can't provide it (bound / not
@@ -53,21 +123,28 @@ export function diffFleet(desired, probes, ctx) {
             else if (probe.cliVersion !== ctx.targetCliVersion) {
                 rowActions.push({ device: d.device, kind: 'upgrade-cli', detail: `agents-cli ${probe.cliVersion} -> ${ctx.targetCliVersion}` });
             }
-            // agents.
+            // agents. A version-pinned spec (`claude@2.1.170`, or an expanded
+            // `claude@all` member) is present only when that exact version is on the
+            // device; a bare/latest spec diffs at id granularity. So `--agent claude@all`
+            // installs every missing version even when some claude is already there.
             for (const spec of d.agents) {
                 const id = agentIdOf(spec);
-                if (!probe.installedAgents.includes(id)) {
-                    rowActions.push({ device: d.device, kind: 'add-agent', agent: id, detail: `install ${spec}` });
+                const want = pinnedVersion(spec);
+                const present = want !== undefined
+                    ? (probe.installedVersions?.[id]?.includes(want) ?? false)
+                    : probe.installedAgents.includes(id);
+                if (!present) {
+                    rowActions.push({ device: d.device, kind: 'add-agent', agent: id, spec, detail: `install ${spec}` });
                 }
             }
             // config.
             if (d.sync.length > 0) {
                 rowActions.push({ device: d.device, kind: 'sync-config', detail: `sync config (${d.sync.join(', ')})` });
             }
-            // login.
+            // login — per agent id, not per spec: `claude@all` names one id many times,
+            // but login propagates once per agent (its credential is version-shared).
             if (d.login === 'sync') {
-                for (const spec of d.agents) {
-                    const id = agentIdOf(spec);
+                for (const id of [...new Set(d.agents.map(agentIdOf))]) {
                     if (canPushLogin(id, probe.platform, ctx.sourceAuth)) {
                         rowActions.push({ device: d.device, kind: 'push-login', agent: id, detail: `propagate ${id} login` });
                     }
@@ -107,8 +184,9 @@ function osHint(platform) {
 function remoteEnv(platform) {
     return platform === 'windows' ? undefined : { PATH: '$HOME/.agents/.cache/shims:$HOME/.local/bin:$PATH' };
 }
-/** Probe one device: reachability + agents-cli version + installed agent ids. */
-export function probeDevice(device) {
+/** Probe one device: reachability + agents-cli version + installed agent ids
+ * (and, when `withVersions`, the installed version strings per agent). */
+export function probeDevice(device, opts) {
     let target;
     try {
         target = sshTargetFor(device);
@@ -133,12 +211,20 @@ export function probeDevice(device) {
             /* agents-cli present but doctor output unparsable — treat as no agents */
         }
     }
+    let installedVersions;
+    if (opts?.withVersions) {
+        const viewCmd = buildRemoteAgentsInvocation(['view', '--json'], undefined, hint, remoteEnv(device.platform));
+        const vres = sshExec(target, viewCmd, { timeoutMs: 30000, multiplex: true });
+        if (vres.code === 0)
+            installedVersions = parseInstalledVersions(vres.stdout);
+    }
     return {
         device: device.name,
         reachable: true,
         platform: device.platform,
         cliVersion: ready.version ?? undefined,
         installedAgents: installed,
+        installedVersions,
     };
 }
 /** Execute one device's planned actions in order. Real SSH — no mocks. */
@@ -165,9 +251,10 @@ export function reconcileDevice(row, device, ctx) {
         steps.push({ kind: cliAction.kind, ok: r.ok, detail: cliAction.detail });
         ok = ok && r.ok;
     }
-    // 2. agents.
+    // 2. agents. Every add-agent action carries the full spec (set in diffFleet);
+    // install it directly rather than re-parsing the human-readable detail string.
     for (const a of row.actions.filter((x) => x.kind === 'add-agent')) {
-        const spec = a.detail.replace(/^install\s+/, '');
+        const spec = a.spec;
         const r = sshAgents(['add', spec, '--yes']);
         steps.push({ kind: 'add-agent', ok: r.code === 0, detail: a.detail });
         ok = ok && r.code === 0;