@phnx-labs/agents-cli 1.22.4 → 1.22.5

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. */

package/dist/lib/model-tiers.js

@@ -1,11 +1,27 @@
 import { getModelCatalog } from './models.js';
 import { getModelPricing } from './pricing/index.js';
+import { resolveTierOverride } from './model-tier-overrides.js';
 /** The four cross-harness cost tiers, cheapest -> most capable. */
 export const MODEL_TIERS = ['cheap', 'default', 'best', 'ultra'];
 /** True if `s` is one of the four tier tokens (not a concrete model id). */
 export function isTierToken(s) {
     return !!s && MODEL_TIERS.includes(s);
 }
+/**
+ * Curated tier ladders for harnesses the auto-ranker can't order from names/price
+ * (subscription harnesses with no price signal). Each rung is `[tier, matcher]` in
+ * cheap -> best order; the newest catalog id matching each rung fills that tier,
+ * missing tiers clamp. Extend this table rather than adding per-harness branches.
+ */
+const CURATED_LADDERS = {
+    // Kimi: K2.7 Highspeed < K2.7 Coding < K3 (the 1M-context default; k3-256k folds
+    // into K3). No ultra. The name heuristic can't tell K3 > K2.7, so curate it.
+    kimi: [
+        { tier: 'cheap', match: /highspeed/i },
+        { tier: 'default', match: /for-coding(?!.*highspeed)/i },
+        { tier: 'best', match: /(^|[-/])k3\b/i }, // K3 family incl. k3-256k; the plain id represents it
+    ],
+};
 // --- single-model harnesses: the tier is reasoning effort, not a model ---------
 const TIER_EFFORT = {
     cheap: 'low',
@@ -169,29 +185,100 @@ function rankCatalog(agent, models) {
 function rungIndexFor(tierIndex, n) {
     return n >= 4 ? Math.round((tierIndex / 3) * (n - 1)) : Math.min(tierIndex, n - 1);
 }
+/** Bucket an ordered (cheap -> dear) rung list onto the four tiers, clamping when < 4. */
+function bucketRungs(rungs) {
+    const n = rungs.length;
+    const map = {};
+    if (n === 0) {
+        // Fail-safe: no catalog -> every tier null, caller drops the --model flag.
+        for (const t of MODEL_TIERS)
+            map[t] = { tier: t, model: null };
+        return map;
+    }
+    // A tier that shares the rung of the tier below has no distinct rung -> mark clamped.
+    for (let i = 0; i < MODEL_TIERS.length; i++) {
+        const t = MODEL_TIERS[i];
+        const idx = rungIndexFor(i, n);
+        const shared = i > 0 && rungIndexFor(i - 1, n) === idx;
+        map[t] = shared
+            ? { tier: t, model: rungs[idx].id, clampedFrom: MODEL_TIERS[i - 1], note: `no distinct ${t} rung; using ${MODEL_TIERS[i - 1]}`, source: 'auto' }
+            : { tier: t, model: rungs[idx].id, source: 'auto' };
+    }
+    return map;
+}
+/** Build a tier map from a curated ladder against a catalog (newest match per rung). */
+function tierizeFromLadder(ladder, models) {
+    const usable = models.filter((m) => !PSEUDO.test(m.id));
+    const rungs = [];
+    for (const rung of ladder) {
+        const matches = usable.filter((m) => rung.match.test(m.id));
+        if (matches.length === 0)
+            continue;
+        // Prefer a plain id over a context-size variant (k3 over k3-256k) -- the
+        // variant folds into the rung but the plain model represents it -- then newest.
+        const plain = matches.filter((m) => !/-\d+[km]\b/i.test(m.id));
+        const pool = plain.length ? plain : matches;
+        rungs.push({ id: pool.reduce((a, b) => (newer(b.id, a.id) > 0 ? b : a)).id });
+    }
+    const map = bucketRungs(rungs);
+    for (const t of MODEL_TIERS)
+        if (map[t].model)
+            map[t].source = 'curated';
+    return map;
+}
 /**
- * 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 function resolveTierMap(agent, version) {
-    // Droid: curated credit-multiplier map (no live catalog).
+    let base;
+    let catalogIds;
     if (agent === 'droid') {
-        return {
-            cheap: { tier: 'cheap', model: DROID_TIERS.cheap, note: 'Droid Core 0.55x' },
-            default: { tier: 'default', model: DROID_TIERS.default, note: 'Droid Core 0.6x' },
-            best: { tier: 'best', model: DROID_TIERS.best, note: '2x' },
-            ultra: { tier: 'ultra', model: DROID_TIERS.ultra, clampedFrom: 'best', note: 'capped at 2x (4x models excluded)' },
+        // Droid: curated credit-multiplier map (no live catalog to validate against).
+        base = {
+            cheap: { tier: 'cheap', model: DROID_TIERS.cheap, note: 'Droid Core 0.55x', source: 'curated' },
+            default: { tier: 'default', model: DROID_TIERS.default, note: 'Droid Core 0.6x', source: 'curated' },
+            best: { tier: 'best', model: DROID_TIERS.best, note: '2x', source: 'curated' },
+            ultra: { tier: 'ultra', model: DROID_TIERS.ultra, clampedFrom: 'best', note: 'capped at 2x (4x excluded)', source: 'curated' },
         };
+        catalogIds = null;
     }
-    const catalog = getModelCatalog(agent, version);
-    return tierizeModels(agent, catalog?.models ?? []);
+    else {
+        const catalog = getModelCatalog(agent, version);
+        const models = catalog?.models ?? [];
+        const ladder = CURATED_LADDERS[agent];
+        base = ladder ? tierizeFromLadder(ladder, models) : tierizeModels(agent, models);
+        catalogIds = catalog ? new Set(models.map((m) => m.id)) : null;
+    }
+    const overrides = resolveTierOverride(agent, version);
+    return applyTierOverrides(overrides, `${agent}@${version}`, catalogIds, base);
+}
+/**
+ * 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 function applyTierOverrides(overrides, label, catalogIds, base) {
+    if (Object.keys(overrides).length === 0)
+        return base;
+    const out = { ...base };
+    for (const t of MODEL_TIERS) {
+        const id = overrides[t];
+        if (!id)
+            continue;
+        if (!catalogIds || catalogIds.has(id)) {
+            out[t] = { tier: t, model: id, source: 'override' };
+        }
+        else {
+            out[t] = { ...base[t], note: `override "${id}" not shipped by ${label}; kept the ${base[t].source ?? 'auto'} pick`, source: base[t].source ?? 'auto' };
+        }
+    }
+    return out;
 }
 /**
- * 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.
+ * 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 function tierizeModels(agent, models) {
     const rungs = rankCatalog(agent, models);
@@ -200,28 +287,10 @@ export function tierizeModels(agent, models) {
         const only = rungs[0].id;
         const map = {};
         for (const t of MODEL_TIERS)
-            map[t] = { tier: t, model: only, effort: TIER_EFFORT[t], note: 'single model — tier maps to reasoning effort' };
-        return map;
-    }
-    const n = rungs.length;
-    const map = {};
-    if (n === 0) {
-        // Fail-safe: no catalog -> every tier null, caller drops the --model flag.
-        for (const t of MODEL_TIERS)
-            map[t] = { tier: t, model: null };
+            map[t] = { tier: t, model: only, effort: TIER_EFFORT[t], note: 'single model — tier maps to reasoning effort', source: 'auto' };
         return map;
     }
-    // Map each tier onto a rung; a tier that shares the rung of the tier below it
-    // has no distinct rung of its own, so mark it clamped for an honest display.
-    for (let i = 0; i < MODEL_TIERS.length; i++) {
-        const t = MODEL_TIERS[i];
-        const idx = rungIndexFor(i, n);
-        const shared = i > 0 && rungIndexFor(i - 1, n) === idx;
-        map[t] = shared
-            ? { tier: t, model: rungs[idx].id, clampedFrom: MODEL_TIERS[i - 1], note: `no distinct ${t} rung; using ${MODEL_TIERS[i - 1]}` }
-            : { tier: t, model: rungs[idx].id };
-    }
-    return map;
+    return bucketRungs(rungs);
 }
 /** Resolve one tier for an (agent, version). Null model => caller drops the flag. */
 export function resolveTier(agent, version, tier) {

package/dist/lib/models.d.ts

@@ -60,6 +60,22 @@ export interface ModelSource {
  * Returns null if nothing usable is found.
  */
 export declare function locateModelSource(agent: AgentId, version: string): ModelSource | null;
+/**
+ * Extract Claude's model catalog from its bundle/binary.
+ *
+ * Bundle/binary contains:
+ *   - alias map: {opus:"claude-opus-4-7",sonnet:"claude-sonnet-4-6",haiku:"..."}
+ *   - per-cloud maps: {firstParty:"claude-opus-4-5-...",bedrock:"...",vertex:"...",...}
+ *   - constants: {OPUS_ID:"...",OPUS_NAME:"...",SONNET_ID:"...",...}
+ */
+/**
+ * Drop a bare `claude-<family>-<major>` (e.g. `claude-opus-4`) when a more specific
+ * sibling (`claude-opus-4-8`) is present. The bare form is only ever an internal
+ * `.includes("claude-opus-4")` prefix-check string in the binary, not a submittable
+ * id (issue #1892); a bare id with no sibling (e.g. `claude-sonnet-5`) is a real
+ * current model and is kept.
+ */
+export declare function dropBareLegacyIds(ids: string[]): string[];
 /**
  * Parse `grok models` stdout into a catalog. Exported for unit tests.
  *

package/dist/lib/models.js

@@ -21,7 +21,7 @@ const CACHE_PATH = getModelsCachePath();
  * Bump when the extractor logic changes shape in an incompatible way so cached
  * catalogs from older agents-cli builds are re-extracted.
  */
-const CACHE_SCHEMA_VERSION = 3;
+const CACHE_SCHEMA_VERSION = 4;
 /**
  * How long a cached 0-model extraction is trusted before we retry it. Bounds
  * the self-healing window for a transient failure (mid-install, a broken
@@ -310,6 +310,19 @@ function extractStrings(filePath, minLen = 6) {
  *   - per-cloud maps: {firstParty:"claude-opus-4-5-...",bedrock:"...",vertex:"...",...}
  *   - constants: {OPUS_ID:"...",OPUS_NAME:"...",SONNET_ID:"...",...}
  */
+/**
+ * Drop a bare `claude-<family>-<major>` (e.g. `claude-opus-4`) when a more specific
+ * sibling (`claude-opus-4-8`) is present. The bare form is only ever an internal
+ * `.includes("claude-opus-4")` prefix-check string in the binary, not a submittable
+ * id (issue #1892); a bare id with no sibling (e.g. `claude-sonnet-5`) is a real
+ * current model and is kept.
+ */
+export function dropBareLegacyIds(ids) {
+    return ids.filter((id) => {
+        const bareMajor = /^claude-[a-z]+-\d+$/.test(id);
+        return !(bareMajor && ids.some((o) => o !== id && o.startsWith(`${id}-`)));
+    });
+}
 function extractClaudeCatalog(text) {
     const aliases = {};
     const aliasMapMatch = text.match(/\{opus:"(claude-[^"]+)",sonnet:"(claude-[^"]+)",haiku:"(claude-[^"]+)"\}/);
@@ -380,8 +393,9 @@ function extractClaudeCatalog(text) {
         let sm;
         while ((sm = idRe.exec(text)) !== null)
             scanned.add(sm[0]);
-        if (scanned.size >= 2)
-            models = build(scanned);
+        const filtered = dropBareLegacyIds([...scanned]);
+        if (filtered.length >= 2)
+            models = build(filtered);
     }
     return { models, aliases };
 }

package/dist/lib/secrets/index.d.ts

@@ -91,6 +91,21 @@ export declare function setKeychainBackendForTest(b: KeychainBackend | null): Ke
  * fast-path must not engage. Always false in production (`backend` is null). */
 export declare function isKeychainBackendOverridden(): boolean;
 export declare const HMAC_KEY_ITEM = "agents-cli.hmackey";
+interface HmacKeyRecord {
+    v: number;
+    /** 64 hex chars — the raw HMAC-SHA256 key. */
+    k: string;
+    /** True once the one-time re-key has moved every cleartext-named item. */
+    migrated: boolean;
+    /** Old cleartext services whose hashed copies are verified but whose
+     * originals are not yet deleted (crash-resume list; deletes are silent). */
+    pendingDeletes?: string[];
+    /** True once this record has been re-stored no-ACL to heal a hmackey item that
+     * an OLD helper (pre the metadata/hmackey no-ACL migration fix) re-stamped with
+     * a biometry ACL. Set on the first read that heals it, so the heal runs exactly
+     * once per machine and never churns the keychain afterward. */
+    healedNoAcl?: boolean;
+}
 /** Force hashed service names on with a fixed key (test only). Pass null to
  * restore lazy production resolution. Composes with setKeychainBackendForTest
  * so unit tests exercise the exact transform production uses. */
@@ -106,6 +121,20 @@ export declare function withRawKeychainServiceNames<T>(fn: () => T): T;
  * the re-key migration and tests; runtime callers go through the primitives,
  * which apply this transparently. */
 export declare function hashedServiceName(item: string, key: Buffer): string;
+/**
+ * Heal a `hmackey` item that an OLD helper (pre the metadata/hmackey no-ACL
+ * migration fix) re-stamped with a biometry ACL. Such an item makes EVERY hashed
+ * keychain lookup pop the generic "Agents CLI needs to authenticate" sheet,
+ * because the HMAC key is read before every hashed name resolves. The migration
+ * fix stopped the re-stamping but never un-stamped an already-damaged item, and
+ * nothing else re-stores it once hashing is already active — so it prompts forever.
+ *
+ * This re-stores the record no-ACL exactly once per machine (guarded by
+ * `healedNoAcl`), turning every future read silent. The read that produced `rec`
+ * has already happened (and already prompted if it was ACL'd); this only writes.
+ * Returns true if it healed. Exported for tests. No-op when already healed.
+ */
+export declare function healHmacKeyNoAclOnce(rec: HmacKeyRecord): boolean;
 /**
  * The storage-layer service name for `item`: hashed when hashing is active,
  * the item itself otherwise. For callers that mix helper-enumerated