@jaguilar87/gaia 5.0.9 → 5.0.10

package/dist/gaia-ops/hooks/modules/tools/bash_validator.py

@@ -911,6 +911,57 @@ class BashValidator:
             reason="Safe by elimination (not blocked, not mutative)",
         )
 
+    def _is_ungranted_t3_component(
+        self, component: str, session_id: str
+    ) -> bool:
+        """Classify a chain component as ungranted-T3 WITHOUT minting or consuming.
+
+        Returns True when the component is a T3 (mutative-verb or
+        flag-dependent) operation for which NO active grant exists -- i.e. the
+        component would, on its own, be blocked pending approval. This is a
+        read-only probe used by the chain COMMAND_SET intake (AC-8) to decide
+        whether >= 2 sub-commands need grouping under ONE consent, BEFORE any
+        per-component minting happens.
+
+        It deliberately does NOT call decide_t3_outcome (no pending minted) and
+        does NOT consume any grant (match_command_set_grant /
+        check_approval_grant are pure lookups; consumption happens later in the
+        real _validate_single_command pass at retry). A component that already
+        matches a COMMAND_SET or semantic grant is treated as NOT ungranted, so
+        it is excluded from a fresh batch.
+        """
+        component = component.strip()
+        if not component:
+            return False
+
+        # Is this T3 (mutative verb or flag-dependent mutation)?
+        detect = detect_mutative_command(component)
+        is_t3 = detect.is_mutative
+        if not is_t3:
+            flag_result = classify_by_flags(component)
+            if (
+                flag_result is not None
+                and flag_result.outcome == FLAG_MUTATIVE
+                and not flag_result.command_family.startswith("git_")
+            ):
+                is_t3 = True
+        if not is_t3:
+            return False
+
+        # Already covered by an active grant? Then it is NOT ungranted -- exclude
+        # it from a fresh batch (pure lookups, no consumption).
+        try:
+            if match_command_set_grant(component) is not None:
+                return False
+        except Exception:
+            pass
+        try:
+            if check_approval_grant(component, session_id=session_id) is not None:
+                return False
+        except Exception:
+            pass
+        return True
+
     def _validate_compound_command(
         self,
         components: List[str],
@@ -918,9 +969,68 @@ class BashValidator:
         session_id: str = "",
         agent_type: str = "",
     ) -> BashValidationResult:
-        """Validate a compound command (multiple components)."""
+        """Validate a compound command (multiple components).
+
+        Chain COMMAND_SET intake (AC-8): when a chain ``a && b && c`` has TWO OR
+        MORE sub-commands that are ungranted T3, classifying them one-at-a-time
+        mints a single-signature pending for the FIRST and short-circuits -- so
+        one approval covers only the first sub-command and the next re-blocks
+        (the double-approval the user hit). To group them, a NON-MINTING
+        classification pass runs FIRST (``_is_ungranted_t3_component``); if >= 2
+        sub-commands are ungranted-T3 (and we are a subagent under the
+        orchestrator), ONE COMMAND_SET pending is minted over exactly those T3
+        sub-commands via ``decide_t3_outcome(command_set=...)``. One approval
+        then covers the chain; each sub-command is still consumed byte-for-byte
+        by its own signature at retry (no consent is widened -- the commands are
+        only grouped). Critically, the per-component minting path
+        (_validate_single_command) is NEVER entered for the batch, so no stray
+        single pendings are minted alongside the COMMAND_SET.
+
+        For every other shape (0 or 1 ungranted-T3, no orchestrator above, or a
+        component that is hard-blocked) the original per-component pass runs
+        unchanged: a hard block fails the chain fast, a lone T3 keeps the
+        singular grant path, and an all-granted/safe chain is allowed.
+        """
         logger.info(f"Compound command detected with {len(components)} components")
 
