fix: the manifest understated the "full" tool surface by ten (v0.1.3) (#1)

`full` binds 38 tools, not ~28. v0.1.1 verified the real count against
driver 0.8.3 and corrected driver.py; the manifest kept the original
estimate in two places and nothing caught it:

  - protoagent.plugin.yaml:29  a yaml comment
  - protoagent.plugin.yaml:70  the tool_surface SETTINGS DESCRIPTION —
    the text an operator reads in the console *before* flipping to
    "full", i.e. the one surface where the number is load-bearing

The ten unlisted tools are the dangerous end of the surface, so the
description now names what "full" adds rather than only counting it:
kill_app, bring_to_front, set_config, check_for_update (driver
self-update, which ADR 0084 keeps operator-driven).

Why it drifted: test_stated_tool_count_matches_the_code already pinned
the "17 tools" claim in that same sentence — its docstring even says
"numbers in prose drift silently — pin it to the list" — but the "full"
half of the sentence was unpinned, so only the guarded half survived.

  - driver.py: VERIFIED_DRIVER_VERSION / VERIFIED_PUBLISHED_TOOLS
    promote the count from a comment to something a test can hold.
  - test_stated_full_surface_count_matches_the_code pins the rendered
    description, the way the core count is pinned.
  - test_manifest_states_no_approximate_tool_counts holds the RAW file:
    yaml comments never reach the parsed manifest, so the :29 copy was
    invisible to any fixture-based test. It bans `~<digits>` — the
    un-pinnable form is the actual tell.

Both new guards verified RED against the pre-fix manifest before being
kept; an earlier version of the second one passed against the bug (it
required the word "tools" after the number, and the stale text read
"~28)" / "~28 and") and was rewritten.

No behavior change — tool_filter and CORE_TOOLS are untouched.


Claude-Session: https://claude.ai/code/session_01Qjyu1YKjvmuga7sFtaxzUw

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: mabry1985

driver.py

@@ -31,9 +31,17 @@
 #: sidecar, which does not inherit your shell's environment.
 _FALLBACK_DIRS = ("~/.local/bin", "/opt/homebrew/bin", "/usr/local/bin")
 
-#: The documented snapshot->act loop (ADR 0084 D3). Driver 0.8.3 publishes **38**
-#: tools; binding all of them costs context on every turn for surface the agent
-#: rarely needs (ADR 0005). Deliberately excluded from the default, available via
+#: The driver build the tool-surface claims were verified against. The published
+#: count is version-dependent, and operator-facing copy quotes it, so it lives
+#: here as a constant the manifest tests can hold rather than as a number in prose
+#: that drifts — which it did: v0.1.1 corrected this file to 38 and left the
+#: manifest saying "~28", where it stayed until v0.1.3.
+VERIFIED_DRIVER_VERSION = "0.8.3"
+VERIFIED_PUBLISHED_TOOLS = 38
+
+#: The documented snapshot->act loop (ADR 0084 D3). Binding all of the driver's
+#: published tools costs context on every turn for surface the agent rarely needs
+#: (ADR 0005). Deliberately excluded from the default, available via
 #: ``extra_tools``:
 #:   bring_to_front     — steals focus, which is the whole thing the driver avoids
 #:   kill_app           — destructive (kill -9)

protoagent.plugin.yaml

@@ -1,6 +1,6 @@
 id: cua
 name: Computer use (cua-driver)
-version: 0.1.2
+version: 0.1.3
 description: >-
   Let the agent drive native GUI apps on THIS machine — snapshot a window's
   accessibility tree, then click/type/scroll by element, without bringing the app
@@ -26,7 +26,8 @@ config:
   # runs with a scrubbed PATH — notably the frozen desktop sidecar (ADR 0058).
   binary_path: ""
   # Tool surface. "core" binds the documented snapshot->act loop only; "full"
-  # binds every tool the driver exposes (~28) and floods context (ADR 0005).
+  # binds every tool the driver exposes (38 on driver 0.8.3) and floods context
+  # (ADR 0005) — including the ones "core" excludes on purpose.
   tool_surface: core
   # Extra tool names to bind on top of "core" — e.g. ["kill_app", "bring_to_front"].
   # Ignored when tool_surface is "full". Verify names with the Test button.
@@ -67,8 +68,11 @@ settings:
     options: [core, full]
     group: "Computer use"
     description: >-
-      “core” binds the documented loop (17 tools). “full” binds all ~28 and
-      costs context on every turn.
+      “core” binds the documented loop (17 tools). “full” binds every tool the
+      installed driver publishes — 38 on driver 0.8.3 — costing context on every
+      turn and adding the surface “core” leaves out on purpose: kill_app,
+      bring_to_front, set_config and check_for_update (driver self-update).
+      “Test connection” reports the real count for your installed driver.
   - key: extra_tools
     label: "Extra tools"
     type: string_list

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cua-plugin"
-version = "0.1.2"
+version = "0.1.3"
 description = "protoAgent plugin: computer use — drive native GUI apps via the third-party cua-driver binary, wrapped as a managed MCP server."
 requires-python = ">=3.11"
 

tests/test_manifest.py

@@ -109,6 +109,32 @@ def test_stated_tool_count_matches_the_code(m):
     assert int(claimed.group(1)) == len(driver.CORE_TOOLS)
 
 
+def test_stated_full_surface_count_matches_the_code(m):
+    """The `full` count is the blast-radius number an operator reads *before*
+    flipping the switch, and nothing pinned it — so it sat at "~28" while the code
+    said 38, from v0.1.1 to v0.1.3. The test above guarded the `core` number in the
+    same sentence. Guard both, or the unguarded half drifts again."""
+    import re
+
+    field = next(s for s in m["settings"] if s["key"] == "tool_surface")
+    claimed = re.search(r"(\d+) on driver", field["description"])
+    assert claimed, "the tool_surface description should state how many tools 'full' binds"
+    assert int(claimed.group(1)) == driver.VERIFIED_PUBLISHED_TOOLS
+    assert driver.VERIFIED_DRIVER_VERSION in field["description"]
+
+
+def test_manifest_states_no_approximate_tool_counts():
+    """Comments aren't parsed into `m`, so the yaml-level copy drifted unseen too —
+    and the approximate form is the tell: "~28" is not a checkable claim, so nothing
+    checked it, so it outlived the code by two releases. The real counts are pinned
+    by the two tests above; ban the un-pinnable form outright. (`~/` paths are fine —
+    this matches `~` followed by a digit.)"""
+    import re
+
+    approx = re.findall(r"~\d+", MANIFEST.read_text())
+    assert not approx, f"approximate count(s) in the manifest — state the real number: {approx}"
+
+
 def test_declares_no_secrets(m):
     """Nothing to leak — the driver is a local binary, not an API."""
     assert not m.get("secrets")