@r1z4x/tezgah 1.0.0 → 1.1.0

package/hooks/tezgah_stack.py

@@ -0,0 +1,382 @@
+#!/usr/bin/env python3
+"""The effective stack each host loads on this machine, and where it collides.
+
+`tezgah-doctor --stack` prints it. For every host it lists, in the host's own
+load order: the context files that exist, the skill dirs and which copy of a
+skill name wins, the hook commands per event with their owner (tezgah, Orca, a
+user's own), and the MCP servers. Then it flags what the owner otherwise finds
+out by hand when omp, Claude Code, Codex, Cursor and opencode run side by side:
+
+  - skill-differs   one host reads two skills of one name whose SKILL.md
+                    differ; the copy that wins is named (first-wins hosts)
+  - skill-dup       the same skill reached twice through two dirs one host reads
+  - skill-stale     a shipped tezgah skill whose copy is not this tree's bytes
+  - rule-twice      two context files one host loads both carry the tezgah block
+  - backup-in-scan  a `.tezgah-bak` inside a dir the host enumerates
+  - hook-twice      one host runs tezgah's same hook command twice for one event
+  - mcp-twice       one host reads two definitions of one MCP server name
+
+The load orders are the hosts' documented ones (docs/hosts.md#precedence), not
+a probe of a running session: this module reads files and runs nothing.
+Read-only, stdlib only.
+"""
+import hashlib
+import json
+import os
+import re
+
+import tezgah_paths as tp
+
+HERE = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+TEZGAH_SKILLS = os.path.join(HERE, "skills")
+BLOCK = "<!-- tezgah:start -->"
+OWNERS = (("tezgah", "tezgah"), ("orca", "orca"), ("ORCA_", "orca"),
+          ("codegraph", "codegraph"))
+
+
+def _read(path, limit=None):
+    try:
+        with open(path, encoding="utf-8", errors="replace") as fh:
+            return fh.read(limit) if limit else fh.read()
+    except OSError:
+        return ""
+
+
+def _json(path):
+    try:
+        with open(path, encoding="utf-8") as fh:
+            data = json.load(fh)
+        return data if isinstance(data, dict) else {}
+    except (OSError, ValueError):
+        return {}
+
+
+def _digest(path):
+    try:
+        with open(path, "rb") as fh:
+            return hashlib.sha256(fh.read()).hexdigest()[:12]
+    except OSError:
+        return None
+
+
+def owner(command):
+    text = str(command)
+    return next((name for key, name in OWNERS if key in text), "other")
+
+
+def yaml_list(text, key):
+    """The `- item` lines under `key:` in a block-style YAML file. omp's
+    config.yml is the only YAML read here, and only for two string lists."""
+    out, indent = [], None
+    for line in text.splitlines():
+        m = re.match(r"^(\s*)%s:\s*$" % re.escape(key), line)
+        if m:
+            indent = len(m.group(1))
+            continue
+        if indent is None:
+            continue
+        item = re.match(r"^(\s*)-\s+(.+?)\s*$", line)
+        if item and len(item.group(1)) >= indent:
+            out.append(item.group(2).strip("\"'"))
+        elif line.strip():
+            break
+    return out
+
+
+def toml_tables(text, prefix):
+    """Names of `[prefix.<name>]` tables in a TOML file (Codex's MCP rows)."""
+    return sorted({m.group(1) for m in re.finditer(
+        r"^\[%s\.([A-Za-z0-9_-]+)\]" % re.escape(prefix), text, re.M)})
+
+
+def hook_rows(data, source, who=None):
+    """{event: [(owner, source, matcher + command)]} from a Claude/Codex/Cursor
+    hooks object. `who` names the owner of every row (a plugin's own hooks
+    file). One command under two matchers answers two different tool sets, so
+    the matcher is part of what makes a row a duplicate."""
+    out = {}
+    hooks = data.get("hooks", {})
+    for event, groups in (hooks.items() if isinstance(hooks, dict) else []):
+        for group in groups if isinstance(groups, list) else []:
+            entries = (group.get("hooks") or [group]) if isinstance(group, dict) else []
+            matcher = str(group.get("matcher") or "") if isinstance(group, dict) else ""
+            for entry in entries:
+                if isinstance(entry, dict) and entry.get("command"):
+                    cmd = str(entry["command"])
+                    key = "%s %s" % (matcher, cmd) if matcher else cmd
+                    out.setdefault(event, []).append((who or owner(cmd), source, key))
+    return out
+
+
+def merge_hooks(*parts):
+    out = {}
+    for part in parts:
+        for event, rows in part.items():
+            out.setdefault(event, []).extend(rows)
+    return out
+
+
+def claude_plugin():
+    """(root of the tezgah plugin copy Claude loads, every tezgah copy on disk)."""
+    plugins = os.path.join(tp.HOST_DIRS["claude"], "plugins")
+    rows = _json(os.path.join(plugins, "installed_plugins.json")).get("plugins") or {}
+    active = next((r[-1].get("installPath") for k, r in rows.items()
+                   if k.split("@")[0] == "tezgah" and r), None)
+    cache = os.path.join(plugins, "cache")
+    copies = []
+    for market in sorted(os.listdir(cache)) if os.path.isdir(cache) else []:
+        base = os.path.join(cache, market, "tezgah")
+        if os.path.isdir(base):
+            copies += [os.path.join(base, v) for v in sorted(os.listdir(base))]
+    return active, copies
+
+
+def host_stack(host, repo):
+    """{context, skills: (mode, [dir]), hooks, mcp, scan} for one host.
+
+    `mode` is `first` when the host keeps the first copy of a name, `all` when
+    it lists every copy (Codex says so; Cursor documents no winner). `scan` is
+    every dir the host enumerates, where a stray backup is one more entry."""
+    h = tp.HOME
+    agents_user = os.path.join(h, ".agents", "skills")
+    agents_repo = os.path.join(repo, ".agents", "skills")
+    if host == "claude":
+        c = tp.HOST_DIRS["claude"]
+        active, _ = claude_plugin()
+        plugin_hooks = hook_rows(_json(os.path.join(active, "hooks", "hooks.json")),
+                                 "plugin", "tezgah") if active else {}
+        mcp = sorted(_json(os.path.join(h, ".claude.json")).get("mcpServers") or {})
+        mcp += ["%s (project)" % n for n in sorted(
+            _json(os.path.join(repo, ".mcp.json")).get("mcpServers") or {})]
+        if active:
+            mcp += ["%s (plugin)" % n for n in sorted(
+                _json(os.path.join(active, ".mcp.json")).get("mcpServers") or {})]
+        return {
+            "context": [os.path.join(c, "CLAUDE.md"), os.path.join(repo, "CLAUDE.md"),
+                        os.path.join(repo, ".claude", "CLAUDE.md"),
+                        os.path.join(repo, "CLAUDE.local.md")],
+            "skills": ("first", [os.path.join(repo, ".claude", "skills"),
+                                 os.path.join(c, "skills")]),
+            "hooks": merge_hooks(
+                hook_rows(_json(os.path.join(c, "settings.json")), "settings.json"),
+                hook_rows(_json(os.path.join(repo, ".claude", "settings.json")), "project"),
+                plugin_hooks),
+            "mcp": mcp,
+            "scan": [os.path.join(c, "agents"), os.path.join(c, "skills"),
+                     os.path.join(c, "commands")],
+        }
+    if host == "codex":
+        c = tp.HOST_DIRS["codex"]
+        user = os.path.join(c, "AGENTS.override.md")
+        return {
+            "context": [user if os.path.isfile(user) else os.path.join(c, "AGENTS.md"),
+                        os.path.join(repo, "AGENTS.md")],
+            "skills": ("all", [agents_repo, agents_user, os.path.join(c, "skills")]),
+            "hooks": merge_hooks(
+                hook_rows(_json(os.path.join(c, "hooks.json")), "hooks.json"),
+                hook_rows(_json(os.path.join(repo, ".codex", "hooks.json")), "project")),
+            "mcp": toml_tables(_read(os.path.join(c, "config.toml")), "mcp_servers"),
+            "scan": [os.path.join(c, "skills"), os.path.join(c, "rules"),
+                     os.path.join(c, "prompts")],
+        }
+    if host == "cursor":
+        c = tp.HOST_DIRS["cursor"]
+        rules = os.path.join(repo, ".cursor", "rules")
+        return {
+            "context": [os.path.join(repo, "AGENTS.md"), os.path.join(repo, ".cursorrules")]
+            + sorted(os.path.join(rules, n) for n in (
+                os.listdir(rules) if os.path.isdir(rules) else []) if n.endswith(".mdc")),
+            # Cursor's documented order; it names no winner for a shared name
+            "skills": ("all", [agents_repo, os.path.join(repo, ".cursor", "skills"),
+                               agents_user, os.path.join(c, "skills"),
+                               os.path.join(repo, ".claude", "skills"),
+                               os.path.join(repo, ".codex", "skills"),
+                               os.path.join(h, ".claude", "skills"),
+                               os.path.join(h, ".codex", "skills")]),
+            "hooks": merge_hooks(
+                hook_rows(_json(os.path.join(c, "hooks.json")), "hooks.json"),
+                hook_rows(_json(os.path.join(repo, ".cursor", "hooks.json")), "project")),
+            "mcp": sorted(_json(os.path.join(c, "mcp.json")).get("mcpServers") or {}),
+            "scan": [os.path.join(c, "skills"), rules],
+        }
+    if host == "opencode":
+        c = tp.HOST_DIRS["opencode"]
+        conf = _json(os.path.join(c, "opencode.json"))
+        plugins = []
+        for d in ("plugins", "plugin"):
+            p = os.path.join(c, d)
+            plugins += [(n, d) for n in sorted(os.listdir(p) if os.path.isdir(p) else [])
+                        if n.endswith((".js", ".ts"))]
+        return {
+            "context": [os.path.join(c, "AGENTS.md")]
+            + [p for p in conf.get("instructions") or [] if isinstance(p, str)]
+            + [os.path.join(repo, "AGENTS.md")],
+            # tezgah denies opencode's native skill tool; its router reads these, first wins
+            "skills": ("first", [os.path.join(c, "skills"), os.path.join(h, ".claude", "skills"),
+                                 agents_user]),
+            "hooks": {"plugin (every event)": [(owner(n), "%s/%s" % (d, n), n)
+                                               for n, d in plugins]},
+            "mcp": sorted(conf.get("mcp") or {}),
+            "scan": [os.path.join(c, "skills"), os.path.join(c, "plugins"),
+                     os.path.join(c, "plugin")],
+        }
+    if host == "omp":
+        a = os.path.join(tp.HOST_DIRS["omp"], "agent")
+        conf = _read(os.path.join(a, "config.yml"))
+        enabled = set(yaml_list(conf, "enabledProviders"))
+        custom = yaml_list(conf, "customDirectories")
+        skills = list(custom) + [os.path.join(repo, ".omp", "skills"),
+                                 os.path.join(a, "skills"),
+                                 os.path.join(repo, ".claude", "skills")]
+        if "claude" in enabled or os.environ.get("CLAUDE_CONFIG_DIR"):
+            skills.append(os.path.join(h, ".claude", "skills"))
+        skills += [agents_repo, agents_user]
+        if "codex" in enabled:
+            skills.append(os.path.join(h, ".codex", "skills"))
+        ext_dir = os.path.join(a, "extensions")
+        found = sorted(os.path.join(ext_dir, n) for n in (
+            os.listdir(ext_dir) if os.path.isdir(ext_dir) else []) if n.endswith((".ts", ".js")))
+        configured = [os.path.expanduser(p) for p in yaml_list(conf, "extensions")]
+        order = found + [p for p in configured if p not in found]
+        hooks = {"extension (every event)": [(owner(p), p, p) for p in order]}
+        for kind in ("pre", "post"):
+            d = os.path.join(a, "hooks", kind)
+            listed = sorted(os.listdir(d)) if os.path.isdir(d) else []
+            if listed:
+                hooks["hooks/%s capability" % kind] = [
+                    (owner(n), n + ("" if n.endswith((".ts", ".js")) else " (listed, not loaded)"), n)
+                    for n in listed if not n.startswith(".")]
+        mcp = sorted(_json(os.path.join(a, "mcp.json")).get("mcpServers") or {})
+        return {
+            "context": [os.path.join(a, "SYSTEM.md"), os.path.join(a, "APPEND_SYSTEM.md"),
+                        os.path.join(a, "RULES.md"), os.path.join(repo, ".omp", "AGENTS.md"),
+                        os.path.join(repo, "AGENTS.md"), os.path.join(repo, "CLAUDE.md")]
+            + ([os.path.join(h, ".claude", "CLAUDE.md")] if "claude" in enabled else []),
+            "skills": ("first", skills),
+            "hooks": hooks,
+            "mcp": mcp,
+            "scan": [os.path.join(a, "agents"), os.path.join(a, "skills"),
+                     os.path.join(a, "hooks", "pre"), os.path.join(a, "hooks", "post"),
+                     os.path.join(a, "rules"), ext_dir],
+        }
+    if host == "dsh":
+        c = tp.HOST_DIRS["dsh"]
+        return {"context": [os.path.join(c, "cordis.patch.yml")],
+                "skills": ("first", [os.path.join(c, "skills")]),
+                "hooks": {}, "mcp": [], "scan": [os.path.join(c, "skills")]}
+    raise ValueError(host)
+
+
+def skill_copies(dirs):
+    """[(name, dir, sha of SKILL.md, realpath)] in dir order."""
+    out = []
+    for d in dirs:
+        for name in sorted(os.listdir(d)) if os.path.isdir(d) else []:
+            path = os.path.join(d, name, "SKILL.md")
+            if os.path.isfile(path):
+                out.append((name, d, _digest(path), os.path.realpath(path)))
+    return out
+
+
+def tezgah_skill_dirs():
+    """The dirs tezgah-setup links its skills into, plus the plugin copy's."""
+    dirs = [os.path.join(tp.HOST_DIRS[x], "skills") for x in ("codex", "cursor", "opencode", "dsh")]
+    dirs.append(os.path.join(tp.HOST_DIRS["omp"], "agent", "skills"))
+    active, _ = claude_plugin()
+    return dirs + ([os.path.join(active, "skills")] if active else [])
+
+
+def conflicts(host, stack, repo):
+    """[(kind, detail)] for one host's stack."""
+    out = []
+    mode, dirs = stack["skills"]
+    by_name = {}
+    for name, d, sha, real in skill_copies(dirs):
+        by_name.setdefault(name, []).append((d, sha, real))
+    shipped = set(os.listdir(TEZGAH_SKILLS)) if os.path.isdir(TEZGAH_SKILLS) else set()
+    if host == "claude":
+        active, _ = claude_plugin()
+        for name, d, sha, real in skill_copies([os.path.join(active, "skills")] if active else []):
+            by_name.setdefault("tezgah:" + name, []).append((d, sha, real))
+    owned = tezgah_skill_dirs()
+    for name, copies in sorted(by_name.items()):
+        bare = name.split(":", 1)[-1]
+        if bare in shipped:
+            want = _digest(os.path.join(TEZGAH_SKILLS, bare, "SKILL.md"))
+            out += [("skill-stale", "%s in %s differs from %s" % (bare, d, TEZGAH_SKILLS))
+                    for d, sha, _real in copies if d in owned and sha != want]
+        if len(copies) < 2:
+            continue
+        where = ", ".join(d for d, _s, _r in copies)
+        if len({sha for _d, sha, _r in copies}) > 1:
+            win = copies[0][0] if mode == "first" else "no documented winner"
+            out.append(("skill-differs", "%s: %s (wins: %s)" % (name, where, win)))
+        elif mode == "all":
+            # a first-wins host collapses identical copies; a list-all host shows each
+            out.append(("skill-dup", "%s: %s" % (name, where)))
+    for event, rows in sorted(stack["hooks"].items()):
+        mine = [cmd for who, _src, cmd in rows if who == "tezgah"]
+        twice = sorted({cmd for cmd in mine if mine.count(cmd) > 1})
+        if twice and "every event" not in event:
+            out.append(("hook-twice", "%s: %s" % (event, ", ".join(twice))))
+    names = [n.split(" (")[0] for n in stack["mcp"]]
+    out += [("mcp-twice", "%s: %s" % (n, ", ".join(m for m in stack["mcp"]
+                                                  if m.split(" (")[0] == n)))
+            for n in sorted(set(names)) if names.count(n) > 1]
+    carrying = [p for p in stack["context"] if BLOCK in _read(p)]
+    if len(carrying) > 1:
+        out.append(("rule-twice", ", ".join(carrying)))
+    for d in stack["scan"]:
+        for root, dirnames, files in os.walk(d) if os.path.isdir(d) else []:
+            dirnames[:] = [] if root.count(os.sep) - d.count(os.sep) >= 1 else dirnames
+            out += [("backup-in-scan", os.path.join(root, n))
+                    for n in sorted(files) if n.endswith(".tezgah-bak")]
+    if host == "claude":
+        active, copies = claude_plugin()
+        out += [("orphan-copy", p) for p in copies
+                if active and os.path.realpath(p) != os.path.realpath(active)]
+    return out
+
+
+def report(repo, hosts=None):
+    """{host: stack + conflicts} for the installed hosts (or `hosts`)."""
+    repo = os.path.abspath(repo)
+    out = {}
+    for host in hosts or [h for h in tp.HOST_DIRS if tp.host_installed(h)]:
+        stack = host_stack(host, repo)
+        mode, dirs = stack["skills"]
+        copies = skill_copies(dirs)
+        out[host] = {
+            "context": [p for p in stack["context"] if os.path.isfile(p)],
+            "skill_mode": mode,
+            "skill_dirs": [(d, sum(1 for c in copies if c[1] == d))
+                           for d in dirs if os.path.isdir(d)],
+            "skills": len({c[0] for c in copies}),
+            "hooks": stack["hooks"],
+            "mcp": stack["mcp"],
+            "conflicts": conflicts(host, stack, repo),
+        }
+    return out
+
+
+def render(data):
+    lines = []
+    for host, s in data.items():
+        lines.append("== %s" % host)
+        lines.append("  context (load order):")
+        lines += ["    %s" % p for p in s["context"]] or ["    (none)"]
+        lines.append("  skills: %d names, %s copy wins" % (
+            s["skills"], "first" if s["skill_mode"] == "first" else "no single"))
+        lines += ["    %4d  %s" % (n, d) for d, n in s["skill_dirs"]]
+        lines.append("  hooks:")
+        for event, rows in sorted(s["hooks"].items()):
+            lines.append("    %-28s %s" % (event, " -> ".join(
+                "%s[%s]" % (who, src) for who, src, _cmd in rows)))
+        lines.append("  mcp: %s" % (", ".join(s["mcp"]) or "(none)"))
+        counts = {}
+        for kind, _ in s["conflicts"]:
+            counts[kind] = counts.get(kind, 0) + 1
+        lines.append("  conflicts: %s" % (", ".join(
+            "%s=%d" % kv for kv in sorted(counts.items())) or "none"))
+        lines += ["    %s  %s" % kv for kv in s["conflicts"]]
+    return "\n".join(lines)