+        # NON-MINTING pre-pass: which components are ungranted T3? (AC-8)
+        if is_subagent and is_ops_mode():
+            ungranted_t3_idx = [
+                idx
+                for idx, comp in enumerate(components)
+                if self._is_ungranted_t3_component(comp, session_id)
+            ]
+            if len(ungranted_t3_idx) >= 2:
+                chain_set = [
+                    {"command": components[idx].strip(), "rationale": ""}
+                    for idx in ungranted_t3_idx
+                ]
+                first_cmd = chain_set[0]["command"]
+                first_detect = detect_mutative_command(first_cmd)
+                verb = first_detect.verb or "command"
+                category = first_detect.category or "MUTATIVE"
+                native_ask_reason = (
+                    f"[T3_APPROVAL_REQUIRED] Chain of {len(chain_set)} T3 commands.\n"
+                    f"Commands:\n"
+                    + "\n".join(f"  - {it['command']}" for it in chain_set)
+                )
+                logger.info(
+                    "Chain COMMAND_SET intake: %d T3 sub-commands grouped under "
+                    "one consent (chain=%s)",
+                    len(chain_set),
+                    " && ".join(it["command"][:30] for it in chain_set),
+                )
+                return decide_t3_outcome(
+                    first_cmd,
+                    verb=verb,
+                    category=category,
+                    has_orchestrator_above=True,
+                    native_ask_reason=native_ask_reason,
+                    session_id=session_id,
+                    agent_type=agent_type,
+                    command_set=chain_set,
+                )
+
         component_results: List[BashValidationResult] = []
         for i, component in enumerate(components, 1):
             result = self._validate_single_command(
@@ -1385,6 +1495,7 @@ def decide_t3_outcome(
     native_ask_reason: str,
     session_id: str = "",
     agent_type: str = "",
+    command_set: list | None = None,
 ) -> BashValidationResult:
     """Single decision point for the outcome of a T3 (state-mutating) command.
 
@@ -1416,34 +1527,68 @@ def decide_t3_outcome(
         native_ask_reason: Reason text for the native-ask fallback branch.
         session_id: Session ID for pending-approval scoping.
         agent_type: Originating agent name (for the sealed payload).
+        command_set: Optional list of ``{command, rationale}`` dicts. When it
+            carries MORE THAN ONE item, this T3 decision covers a chain
+            (``a && b && c``) whose sub-commands are all T3, and the pending is
+            minted as ONE COMMAND_SET envelope (the chain-intake path, AC-8)
+            instead of a single semantic-signature pending. ONE user approval
+            then covers the whole chain; each sub-command is still consumed
+            byte-for-byte by its own signature at retry. A None / single-item
+            set keeps the singular behaviour. Only honoured in the
+            subagent-under-orchestrator branch (the native-ask branch has no
+            COMMAND_SET concept).
 
     Returns:
         A blocked BashValidationResult (allowed=False, tier T3) whose
         block_response is either a "deny" (with approval_id) or an "ask".
     """
+    # A genuine multi-command chain is a set of >= 2 items. Anything else
+    # collapses to the singular path so we never mint a COMMAND_SET for one
+    # command (mirrors _build_sealed_payload's is_command_set guard).
+    _normalized_set: list = []
+    if command_set:
+        for _item in command_set:
+            if isinstance(_item, dict) and _item.get("command"):
+                _normalized_set.append(
+                    {
+                        "command": _item["command"],
+                        "rationale": _item.get("rationale", ""),
+                    }
+                )
+    is_chain_command_set = len(_normalized_set) > 1
+
     if has_orchestrator_above:
         # Subagent-under-orchestrator: deny + persisted approval_id so the
         # orchestrator can run the approval cycle.  Reuse an existing pending
         # approval on retry to avoid generating duplicates while the user reviews.
-        approval_id = _find_pending_in_db(session_id or "", command)
-        if approval_id:
-            logger.info(
-                "Reusing pending approval_id=%s for retry: %s",
-                approval_id, command[:80],
-            )
-            reason = build_t3_blocked_denial_message(
-                approval_id=approval_id,
-                command=command,
-                verb=verb,
-                category=category,
-            )
-            hook_deny = build_hook_permission_response("deny", reason)
-            return BashValidationResult(
-                allowed=False,
-                tier=SecurityTier.T3_BLOCKED,
-                reason=f"T3 {category.lower()} command: {command[:60]}",
-                block_response=hook_deny,
-            )
+        #
+        # For a COMMAND_SET chain the pending id is CONTENT-derived (matching the
+        # plan-first intake), so a retry of the same chain produces the same id
+        # and the fingerprint-dedup in insert_requested reuses the pending. The
+        # singular reuse probe (_find_pending_in_db) matches a SINGLE command's
+        # signature and must NOT be consulted for the chain -- it would match one
+        # leftover single pending of a sub-command and degrade the chain back to
+        # a single grant. So the chain path skips it entirely.
+        if not is_chain_command_set:
+            approval_id = _find_pending_in_db(session_id or "", command)
+            if approval_id:
+                logger.info(
+                    "Reusing pending approval_id=%s for retry: %s",
+                    approval_id, command[:80],
+                )
+                reason = build_t3_blocked_denial_message(
+                    approval_id=approval_id,
+                    command=command,
+                    verb=verb,
+                    category=category,
+                )
+                hook_deny = build_hook_permission_response("deny", reason)
+                return BashValidationResult(
+                    allowed=False,
+                    tier=SecurityTier.T3_BLOCKED,
+                    reason=f"T3 {category.lower()} command: {command[:60]}",
+                    block_response=hook_deny,
+                )
 
         # No existing pending -- insert via DB (D16: exclusive path).
         sealed_payload = _build_sealed_payload(
@@ -1451,13 +1596,25 @@ def decide_t3_outcome(
             verb=verb,
             category=category,
             agent_type=agent_type,
+            command_set=_normalized_set if is_chain_command_set else None,
         )
         try:
             from gaia.approvals.store import insert_requested
+            # COMMAND_SET chains use a CONTENT-derived id (deterministic over the
+            # sub-command list) so a retry of the same chain reproduces the same
+            # id and reuses the pending via fingerprint dedup -- identical to the
+            # plan-first intake in handoff_persister. Singular T3 keeps uuid4.
+            supplied_id = None
+            if is_chain_command_set:
+                from gaia.approvals.store import derive_command_set_id
+                supplied_id = derive_command_set_id(
+                    [it["command"] for it in _normalized_set]
+                )
             approval_id = insert_requested(
                 sealed_payload,
                 agent_id=agent_type or None,
                 session_id=session_id or None,
+                approval_id=supplied_id,
             )
         except Exception as _store_err:
             logger.warning(

package/dist/gaia-ops/skills/security-tiers/SKILL.md

@@ -42,7 +42,7 @@ The runtime, not this skill, enforces tiers. Three modules layer the decision:
 
 - `tiers.py` -- the `SecurityTier` enum (`T0_READ_ONLY`, `T1_VALIDATION`, `T2_DRY_RUN`, `T3_BLOCKED`) and `_classify_command_tier_cached` assign every command a tier.
 - `blocked_commands.py` -- pattern-matches irreversible commands and permanently denies them (exit 2, never approvable).
-- `mutative_verbs.py` -- CLI-agnostic detection of mutative verbs; drives the nonce / approval flow for T3.
+- `mutative_verbs.py` -- CLI-agnostic detection of mutative verbs; drives the nonce / approval flow for T3. Includes script-file detection (Step 1d, `_check_script_file`): when a command is `<interpreter> <script-file>` (`python3 deploy.py`, `bash setup.sh`, `node migrate.js`) or `./script.ext`, the file is read and classified by its real invocations -- AST analysis for Python, the blocked/mutative regex layer for shells and other interpreters. A script that is missing, unreadable, or whose interpreter is unrecognized defaults to T3 (conservative). This prevents the evasion path where `<interp> <file>` bypasses the verb scanner because the filename token has no recognizable subcommand.
 - `composition_rules.py` -- `check_composition` / `classify_stage` classify pipe compositions (FILE_READ→EXEC_SINK, network→exec, decode→exec); triggers T3 on dangerous pipelines such as `file_to_exec`.
 - `flag_classifiers.py` -- `_classify_curl` / `classify_by_flags` detect flag-dependent mutations; triggers T3 on commands whose flags make them mutative (e.g., `curl -X POST`).
 

package/dist/gaia-security/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gaia-security",
-  "version": "5.0.9",
+  "version": "5.0.10",
   "description": "Keeps you in the loop only when it matters. Gaia Security analyzes every command and classifies it into risk tiers: read-only queries run freely, simulations and validations pass through, and state-changing operations (create, delete, apply, push) pause for your explicit approval before executing. Irreversible commands like dropping databases or deleting cloud infrastructure are permanently blocked.",
   "author": {
     "name": "jaguilar87",

package/dist/gaia-security/hooks/modules/core/plugin_setup.py

@@ -347,11 +347,6 @@ def setup_project_permissions() -> bool:
     existing["permissions"]["deny"] = merged_deny
     existing["permissions"].setdefault("ask", [])
 
-    # Add env vars (smart merge: add if not present, don't overwrite)
-    env = existing.setdefault("env", {})
-    if "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS" not in env:
-        env["CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS"] = "1"
-
     claude_dir.mkdir(parents=True, exist_ok=True)
     settings_path.write_text(json.dumps(existing, indent=2) + "\n")
     logger.info("Merged gaia %s permissions and env into %s", mode, settings_path)

package/dist/gaia-security/hooks/modules/security/capability_classes.py

@@ -42,12 +42,21 @@ as follows:
 1. If a redirect-input token (``<``) or a pipe-input is present, the
    payload is considered external and uninspected -- keep MUTATIVE.
 2. If a positional argument starts with a sqlite-style dot-command that
-   loads a script (``.read``, ``.import``, ``.restore``), keep MUTATIVE.
-3. If a flag override matches (e.g. ``-readonly``), classify as READ_ONLY.
-4. If the command exposes an inline payload via a recognised flag pair
+   loads or executes a script / writes to disk (``.read``, ``.import``,
+   ``.restore``, ``.clone``, ``.load``, ``.system``, ``.shell``, ``.save``),
+   keep MUTATIVE.
+3. If every dot-command present is a strictly read-only sqlite3 schema /
+   metadata command (``.schema``, ``.tables``, ``.databases``,
+   ``.indexes`` / ``.indices``, ``.dbinfo``, ``.show``, ``.fullschema``),
+   classify as READ_ONLY.  This check runs *after* rule 2, so the
+   write-capable dot-commands above are caught first and never downgraded;
+   ``.dump`` / ``.output`` / ``.once`` / ``.backup`` are deliberately left
+   out of the read-only set (conservative) and fall through to MUTATIVE.
+4. If a flag override matches (e.g. ``-readonly``), classify as READ_ONLY.
+5. If the command exposes an inline payload via a recognised flag pair
    (``-c``, ``-e``, ``--eval``) and the payload matches the read-only
    regex, classify as READ_ONLY.
-5. Otherwise return ``default_intent`` (MUTATIVE).
+6. Otherwise return ``default_intent`` (MUTATIVE).
 
 A future Nivel 2 (`sql_payload_analyzer.py`) will parse external SQL files
 and inline payloads into an AST and downgrade more cases -- e.g., a file
@@ -105,6 +114,29 @@ _SQLITE_MUTATIVE_DOT_COMMANDS: FrozenSet[str] = frozenset({
     ".read", ".import", ".restore", ".clone", ".load", ".system", ".shell", ".save",
 })
 
+#: SQLite dot-commands that are strictly read-only schema/metadata introspection.
+#: These produce no side effects on the database file and write nothing to disk.
+#:
+#: NOT included (remain MUTATIVE):
+#:   .import, .restore, .backup, .clone, .save  -- write to db/file
+#:   .read                                       -- executes an arbitrary script
+#:   .output / .once                             -- redirects output to a file
+#:   .load                                       -- loads a native extension (exec)
+#:   .system / .shell                            -- arbitrary OS command execution
+#:   .dump                                       -- NOT included: commonly piped to
+#:                                                  files and by default prints the
+#:                                                  full db; conservative exclusion.
+_SQLITE_READONLY_DOT_COMMANDS: FrozenSet[str] = frozenset({
+    ".schema",      # prints CREATE statements for tables/indexes
+    ".tables",      # lists tables in the database
+    ".databases",   # lists attached databases
+    ".indexes",     # lists indexes for a table or all tables
+    ".indices",     # alias for .indexes
+    ".dbinfo",      # prints low-level metadata about the db file
+    ".show",        # prints current settings (not data)
+    ".fullschema",  # prints CREATE statements including schema_table
+})
+
 #: Tokens shlex emits for unquoted shell redirects.  Their presence in the
 #: positional argument stream means the inline command was fed from an
 #: external source -- the payload is uninspected at Nivel 1.
@@ -258,6 +290,29 @@ def _has_sqlite_load_dot_command(tokens: Tuple[str, ...]) -> bool:
     return False
 
 
+def _has_sqlite_readonly_dot_command(tokens: Tuple[str, ...]) -> bool:
+    """Return True when ALL dot-commands present in the tokens are
+    strictly read-only schema/metadata commands.
+
+    Returns False (falls through) when no dot-command is present so the
+    regular inline-payload and default rules continue to apply.
+    Returns False when a dot-command outside the read-only allowlist is
+    found -- the caller should treat those as MUTATIVE.
+    """
+    dot_cmds_found = []
+    for tok in tokens:
+        stripped = tok.strip().strip('"').strip("'")
+        first_word = stripped.split(None, 1)[0] if stripped else ""
+        if first_word.startswith("."):
+            dot_cmds_found.append(first_word.lower())
+
+    if not dot_cmds_found:
+        return False
+
+    # Every dot-command present must be in the read-only set.
+    return all(cmd in _SQLITE_READONLY_DOT_COMMANDS for cmd in dot_cmds_found)
+
+
 # ============================================================================
 # Main entry point
 # ============================================================================
@@ -271,8 +326,16 @@ def classify_capability(semantics: CommandSemantics) -> CapabilityResult:
 
     Resolution order (mirrors module docstring):
 
-    1. External payload (redirect ``<`` or sqlite ``.read``-style command)
-       -> MUTATIVE.
+    1. External payload (redirect ``<``) -> MUTATIVE.
+    1b. sqlite write-capable dot-command (``.read`` / ``.import`` /
+        ``.restore`` / ``.clone`` / ``.load`` / ``.system`` / ``.shell`` /
+        ``.save``) -> MUTATIVE.
+    1c. sqlite read-only schema/metadata dot-command (``.schema`` /
+        ``.tables`` / ``.databases`` / ``.indexes`` / ``.indices`` /
+        ``.dbinfo`` / ``.show`` / ``.fullschema``) -> READ_ONLY.  Runs after
+        1b so write-capable dot-commands are never downgraded; ``.dump`` /
+        ``.output`` / ``.once`` / ``.backup`` are excluded (conservative)
+        and fall through to the default.
     2. Flag override -> READ_ONLY.
     3. Inline-payload override -> READ_ONLY.
     4. Default -> ``default_intent`` (always MUTATIVE today).
@@ -314,6 +377,20 @@ def classify_capability(semantics: CommandSemantics) -> CapabilityResult:
             ),
         )
 
+    # --- Rule 1c: sqlite read-only dot-commands -> READ_ONLY ----------------
+    # Must run after the mutative-dot-command check so that write-capable
+    # dot-commands (.read, .import, ...) are never downgraded here.
+    if base_cmd in {"sqlite3", "sqlite"} and _has_sqlite_readonly_dot_command(tokens):
+        return CapabilityResult(
+            matched=True,
+            capability_class=class_name,
+            intent=CATEGORY_READ_ONLY,
+            reason=(
+                f"{class_name}: sqlite dot-command is a read-only schema/metadata "
+                "introspection command (.schema / .tables / .databases / ...)"
+            ),
+        )
+
     # --- Rule 2: flag-based overrides ---------------------------------------
     flag_overrides = [
         rule["flag"] for rule in overrides

package/dist/gaia-security/hooks/modules/security/inline_ast_analyzer.py

@@ -38,6 +38,7 @@ from __future__ import annotations
 
 import ast
 import logging
+import re
 from dataclasses import dataclass
 from typing import FrozenSet, Optional, Set, Tuple
 
@@ -239,6 +240,242 @@ def analyze_python_inline(code: str) -> InlineAstResult:
     return InlineAstResult()
 
 
+# ============================================================================
+# Provable read-only classification (positive allowlist)
+# ============================================================================
+# Rationale: ``analyze_python_inline`` uses a *blocklist* — a clean result
+# means "no KNOWN dangerous call was found", which is NOT the same as
+# "read-only".  Bound-method mutations the catalog cannot see statically —
+# ``cur.execute("INSERT ...")``, ``con.commit()``, ``f.write(...)`` on a
+# handle whose write-mode was set elsewhere — parse cleanly yet mutate.
+#
+# This second classifier exists ONLY to safely exempt long-but-harmless
+# inline code from the length heuristic (``heuristic-long-code``).  It is the
+# inverse discipline: it returns True ONLY when EVERY statement and EVERY call
+# in the payload is on a positive read-only allowlist.  Anything unrecognized
+# — any node type, call target, assignment target, or SQL verb it cannot
+# prove safe — makes it return False, leaving the length heuristic in force.
+# No-false-negative is the contract: a mutation must never be classified
+# read-only, even at the cost of leaving some genuinely-read-only payloads
+# subject to the length flag (those remain T3-approvable, never silently run).
+
+# Builtins that never mutate external state.  Deliberately conservative:
+# ``open`` is excluded (write modes), ``exec``/``eval``/``compile``/
+# ``__import__``/``input``/``getattr``/``setattr``/``delattr`` are excluded
+# (dynamic dispatch defeats static analysis), ``print`` is allowed (stdout
+# only).
+_READ_ONLY_BUILTINS: FrozenSet[str] = frozenset({
+    "print", "len", "str", "repr", "int", "float", "bool", "list", "tuple",
+    "dict", "set", "frozenset", "sorted", "reversed", "enumerate", "zip",
+    "map", "filter", "range", "sum", "min", "max", "abs", "round", "any",
+    "all", "format", "ascii", "bin", "hex", "oct", "ord", "chr", "type",
+    "isinstance", "issubclass", "hasattr", "iter", "next", "bytes",
+    "bytearray", "id", "hash", "divmod", "pow", "vars", "dir",
+})
+
+# Read-only methods, matched by leaf attribute name regardless of receiver.
+# These are common DB-cursor / mapping / sequence / string read accessors.
+# ``execute``/``executemany``/``executescript`` are handled SEPARATELY: they
+# are allowed ONLY when the SQL argument is a literal read-only statement.
+_READ_ONLY_METHODS: FrozenSet[str] = frozenset({
+    # DB cursor/connection read surface
+    "fetchone", "fetchall", "fetchmany", "cursor", "close",
+    # mapping / sequence reads
+    "keys", "values", "items", "get", "copy", "index", "count",
+    # string reads
+    "strip", "lstrip", "rstrip", "split", "rsplit", "splitlines", "join",
+    "lower", "upper", "title", "capitalize", "startswith", "endswith",
+    "find", "rfind", "format", "encode", "decode", "replace", "zfill",
+    "ljust", "rjust", "center",
+    # iteration / misc pure reads
+    "isoformat", "total_seconds", "group", "groups", "groupdict", "read",
+    "readline", "readlines",
+})
+
+# SQL statement prefixes that are read-only.  Matched case-insensitively
+# against the leading token of a literal SQL string.  ``WITH`` (CTE) is
+# allowed only when it ultimately SELECTs — but a CTE can wrap an
+# INSERT/UPDATE/DELETE (``WITH x AS (...) DELETE ...``), so to stay airtight
+# we require the literal to ALSO contain no mutating keyword.  Simpler and
+# safer: allow the prefix, then reject if any mutating keyword appears
+# anywhere in the literal.
+_READ_ONLY_SQL_PREFIXES: Tuple[str, ...] = (
+    "select", "pragma", "explain", "with", "values", "show",
+)
+_MUTATING_SQL_KEYWORDS: Tuple[str, ...] = (
+    "insert", "update", "delete", "drop", "create", "alter", "replace",
+    "truncate", "attach", "detach", "vacuum", "reindex", "commit",
+    "rollback", "savepoint", "grant", "revoke", "merge", "upsert", "begin",
+)
+_SQL_EXEC_METHODS: FrozenSet[str] = frozenset({
+    "execute", "executemany", "executescript",
+})
+
+
+def is_provably_read_only_python(code: str) -> bool:
+    """Return True ONLY if every construct in ``code`` is provably read-only.
+
+    Positive allowlist over the AST.  Any node type, call, assignment target,
+    or SQL verb that cannot be proven safe returns False.  Used to exempt
+    long-but-harmless inline code from the length heuristic; never used to
+    grant execution by itself.
+
+    Args:
+        code: Python source extracted from ``python3 -c "..."`` (unquoted).
+
+    Returns:
+        True when the payload contains exclusively read-only constructs;
+        False on any uncertainty (including parse failure).
+    """
+    if not code or not code.strip():
+        # Empty payload: nothing to exempt; let caller's default path handle.
+        return False
+
+    try:
+        tree = ast.parse(code, mode="exec")
+    except SyntaxError:
+        return False
+
+    checker = _ReadOnlyChecker()
+    return checker.is_read_only(tree)
+
+
+class _ReadOnlyChecker:
+    """Walks an AST and proves it contains only read-only constructs."""
+
+    # Statement node types that are structurally inert (control flow,
+    # definitions, expression evaluation).  Mutation can only happen via a
+    # Call, an attribute/subscript assignment, del, or import side effects —
+    # all handled explicitly below.
+    _ALLOWED_STMT_TYPES = (
+        ast.Import, ast.ImportFrom, ast.Expr, ast.Assign, ast.AnnAssign,
+        ast.AugAssign, ast.For, ast.While, ast.If, ast.With, ast.FunctionDef,
+        ast.Return, ast.Pass, ast.Break, ast.Continue, ast.Assert,
+        ast.AsyncFunctionDef, ast.AsyncFor, ast.AsyncWith,
+    )
+
+    def is_read_only(self, tree: ast.AST) -> bool:
+        for node in ast.walk(tree):
+            # Reject statements we do not explicitly allow.
+            if isinstance(node, ast.stmt):
+                if not isinstance(node, self._ALLOWED_STMT_TYPES):
+                    return False
+                # ``del`` removes bindings / can call __delitem__/__delattr__.
+                if isinstance(node, ast.Delete):
+                    return False
+            # Assignment targets must be plain names or name-tuples.  A
+            # Subscript or Attribute target (``os.environ[k]=v``,
+            # ``obj.attr=v``) can mutate external state via __setitem__ /
+            # __setattr__.
+            if isinstance(node, (ast.Assign, ast.AnnAssign, ast.AugAssign)):
+                if not self._targets_are_local(node):
+                    return False
+            # Every call must be on the allowlist.
+            if isinstance(node, ast.Call):
+                if not self._call_is_read_only(node):
+                    return False
+            # ``with`` items: the context manager is itself a Call/expr and is
+            # validated by the Call check above; nothing extra needed.
+        return True
+
+    def _targets_are_local(self, node: ast.AST) -> bool:
+        targets = []
+        if isinstance(node, ast.Assign):
+            targets = node.targets
+        elif isinstance(node, (ast.AnnAssign, ast.AugAssign)):
+            targets = [node.target]
+        for tgt in targets:
+            if not self._is_local_target(tgt):
+                return False
+        return True
+
+    def _is_local_target(self, tgt: ast.AST) -> bool:
+        if isinstance(tgt, ast.Name):
+            return True
+        if isinstance(tgt, (ast.Tuple, ast.List)):
+            return all(self._is_local_target(e) for e in tgt.elts)
+        if isinstance(tgt, ast.Starred):
+            return self._is_local_target(tgt.value)
+        # Subscript / Attribute targets can mutate external state.
+        return False
+
+    def _call_is_read_only(self, node: ast.Call) -> bool:
+        func = node.func
+        # Bare name call: must be a read-only builtin.  (Unresolved local
+        # function calls are rejected — we cannot prove their body is safe.)
+        if isinstance(func, ast.Name):
+            return func.id in _READ_ONLY_BUILTINS
+        # Attribute call: ``x.method(...)``.
+        if isinstance(func, ast.Attribute):
+            method = func.attr
+            if method in _SQL_EXEC_METHODS:
+                return self._sql_arg_is_read_only(node)
+            if method in _READ_ONLY_METHODS:
+                return True
+            # Allow ``sqlite3.connect(...)`` and module-qualified pure reads
+            # we can name explicitly; everything else is rejected.
+            return self._dotted_call_is_read_only(func)
+        # Any other callable form (subscript result, lambda, call chain head)
+        # cannot be proven safe.
+        return False
+
+    def _dotted_call_is_read_only(self, func: ast.Attribute) -> bool:
+        # Build dotted source name (best-effort).  Only a tiny set of
+        # module-level read-only constructors are permitted.
+        parts = []
+        cur: ast.AST = func
+        while isinstance(cur, ast.Attribute):
+            parts.append(cur.attr)
+            cur = cur.value
+        if isinstance(cur, ast.Name):
+            parts.append(cur.id)
+            parts.reverse()
+            dotted = ".".join(parts)
+            return dotted in _READ_ONLY_DOTTED_CALLS
+        return False
+
+    def _sql_arg_is_read_only(self, node: ast.Call) -> bool:
+        # ``execute``/``executemany`` are read-only ONLY when the first
+        # positional argument is a string LITERAL whose leading token is a
+        # read-only SQL verb AND which contains no mutating keyword.  A
+        # non-literal SQL argument (variable, f-string, concatenation) cannot
+        # be proven safe and is rejected.
+        if not node.args:
+            return False
+        first = node.args[0]
+        if not (isinstance(first, ast.Constant) and isinstance(first.value, str)):
+            return False
+        sql = first.value.strip().lower()
+        if not sql:
+            return False
+        # Strip a leading comment / whitespace already done; take first word.
+        leading = sql.split(None, 1)[0] if sql.split() else ""
+        if leading not in _READ_ONLY_SQL_PREFIXES:
+            return False
+        # Reject if ANY mutating keyword appears anywhere (defeats CTE-wrapped
+        # writes like ``WITH x AS (...) DELETE ...`` and stacked statements).
+        for kw in _MUTATING_SQL_KEYWORDS:
+            if re.search(r"\b" + re.escape(kw) + r"\b", sql):
+                return False
+        return True
+
+
+# Module-level read-only constructors permitted in a provable-read-only
+# payload (dotted source names).  ``sqlite3.connect`` opens a handle;
+# mutation would require a subsequent write call, which is independently
+# checked.  Kept deliberately small.
+_READ_ONLY_DOTTED_CALLS: FrozenSet[str] = frozenset({
+    "sqlite3.connect",
+    "json.dumps", "json.loads", "json.load",
+    "os.getcwd", "os.getenv", "os.listdir", "os.path.join", "os.path.exists",
+    "os.path.basename", "os.path.dirname", "os.path.abspath",
+    "os.path.isfile", "os.path.isdir", "os.path.getsize",
+    "sys.exit",
+    "datetime.now", "datetime.utcnow", "time.time",
+    "pathlib.Path", "Path",
+})
+
+
 # ============================================================================
 # Internal helpers
 # ============================================================================