imbad0202__academic-research-skills/scripts/check_tools_allowlist.py

#!/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())