package/hooks/tezgah_stopspec.py

@@ -52,7 +52,7 @@ ROW_ATOMS = (
     "Dc",     # a component write (`_design_evidence`)
     "Dk",     # a `tezgah-design check` that passed
     "X",      # a read of an external system's own state (`_external_read_row`)
-    "W",      # a work row (`WORK_KINDS`)
+    "W",      # a work row (`_work_row`: WORK_KINDS less a prose edit)
 )
 SCOPE_ATOMS = ("T",)  # the turn marker
 
@@ -213,7 +213,7 @@ class Trace:
                     and kind in ("run", "verify", "verify_ok", "verify_fail")
                     and bool(ti.EXTERNAL_READ.search(self.masked(i))))
         if name == "W":
-            return kind in ti.WORK_KINDS
+            return ti._work_row(row)
         if name == "T":
             return kind == ti.TURN_KIND
         raise KeyError(name)

package/hosts/codex/hook.py

@@ -29,7 +29,7 @@ try:
     from tezgah_context import (  # noqa: E402
         TOOL_USE_MEASURES, command_text, context_for, health_lines, record,
         shell_kind)
-    from tezgah_gate import decision  # noqa: E402
+    from tezgah_gate import decision, graph_advice  # noqa: E402
     from tezgah_integrity import (  # noqa: E402
         SUBAGENT_CHANNEL, bind_session, changed_files_notice, note_tool, ran_nothing,
         report_bytes, stop_reason, untrusted_source)
