Merge pull request #99 from open-coder-ai/w42/d5-singleton-folds

Author: jothimani-rajendran

CHANGELOG.md

@@ -30,6 +30,25 @@ versioning: [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   chains (demonstrated, not merely asserted).
 
 ### Changed
+- **The three singleton adapters are folded onto the engine**
+  (`docs/design/dialect-families.md` D5). `cursor`, `windsurf` and `antigravity` are no
+  longer hand-written modules: each is a small family module (shape-inferred claims and
+  event naming, which §3.3 keeps as code, plus cursor's G4 permission-object renderer and
+  windsurf's G5 exit-code renderer) over the shared accessor and its
+  `data/vendors/<agent>.json` entry, which now carries the dialect's words and note strings
+  verbatim. The golden wire fixtures pass **byte-for-byte unchanged**. The engine devices
+  this needed are opt-in schema keys absent from every F1/F2 entry: a generic dotted-path
+  field accessor (`toolCall.args.X`, `workspacePaths[0]`, top-level `edits[].new_string`),
+  `stringify`, `empty_object_events`, per-gate `words_at` overrides, `flag_note` templates,
+  `hook_entry.also_wires` (windsurf's second pre_tool wire name, moved out of
+  `entry_extra`, which would have copied it into entries verbatim), the `cursor` and
+  `flat_entries` hook wrappers with `group` nesting, and a G1 block reroute for an escalate
+  degraded from a transform where the entry names that degradation. `_hook_json.py` split
+  by activity into `_payload.py` (claims/parse) and the renderers to stay in the review
+  budget. windsurf's `pre_mcp_tool_use` gate — blocking in the adapter but invisible to
+  D1's one-wire-per-canonical-event fixture — joins `_EXTRA_GATE_NAMES` and is recounted by
+  executing the dispatcher. vscode_copilot remains the one dialect module (W38's recorded
+  design feedback; folding it is an owner decision).
 - **The four `flat_decision` adapters are folded onto the same engine**
   (`docs/design/dialect-families.md` D4). `gemini_cli`, `tabnine`, `junie` and `grok` are
   no longer hand-written modules: the D3 engine executes their `data/vendors/<agent>.json`

docs/design/dialect-families.md

@@ -332,6 +332,23 @@ first, D3/D4 swap cleanly — they share only D1+D2.
   (escalate word path, two transform-body variants, template notes, per-gate reason
   defaults, allow-body context/silence, a reverse-map wire fallback, a tool-input
   envelope chain, write-gated content, literal hook-entry extras).
+- **[v]** D5's singleton numbers, measured at its base (main `38023f4`, where the pre-fold
+  bundles stood at cursor 524 / windsurf 424 / antigravity 442): cursor 883, windsurf 814,
+  antigravity 796 — +69% to +92%, the steepest growth of the three folds and far above §4's
+  "singletons roughly unchanged" estimate. The composition explains it: a singleton's legacy
+  bundle spliced only its own small module, while an engine bundle inlines the whole shared
+  engine (accessor, G1/G2 renderers, hook-entry wrappers) plus the family module plus the
+  `VENDOR` literal — the same trade D3/D4 made, and D6 owns any trimming. The source-tree
+  payoff held a third time: the three deleted modules were 472 lines, replaced by three
+  family modules of 219 (cursor's G4 renderer and shape claims, windsurf's G5 exit-code
+  renderer, antigravity's 3-line shape functions over the engine's G1) — everything
+  word-shaped moved into the entries as opt-in schema keys (`words_at` per-gate overrides,
+  `empty_object_events`, `flag_note`/`flag_note_default`, `stringify`, `also_wires`, a
+  generic dotted-path accessor with `[0]`/top-level `[].` forms, and a block reroute for an
+  escalate degraded from a transform where the entry names that degradation). The
+  config/code line held without a new named probe: shape inference stays the three family
+  modules' code, exactly as §3.3 drew it, and windsurf's two-key pre_tool fan-out folded as
+  `hook_entry.also_wires` (wiring data) rather than an `entry_extra` entry field.
 - **[v]** (was [h]) The `reject_probes: ["looks_like_claude_code"]` device (named engine
   predicates referenced from config) is the narrowest crack in the code/config line;
   if D2 finds more than ~3 named probes are needed, that is evidence the line is drawn

src/agentseam/adapters/__init__.py

@@ -3,25 +3,27 @@
 from __future__ import annotations
 
 from .._data import load
-from . import (
-    antigravity,
-    cursor,
-    vscode_copilot,
-    windsurf,
-)
+from . import vscode_copilot
 from ._family import bind
 
-#: hook_json (D3) and flat_decision (D4) vendors driven by engine + data/vendors entry;
+#: Every vendor but one is a family engine (D3-D5) bound to its data/vendors entry;
 #: vscode_copilot stays a dialect module -- its three-path claims() and memory-tool
 #: branching are beyond what the flat config may carry (§3.1).
-_CONFIG_DRIVEN = ("claude_code", "codex_cli", "devin", "gemini_cli", "grok", "junie", "kimi_code", "tabnine")
-
-ADAPTERS = {
-    antigravity.AGENT: antigravity,
-    cursor.AGENT: cursor,
-    vscode_copilot.AGENT: vscode_copilot,
-    windsurf.AGENT: windsurf,
-}
+_CONFIG_DRIVEN = (
+    "antigravity",
+    "claude_code",
+    "codex_cli",
+    "cursor",
+    "devin",
+    "gemini_cli",
+    "grok",
+    "junie",
+    "kimi_code",
+    "tabnine",
+    "windsurf",
+)
+
+ADAPTERS = {vscode_copilot.AGENT: vscode_copilot}
 ADAPTERS.update({agent: bind(load("vendors/%s.json" % agent)) for agent in _CONFIG_DRIVEN})
 
 

src/agentseam/adapters/_antigravity.py

@@ -0,0 +1,34 @@
+"""The F5 `antigravity` family: event-less payloads classified by shape.
+
+Only the shape inference is code (dialect-families.md §3.3) -- the verdicts are the
+engine's G1 renderer over `data/vendors/antigravity.json`'s word tables.
+"""
+
+from __future__ import annotations
+
+from ._hook_json import hj_respond
+from ._payload import hj_parse
+
+
+def antigravity_wire(raw):
+    """Name the event from shape; ties go to PreToolUse so the gate stays a gate."""
+    if "terminationReason" in raw or "fullyIdle" in raw:
+        return "Stop"
+    if isinstance(raw.get("toolCall"), dict):
+        return "PostToolUse" if "error" in raw else "PreToolUse"
+    return None
+
+
+def antigravity_claims(cfg, raw):
+    """Structural: `conversationId` with `workspacePaths` is Antigravity's own envelope."""
+    if not isinstance(raw, dict):
+        return False
+    return "conversationId" in raw and isinstance(raw.get("workspacePaths"), list)
+
+
+def antigravity_parse(cfg, raw):
+    return hj_parse(cfg, raw, wire=antigravity_wire(raw))
+
+
+def antigravity_respond(cfg, decision, event):
+    return hj_respond(cfg, decision, event, wire=antigravity_wire(event.raw or {}))

src/agentseam/adapters/_cursor.py

@@ -0,0 +1,132 @@
+"""The F3 `cursor` family: shape-inferred claims and the G4 permission-object dialect.
+
+Shape inference stays code (dialect-families.md §3.3); everything word- or chain-shaped
+comes from the vendor's `data/vendors/cursor.json` entry.
+"""
+
+from __future__ import annotations
+
+import json as _json
+
+from ..contract import (
+    DENY,
+    ESCALATE,
+    FILE_CHANGED,
+    POST_TOOL,
+    PRE_TOOL,
+    PROMPT_SUBMIT,
+    TOOL_FAILURE,
+    TRANSFORM,
+    degraded_from,
+)
+from ._payload import hj_parse
+
+#: Wire names other vendors also spell this way; a payload naming one is claimed only on
+#: Cursor's own base-schema envelope markers.
+_AMBIGUOUS_NAMES = (
+    "preToolUse",
+    "postToolUse",
+    "sessionStart",
+    "sessionEnd",
+    "preCompact",
+    "stop",
+    "subagentStart",
+    "subagentStop",
+)
+
+_MARKERS = ("conversation_id", "generation_id", "cursor_version", "workspace_roots")
+
+
+def cursor_wire(raw):
+    """The wire event name, inferred from shape when the payload names none."""
+    name = raw.get("hook_event_name")
+    if name is None:
+        return "afterFileEdit" if isinstance(raw.get("edits"), list) else "beforeShellExecution"
+    return name
+
+
+def cursor_claims(cfg, raw):
+    """True when this payload looks like Cursor's shape."""
+    if not isinstance(raw, dict):
+        return False
+    name = raw.get("hook_event_name")
+    if name in cfg["events"]:
+        if name in _AMBIGUOUS_NAMES:
+            return any(k in raw for k in _MARKERS)
+        return True
+    if isinstance(raw.get("command"), str) and ("sandbox" in raw or "cwd" in raw) and "tool_input" not in raw:
+        return True
+    return "file_path" in raw and isinstance(raw.get("edits"), list) and "tool_name" not in raw
+
+
+def cursor_parse(cfg, raw):
+    name = cursor_wire(raw)
+    event = hj_parse(cfg, raw, wire=name)
+    event.tool = event.tool or name
+    return event
+
+
+def _because(reason, note):
+    """Keep the handler's own reason and add why the outcome changed shape."""
+    return "%s (%s)" % (reason, note) if reason else note
+
+
+def _wire_of(cfg, event):
+    """The wire name to answer at: the payload's own, `tool` where `parse` kept it there,
+    else the entry's default gate."""
+    name = (event.raw or {}).get("hook_event_name")
+    if name in cfg["events"]:
+        return name
+    return event.tool if event.tool in cfg["events"] else cfg["verdicts"].get("default_wire_event")
+
+
+def cursor_respond(cfg, decision, event):
+    v = cfg["verdicts"]
+    name = _wire_of(cfg, event)
+    canonical = cfg["events"].get(name)
+
+    if canonical == FILE_CHANGED:
+        return "", 0
+
+    if canonical in (POST_TOOL, TOOL_FAILURE):
+        if decision.outcome in (DENY, ESCALATE):
+            note = v["flag_note"] % (name, decision.reason or v["flag_note_default"])
+            return _json.dumps({"additional_context": note}), 0
+        return "", 0
+
+    if canonical == PROMPT_SUBMIT:
+        payload = {"continue": decision.outcome not in (DENY, ESCALATE, TRANSFORM)}
+        if decision.reason:
+            payload["user_message"] = decision.reason
+        return _json.dumps(payload), 0
+
+    gate = v["gates"].get(name)
+    if gate is None or canonical != PRE_TOOL:
+        return "", 0
+
+    words = v["words"]
+    notes = v["degrade_notes"]
+    reason = decision.reason
+
+    if decision.outcome == TRANSFORM:
+        if gate["honours_transform"] and decision.updated_input is not None:
+            payload = {"permission": words["allow"], "updated_input": decision.updated_input}
+        else:
+            payload = {"permission": words["block"]}
+            reason = _because(reason, notes["transform"])
+    elif decision.outcome == DENY:
+        payload = {"permission": words["block"]}
+    elif decision.outcome == ESCALATE:
+        if gate["honours_escalate"]:
+            payload = {"permission": words["escalate"]}
+        else:
+            note = notes["escalate_from_transform"] if degraded_from(decision) == TRANSFORM else notes["escalate"]
+            payload = {"permission": words["block"]}
+            reason = _because(reason, note % name)
+    else:
+        payload = {"permission": words["allow"]}
+
+    if reason and payload["permission"] != words["allow"]:
+        payload["user_message"] = reason
+        payload["agent_message"] = reason
+    return _json.dumps(payload), 0

src/agentseam/adapters/_family.py

@@ -3,9 +3,13 @@
 from __future__ import annotations
 
 from . import _hook_json
+from ._antigravity import antigravity_claims, antigravity_parse, antigravity_respond
+from ._cursor import cursor_claims, cursor_parse, cursor_respond
 from ._hook_entry import hook_entry_config, render_config
-from ._hook_json import hj_claims, hj_parse, hj_respond, hj_reverse
+from ._hook_json import hj_respond, hj_reverse
+from ._payload import hj_claims, hj_parse
 from ._windows import powershell_command
+from ._windsurf import windsurf_claims, windsurf_parse, windsurf_respond
 
 
 class ConfigAdapter:
@@ -48,10 +52,55 @@ def hook_config(self, canonical_events, command, matcher=None):
         return hook_entry_config(self.CONFIG, canonical_events, command, matcher)
 
 
+class _CursorAdapter(ConfigAdapter):
+    """F3: the G4 dialect, and the only hook_config that takes fail_closed."""
+
+    def claims(self, raw):
+        return cursor_claims(self.CONFIG, raw)
+
+    def parse(self, raw):
+        return cursor_parse(self.CONFIG, raw)
+
+    def respond(self, decision, event):
+        return cursor_respond(self.CONFIG, decision, event)
+
+    def hook_config(self, canonical_events, command, matcher=None, fail_closed=True):
+        return hook_entry_config(self.CONFIG, canonical_events, command, matcher, fail_closed)
+
+
+class _WindsurfAdapter(ConfigAdapter):
+    """F4: the G5 exit-code dialect."""
+
+    def claims(self, raw):
+        return windsurf_claims(self.CONFIG, raw)
+
+    def parse(self, raw):
+        return windsurf_parse(self.CONFIG, raw)
+
+    def respond(self, decision, event):
+        return windsurf_respond(self.CONFIG, decision, event)
+
+
+class _AntigravityAdapter(ConfigAdapter):
+    """F5: shape-inferred events over the engine's G1 renderer."""
+
+    def claims(self, raw):
+        return antigravity_claims(self.CONFIG, raw)
+
+    def parse(self, raw):
+        return antigravity_parse(self.CONFIG, raw)
+
+    def respond(self, decision, event):
+        return antigravity_respond(self.CONFIG, decision, event)
+
+
+_FAMILY_ADAPTERS = {"cursor": _CursorAdapter, "windsurf": _WindsurfAdapter, "antigravity": _AntigravityAdapter}
+
+
 def _hook_entry_windows(cfg):
     return tuple(cfg["hook_entry"].get("entry_extra", {}))
 
 
 def bind(cfg):
     """The adapter object for one vendor config entry."""
-    return ConfigAdapter(cfg)
+    return _FAMILY_ADAPTERS.get(cfg["family"], ConfigAdapter)(cfg)

src/agentseam/adapters/_hook_entry.py

@@ -21,11 +21,16 @@ def _hook_dict(cfg, command):
     return entry
 
 
-def hook_entry_config(cfg, canonical_events, command, matcher=None):
-    """The vendor's hooks-config fragment wiring `command` for these canonical events."""
+def hook_entry_config(cfg, canonical_events, command, matcher=None, fail_closed=True):
+    """The vendor's hooks-config fragment wiring `command` for these canonical events.
+
+    `fail_closed` is read only by the `cursor` wrapper, whose gates fail open unless the
+    entry says otherwise; a False installs an observer, not a gate.
+    """
     hook_entry = cfg["hook_entry"]
     reverse = hj_reverse(cfg)
-    if hook_entry["wrapper"] == "flat_list":
+    wrapper = hook_entry["wrapper"]
+    if wrapper == "flat_list":
         rules = []
         for ev in canonical_events:
             name = reverse.get(ev)
@@ -36,6 +41,29 @@ def hook_entry_config(cfg, canonical_events, command, matcher=None):
                 rule["matcher"] = matcher
             rules.append(rule)
         return rules
+    if wrapper == "cursor":
+        gates = cfg["verdicts"]["answer_events"]
+        hooks = {}
+        for ev in canonical_events:
+            name = reverse.get(ev)
+            if not name:
+                continue
+            entry = {"command": command}
+            if fail_closed and name in gates:
+                entry["failClosed"] = True
+            hooks.setdefault(name, []).append(entry)
+        return {"version": 1, "hooks": hooks}
+    if wrapper == "flat_entries":
+        hooks = {}
+        for ev in canonical_events:
+            name = reverse.get(ev)
+            if not name:
+                continue
+            hooks.setdefault(name, []).append({"command": command})
+            extra = hook_entry.get("also_wires", {}).get(ev)
+            if extra:
+                hooks.setdefault(extra, []).append({"command": command})
+        return {"hooks": hooks}
     hooks = {}
     for ev in canonical_events:
         name = reverse.get(ev)
@@ -45,6 +73,8 @@ def hook_entry_config(cfg, canonical_events, command, matcher=None):
         if matcher and hook_entry["matcher"]:
             entry["matcher"] = matcher
         hooks.setdefault(name, []).append(entry)
+    if hook_entry.get("group"):
+        return {hook_entry["group"]: hooks}
     return hooks if hook_entry.get("bare") else {"hooks": hooks}