@miller-tech/uap 1.183.1 → 1.183.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miller-tech/uap",
-  "version": "1.183.1",
+  "version": "1.183.2",
   "description": "Autonomous AI agent memory system with CLAUDE.md protocol enforcement",
   "type": "module",
   "main": "dist/index.js",
@@ -21,7 +21,7 @@
     "start": "node dist/bin/cli.js",
     "test": "vitest",
     "test:ci": "vitest run",
-    "test:enforcers": "UAP_PROXY_ENV_AUTOLOAD=0 python3 -m unittest tools.agents.tests.test_enforcement_self_protect tools.agents.tests.test_schema_diff_gate tools.agents.tests.test_stream_telemetry tools.agents.tests.test_project_telemetry_events tools.agents.tests.test_workdir_scope_enforcer tools.agents.tests.test_path_containment tools.agents.tests.test_path_normalizer_hardened tools.agents.tests.test_sandbox_tool_strip tools.agents.tests.test_proxy_env_loader tools.agents.tests.test_stream_required_tool tools.agents.tests.test_tool_call_wrapper_profiles tools.agents.tests.test_tool_convert_cache tools.agents.tests.test_doubling_break tools.agents.tests.test_error_loop_ignores_correctives tools.agents.tests.test_attractor_detection tools.agents.tests.test_client_disconnect tools.agents.tests.test_confidence_escalation tools.agents.tests.test_coordination_ban tools.agents.tests.test_coordination_early_ban tools.agents.tests.test_cycle_break_exploration tools.agents.tests.test_deferral_break tools.agents.tests.test_deliver_autoroute tools.agents.tests.test_delivery_enforcement_all_langs tools.agents.tests.test_delivery_enforcement_exemptions tools.agents.tests.test_delivery_enforcement_filepath tools.agents.tests.test_delivery_enforcement_web_and_bash tools.agents.tests.test_disconnect_watcher tools.agents.tests.test_empty_maxtokens_recovery tools.agents.tests.test_empty_tool_loop_break tools.agents.tests.test_enforcer_escape_hatches tools.agents.tests.test_error_loop_break tools.agents.tests.test_finalize_suppression tools.agents.tests.test_malformed_unclosed_think tools.agents.tests.test_mandate_beats_recon tools.agents.tests.test_mandate_deliver tools.agents.tests.test_overflow_truncate_count_tokens tools.agents.tests.test_passthrough_oauth tools.agents.tests.test_project_telemetry tools.agents.tests.test_proxy_auth_headers tools.agents.tests.test_prune_preserve_force_write tools.agents.tests.test_recon_deliver_gate tools.agents.tests.test_session_admission tools.agents.tests.test_stream_heartbeat tools.agents.tests.test_stuck_break_reattach tools.agents.tests.test_turn_count_breaker_periodic tools.agents.tests.test_upstream_chokepoint tools.agents.tests.test_vision_passthrough tools.agents.tests.test_worktree_required tools.agents.tests.test_enforcer_suite_coverage tools.agents.tests.test_validate_plan_gate tools.agents.tests.test_validate_plan_inside_project tools.agents.tests.test_anthropic_proxy_streaming tools.agents.tests.test_delivery_enforcement_worktree tools.agents.tests.test_output_token_ceilings",
+    "test:enforcers": "UAP_PROXY_ENV_AUTOLOAD=0 python3 -m unittest tools.agents.tests.test_enforcement_self_protect tools.agents.tests.test_schema_diff_gate tools.agents.tests.test_stream_telemetry tools.agents.tests.test_project_telemetry_events tools.agents.tests.test_workdir_scope_enforcer tools.agents.tests.test_path_containment tools.agents.tests.test_path_normalizer_hardened tools.agents.tests.test_sandbox_tool_strip tools.agents.tests.test_proxy_env_loader tools.agents.tests.test_stream_required_tool tools.agents.tests.test_tool_call_wrapper_profiles tools.agents.tests.test_tool_convert_cache tools.agents.tests.test_doubling_break tools.agents.tests.test_error_loop_ignores_correctives tools.agents.tests.test_attractor_detection tools.agents.tests.test_client_disconnect tools.agents.tests.test_confidence_escalation tools.agents.tests.test_coordination_ban tools.agents.tests.test_coordination_early_ban tools.agents.tests.test_cycle_break_exploration tools.agents.tests.test_deferral_break tools.agents.tests.test_deliver_autoroute tools.agents.tests.test_delivery_enforcement_all_langs tools.agents.tests.test_delivery_enforcement_exemptions tools.agents.tests.test_delivery_enforcement_filepath tools.agents.tests.test_delivery_enforcement_web_and_bash tools.agents.tests.test_disconnect_watcher tools.agents.tests.test_empty_maxtokens_recovery tools.agents.tests.test_empty_tool_loop_break tools.agents.tests.test_enforcer_escape_hatches tools.agents.tests.test_error_loop_break tools.agents.tests.test_finalize_suppression tools.agents.tests.test_malformed_unclosed_think tools.agents.tests.test_mandate_beats_recon tools.agents.tests.test_mandate_deliver tools.agents.tests.test_overflow_truncate_count_tokens tools.agents.tests.test_passthrough_oauth tools.agents.tests.test_project_telemetry tools.agents.tests.test_proxy_auth_headers tools.agents.tests.test_prune_preserve_force_write tools.agents.tests.test_recon_deliver_gate tools.agents.tests.test_session_admission tools.agents.tests.test_stream_heartbeat tools.agents.tests.test_stuck_break_reattach tools.agents.tests.test_turn_count_breaker_periodic tools.agents.tests.test_upstream_chokepoint tools.agents.tests.test_vision_passthrough tools.agents.tests.test_worktree_required tools.agents.tests.test_enforcer_suite_coverage tools.agents.tests.test_validate_plan_gate tools.agents.tests.test_validate_plan_inside_project tools.agents.tests.test_anthropic_proxy_streaming tools.agents.tests.test_delivery_enforcement_worktree tools.agents.tests.test_output_token_ceilings tools.agents.tests.test_tool_narrowing_core",
     "test:coverage": "vitest --coverage",
     "bench": "vitest --config vitest.bench.config.ts",
     "lint": "eslint src --ext .ts",