@@ -195,6 +195,12 @@ def main():
                             if untrusted_source(tool, inp) == SUBAGENT_CHANNEL
                             else result_size(result)),
                  empty_run=ran_nothing(result))
+        # The gate's graph line for a code-symbol search rides the same
+        # non-blocking channel (tezgah_gate.graph_advice): a Codex PreToolUse
+        # carries a deny and nothing else.
+        advice = (safe(session_id, graph_advice, tool, inp, cwd, "codex")
+                  if root_for(cwd) else None)
+        notice = "\n".join(p for p in (notice, advice) if p)
         if notice:
             # Codex's PostToolUse output carries `additionalContext` with the
             # result - the field is part of its own hook output schema

package/hosts/cursor/hook.py

@@ -48,7 +48,7 @@ from tezgah_guard import attest_session, import_failed, safe  # noqa: E402
 try:
     from tezgah_context import (  # noqa: E402
         command_text, context_for, record, shell_kind, slug, under)
-    from tezgah_gate import decision, explored  # noqa: E402
+    from tezgah_gate import decision, explored, graph_advice  # noqa: E402
     from tezgah_integrity import (  # noqa: E402
         SUBAGENT_CHANNEL, bind_session, note, note_tool, ran_nothing, report_bytes,
         stop_reason)
