psyclaw 0.27.22 → 0.28.0

package/vendor/ars/scripts/check_tools_allowlist.py

@@ -0,0 +1,538 @@
+#!/usr/bin/env python3
+"""Lint: pin the #514 tools-allowlist CONTENT on the three plugin agents (#524).
+
+#521 shipped `tools: Read, Write, Edit, Grep, Glob` on the three top-level
+plugin agents (deep-research sources + agents/ mirrors), but no lint read a
+frontmatter `tools` key: check_agents_mirror_sync.py pins mirror==source
+byte-equality (the PAIR, never the VALUE), and the runtime write-scope guard
+(scripts/ars_write_scope_guard.py) keys on agent NAME, never frontmatter. A
+future PR editing a source+mirror pair symmetrically back to `..., Bash` (or
+dropping `Grep`, or typoing a tool name) would pass every CI gate green —
+exactly the drift class the repo's defrift locks exist to catch (cf. the
+v3.15 locks). This lint pins the VALUE.
+
+Design: YAML is the authority, not a line scan. Claude Code defines these
+files as YAML frontmatter, and a raw-line/regex scan can never see every
+YAML-legal spelling of a key or value (quoted, tagged, aliased, escaped,
+`\\u0073`-escaped, tab-indented, flow/block list, `Bash(...)` specifier). So
+every semantic decision is read from a DUPLICATE-PRESERVING YAML node tree
+(`yaml.compose`, which — unlike `safe_load` — keeps a shadowed duplicate key
+visible AND resolves an alias into shared node identity). Any frontmatter
+that will not compose to a mapping, OR uses a merge key (`<<`) / alias
+(constructs that inject or share keys the literal-key scan cannot see), is a
+fail-closed ERROR, never a skip. The frontmatter fence is a COLUMN-0 `---`
+only, so an indented `---` inside a block scalar cannot truncate the block
+and hide keys below it. The exact PINNED_TOOLS_LINE raw-line check is kept
+ON TOP as an additive, stricter witness (it also pins byte-level form:
+CR-sensitive, so a symmetric LF→CRLF conversion is drift; and it fires when
+the verbatim pinned line is absent), but it can only ADD findings, never
+subtract them — the semantic node-tree check stands alone as the security
+floor.
+
+Invariants:
+  1. Every file in ALLOWLISTED_FILES exists, its frontmatter composes to a
+     YAML mapping with EXACTLY ONE `tools` key (counted from the
+     duplicate-preserving node tree, so a shadowed `"tools":` / `"tool\\u0073":`
+     duplicate is caught), and that key's value normalizes to exactly the
+     canonical five tools. On top, the single raw `tools:` frontmatter line
+     must be byte-equal to PINNED_TOOLS_LINE. Changing the allowlist is a
+     deliberate security-surface change: edit the agent files AND this
+     lint's PINNED_TOOLS_LINE in the same commit (standard lock semantics).
+  2. Frontmatter/guard reconciliation: any agent file under AGENT_DIRS whose
+     frontmatter `name` is a Bucket A key in
+     scripts/ars_phase_scope_manifest.json must NOT declare Bash in a
+     `tools:` key — in ANY YAML-legal form. `Bash` is matched as an exact
+     base tool name (`BashOutput` is a different tool and is not flagged;
+     `Bash(git:*)` normalizes to `Bash` and IS). The runtime guard denies
+     Bucket A agents ALL Bash (zero fail-open); a frontmatter advertising
+     Bash would silently widen capability in hook-less installs while
+     contradicting the guard in hook-active ones. Agents with no `tools:`
+     key inherit and are untouched (the runtime guard still fences them).
+     Fail-closed: an agent file whose frontmatter will not compose to a
+     mapping is treated as a POSSIBLE Bucket A member and errors (we cannot
+     read its `name` to clear it), and a Bucket A agent whose `tools` value
+     has an unrecognized shape (non-string list member, mapping) errors.
+
+The manifest is load-bearing for invariant 2, so a missing, unparseable, or
+non-mapping manifest FAILS the lint (fail-closed) rather than skipping.
+"""
+from __future__ import annotations
+
+import json
+import sys
+import unicodedata
+from pathlib import Path
+
+import yaml
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+
+# The exact frontmatter line shipped by #521 (frozen #514 spec). Single
+# source of truth for the VALUE — a symmetric source+mirror edit cannot
+# change it without touching this lint in the same commit.
+PINNED_TOOLS_LINE = "tools: Read, Write, Edit, Grep, Glob"
+CANONICAL_TOOLS = ("Read", "Write", "Edit", "Grep", "Glob")
+
+# The six #514 surfaces: three canonical sources + three agents/ mirrors
+# (mirror==source byte-equality is check_agents_mirror_sync.py's job; the
+# mirrors are still listed here so THIS lint stays correct even if that one
+# is skipped or edited — deliberately re-derived, not imported, per the
+# repo's independent-second-witness lint convention).
+ALLOWLISTED_FILES = (
+    "deep-research/agents/report_compiler_agent.md",
+    "deep-research/agents/research_architect_agent.md",
+    "deep-research/agents/synthesis_agent.md",
+    "agents/report_compiler_agent.md",
+    "agents/research_architect_agent.md",
+    "agents/synthesis_agent.md",
+)
+
+# Every directory that holds agent prompt files (invariant 2 scan surface).
+AGENT_DIRS = (
+    "deep-research/agents",
+    "academic-paper/agents",
+    "academic-paper-reviewer/agents",
+    "academic-pipeline/agents",
+    "shared/agents",
+    "agents",
+)
+
+MANIFEST = "scripts/ars_phase_scope_manifest.json"
+
+
+def _read_raw(path: Path) -> str:
+    """Read WITHOUT universal-newline translation, so a CRLF file keeps its
+    `\\r` bytes and cannot satisfy an exact LF line pin. A leading UTF-8 BOM
+    is stripped: a YAML reader (and Claude Code) skips it, so leaving it on
+    would make `\\ufeff---` fail the column-0 fence match and the whole file
+    read as frontmatter-less — a fail-open that lets a BOM-prefixed Bucket A
+    agent smuggle Bash past invariant 2's skip-when-no-frontmatter branch."""
+    return path.read_bytes().decode("utf-8").lstrip("")
+
+
+def _frontmatter(text: str) -> str | None:
+    """The raw YAML frontmatter block (the byte-faithful substring between the
+    two `---` fences), or None when the file has no frontmatter.
+
+    Line breaks are found with `str.splitlines`, which recognizes EVERY YAML
+    line break — `\\n`, `\\r\\n`, and a bare `\\r` (old-Mac) plus the Unicode
+    breaks NEL/LS/PS — so a bare-CR-delimited file is not silently read as
+    frontmatter-less and skipped (a real fail-open, #524 r8). A fence is
+    exactly `---` at column 0: an INDENTED `---` is block-scalar content, not
+    a fence (matching it would truncate the block and hide keys). The block
+    returned is the raw substring (original break bytes intact) so `compose`
+    sees the true bytes and the byte-witness — anchored to `start_mark.index`
+    — stays byte-faithful; a bare `\\r`/CRLF file therefore still fires the
+    byte-witness as drift."""
+    lines = text.splitlines(keepends=True)
+    if not lines or lines[0].splitlines()[0] != "---":
+        return None
+    # Byte offset just past the opening fence line (start of the block body).
+    body_start = len(lines[0])
+    offset = body_start
+    for raw in lines[1:]:
+        content = raw.splitlines()[0] if raw.splitlines() else raw
+        if content == "---":  # column-0 closing fence
+            return text[body_start:offset]
+        offset += len(raw)
+    return None
+
+
+def _mapping_node(block: str) -> yaml.MappingNode | None:
+    """The frontmatter composed to a DUPLICATE-PRESERVING mapping node, or
+    None when it is not a mapping / will not compose / is too deeply nested
+    to compose safely. Unlike `safe_load`, `compose` keeps a shadowed
+    duplicate key visible in the node tree. A RecursionError on pathological
+    nesting maps to None so the caller fails closed rather than crashing."""
+    try:
+        node = yaml.compose(block, Loader=yaml.SafeLoader)
+    except (yaml.YAMLError, RecursionError):
+        return None
+    return node if isinstance(node, yaml.MappingNode) else None
+
+
+_UNRESOLVED = object()
+
+
+def _scalar_py(scalar: yaml.ScalarNode) -> object:
+    """The Python value a scalar node resolves to, so `"tool\\u0073"`,
+    `'tools'`, and `tools` all compare equal. `compose` already stamps each
+    node with its resolved tag, so the SafeLoader constructs it exactly as
+    `safe_load` would (quotes, `\\u` escapes, explicit `!!` tags, block/flow
+    styles all honored). Any tag the safe constructor cannot build (a `<<`
+    merge scalar, an unknown `!Tag`) yields _UNRESOLVED so callers fail
+    closed rather than crash."""
+    try:
+        return yaml.SafeLoader("").construct_object(scalar)
+    except yaml.YAMLError:
+        return _UNRESOLVED
+
+
+_MERGE_TAG = "tag:yaml.org,2002:merge"
+
+
+def _uses_merge_or_alias(node: yaml.Node) -> bool:
+    """True if the composed frontmatter uses a YAML merge key (`<<`) or an
+    alias (`*name`). safe_load resolves both — a `<<: *base` injects a
+    `tools`/`name` the literal-key scan never sees, and an alias shares a
+    value node — so their presence makes the duplicate-preserving key scan
+    unsound. Detected from the COMPOSED NODE TREE, not text (text scanning is
+    not a sound YAML authority — the reviews' recurring lesson): the `merge`
+    tag can land on a node of ANY type (`<<:` is a scalar key, but `? !!merge
+    [x]` is a merge-tagged sequence/mapping key), so we check the tag on
+    every node before dispatching on its type; an alias surfaces as the SAME
+    node object reachable by two paths (compose resolves `*a` to shared
+    identity). These hand-authored files never need either, so we fail closed
+    rather than reimplement merge resolution. A RecursionError on pathological
+    nesting also fails closed (True) — we could not prove the tree clean."""
+    seen: set[int] = set()
+
+    def walk(nd: yaml.Node) -> bool:
+        if nd is None:
+            return False
+        if nd.tag == _MERGE_TAG:  # merge tag on ANY node type (key or value)
+            return True
+        if id(nd) in seen:
+            return True  # reached twice = an alias shares this node
+        seen.add(id(nd))
+        if isinstance(nd, yaml.SequenceNode):
+            return any(walk(i) for i in nd.value)
+        if isinstance(nd, yaml.MappingNode):
+            return any(walk(k) or walk(v) for k, v in nd.value)
+        return False
+
+    try:
+        return walk(node)
+    except RecursionError:
+        return True
+
+
+def _key_values(node: yaml.MappingNode, key: str) -> list[yaml.Node]:
+    """Every value node whose key resolves to `key`, duplicates included
+    (the node tree preserves a shadowed key that safe_load would collapse)."""
+    return [v for k, v in node.value
+            if isinstance(k, yaml.ScalarNode) and _scalar_py(k) == key]
+
+
+def _key_nodes(node: yaml.MappingNode, key: str) -> list[yaml.ScalarNode]:
+    """Every KEY node that resolves to `key` (for line marks), duplicates
+    included."""
+    return [k for k, v in node.value
+            if isinstance(k, yaml.ScalarNode) and _scalar_py(k) == key]
+
+
+def _node_to_py(value_node: yaml.Node) -> object:
+    """A value node converted to its Python value, or the sentinel
+    _UNRESOLVED when it is not a plain scalar/sequence of scalars (a nested
+    list, a mapping member, or a mapping value — all unrecognized shapes)."""
+    if isinstance(value_node, yaml.ScalarNode):
+        return _scalar_py(value_node)
+    if isinstance(value_node, yaml.SequenceNode):
+        if not all(isinstance(i, yaml.ScalarNode) for i in value_node.value):
+            return _UNRESOLVED  # nested list / mapping member
+        return [_scalar_py(i) for i in value_node.value]
+    return _UNRESOLVED
+
+
+def _fold(text: str) -> str:
+    """Text folded so an invisible/compatibility re-spelling collapses onto its
+    plain ASCII form. Removes Unicode format characters (category `Cf` —
+    BOM/`\\ufeff`, zero-width space/`\\u200b`, zero-width non-joiner/`\\u200c`,
+    etc.), which `str.strip()` does NOT remove, so `\\ufeffBash\\ufeff` would
+    otherwise survive as a token distinct from `Bash` and slip the `"Bash" in
+    declared` membership test (#524 r9) — a fenced Bucket A agent could declare
+    a zero-width-padded Bash and pass. Then NFKC-normalizes to fold
+    compatibility homoglyphs (fullwidth, etc.) onto ASCII. All six real tool
+    names + the `Bash(git:*)` permission form are pure ASCII and fold to
+    themselves, so no legitimate value is altered."""
+    stripped = "".join(c for c in text if unicodedata.category(c) != "Cf")
+    return unicodedata.normalize("NFKC", stripped)
+
+
+def _normalized_tools(value: object) -> list[str] | None:
+    """A `tools` value normalized to base tool names, or None when the shape
+    is unrecognized. Accepts the comma-string form and a list of strings; a
+    `Bash(git:*)`-style permission specifier normalizes to `Bash`. Folding
+    (`_fold`) happens BEFORE any split, on the whole string (or on each list
+    member whole), so every compatibility separator becomes its ASCII form
+    first: a fullwidth comma `，` (U+FF0C) in the string form — which
+    `split(",")` would miss, leaving `Read，Bash` as one token that an
+    NFKC-normalizing consumer would re-split to grant Bash (#524 r11) — and a
+    fullwidth-paren specifier `Bash（git:*）` (U+FF08/U+FF09) that the ASCII `(`
+    split would miss (#524 r10) both reduce correctly. Splitting before folding
+    reintroduces either hole. `value` comes from `_node_to_py`, which already
+    collapses a non-scalar list member to `_UNRESOLVED`, so a list reaching
+    here is all-strings; any non-str/list value (including `_UNRESOLVED`) is
+    unrecognized."""
+    if isinstance(value, str):
+        items: list[str] = _fold(value).split(",")
+    elif isinstance(value, list) and all(isinstance(i, str) for i in value):
+        # A YAML list is already tokenized; fold each member whole (a
+        # fullwidth comma inside a member is not a YAML separator, so it stays
+        # one token — correctly, since no list consumer re-splits an element).
+        items = [_fold(i) for i in value]
+    else:
+        return None
+    out = []
+    for item in items:
+        base = item.split("(", 1)[0].strip()
+        if base:
+            out.append(base)
+    return out
+
+
+def _raw_tools_line(block: str, key_node: yaml.ScalarNode) -> str | None:
+    """The raw frontmatter line the composed `tools` key SITS ON, for the
+    byte-exact PINNED_TOOLS_LINE witness. Anchored to the node's
+    `start_mark.index` — the character offset into `block` — sliced to the
+    surrounding physical-`\\n` line, NOT `start_mark.line` (which counts
+    YAML's Unicode line breaks NEL/LS/PS that `split("\\n")` does not, so the
+    two indexings can diverge and select the wrong line — #524 r7). Using the
+    byte offset makes the two agree by construction. Anchoring (not a text
+    scan) also means a `tools:`-looking line inside a block scalar — e.g. a
+    `description: |` documenting the tools — is never mistaken for the key
+    line (round-6 false-positive). An ADDITIVE (still CI-gating) layer on top
+    of the node-tree check: it only adds findings a capability-equivalent
+    re-spelling would slip past (CRLF, trailing/interior whitespace, exact
+    spelling), never clears the semantic check. Returns None when the offset
+    is out of range."""
+    idx = key_node.start_mark.index
+    if not (0 <= idx <= len(block)):
+        return None
+    start = block.rfind("\n", 0, idx) + 1        # char after the prev newline
+    end = block.find("\n", idx)                  # next newline, or end
+    return block[start:] if end == -1 else block[start:end]
+
+
+def _tools_value(node: yaml.MappingNode) -> object:
+    """The effective (last-wins) `tools` Python value from the node tree, or
+    _UNRESOLVED when the key is absent or its value has an unreadable shape."""
+    values = _key_values(node, "tools")
+    if not values:
+        return _UNRESOLVED
+    return _node_to_py(values[-1])  # YAML last-wins
+
+
+def _name_value(node: yaml.MappingNode) -> str:
+    """The effective `name` from the node tree ('' when absent/non-scalar)."""
+    values = _key_values(node, "name")
+    if not values:
+        return ""
+    py = _node_to_py(values[-1])
+    return str(py).strip() if isinstance(py, str) else ""
+
+
+def _bucket_a_names(root: Path) -> tuple[set[str] | None, str | None]:
+    """Bucket A agent names from the manifest, or (None, error)."""
+    mp = root / MANIFEST
+    try:
+        data = json.loads(mp.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        return None, (
+            f"{MANIFEST}: unreadable or unparseable ({exc}) — invariant 2 "
+            "(frontmatter/guard reconciliation) cannot run; failing closed."
+        )
+    agents = data.get("agents") if isinstance(data, dict) else None
+    if not isinstance(agents, dict):
+        return None, (
+            f"{MANIFEST}: no `agents` mapping — invariant 2 cannot run; "
+            "failing closed."
+        )
+    return set(agents), None
+
+
+def check(root: Path) -> list[str]:
+    errors: list[str] = []
+
+    # --- invariant 1: exactly-one canonical `tools` on the six files ---------
+    for rel in ALLOWLISTED_FILES:
+        path = root / rel
+        if not path.is_file():
+            errors.append(
+                f"{rel}: allowlisted agent file is missing — the #514 "
+                "surface changed; update ALLOWLISTED_FILES in "
+                "check_tools_allowlist.py deliberately or restore the file."
+            )
+            continue
+        block = _frontmatter(_read_raw(path))
+        if block is None:
+            errors.append(f"{rel}: no YAML frontmatter block found.")
+            continue
+        node = _mapping_node(block)
+        if node is None:
+            errors.append(
+                f"{rel}: frontmatter does not compose to a YAML mapping — "
+                "the tools allowlist cannot be verified; failing closed."
+            )
+            continue
+        if _uses_merge_or_alias(node):
+            errors.append(
+                f"{rel}: frontmatter uses a YAML merge key / alias — these "
+                "resolve to keys the pin cannot see (a `<<` can inject a "
+                "`tools` value); not supported in agent frontmatter, "
+                "failing closed."
+            )
+            continue
+        tools_nodes = _key_values(node, "tools")
+        if not tools_nodes:
+            errors.append(
+                f"{rel}: frontmatter has no `tools:` key — the #514 "
+                "allowlist was dropped (a silent capability widening: the "
+                "agent would inherit ALL tools). Restore "
+                f"`{PINNED_TOOLS_LINE}`."
+            )
+        elif len(tools_nodes) > 1:
+            errors.append(
+                f"{rel}: {len(tools_nodes)} `tools` keys in frontmatter "
+                "(duplicate-preserving parse — quoted / escaped variants "
+                "included) — exactly one expected; a duplicate key overrides "
+                "the pinned value under YAML last-wins resolution."
+            )
+        else:
+            normalized = _normalized_tools(_node_to_py(tools_nodes[0]))
+            if normalized != list(CANONICAL_TOOLS):
+                errors.append(
+                    f"{rel}: the `tools` value diverges from the canonical "
+                    f"{', '.join(CANONICAL_TOOLS)} — the effective allowlist "
+                    "is not what #514 froze."
+                )
+        # Byte-exact witness ON TOP (also pins CRLF / spelling). Additive
+        # layer: it can only add findings, never clear the semantic check.
+        # Anchored to the composed `tools` key's own line (not a text scan),
+        # so a `tools:`-looking line inside a block scalar is not mistaken for
+        # it. Only meaningful for the exactly-one-key case; the missing /
+        # duplicate cases already fired via the semantic branch above. A
+        # non-verbatim line (escaped/tagged/folded spelling, or CRLF /
+        # whitespace drift) fires — the semantic check independently catches
+        # the value-changing subset.
+        key_nodes = _key_nodes(node, "tools")
+        if len(key_nodes) == 1:
+            raw_line = _raw_tools_line(block, key_nodes[0])
+            if raw_line != PINNED_TOOLS_LINE:
+                found = raw_line if raw_line is not None else \
+                    "(tools key not on its own line)"
+                errors.append(
+                    f"{rel}: the `tools` line is not byte-equal to the frozen "
+                    f"#514 form.\n    expected: {PINNED_TOOLS_LINE}\n    "
+                    f"found:    {found!r}\n  Changing the allowlist is a "
+                    "deliberate security-surface change: update "
+                    "PINNED_TOOLS_LINE in check_tools_allowlist.py in the "
+                    "same commit."
+                )
+
+    # --- invariant 2: no Bucket A agent declares Bash -------------------------
+    bucket_a, manifest_err = _bucket_a_names(root)
+    if manifest_err:
+        errors.append(manifest_err)
+        return errors
+    for rel_dir in AGENT_DIRS:
+        d = root / rel_dir
+        if not d.is_dir():
+            continue
+        # rglob does NOT descend into directory symlinks, so a tracked
+        # `agents/nested -> ../payload` could hide a Bucket A `.md` declaring
+        # Bash (#524 r8). Fail closed on any directory symlink under an agent
+        # dir — these hand-authored trees have no reason for one, and
+        # reconciliation cannot see through it.
+        for sub in sorted(d.rglob("*")):
+            if sub.is_symlink() and sub.is_dir():
+                errors.append(
+                    f"{sub.relative_to(root).as_posix()}: directory symlink "
+                    "under an agent dir — rglob does not descend into it, so a "
+                    "Bucket A agent declaring Bash could hide behind it; "
+                    "failing closed. Replace with real files."
+                )
+        # rglob, not glob: a nested `agents/subdir/x.md` could carry a Bucket
+        # A `name` + Bash and the runtime guard keys on name regardless of
+        # path, so the reconciliation must reach nested files too (#524 r7).
+        for path in sorted(d.rglob("*.md")):
+            rel = path.relative_to(root).as_posix()
+            block = _frontmatter(_read_raw(path))
+            if block is None:
+                continue
+            node = _mapping_node(block)
+            if node is None:
+                # Cannot read `name` to clear it — treat as a possible
+                # Bucket A member and fail closed.
+                errors.append(
+                    f"{rel}: agent frontmatter does not compose to a YAML "
+                    "mapping — cannot confirm it is not a Bucket A agent "
+                    "advertising Bash; failing closed."
+                )
+                continue
+            if _uses_merge_or_alias(node):
+                # A `<<`/alias could inject `tools` or rewrite `name`
+                # invisibly to the literal-key scan — fail closed rather than
+                # clear the file on a name it may not really carry.
+                errors.append(
+                    f"{rel}: agent frontmatter uses a YAML merge key / alias "
+                    "— cannot soundly confirm it is not a Bucket A agent "
+                    "advertising Bash; failing closed."
+                )
+                continue
+            # Duplicate `name`/`tools` handling is parser-dependent (last-wins
+            # here, but another consumer may take first-wins). If ANY resolved
+            # `name` is a Bucket A key, the file is in scope — and if it also
+            # carries a duplicate `tools`, one resolution could hide Bash
+            # behind the other. Fail closed rather than pick a winner, exactly
+            # as invariant 1 rejects a duplicate `tools`.
+            name_nodes = _key_values(node, "name")
+            resolved_names = {_node_to_py(n) for n in name_nodes}
+            if not resolved_names & bucket_a:
+                continue
+            if len(name_nodes) > 1:
+                errors.append(
+                    f"{rel}: {len(name_nodes)} `name` keys in frontmatter, one "
+                    "resolving to a Bucket A agent — duplicate-key resolution "
+                    "is parser-dependent; failing closed."
+                )
+                continue
+            if len(_key_values(node, "tools")) > 1:
+                errors.append(
+                    f"{rel}: Bucket A agent has {len(_key_values(node, 'tools'))} "
+                    "`tools` keys — duplicate-key resolution is "
+                    "parser-dependent and one could hide Bash behind another; "
+                    "failing closed."
+                )
+                continue
+            tools_value = _tools_value(node)
+            if tools_value is _UNRESOLVED:
+                if _key_values(node, "tools"):
+                    errors.append(
+                        f"{rel}: Bucket A agent has a `tools` value of "
+                        "unrecognized shape — cannot verify it excludes "
+                        "Bash; failing closed."
+                    )
+                continue
+            declared = _normalized_tools(tools_value)
+            if declared is None:
+                errors.append(
+                    f"{rel}: Bucket A agent has a `tools` value of "
+                    "unrecognized shape — cannot verify it excludes Bash; "
+                    "failing closed."
+                )
+            elif "Bash" in declared:
+                errors.append(
+                    f"{rel}: frontmatter declares Bash but this is a Bucket "
+                    f"A agent in {MANIFEST} — the runtime guard denies "
+                    "Bucket A agents ALL Bash (zero fail-open), so this "
+                    "grant is either dead (hook-active) or a silent widening "
+                    "(hook-less). Remove Bash from the tools list."
+                )
+
+    return errors
+
+
+def main() -> int:
+    errors = check(REPO_ROOT)
+    if errors:
+        print("tools allowlist check failed (#524):")
+        for err in errors:
+            print(f"- {err}")
+        return 1
+    print("tools allowlist check passed.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())