Guarding the Turn Boundary in Non-Interactive Runs: A Command Table and a Fail-Closed Gate

#!/usr/bin/env python3
"""Extract command invocations from shell scripts and classify whether a
static scanner can read them as literal strings."""
import re, sys, os, json
 
CMD_TOKEN = re.compile(r'(?:^|[;|&]{1,2}\s*|\$\(\s*|`\s*)\s*([A-Za-z_][\w./-]*)\s')
VAR_REF   = re.compile(r'\$\{?[A-Za-z_][\w]*\}?')
HEREDOC   = re.compile(r'<<-?\s*[\'"]?([A-Za-z_][\w]*)')
 
def classify_line(line):
    """literal / dynamic / None"""
    s = line.strip()
    if not s or s.startswith('#'):
        return None
    m = CMD_TOKEN.search(' ' + s)
    if not m:
        return None
    head = m.group(1)
    parts = s.split()
    if parts and VAR_REF.search(parts[0]):
        return ('dynamic', head)          # the command name itself expands
    rest = s[m.end():]
    if VAR_REF.search(rest) or '$(' in rest or '`' in rest:
        return ('dynamic', head)          # arguments resolved at runtime
    return ('literal', head)
 
def scan(path):
    stats = {'literal': 0, 'dynamic': 0, 'heredoc_blocks': 0, 'lines': 0}
    heads = {}
    try:
        text = open(path, encoding='utf-8', errors='replace').read()
    except OSError:
        return stats, heads
    stats['heredoc_blocks'] = len(HEREDOC.findall(text))
    for line in text.splitlines():
        stats['lines'] += 1
        r = classify_line(line)
        if not r:
            continue
        kind, head = r
        stats[kind] += 1
        heads.setdefault(head, {'literal': 0, 'dynamic': 0})[kind] += 1
    return stats, heads
 
def main(roots):
    total = {'literal': 0, 'dynamic': 0, 'heredoc_blocks': 0, 'lines': 0}
    allheads, files = {}, 0
    for root in roots:
        for dirpath, dirnames, filenames in os.walk(root):
            dirnames[:] = [d for d in dirnames
                           if d not in ('.git', 'node_modules', '.next')]
            for fn in filenames:
                if not fn.endswith(('.sh', '.bash', '.md', '.txt')):
                    continue
                p = os.path.join(dirpath, fn)
                try:
                    if os.path.getsize(p) > 400_000:
                        continue
                except OSError:
                    continue
                s, h = scan(p)
                if s['literal'] + s['dynamic'] == 0:
                    continue
                files += 1
                for k in total:
                    total[k] += s[k]
                for head, c in h.items():
                    a = allheads.setdefault(head, {'literal': 0, 'dynamic': 0})
                    a['literal'] += c['literal']
                    a['dynamic'] += c['dynamic']
    print(json.dumps({'files': files, 'total': total}))
    tops = sorted(allheads.items(),
                  key=lambda kv: -(kv[1]['literal'] + kv[1]['dynamic']))[:12]
    for head, c in tops:
        n = c['literal'] + c['dynamic']
        print(f"{head:14s} n={n:5d} dynamic={c['dynamic'] / n * 100:5.1f}%")
 
if __name__ == '__main__':
    main(sys.argv[1:])

#!/usr/bin/env python3
"""Compare a naive exact-match table against a normalizing classifier."""
import time, statistics
from turn_gate import classify, READONLY, TURN, INTERACTIVE_ONLY
 
CASES = [
    ("/usage", "readonly"), ("usage", "readonly"), (" /usage ", "readonly"),
    ("/usage --output-format json", "readonly"), ("/Usage", "readonly"),
    ("/mcp:list", "readonly"), ("/mcp list", "readonly"), ("/status", "readonly"),
    ("/cost", "readonly"), ("/context", "readonly"), ("/config get model", "readonly"),
    ("/model", "readonly"), ("/help", "readonly"),
    ("/init", "turn"), ("init", "turn"), ("/review --base main", "turn"),
    ("/compact", "turn"), ("/agent run x", "turn"), ("/fix", "turn"),
    ("/settings", "interactive"), ("/login", "interactive"),
    ("/resume", "interactive"), ("/clear", "interactive"),
    ("/telemetry", "unclassified"), ("/doctor", "unclassified"),
    ("", "unclassified"), ("   ", "unclassified"),
    ('/usage "unclosed', "unclassified"), ("--output-format json", "unclassified"),
]
 
def naive(raw):
    """Exact-match table with no normalization"""
    if raw in {"/" + c for c in READONLY}:
        return "readonly"
    if raw in {"/" + c for c in TURN}:
        return "turn"
    if raw in {"/" + c for c in INTERACTIVE_ONLY}:
        return "interactive"
    return "unclassified"
 
def score(fn):
    ok = sum(1 for raw, exp in CASES if fn(raw) == exp)
    # unsafe: a turn-spending or interactive command read as readonly
    unsafe = sum(1 for raw, exp in CASES
                 if exp in ("turn", "interactive") and fn(raw) == "readonly")
    # over-block: a readonly command refused as unclassified
    overblock = sum(1 for raw, exp in CASES
                    if exp == "readonly" and fn(raw) == "unclassified")
    return ok, unsafe, overblock
 
N = len(CASES)
for label, fn in (("exact  ", naive), ("normal ", lambda r: classify(r)[0])):
    ok, unsafe, over = score(fn)
    print(f"{label}: correct {ok}/{N} ({ok / N * 100:.1f}%)  "
          f"unsafe {unsafe}  over-block {over}")
 
t = []
for _ in range(5):
    s = time.perf_counter()
    for _ in range(20000):
        for raw, _e in CASES:
            classify(raw)
    t.append((time.perf_counter() - s) / (20000 * N) * 1e6)
print(f"per-decision cost: {statistics.median(t):.3f} us (median of 5)")