@@ -318,9 +318,12 @@ def dispatch(payload):
         if (kind in ("graph", "consult") and under(cwd) and not quiet
                 and first_time(session_id, "graph")):
             reinforce = REINFORCE
-        # both are one line for the model, on the result they belong to; a turn
-        # that earns both reads them together rather than one replacing the other
-        text = "\n".join(t for t in (notice, reinforce) if t)
+        # the gate's graph line for a code-symbol search (graph_advice) rides
+        # the same channel; all three are one line each for the model, on the
+        # result they belong to, read together rather than one replacing another
+        advice = (graph_advice(gate_name(payload.get("tool_name", "")), inp, cwd,
+                               "cursor") if under(cwd) and not quiet else None)
+        text = "\n".join(t for t in (notice, reinforce, advice) if t)
         out = {"additional_context": text} if text else {}
     elif event == "postToolUseFailure":
         if kind:

package/hosts/omp/hook.py

@@ -19,7 +19,8 @@ the same code every other host runs.
     {"event": "user_prompt", "cwd": ..., "prompt": ...}
         -> {"context": <reminder + the rules this prompt arms>}
     {"event": "pre_tool_use", "cwd": ..., "tool": ..., "input": {...}}
-        -> {"deny": reason}
+        -> {"deny": reason} | {"advice": line} (the graph line the bridge hands
+           the model with this call's result; never a block)
     {"event": "post_tool_use", "cwd": ..., "tool": ..., "input": {...},
      "failed": bool, "idx": glyph}
         -> {"status": "pony✓ ...", "idx": glyph, "label": one line}
@@ -57,7 +58,7 @@ try:
     from tezgah_context import (  # noqa: E402
         color_default, command_text, context_for, health_segments, record,
         render_tiers, shell_kind, skill_read_kind)
-    from tezgah_gate import decision  # noqa: E402
+    from tezgah_gate import decision, graph_advice  # noqa: E402
     from tezgah_integrity import (  # noqa: E402
         SUBAGENT_CHANNEL, bind_session, note, note_tool, stop_reason, untrusted_label,
         untrusted_source)
@@ -142,9 +143,12 @@ def handle(payload):
         # answered at every turn boundary
         return answered(*status_line(cwd, session_id))
     if event == "pre_tool_use":
-        reason = decision(payload.get("tool", ""), payload.get("input") or {},
-                          cwd, session_id)
-        return {"deny": reason} if reason else {}
+        tool, inp = payload.get("tool", ""), payload.get("input") or {}
+        reason = decision(tool, inp, cwd, session_id)
+        if reason:
+            return {"deny": reason}
+        advice = graph_advice(tool, inp, cwd, "omp")
+        return {"advice": advice} if advice else {}
     if not root_for(cwd):
         return {}
     if event == "session_start":
@@ -179,7 +183,9 @@ def handle(payload):
                               with_core=False)
         return {"context": context} if context else {}
     if event == "user_prompt":
