@phnx-labs/agents-cli 1.22.4 → 1.22.6

package/dist/lib/crabbox/cli.js

@@ -12,7 +12,7 @@
  * from a secrets bundle when one is configured (see `crabboxEnv`).
  */
 import { spawn, spawnSync } from 'child_process';
-import { readAndResolveBundleEnv, isHeadlessSecretsContext, listBundles, bundleExists } from '../secrets/bundles.js';
+import { readAndResolveBundleEnv, listBundles, bundleExists } from '../secrets/bundles.js';
 import { readMeta, writeMeta } from '../state.js';
 /** Locate the crabbox binary, or throw an actionable error. */
 export function findCrabbox() {
@@ -73,10 +73,14 @@ function resolveTailscaleBundleMemo() {
  * and the single-key subset read (`keys: [ts.key]`) is rejected by
  * `canCacheResolvedEnv` for broker auto-cache — so without this memo a
  * non-broker-held tailscale bundle re-read the keychain on EVERY call (and,
- * pre-guard, could pop a Touch ID sheet each time). One read per process,
- * success or failure (a failed read memoizes as undefined: the catch below
- * already degrades to a public-network lease, retrying mid-process only
- * repeats the same failure).
+ * pre-guard, could pop a Touch ID sheet each time). The read is always
+ * `agentOnly: true` (broker-only, SEC-13): tailscale is opt-in plumbing, a
+ * `--lease` run is headless by contract, and even an interactive `--lease`
+ * invocation must never pop an unwatched Touch ID sheet for this best-effort
+ * read — a locked bundle degrades silently to a public-network lease via the
+ * catch below. One read per process, success or failure (a failed read
+ * memoizes as undefined: the catch below already degrades to a public-network
+ * lease, retrying mid-process only repeats the same failure).
  */
 let tailscaleValueMemo;
 function resolveTailscaleKeyValueMemo(ts) {
@@ -86,7 +90,7 @@ function resolveTailscaleKeyValueMemo(ts) {
             const { env } = readAndResolveBundleEnv(ts.name, {
                 caller: 'agents run --lease (crabbox tailscale)',
                 keys: [ts.key],
-                agentOnly: isHeadlessSecretsContext(),
+                agentOnly: true,
             });
             value = env[ts.key];
         }
@@ -102,6 +106,7 @@ export function resetCrabboxSecretsMemosForTest() {
     tailscaleBundleMemo = undefined;
     tailscaleValueMemo = undefined;
     leaseBundleMemo = undefined;
+    leaseEnvMemo = undefined;
 }
 /**
  * The secrets bundle to feed crabbox, resolved in priority order:
@@ -150,6 +155,59 @@ function resolveLeaseBundleMemo() {
         leaseBundleMemo = { value: resolveLeaseBundle() };
     return leaseBundleMemo.value;
 }
+/**
+ * Process-lifetime memo for the RESOLVED provider-token env, resolved ONCE up
+ * front. `crabboxEnv` is called on every `crabboxWaitReady` poll iteration
+ * (crabboxWaitReady → crabboxFind → crabboxList → crabboxEnv), so without this
+ * memo the lease-token keychain read re-ran every ~5s of the ready wait — the
+ * per-poll storm this fix exists to kill. The read is now `agentOnly: true`
+ * (SEC-13: a `--lease` run is headless by contract and must never pop an
+ * unwatched Touch ID sheet). A locked `hold`/`always` bundle makes that read
+ * THROW the actionable "unlock <name>" message; we memoize the thrown error too
+ * and re-raise it on every subsequent call, so the failure surfaces loud ONCE
+ * up front (crabboxWarmup / the first crabboxList, before any poll loop) and the
+ * loop never re-issues the read. A `never`/no-ACL or broker-held bundle resolves
+ * silently. `undefined` when no lease bundle is configured (crabbox uses its own
+ * `crabbox login`). The memo (success OR failure) is cleared per test by
+ * resetCrabboxSecretsMemosForTest.
+ */
+let leaseEnvMemo;
+function resolveLeaseEnvMemo(explicitBundle) {
+    if (!leaseEnvMemo) {
+        const resolved = explicitBundle
+            ? { name: explicitBundle }
+            : resolveLeaseBundleMemo();
+        if (!resolved) {
+            leaseEnvMemo = {};
+        }
+        else {
+            try {
+                // Auto-detected bundle → inject ONLY the provider token key(s) (least
+                // privilege; an unrelated bundle can't leak its other secrets into crabbox).
+                // An explicitly-named bundle (env/config or `opts.secretsBundle`) injects
+                // whole — the user chose it. Same resolver `agents secrets exec` uses.
+                const { env } = readAndResolveBundleEnv(resolved.name, {
+                    caller: 'agents run --lease (crabbox)',
+                    keys: resolved.keys,
+                    // --lease is headless by contract and a locked bundle must fail loud with
+                    // an unlock hint, NEVER pop a Touch ID sheet — the read cannot be answered
+                    // in a background lease (SEC-13).
+                    agentOnly: true,
+                });
+                leaseEnvMemo = { env };
+            }
+            catch (e) {
+                leaseEnvMemo = {
+                    error: new Error(`Could not load secrets bundle "${resolved.name}" for crabbox: ${e.message}. ` +
+                        `Fix the bundle (agents secrets view ${resolved.name}) or unset lease.secretsBundle to use crabbox's own login.`),
+                };
+            }
+        }
+    }
+    if (leaseEnvMemo.error)
+        throw leaseEnvMemo.error;
+    return leaseEnvMemo.env;
+}
 /** Persist `lease.secretsBundle` in agents config so `--lease` needs no env var. */
 export function setLeaseSecretsBundle(name) {
     const meta = readMeta();
@@ -159,30 +217,14 @@ export function setLeaseSecretsBundle(name) {
 /** Build the child env for crabbox, injecting a secrets bundle when configured. */
 export function crabboxEnv(opts) {
     const out = { ...process.env };
-    const resolved = opts.secretsBundle
-        ? { name: opts.secretsBundle }
-        : resolveLeaseBundleMemo();
-    if (resolved) {
-        try {
-            // Auto-detected bundle → inject ONLY the provider token key(s) (least
-            // privilege; an unrelated bundle can't leak its other secrets into crabbox).
-            // An explicitly-named bundle (env/config or `opts.secretsBundle`) injects
-            // whole — the user chose it. Same resolver `agents secrets exec` uses.
-            const { env } = readAndResolveBundleEnv(resolved.name, {
-                caller: 'agents run --lease (crabbox)',
-                keys: resolved.keys,
-                // --lease is headless by contract and crabboxEnv is called several times
-                // per run (list/wait/spawn/stop) — resolve broker-only so a keychain bundle
-                // can't pop repeated unwatched Touch ID sheets mid-lease.
-                agentOnly: isHeadlessSecretsContext(),
-            });
-            Object.assign(out, env);
-        }
-        catch (e) {
-            throw new Error(`Could not load secrets bundle "${resolved.name}" for crabbox: ${e.message}. ` +
-                `Fix the bundle (agents secrets view ${resolved.name}) or unset lease.secretsBundle to use crabbox's own login.`);
-        }
-    }
+    // The lease provider-token read is resolved ONCE up front and memoized (env or
+    // thrown error) for the process — crabboxEnv runs on every crabboxWaitReady
+    // poll, so re-reading here was the per-poll storm. A locked bundle re-raises
+    // the memoized "unlock <name>" error every call, so the failure surfaces loud
+    // on the first crabboxEnv (before any poll loop) and never re-issues the read.
+    const leaseEnv = resolveLeaseEnvMemo(opts.secretsBundle);
+    if (leaseEnv)
+        Object.assign(out, leaseEnv);
     // Tailscale plumbing (F5): inject CRABBOX_TAILSCALE_AUTH_KEY from a bundle that
     // declares a tailscale auth key, when the ambient env doesn't already set one.
     // Best-effort and opt-in — a missing/unreadable tailscale bundle never fails a

package/dist/lib/event-stream.d.ts

@@ -20,6 +20,9 @@ export interface UnifiedQuery {
     agent?: string;
     /** Only events stamped with this session id (payload `sessionId`, the provenance floor). */
     sessionId?: string;
+    /** Only events carrying this bundle name in their payload (e.g. secrets events).
+     * Combined with `sessionId`, answers "which session read this secrets bundle". */
+    bundle?: string;
     caller?: string;
     command?: string;
     module?: string;

package/dist/lib/event-stream.js

@@ -31,6 +31,8 @@ function matches(r, q) {
         return false;
     if (q.sessionId && r.sessionId !== q.sessionId)
         return false;
+    if (q.bundle && r.bundle !== q.bundle)
+        return false;
     if (q.caller && r.caller !== q.caller)
         return false;
     if (q.command && r.command !== q.command &&
@@ -47,6 +49,8 @@ function matches(r, q) {
  * result (each source is fetched up to `limit`, so the top-N is exact).
  */
 export function readUnifiedEvents(q = {}) {
+    // `bundle` is filtered inside query()'s scan (before its limit cutoff) so a
+    // matching-bundle record older than the newest-`limit` window is not dropped.
     const ops = query({
         startDate: q.startDate,
         endDate: q.endDate,
@@ -57,6 +61,7 @@ export function readUnifiedEvents(q = {}) {
         caller: q.caller,
         command: q.command,
         module: q.module,
+        bundle: q.bundle,
         limit: q.limit,
     });
     if (q.includeActivity === false)

package/dist/lib/events.d.ts

@@ -213,6 +213,8 @@ export declare function query(options: {
     caller?: string;
     command?: string;
     module?: string;
+    /** Only events carrying this bundle name in their payload (e.g. secrets events). */
+    bundle?: string;
     limit?: number;
 }): EventRecord[];
 /**

package/dist/lib/events.js

@@ -729,7 +729,7 @@ export function maybeRotate() {
  * @returns Array of event records
  */
 export function query(options) {
-    const { startDate, endDate = new Date(), eventTypes, level, agent, sessionId, caller, command, module, limit } = options;
+    const { startDate, endDate = new Date(), eventTypes, level, agent, sessionId, caller, command, module, bundle, limit } = options;
     const results = [];
     if (!fs.existsSync(eventsDir()))
         return results;
@@ -783,6 +783,11 @@ export function query(options) {
                     continue;
                 if (module && record.module !== module)
                     continue;
+                // Filter bundle in the SAME scan, before the limit cutoff — a post-filter
+                // on the already-capped result silently drops matching-bundle records that
+                // fell outside the newest-`limit` window (a data-loss bug for an audit query).
+                if (bundle && record.bundle !== bundle)
+                    continue;
                 results.push(record);
                 if (limit && results.length >= limit) {
                     return results;

package/dist/lib/feed.d.ts

@@ -218,7 +218,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# 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";
+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 declared block (`agents feed post --blocked`) is the agent explicitly\n        # saying it is stuck. Unlike a question/notification/approval block -- which\n        # tracks an in-flight harness prompt that a lifecycle event resolves -- a\n        # declared block stays open until it is actually ANSWERED. So while it is\n        # still UNANSWERED, Stop/SessionEnd/PostToolUse must never silently drop it:\n        # otherwise the needs-you record vanishes the moment the agent parks the block\n        # and its turn ends -- exactly when the owner still needs to see and answer it.\n        # Once it IS answered (an answered marker exists), it clears like any other\n        # block by falling through below -- which frees that marker too, so a later\n        # `--blocked` in the same session is not falsely locked as already-answered\n        # (recordAnswer creates the marker with O_EXCL).\n        try:\n            with open(target) as existing_file:\n                existing = json.load(existing_file)\n            answered = os.path.exists(os.path.join(answered_dir, f\"{block_id}.json\"))\n            if existing.get(\"kind\") == \"declared\" and not answered:\n                return\n        except Exception:\n            pass\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;

package/dist/lib/feed.js

@@ -442,6 +442,25 @@ def main():
     hook_event = payload.get("hook_event_name", "PreToolUse")
 
     if hook_event in CLEAR_EVENTS:
+        # A declared block (\`agents feed post --blocked\`) is the agent explicitly
+        # saying it is stuck. Unlike a question/notification/approval block -- which
+        # tracks an in-flight harness prompt that a lifecycle event resolves -- a
+        # declared block stays open until it is actually ANSWERED. So while it is
+        # still UNANSWERED, Stop/SessionEnd/PostToolUse must never silently drop it:
+        # otherwise the needs-you record vanishes the moment the agent parks the block
+        # and its turn ends -- exactly when the owner still needs to see and answer it.
+        # Once it IS answered (an answered marker exists), it clears like any other
+        # block by falling through below -- which frees that marker too, so a later
+        # \`--blocked\` in the same session is not falsely locked as already-answered
+        # (recordAnswer creates the marker with O_EXCL).
+        try:
+            with open(target) as existing_file:
+                existing = json.load(existing_file)
+            answered = os.path.exists(os.path.join(answered_dir, f"{block_id}.json"))
+            if existing.get("kind") == "declared" and not answered:
+                return
+        except Exception:
+            pass
         # 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

package/dist/lib/model-tier-overrides.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Human overrides for the cost-tier -> model mapping.
+ *
+ * The auto-ranking (lib/model-tiers.ts) is a best guess; for subscription harnesses
+ * with no price signal (Kimi, Cursor) it can be wrong. A user pins the right model
+ * per tier with `agents models tier set <agent[@version]> <tier> <model>`, which
+ * writes here — the user never hand-edits the file.
+ *
+ * Stored under agents.yaml, same selector shape as run.defaults:
+ *
+ *   model:
+ *     tiers:
+ *       "kimi:*":                 # applies to every installed kimi
+ *         best: kimi-code/k3
+ *         default: kimi-code/kimi-for-coding
+ *       "kimi:0.19.2":            # a specific version wins over the wildcard
+ *         best: kimi-code/k3-256k
+ *
+ * Resolution (most-specific-first): `<agent>:<version>` beats `<agent>:*` beats the
+ * auto-ranking. resolveTierMap (model-tiers.ts) applies the result and falls back to
+ * auto for any tier whose overridden id isn't in that version's catalog.
+ */
+import type { AgentId } from './types.js';
+import { type ModelTier } from './model-tiers.js';
+export type TierOverrideMap = Partial<Record<ModelTier, string>>;
+export interface TierOverrideEntry {
+    selector: string;
+    tiers: TierOverrideMap;
+}
+/** Validate a tier token, throwing a friendly error otherwise. */
+export declare function parseTier(input: string): ModelTier;
+/**
+ * The effective tier overrides for an (agent, version): the `<agent>:*` wildcard
+ * merged under the exact `<agent>:<version>` selector (exact wins per-tier).
+ */
+export declare function resolveTierOverrideFrom(all: Record<string, unknown>, agent: AgentId, version?: string | null): TierOverrideMap;
+export declare function resolveTierOverride(agent: AgentId, version?: string | null): TierOverrideMap;
+/** Every configured override entry, sorted by selector (for `agents models tier list`). */
+export declare function listTierOverrides(): TierOverrideEntry[];
+/** Pin `tier -> model` for a selector. Writes agents.yaml. */
+export declare function setTierOverride(selectorInput: string, tierInput: string, model: string): TierOverrideEntry;
+/** Clear one tier (or all tiers when `tierInput` is omitted) for a selector. Returns true if anything changed. */
+export declare function clearTierOverride(selectorInput: string, tierInput?: string): boolean;

package/dist/lib/model-tier-overrides.js

@@ -0,0 +1,97 @@
+import { readMeta, updateMeta } from './state.js';
+import { parseRunDefaultSelector } from './run-defaults.js';
+import { MODEL_TIERS } from './model-tiers.js';
+function isTier(value) {
+    return MODEL_TIERS.includes(value);
+}
+/** Validate a tier token, throwing a friendly error otherwise. */
+export function parseTier(input) {
+    const t = input.trim().toLowerCase();
+    if (!isTier(t)) {
+        throw new Error(`Invalid tier '${input}'. Use one of: ${MODEL_TIERS.join(', ')}.`);
+    }
+    return t;
+}
+/** Normalize a stored selector's tier map, dropping unknown/empty entries. */
+function normalize(raw) {
+    const out = {};
+    if (!raw || typeof raw !== 'object')
+        return out;
+    for (const [k, v] of Object.entries(raw)) {
+        if (isTier(k) && typeof v === 'string' && v.trim())
+            out[k] = v.trim();
+    }
+    return out;
+}
+function sortedSelectors(map) {
+    return Object.fromEntries(Object.entries(map).sort(([a], [b]) => a.localeCompare(b)));
+}
+/**
+ * The effective tier overrides for an (agent, version): the `<agent>:*` wildcard
+ * merged under the exact `<agent>:<version>` selector (exact wins per-tier).
+ */
+export function resolveTierOverrideFrom(all, agent, version) {
+    const merged = { ...normalize(all[`${agent}:*`]) };
+    if (version) {
+        for (const [tier, model] of Object.entries(normalize(all[`${agent}:${version}`]))) {
+            merged[tier] = model;
+        }
+    }
+    return merged;
+}
+export function resolveTierOverride(agent, version) {
+    return resolveTierOverrideFrom(readMeta().model?.tiers ?? {}, agent, version);
+}
+/** Every configured override entry, sorted by selector (for `agents models tier list`). */
+export function listTierOverrides() {
+    const all = readMeta().model?.tiers ?? {};
+    return Object.entries(all)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([selector, tiers]) => ({ selector, tiers: normalize(tiers) }));
+}
+/** Pin `tier -> model` for a selector. Writes agents.yaml. */
+export function setTierOverride(selectorInput, tierInput, model) {
+    const parsed = parseRunDefaultSelector(selectorInput);
+    const tier = parseTier(tierInput);
+    const id = model.trim();
+    if (!id)
+        throw new Error('A model id is required.');
+    updateMeta((meta) => {
+        const modelCfg = { ...(meta.model ?? {}) };
+        const tiers = { ...(modelCfg.tiers ?? {}) };
+        tiers[parsed.selector] = { ...(tiers[parsed.selector] ?? {}), [tier]: id };
+        modelCfg.tiers = sortedSelectors(tiers);
+        return { ...meta, model: modelCfg };
+    });
+    return { selector: parsed.selector, tiers: normalize(readMeta().model?.tiers?.[parsed.selector]) };
+}
+/** Clear one tier (or all tiers when `tierInput` is omitted) for a selector. Returns true if anything changed. */
+export function clearTierOverride(selectorInput, tierInput) {
+    const parsed = parseRunDefaultSelector(selectorInput);
+    const tier = tierInput ? parseTier(tierInput) : null;
+    let changed = false;
+    updateMeta((meta) => {
+        if (!meta.model?.tiers?.[parsed.selector])
+            return meta;
+        const model = { ...meta.model };
+        const tiers = { ...(model.tiers ?? {}) };
+        if (tier) {
+            const entry = { ...tiers[parsed.selector] };
+            if (entry[tier] !== undefined) {
+                delete entry[tier];
+                changed = true;
+            }
+            if (Object.keys(entry).length === 0)
+                delete tiers[parsed.selector];
+            else
+                tiers[parsed.selector] = entry;
+        }
+        else {
+            delete tiers[parsed.selector];
+            changed = true;
+        }
+        model.tiers = tiers;
+        return { ...meta, model };
+    });
+    return changed;
+}

package/dist/lib/model-tiers.d.ts

@@ -36,18 +36,24 @@ export interface TierResolution {
     clampedFrom?: ModelTier;
     /** Human note (e.g. why it clamped, or that it is a curated/subscription mapping). */
     note?: string;
+    /** Where the model came from: 'auto' ranking, a user 'override', or a 'curated' ladder. */
+    source?: 'auto' | 'override' | 'curated';
 }
 /**
- * Resolve all four tiers for an (agent, version). The map is what `agents models`
- * prints and what `resolveTier` indexes into.
+ * Resolve all four tiers for an (agent, version) -- what `agents models` prints and
+ * `resolveTier` indexes. Precedence: user override -> curated ladder / auto-ranking.
  */
 export declare function resolveTierMap(agent: AgentId, version: string): Record<ModelTier, TierResolution>;
 /**
- * Map a harness's catalog models onto the four tiers. Pure (no catalog lookup)
- * so it is directly testable with synthetic inputs. Ranks the models, collapses
- * variants, buckets onto cheap/default/best/ultra, and clamps absent tiers down
- * to the nearest lower one. A single-model harness maps the tiers to reasoning
- * effort instead of models.
+ * Apply user overrides on top of the auto/curated map. Pure (takes the resolved
+ * override map, no config lookup) so it is directly testable. An overridden id is
+ * used only when the version actually ships it (or when there is no catalog to
+ * check, e.g. Droid); otherwise the tier keeps its base value with a note.
+ */
+export declare function applyTierOverrides(overrides: Partial<Record<ModelTier, string>>, label: string, catalogIds: Set<string> | null, base: Record<ModelTier, TierResolution>): Record<ModelTier, TierResolution>;
+/**
+ * Map a harness's catalog models onto the four tiers. Pure (no catalog lookup) so
+ * it is directly testable. A single-model harness maps the tiers to reasoning effort.
  */
 export declare function tierizeModels(agent: AgentId, models: ModelInfo[]): Record<ModelTier, TierResolution>;
 /** Resolve one tier for an (agent, version). Null model => caller drops the flag. */