package/tools/agents/scripts/anthropic_proxy.py

@@ -5113,13 +5113,64 @@ def _tokenize_for_tool_ranking(text: str) -> set[str]:
 
 
 # Core action tools a coding agent must always retain through narrowing — losing
-# any of these strands the agent (it can read/think but not act). Names are the
-# Claude Code canonical tool names, matched case-insensitively.
+# any of these strands the agent (it can read/think but not act).
+#
+# This started as Claude Code's canonical names only, and that made the guard
+# a no-op for every client that names its tools differently. Hermes (2026-08-03)
+# sends terminal/execute_code/write_file/search_files/patch — ZERO overlap — so
+# narrowing cut 36 tools to 8, kept browser_type/clarify/cronjob and dropped
+# terminal AND write_file. The model then tried to run `ls -la` through
+# browser_type, failed on "no browser session" three times, CYCLE BREAK removed
+# browser_type leaving 6 tools, and it spent the rest of the session emitting
+# `clarify` calls that said "I've been stuck in a loop". That is the exact
+# failure the comment here already claimed to have fixed, recurring for a
+# client whose tools have other names.
+#
+# Kept as an exact-match fast path; _is_core_action_tool() below adds semantic
+# classification so an unknown client is covered without an entry here.
 _CORE_TOOL_NAMES = frozenset({
+    # Claude Code canonical
     "read", "write", "edit", "multiedit", "notebookedit",
     "bash", "glob", "grep", "ls", "applypatch", "apply_patch",
+    # Common equivalents across other clients (hermes, Forge, opencode, …)
+    "terminal", "shell", "run_command", "run_shell_command", "execute_command",
+    "execute_code", "python", "run_python",
+    "write_file", "create_file", "save_file", "new_file",
+    "edit_file", "patch", "str_replace", "str_replace_editor", "replace_in_file",
+    "read_file", "view_file", "open_file", "cat",
+    "list_dir", "list_files", "search_files", "find_files", "file_search",
 })
 