-        context = context_for("user_prompt", cwd, payload)
+        # host="omp": the skill hint drops the absolute path, since omp's
+        # read tool resolves the skill:// address on its own
+        context = context_for("user_prompt", cwd, dict(payload, host="omp"))
         return {"context": context} if context else {}
     if event == "post_tool_use":
         tool = payload.get("tool", "")

package/hosts/omp/tezgah-hook.ts.in

@@ -263,11 +263,17 @@ function skillRead(tool: string, args: any): boolean {
 
 // The gate is only consulted for the tools the shared rule knows: the refusal
 // of the grep-only explorer (task/agent), the anti-shortcut and attribution
-// checks (bash), and the test-skip check (the edit/write names). An MCP tool is
+// checks (bash), the test-skip check (the edit/write names), and the code-graph
+// nudge on omp's search tools (grep, find, search, ast_grep). An MCP tool is
 // consulted when its name carries an effect verb (MCP_EFFECT, see `tool_call`).
-const GATED = ["grep", "bash", "shell", "command", "task", "agent", "edit",
-  "write", "multiedit", "notebookedit", "apply_patch", "edit_file", "write_file",
-  "search_replace", "powershell", "pwsh"];
+const GATED = ["grep", "find", "search", "ast_grep", "bash", "shell", "command",
+  "task", "agent", "edit", "write", "multiedit", "notebookedit", "apply_patch",
+  "edit_file", "write_file", "search_replace", "powershell", "pwsh"];
+
+// The gate's non-blocking graph line (tezgah_gate.graph_advice), held from the
+// call to its result: `tool_call` can only block, `tool_result` can hand the
+// model `additionalContext`, and carrying it across costs no second spawn.
+const ADVICE = new Map<string, string>();
 
 // The effect verbs of tezgah_integrity.MCP_VERBS, as one pattern: a read-only
 // MCP call (a code-graph query) reaches no content rule, so it pays no spawn.
@@ -647,15 +653,22 @@ export default function tezgahOmp(pi: any): void {
       return undefined;  // a hook that cannot answer cannot refuse either
     }
     if (res.deny) return { block: true, reason: res.deny };
+    if (res.advice && event?.toolCallId != null) {
+      ADVICE.set(String(event.toolCallId), String(res.advice));
+    }
     return undefined;
   });
 
   pi.on("tool_result", async (event: any, ctx: any) => {
     const tool = String(event?.toolName ?? "");
     const args = event?.input ?? {};
+    const id = event?.toolCallId != null ? String(event.toolCallId) : "";
+    const advice = ADVICE.get(id);
+    ADVICE.delete(id);
+    const graph = advice ? { additionalContext: advice } : undefined;
     if (!WATCHED.includes(tool.toLowerCase()) && !tool.startsWith("mcp__")
         && !skillRead(tool, args)) {
-      return;
+      return graph;
     }
     // Tri-state: an unread outcome must never be written as a passed check,
     // because the Stop rule below reads this ledger as evidence.
@@ -680,9 +693,9 @@ export default function tezgahOmp(pi: any): void {
     // place; every other result is left exactly as the host produced it.
     if (res.label) {
       const content = labelled(event?.content, res.label);
-      if (content) return { content };
+      if (content) return { content, ...graph };
     }
-    return undefined;
+    return graph;
   });
 
   pi.on("session_stop", async (event: any, ctx: any) => {

package/hosts/opencode/plugins/tezgah.js

@@ -105,7 +105,8 @@ const SETUP_BIN = join(CONFIG, "bin", "tezgah-setup")
 const CONTEXT_BIN = join(CONFIG, "bin", "tezgah-context")
 const CAPTURE_BIN = join(CONFIG, "bin", "tezgah-capture")
 const GATE_BIN = join(CONFIG, "bin", "tezgah-gate")
-const IDENT = /^[A-Za-z_][A-Za-z0-9_]{2,}$/
+const SEARCH_SYMBOL =
+  /^(?:\\b)?(?:(def|class|function|func|fn|interface|struct|type)\s+)?([A-Za-z_][A-Za-z0-9_]{2,})(\\?\()?(?:\\b)?$/
 // A hung core must not hold a tool call open. Every awaited core CLI runs
 // through `collect`, which gives it a deadline and answers a timeout with the
 // same fail-open value a missing binary or a non-zero exit gets: a core that
@@ -2111,10 +2112,12 @@ function ledgerStem(sessionID) {
 }
 
 // The nearest enclosing project that holds a codegraph index. The answer is the
-// indexed directory itself, which is what the nudge names.
+// indexed directory itself, which is what the nudge names; a `.no-graph` met
+// first is the repo's own switch (hooks/tezgah_gate.index_slug), so no index.
 function indexSlug(dir) {
   let d = dir
   for (;;) {
+    if (existsSync(join(d, ".no-graph"))) return null
     if (existsSync(join(d, GRAPH_DB))) return d
     const parent = d.replace(/\/[^/]+\/?$/, "")
     if (!parent || parent === d) return null
@@ -2122,17 +2125,23 @@ function indexSlug(dir) {
   }
 }
 
+// hooks/tezgah_gate.symbol_in: a code symbol (inner underscore, a lower-to-upper
+// step, or any identifier in a `def x` / `x(` pattern); a plain word such as
+// `TODO` is literal text and is never nudged.
+function symbolIn(text) {
+  const m = String(text || "").trim().replace(/^['"]+|['"]+$/g, "").match(SEARCH_SYMBOL)
+  if (!m) return null
+  const tok = m[2]
+  const shaped = tok.replace(/^_+|_+$/g, "").includes("_") || /[a-z][A-Z]/.test(tok)
+  return m[1] || m[3] || shaped ? tok : null
+}
+
 function identifierFrom(tool, args) {
-  if (tool === "grep") {
-    const p = String(args.pattern || "")
-    return IDENT.test(p) ? p : null
-  }
+  if (tool === "grep") return symbolIn(args.pattern)
   if (tool === "bash" || tool === "shell") {
     const cmd = String(args.command || "")
     const m = cmd.match(/(?:^|[|;&(]\s*|\s)(?:grep|rg)\s+((?:-\S+\s+)*)(\S+)/)
-    if (!m) return null
-    const tok = m[2].replace(/^['"]|['"]$/g, "")
-    return IDENT.test(tok) ? tok : null
+    return m ? symbolIn(m[2]) : null
   }
   return null
 }