+# Phrases that identify a core ACTION capability from a tool's description, for
+# clients whose names we do not know. Deliberately require a file/command noun:
+# "type text into an element" (browser_type) must NOT read as a file write, and
+# it is better to under-match here than to pin a browser tool as core.
+_CORE_TOOL_DESC_PATTERNS = (
+    r"\b(execute|run)\b[^.]{0,40}\b(shell|bash|command|script|code)\b",
+    r"\bcommand[- ]line\b",
+    r"\b(write|create|save)\b[^.]{0,40}\bfile\b",
+    r"\b(edit|modify|patch|replace)\b[^.]{0,40}\b(file|code)\b",
+    r"\bread\b[^.]{0,40}\b(file|contents)\b",
+    r"\b(list|search|find)\b[^.]{0,40}\b(file|directory|directories)\b",
+)
+
+
+def _is_core_action_tool(name: str, description: str = "") -> bool:
+    """True when a tool is a core action tool that narrowing must never drop.
+
+    Exact name match first (cheap, and what most clients hit), then a semantic
+    read of the description so a client we have never seen still keeps its
+    ability to act. Losing shell/write is what strands an agent; everything else
+    is recoverable.
+    """
+    nm = (name or "").strip().lower()
+    if nm in _CORE_TOOL_NAMES:
+        return True
+    desc = (description or "").strip().lower()
+    if not desc:
+        return False
+    return any(re.search(p, desc) for p in _CORE_TOOL_DESC_PATTERNS)
+
 
 def _narrow_tools_for_request(
     anthropic_body: dict, openai_tools: list[dict]
@@ -5187,10 +5238,27 @@ def _narrow_tools_for_request(
     # otherwise keep an arbitrary first-N subset — observed dropping
     # Write/Edit/Bash entirely and stalling the agent on meta-tools. `keep` thus
     # acts as a soft floor: core tools are added on top of the top-scored set.
+    core_ids = set()
     for tool in openai_tools:
-        nm = tool.get("function", {}).get("name", "").lower()
-        if nm in _CORE_TOOL_NAMES:
-            selected.add(id(tool))
+        fn = tool.get("function", {}) or {}
+        if _is_core_action_tool(fn.get("name", ""), fn.get("description", "")):
+            core_ids.add(id(tool))
+
+    # FAIL-SAFE: if NOTHING in this client's surface reads as a core action tool,
+    # we do not understand it well enough to prune it, and pruning it anyway is
+    # exactly how hermes lost terminal + write_file and burned a session looping.
+    # Ranking is lexical overlap with the user's text, which happily promotes
+    # cronjob/clarify over the tools that do the work. Keep everything and say so
+    # — an unnarrowed request costs prompt tokens; a stranded agent costs the run.
+    if not core_ids:
+        logger.info(
+            "TOOL NARROWING: skipped — no core action tool recognised among %d tools "
+            "(unknown client surface; not pruning blind)",
+            len(openai_tools),
+        )
+        return openai_tools
+
+    selected |= core_ids
     narrowed = [tool for tool in openai_tools if id(tool) in selected]
 
     top_names = [t.get("function", {}).get("name", "") for t in narrowed[:4]]

package/tools/agents/tests/test_tool_narrowing_core.py

@@ -0,0 +1,103 @@
+"""Tool narrowing must never strand an agent by dropping its core action tools.
+
+Regression (hermes, 2026-08-03): _CORE_TOOL_NAMES listed only Claude Code's
+canonical names, so the always-retain guard was a no-op for any other client.
+Hermes sends terminal/execute_code/write_file/search_files/patch — zero overlap.
+Narrowing cut 36 tools to 8, kept browser_type/clarify/cronjob and dropped
+terminal AND write_file. The model tried to run `ls -la` through browser_type,
+failed "no browser session" three times, CYCLE BREAK then removed browser_type
+leaving 6 tools, and the session ended in 12 `clarify` calls whose text was
+"I've been stuck in a loop".
+"""
+import importlib.util
+import os
+import unittest
+from pathlib import Path
+
+os.environ["PROXY_TOOL_NARROWING"] = "on"
+proxy_path = Path(__file__).resolve().parents[3] / "tools" / "agents" / "scripts" / "anthropic_proxy.py"
+spec = importlib.util.spec_from_file_location("anthropic_proxy", proxy_path)
+ap = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(ap)
+
+
+def tool(name, desc=""):
+    return {"type": "function", "function": {"name": name, "description": desc}}
+
+
+def body(text):
+    return {"messages": [{"role": "user", "content": [{"type": "text", "text": text}]}]}
+
+
+class IsCoreActionToolTest(unittest.TestCase):
+    def test_claude_code_names_are_core(self):
+        for n in ("Bash", "Write", "Edit", "Read", "Glob", "Grep"):
+            self.assertTrue(ap._is_core_action_tool(n, ""), n)
+
+    def test_other_clients_names_are_core(self):
+        # The whole point: these are hermes/Forge names, not Claude Code's.
+        for n in ("terminal", "execute_code", "write_file", "read_file",
+                  "search_files", "patch", "str_replace", "run_command"):
+            self.assertTrue(ap._is_core_action_tool(n, ""), n)
+
+    def test_unknown_name_classified_from_description(self):
+        # A client we have never seen still keeps the ability to act.
+        self.assertTrue(ap._is_core_action_tool("zsh_exec", "Execute a shell command"))
+        self.assertTrue(ap._is_core_action_tool("blob_put", "Write content to a file"))
+        self.assertTrue(ap._is_core_action_tool("slurp", "Read the contents of a file"))
+
+    def test_non_action_tools_are_not_core(self):
+        # browser_type is the trap: its description says "type text", which must
+        # NOT read as a file write, or the cycling tool gets pinned as core.
+        self.assertFalse(ap._is_core_action_tool("browser_type", "Type text into an element on the page"))
+        self.assertFalse(ap._is_core_action_tool("clarify", "Ask the user a clarifying question"))
+        self.assertFalse(ap._is_core_action_tool("cronjob", "Schedule a recurring job"))
+        self.assertFalse(ap._is_core_action_tool("memory", "Store or recall a memory"))
+        self.assertFalse(ap._is_core_action_tool("browser_navigate", "Navigate the browser to a URL"))
+
+    def test_empty_description_unknown_name_is_not_core(self):
+        self.assertFalse(ap._is_core_action_tool("mystery", ""))
+
+
+class NarrowingRetainsCoreToolsTest(unittest.TestCase):
+    def hermes_surface(self):
+        tools = [
+            tool("terminal", "Run a shell command on the host"),
+            tool("write_file", "Write content to a file at a path"),
+            tool("execute_code", "Execute Python code in a sandbox"),
+            tool("read_file", "Read the contents of a file"),
+            tool("clarify", "Ask the user a clarifying question"),
+            tool("browser_type", "Type text into an element on the page"),
+            tool("cronjob", "Schedule a recurring job"),
+            tool("memory", "Store or recall a memory"),
+        ]
+        tools += [tool(f"misc_{i}", f"Miscellaneous capability {i}") for i in range(28)]
+        return tools
+
+    def test_terminal_and_write_file_survive_narrowing(self):
+        # The exact regression: a mission whose words share nothing with the
+        # tool names, so lexical ranking alone promotes meta-tools.
+        out = ap._narrow_tools_for_request(
+            body("Build a complete vanilla JS and Canvas space shooter game"),
+            self.hermes_surface(),
+        )
+        names = [t["function"]["name"] for t in out]
+        self.assertIn("terminal", names)
+        self.assertIn("write_file", names)
+        self.assertIn("execute_code", names)
+        self.assertLess(len(out), 36, "narrowing should still narrow")
+
+    def test_no_recognisable_core_tool_disables_narrowing(self):
+        # Fail-safe: a surface we cannot classify is one we must not prune.
+        opaque = [tool(f"opaque_{i}", f"Capability {i}") for i in range(30)]
+        out = ap._narrow_tools_for_request(body("do the thing"), opaque)
+        self.assertEqual(len(out), len(opaque))
+
+    def test_narrowing_still_prunes_when_core_tools_present(self):
+        # The fail-safe must not become a blanket opt-out.
+        out = ap._narrow_tools_for_request(body("build a game"), self.hermes_surface())
+        self.assertLess(len(out), 36)
+
+
+if __name__ == "__main__":
+    unittest.main()