diff --git a/.chock/bin/_chock_runtime.py b/.chock/bin/_chock_runtime.py index dbde6c7..3692629 100644 --- a/.chock/bin/_chock_runtime.py +++ b/.chock/bin/_chock_runtime.py @@ -10,8 +10,11 @@ import json import sys +import contextvars as _chock_contextvars +import signal as _chock_signal import hashlib as _chock_hashlib import fnmatch as _chock_fnmatch +import io as _chock_io import re as _chock_re import os as _chock_os import queue as _chock_queue @@ -39,9 +42,74 @@ PATTERN_JUDGE_SOURCE = "import json, re, sys\nprint('ready', flush=True)\nfor line in sys.stdin:\n out = []\n for pattern, texts in json.loads(line):\n search = re.compile(pattern).search\n out.append([index for index, text in enumerate(texts) if search(text)])\n print(json.dumps(out), flush=True)\n" +MEMBER_DEADLINE = _chock_contextvars.ContextVar('chock_member_deadline', default=None) + def engine_deadline(): - """The monotonic instant this invocation's budget runs out.""" - return _chock_time.monotonic() + ENGINE_BUDGET_SECONDS + """The monotonic instant this invocation's budget runs out: the member's own deadline when one is set.""" + member = MEMBER_DEADLINE.get() + return member if member is not None else _chock_time.monotonic() + ENGINE_BUDGET_SECONDS + +def last_state(var): + """This thread's mutable record in the ContextVar `var`: a thread starts with none, so none is shared.""" + state = var.get(None) + if state is None: + state = {} + var.set(state) + return state + +LIVE_TREES = {} + +def track_tree(proc): + """Record `proc` (started with `tree_spawn_options`) as a tree to end if the hook leaves while it runs.""" + LIVE_TREES[proc.pid] = proc + +def untrack_tree(proc): + """Forget `proc`: it ended, or its tree was killed.""" + LIVE_TREES.pop(proc.pid, None) + +def kill_live_trees(): + """Kill every tree still recorded, whichever thread started it.""" + for proc in tuple(LIVE_TREES.copy().values()): + kill_tree(proc) + untrack_tree(proc) + +def tree_spawn_options(): + """Popen options that put a child in its own process group (POSIX session; Windows new process group).""" + if _chock_os.name == 'nt': + return {'creationflags': _chock_subprocess.CREATE_NEW_PROCESS_GROUP} + return {'start_new_session': True} + +def kill_tree(proc): + """Kill `proc` and everything it started: killpg on POSIX, `taskkill /T /F` on Windows.""" + with contextlib.suppress(OSError): + if _chock_os.name == 'nt': + _chock_subprocess.run(['taskkill', '/T', '/F', '/PID', str(proc.pid)], capture_output=True, check=False) + else: + _chock_os.killpg(proc.pid, _chock_signal.SIGKILL) + with contextlib.suppress(OSError): + proc.kill() + +def run_tree(argv, *, timeout=None, **options): + """`subprocess.run` that, on a timeout, kills the child's whole process tree before raising.""" + options.pop('check', None) + stdin_text = options.pop('input', None) + if options.pop('capture_output', False): + options.update(stdout=_chock_subprocess.PIPE, stderr=_chock_subprocess.PIPE) + if stdin_text is not None: + options['stdin'] = _chock_subprocess.PIPE + if 'text' in options or 'encoding' in options: + options['text'] = True + with _chock_subprocess.Popen(argv, **options, **tree_spawn_options()) as proc: + track_tree(proc) + try: + out, err = proc.communicate(stdin_text, timeout=timeout) + except BaseException: + kill_tree(proc) + proc.communicate() + raise + finally: + untrack_tree(proc) + return _chock_subprocess.CompletedProcess(argv, proc.returncode, out, err) def engine_remaining(deadline): """Seconds left before `deadline`, never negative.""" @@ -68,10 +136,11 @@ def _pump_lines(proc, lines): lines.put(None) def _start_judge(judge): - proc = _chock_subprocess.Popen(judge['argv'], stdin=_chock_subprocess.PIPE, stdout=_chock_subprocess.PIPE, stderr=_chock_subprocess.PIPE, text=True, encoding='utf-8') + proc = _chock_subprocess.Popen(judge['argv'], stdin=_chock_subprocess.PIPE, stdout=_chock_subprocess.PIPE, stderr=_chock_subprocess.PIPE, text=True, encoding='utf-8', **tree_spawn_options()) lines = _chock_queue.Queue() _chock_threading.Thread(target=_pump_lines, args=(proc, lines), daemon=True).start() judge['proc'], judge['lines'] = (proc, lines) + track_tree(proc) try: ready = lines.get(timeout=PATTERN_START_SECONDS) except _chock_queue.Empty: @@ -88,8 +157,9 @@ def close_judge(judge): if proc is None: return '' if proc.poll() is None: - proc.kill() + kill_tree(proc) proc.wait() + untrack_tree(proc) try: spoken = proc.stderr.read() except (OSError, ValueError): @@ -687,7 +757,7 @@ def halt_git_roots(repo_root: _chock_Path) -> list[_chock_Path]: _FOUND_BASH = {} -GUARD_LAST = {} +GUARD_LAST = _chock_contextvars.ContextVar('chock_guard_last') GUARD_MISSING = 'missing' @@ -818,14 +888,14 @@ def run_guard_detailed(guard: _chock_Path, command: str, tool: str='', *, can_as if fallback: env[ARGV_FALLBACK_ENV] = '1' env.update({} if can_ask is None else {CAN_ASK_ENV: '1' if can_ask else '0'}) - proc = _chock_subprocess.run([interpreter, str(guard), *args], capture_output=True, text=True, encoding='utf-8', errors='replace', env=env, timeout=time_left(deadline, [interpreter, str(guard)]), check=False) + proc = run_tree([interpreter, str(guard), *args], capture_output=True, text=True, encoding='utf-8', errors='replace', env=env, timeout=time_left(deadline, [interpreter, str(guard)]), check=False) except _chock_subprocess.TimeoutExpired: print(f'chock: guard timed out after {ENGINE_BUDGET_SECONDS}s, not checked', file=sys.stderr) return (GUARD_ERRORED, '') except (OSError, UnicodeError) as exc: print(f'chock: guard could not run, not checked: {exc}', file=sys.stderr) return (GUARD_ERRORED, '') - GUARD_LAST['code'] = proc.returncode + last_state(GUARD_LAST)['code'] = proc.returncode output = ((proc.stderr or '') + (proc.stdout or '')).strip() first_line = output.splitlines()[0].strip() if output else '' if proc.returncode == GUARD_VIOLATION: @@ -854,10 +924,10 @@ def evaluate(argv: list[str], command: str, tool: str='', *, can_ask: bool | Non if guard is None: return None if not guard.exists(): - GUARD_LAST['outcome'] = GUARD_MISSING + last_state(GUARD_LAST)['outcome'] = GUARD_MISSING return (VERDICT_DENY, f"chock guard {guard} is missing, so this command cannot be checked. Run `chock sync --repo .` to reinstall the policy's guards.") verdict, message = run_guard_detailed(guard, command, tool, can_ask=can_ask) - GUARD_LAST['outcome'] = verdict + last_state(GUARD_LAST)['outcome'] = verdict if verdict == GUARD_BLOCKED: return (VERDICT_DENY, f'Blocked by chock policy: {guard.stem}: {message}') if verdict == GUARD_ASKED: @@ -1001,7 +1071,7 @@ def dlog_fields(event, repo): _DLOG_GATE_LOGGED_CODES = (0, 1, 3, 4) -GATE_LAST = {} +GATE_LAST = _chock_contextvars.ContextVar('chock_gate_last') def _dlog_flag_value(argv, flag): if flag in argv: @@ -1066,8 +1136,8 @@ def _dlog_trace(event, wire, rule, stages): trace['command'] = log_trace_text(event.command) if event.path: trace['path'] = log_trace_text(event.path) - if 'code' in GUARD_LAST: - trace['exit_code'] = GUARD_LAST['code'] + if 'code' in last_state(GUARD_LAST): + trace['exit_code'] = last_state(GUARD_LAST)['code'] return trace def _dlog_reason(source, outcome): @@ -1076,8 +1146,8 @@ def _dlog_reason(source, outcome): return 'no-rule' if source == HALT_REASON: return HALT_REASON - if source == 'guard' and 'outcome' in GUARD_LAST: - guarded = GUARD_LAST['outcome'] + if source == 'guard' and 'outcome' in last_state(GUARD_LAST): + guarded = last_state(GUARD_LAST)['outcome'] return f'guard-{guarded}' if source == 'fault': return source @@ -1101,7 +1171,7 @@ def log_decision(argv, event, decision, judged, context): runtime = globals().get('__file__') or sys.argv[0] route = runtime_route(runtime) source, rule, started, stages = judged - gate_wrote = event.event != 'pre_tool' or GATE_LAST.get('code') in _DLOG_GATE_LOGGED_CODES + gate_wrote = event.event != 'pre_tool' or last_state(GATE_LAST).get('code') in _DLOG_GATE_LOGGED_CODES if route == DLOG_ROUTE_SYNC and _DLOG_GATE_FLAG in argv and (source in (None, 'gate')) and gate_wrote: return agent = str(getattr(event, 'agent', None) or 'unknown') @@ -2556,12 +2626,12 @@ def run_gate(gate, writes, event, run_in, deadline): return (GATE_ERRORED, 'the vendored gate runner is not installed beside this gate') argv = [sys.executable, str(runner), 'run', '--gate', str(gate), '--event', event] try: - proc = _chock_subprocess.run(argv, input=json.dumps({'writes': writes, **(extra or {})}), capture_output=True, text=True, encoding=_UTF8, errors='replace', timeout=time_left(deadline, argv), check=False, cwd=str(root) if root is not None else None) + proc = run_tree(argv, input=json.dumps({'writes': writes, **(extra or {})}), capture_output=True, text=True, encoding=_UTF8, errors='replace', timeout=time_left(deadline, argv), check=False, cwd=str(root) if root is not None else None) except _chock_subprocess.TimeoutExpired as exc: return (GATE_ERRORED, f'the gate runner gave no verdict within {allowed_seconds(exc)}') except (OSError, _chock_subprocess.SubprocessError) as exc: return (GATE_ERRORED, str(exc)) - GATE_LAST['code'] = proc.returncode + last_state(GATE_LAST)['code'] = proc.returncode return runner_outcome(proc.returncode, proc.stderr) _EVENT_ARG = {'pre_tool': 'pre-tool-use', 'stop': 'stop'} @@ -2620,7 +2690,7 @@ def _gate_says(gate, event, deadline, root, case_blind): def evaluate_gate(argv, event, *, case_blind=None): """The decision this event earns from a compiled gate, or None when it has nothing to say.""" - GATE_LAST.clear() + last_state(GATE_LAST).clear() gate = gate_path_from_argv(argv) if gate is None or getattr(event, 'event', '') not in _EVENT_ARG: return None @@ -2699,7 +2769,7 @@ def _tool_call_script(spec, root, payload, deadline=None): deadline = engine_deadline() if deadline is None else deadline argv = [sys.executable, str(script)] try: - proc = _chock_subprocess.run(argv, input=json.dumps(payload), capture_output=True, text=True, encoding='utf-8', errors='replace', cwd=str(root), env={**_chock_os.environ, **BYTECODE_OFF}, timeout=time_left(deadline, argv), check=False) + proc = run_tree(argv, input=json.dumps(payload), capture_output=True, text=True, encoding='utf-8', errors='replace', cwd=str(root), env={**_chock_os.environ, **BYTECODE_OFF}, timeout=time_left(deadline, argv), check=False) except _chock_subprocess.TimeoutExpired as exc: budget = f'gave no verdict within {allowed_seconds(exc)}' return ('deny', f'script gate: {script.name} {budget}{_TOOL_CALL_UNDECIDED}') @@ -2766,3 +2836,157 @@ def evaluate_tool_call(argv, event): if spec.get('kind') in _TOOL_CALL_NEEDS_SESSION: session_record(root, event, 'pre', _TOOL_CALL_BLOCKED if verdict and verdict[0] == 'deny' else None) return verdict + +MULTI_FLAG = '--multi' + +INDEX_SHA_FLAG = '--index-sha256' + +ROOT_FLAG = '--root' + +OFF_FLAG = '--off' + +MEMBER_DEFAULT_SECONDS = 30 + +_MEMBER_SEPARATOR = '\n' + +def multi_from_argv(argv): + """(index path, pinned sha256) when the hook command names an index, else None.""" + if MULTI_FLAG not in argv: + return None + path = argv[argv.index(MULTI_FLAG) + 1] if argv.index(MULTI_FLAG) + 1 < len(argv) else '' + pin = argv[argv.index(INDEX_SHA_FLAG) + 1] if INDEX_SHA_FLAG in argv and argv.index(INDEX_SHA_FLAG) + 1 < len(argv) else '' + return (path, pin) + +def root_from_argv(argv): + """The plugin root a hook command names with `--root`, "" when the flag has no value, None when it is absent.""" + if ROOT_FLAG not in argv: + return None + at = argv.index(ROOT_FLAG) + 1 + return argv[at] if at < len(argv) else '' + +def off_from_argv(argv): + """The bundle members a toggle wrapper switched off for this call (`--off a,b`), as a set of ids.""" + at = argv.index(OFF_FLAG) + 1 if OFF_FLAG in argv else len(argv) + return {name for name in (argv[at] if at < len(argv) else '').split(',') if name} + +def sha256_of(path): + """The sha256 of a file's bytes with CRLF read as LF, so a checkout that converted line endings still matches.""" + return _chock_hashlib.sha256(_chock_Path(path).read_bytes().replace(b'\r\n', b'\n')).hexdigest() + +def _escapes(path): + """True for a path that is absolute, drive- or root-qualified, or climbs out of the root by a `..` part, on either flavour.""" + return any((flavour(path).is_absolute() or '..' in flavour(path).parts or flavour(path).drive or flavour(path).root for flavour in (_chock_PurePosixPath, _chock_PureWindowsPath))) + +def _member_fault(member, root): + """Why one index member cannot be trusted (an escaping path, a file off its pin, an unreadable shape), else None.""" + named = [*member['files'], *(a for a in member['argv'] if isinstance(a, str) and (not a.startswith('-')))] + for relative in named: + if not isinstance(relative, str) or _escapes(relative): + return f'the policy index names {relative!r}, which is outside the repository root' + for relative, expected in member['files'].items(): + if sha256_of(_chock_Path(root) / relative) != expected: + return f'{relative} does not match the hash the policy index pins' + if not isinstance(member['argv'], list) or not float(member.get('timeout', MEMBER_DEFAULT_SECONDS)) > 0: + return 'the policy index holds a member chock cannot read' + return None + +def _rooted(member, root): + """`member` with each path its argv names joined to `root`: a plugin's members are paths relative to its root.""" + argv = [a if not isinstance(a, str) or a.startswith('-') else str(_chock_Path(root) / a) for a in member['argv']] + return {**member, 'argv': argv} + +def load_index(path, pin, root, *, rooted=False): + """(members, None) when the index matches its pin and every member's files match theirs; else (None, why). + + `root` is where the member paths resolve; `rooted` (a plugin's `--root`) also joins it to each argv path. + """ + try: + if not root: + return (None, 'the hook command names an empty plugin root, so its policy index cannot be checked') + if not pin or sha256_of(path) != pin: + return (None, f'the policy index {path} does not match the hash the hook pins') + members = json.loads(_chock_Path(path).read_text(encoding='utf-8'))['members'] + if not isinstance(members, list) or not members: + return (None, f'the policy index {path} lists no policies, which is a build fault, never an allow') + for member in members: + why = _member_fault(member, root) + if why: + return (None, why) + if rooted: + members = [_rooted(member, root) for member in members] + except (OSError, ValueError, KeyError, TypeError, AttributeError) as exc: + return (None, f'the policy index {path} cannot be read ({type(exc).__name__})') + return (members, None) + +def _fault(member, exc): + return (VERDICT_DENY, f'chock could not check this call with {member_name(member)} ({type(exc).__name__}: {exc}). Refusing rather than reporting an allow it never established.') + +def member_name(member): + """A member's policy, as its argv names it (the file after its first flag).""" + return next((arg for arg in member['argv'][1:2]), 'a policy') + +def _member_thread(member, judge_one, slot): + MEMBER_DEADLINE.set(_chock_time.monotonic() + float(member.get('timeout', MEMBER_DEFAULT_SECONDS))) + try: + slot['verdict'] = judge_one(member['argv']) + except (Exception, SystemExit) as exc: + slot['verdict'] = _fault(member, exc) + slot['done'] = True + +def settle(verdict, *, can_ask=True, warn_speaks=True): + """One member's verdict as the client can honour it: an ask the client ignores is a deny, a warn it never shows is nothing.""" + if verdict is None: + return None + kind, reason = verdict + if kind == VERDICT_ESCALATE and (not can_ask): + return (VERDICT_DENY, reason) + if kind == VERDICT_WARN and (not warn_speaks): + return None + return verdict + +def run_members(members, judge_one, *, can_ask=True, warn_speaks=True, said=None): + """Each member's settled verdict (or None), in index order. A member past its own deadline refuses its own call. + + The members share this process's streams, so they get none: stdin is empty and what they print on stdout is + dropped. What they write to stderr (a stop's warning, a note that a worktree went unchecked) is appended to `said`. + """ + started = _chock_time.monotonic() + saved = (sys.stdin, sys.stdout, sys.stderr) + sys.stdin, sys.stdout, sys.stderr = (_chock_io.StringIO(''), _chock_io.StringIO(), _chock_io.StringIO()) + try: + running = [] + for member in members: + slot = {'done': False, 'verdict': None} + thread = _chock_threading.Thread(target=_member_thread, args=(member, judge_one, slot), daemon=True) + thread.start() + running.append((member, thread, slot)) + verdicts = [] + for member, thread, slot in running: + allowed = float(member.get('timeout', MEMBER_DEFAULT_SECONDS)) + thread.join(max(started + allowed - _chock_time.monotonic(), 0.0)) + if slot['done']: + verdicts.append(settle(slot['verdict'], can_ask=can_ask, warn_speaks=warn_speaks)) + else: + verdicts.append((VERDICT_DENY, f'{member_name(member)} gave no verdict within {allowed:g}s, so it refuses this call.')) + finally: + written = sys.stderr.getvalue() if isinstance(sys.stderr, _chock_io.StringIO) else '' + sys.stdin, sys.stdout, sys.stderr = saved + if said is not None and written: + said.append(written) + return verdicts + +def combine(verdicts): + """One verdict from many, in index order: any deny wins, then any ask, then the warns; None when all allow.""" + for outcome in (VERDICT_DENY, VERDICT_ESCALATE, VERDICT_WARN): + reasons = [reason for verdict in verdicts if verdict is not None for kind, reason in [verdict] if kind == outcome] + if reasons: + return (outcome, _MEMBER_SEPARATOR.join(reasons)) + return None + +def flush_and_exit(code): + """End every child tree a member left running, write what was said, then leave without waiting for its thread.""" + kill_live_trees() + for stream in (sys.stdout, sys.stderr): + with contextlib.suppress(OSError, ValueError): + stream.flush() + _chock_os._exit(code) diff --git a/.chock/bin/claude_code.py b/.chock/bin/claude_code.py index 70e66df..30f363a 100755 --- a/.chock/bin/claude_code.py +++ b/.chock/bin/claude_code.py @@ -9,6 +9,22 @@ from __future__ import annotations +import sys as _chock_sys +if _chock_sys.version_info < (3, 11): + # An older Python writes no marker, so the launcher tries its next candidate. Run as the + # launcher runs it, leave quietly; imported, raise instead -- importing never exits. + if __name__ == "__main__": + _chock_sys.exit(1) + raise ImportError("chock's hook runtime needs Python %d.%d or newer" % (3, 11)) +try: + import os as _chock_start_os + + if _chock_start_os.environ.pop("CHOCK_START_FD", "") == "9": # only the launcher's own fd; no child inherits the name + _chock_start_os.write(9, b"chock-python") + _chock_start_os.close(9) +except OSError: + pass + import contextlib import io import json @@ -16,6 +32,7 @@ import os import sys +import copy as _chock_copy import os as _chock_os import shutil as _chock_shutil import subprocess as _chock_subprocess @@ -837,7 +854,7 @@ def degrade(decision, event): # Not self-contained: chock's guard logic lives in the sibling _chock_runtime.py, loaded from this # file's own folder and pinned to the sha256 of that file's bytes (CRLF read as LF), hashed before they are executed. # Missing, unreadable, another version, or failing to import: every call refuses (_CHOCK_RUNTIME_FAULT), never allows. -_CHOCK_RUNTIME_PIN = 'a7302f5f8e1deb74d6f245a97474228ce9258ed2c04313a30af7799787a9d259' +_CHOCK_RUNTIME_PIN = '8e3b4b73f866de5887946c8afe0dee895548a5d67146470d63350fa84b08b5f2' def _chock_load_runtime(): @@ -848,15 +865,24 @@ def _chock_load_runtime(): path = _chock_os.path.join(here, '_chock_runtime.py') try: from hashlib import sha256 - from importlib.abc import InspectLoader + from importlib.machinery import SourceFileLoader from importlib.util import module_from_spec, spec_from_loader - class PinnedBytes(InspectLoader): - """Hands the import machinery the bytes already read and hashed; it never opens the file again.""" + class PinnedBytes(SourceFileLoader): + """Hands the import machinery the bytes already read and hashed; it never opens the file again. + + SourceFileLoader, not importlib.abc.InspectLoader: importing importlib.abc loads inspect on every call. + """ def __init__(self, source): + super().__init__('_chock_runtime', path) self.source = source + def get_data(self, data_path): + if data_path != path: + raise OSError("only the pinned bytes are served") + return self.source + def get_source(self, fullname): return self.source.decode("utf-8") @@ -972,9 +998,8 @@ def _chock_spec_action(path): return action if action in ("ask", "warn") else "block" -def _chock_declared(): - """(strictest action, event, gate) of the judging flags; (None, None, None) where this run judges nothing.""" - argv = sys.argv[1:] +def _chock_declared_by(argv): + """(strictest action, event, gate) of the judging flags in `argv`; (None, None, None) where it judges nothing.""" actions = ["block"] if guard_path_from_argv(argv) is not None else [] event = PRE_TOOL gate = _flag_path(argv, GATE_FLAG) @@ -992,6 +1017,29 @@ def _chock_declared(): return None, None, None +def _chock_declared(): + """(strictest action, event, gate) of the judging flags, or of every member of a pinned index; an index that fails its pin blocks.""" + argv = sys.argv[1:] + pinned = multi_from_argv(argv) + if pinned is None: + return _chock_declared_by(argv) + stopped = _chock_declared_by([HALT_HOOK_FLAG]) if HALT_HOOK_FLAG in argv else (None, None, None) + if stopped[0] is not None: # the folded stop check: stopped, an unreadable call is refused whatever the members + return stopped + named = root_from_argv(argv) + members, _why = load_index( + pinned[0], pinned[1], _chock_Path.cwd() if named is None else named, rooted=named is not None + ) + if members is None: + return "block", PRE_TOOL, None + found = [_chock_declared_by(member["argv"]) for member in members] + for action in ("block", "ask", "warn"): + stopping = [f for f in found if f[0] == action and f[1] == STOP] + if stopping or action in (f[0] for f in found): + return stopping[0] if stopping else next(f for f in found if f[0] == action) + return None, None, None + + def _chock_refuses(text, code): if code == 2: return True @@ -1069,6 +1117,16 @@ def _spoken(verdict): return Decision.escalate(reason) if outcome == ESCALATE else Decision.deny(reason) +#: Set by a multi-policy hook: its exit ends what a hung member left running and does not wait for its thread. +_CHOCK_LEAVE = [] + + +def _chock_leave(code): + if _CHOCK_LEAVE: + flush_and_exit(code) + sys.exit(code) + + def _chock_timed(judged, stage, ask): started = _chock_time.monotonic() try: @@ -1077,24 +1135,24 @@ def _chock_timed(judged, stage, ask): judged[3][stage] = round((_chock_time.monotonic() - started) * 1000) -def _judge(event, judged): +def _judge(event, judged, argv): halted = repo_stop_refusal(event) if halted is not None: judged[0:2] = [HALT_REASON, ".chock/stop.json"] return Decision.deny(halted) if event.event == "pre_tool" and event.command: verdict = _chock_timed(judged, "guard", lambda: evaluate( - sys.argv[1:], event.command, event.tool or "", can_ask=_chock_can_ask(event.raw) + argv, event.command, event.tool or "", can_ask=_chock_can_ask(event.raw) )) if verdict is not None: - judged[0:2] = ["guard", _chock_Path(guard_path_from_argv(sys.argv[1:])).stem] + judged[0:2] = ["guard", _chock_Path(guard_path_from_argv(argv)).stem] outcome, reason = verdict return Decision.escalate(reason) if outcome == ESCALATE else Decision.deny(reason) - gated = _chock_timed(judged, "gate", lambda: evaluate_gate(sys.argv[1:], event)) + gated = _chock_timed(judged, "gate", lambda: evaluate_gate(argv, event)) if gated is not None: - judged[0:2] = ["gate", gate_path_from_argv(sys.argv[1:]).parent.parent.name] + judged[0:2] = ["gate", gate_path_from_argv(argv).parent.parent.name] return _spoken(gated) - called = _chock_timed(judged, "tool_call", lambda: evaluate_tool_call(sys.argv[1:], event)) + called = _chock_timed(judged, "tool_call", lambda: evaluate_tool_call(argv, event)) if called is not None: judged[0:2] = ["tool_call", str(event.tool or "")] return _spoken(called) @@ -1103,6 +1161,60 @@ def _judge(event, judged): return None +def _chock_member_verdict(event, record, argv): + """One member's verdict on the event it was handed; its decision and last-run state wait in `record` for the log.""" + judged = [None, None, _chock_time.monotonic(), {}] + try: + decision = _judge(event, judged, argv) + except Exception as exc: # noqa: BLE001 -- any failure here must refuse, never fall through + judged[0:2] = ["fault", type(exc).__name__] + decision = Decision.deny( + "chock could not check this call (%s: %s). Refusing rather than reporting an " + "allow it never established." % (type(exc).__name__, exc) + ) + record[id(argv)] = (decision, judged, dict(last_state(GUARD_LAST)), dict(last_state(GATE_LAST))) + return None if decision is None else (decision.outcome, decision.reason) + + +def _chock_multi_log(event, members, verdicts, record, context): + """Each member's decision log line, in index order, once every member has finished.""" + for member, verdict in zip(members, verdicts): + decision, judged, guard, gate = record.get( + id(member["argv"]), (None if verdict is None else _spoken(verdict), ["fault", "member"], {}, {}) + ) + for var, state in ((GUARD_LAST, guard), (GATE_LAST, gate)): + last_state(var).clear() + last_state(var).update(state) + log_decision(member["argv"], event, decision, judged, context) + + +def _chock_multi(event, pinned, context): + """The one decision of every policy the pinned index lists, each judged on this event, never on stdin.""" + named = root_from_argv(sys.argv[1:]) + members, why = load_index( + pinned[0], pinned[1], _chock_Path.cwd() if named is None else named, rooted=named is not None + ) + if members is None: + _report(why + "\n") + return Decision.deny(why) + off = off_from_argv(sys.argv[1:]) + members = [member for member in members if member.get("member") not in off] + record, said = {}, [] + verdicts = run_members( + members, + lambda argv: _chock_member_verdict(_chock_copy.deepcopy(event), record, argv), + can_ask=context["can_ask"], + said=said, + ) + kill_live_trees() + for text in said: + _report(text) + if event.event != "session_start": + _chock_multi_log(event, members, verdicts, record, context) + combined = combine(verdicts) + return None if combined is None else _spoken(combined) + + def handle(event): if _CHOCK_RUNTIME_FAULT is not None: _report(_CHOCK_RUNTIME_FAULT + "\n") @@ -1113,22 +1225,40 @@ def handle(event): # A door that cannot decide refuses. An exception escaping here would exit the hook # with a traceback, which every client reads as a non-blocking error: fail-open, with # the reason on a stderr nobody watches. The refusal carries the reason instead. + context = {"manifests": _CHOCK_PLUGIN_MANIFESTS} + try: + context.update(wire=_chock_wire(event.raw), can_ask=_chock_can_ask(event.raw)) + except Exception: # noqa: BLE001 -- the log's context must never change the decision + pass + pinned = multi_from_argv(sys.argv[1:]) + if pinned is not None: + context.setdefault("can_ask", False) + _CHOCK_LEAVE.append(True) + try: + # The stop check folded into this entry: once, before any member; a stop or a fault refuses at once. + stopped = _chock_one(event, [HALT_HOOK_FLAG], context) if HALT_HOOK_FLAG in sys.argv[1:] else None + return stopped if stopped is not None else _chock_multi(event, pinned, context) + except Exception as exc: # noqa: BLE001 -- any failure here must refuse, never fall through + return Decision.deny( + "chock could not check this call (%s: %s). Refusing rather than reporting an " + "allow it never established." % (type(exc).__name__, exc) + ) + return _chock_one(event, sys.argv[1:], context, logged=not starting) # a session start's one line is its heartbeat + + +def _chock_one(event, argv, context, logged=True): + """The decision of the one policy (or the stop check) `argv` names, and its log line.""" judged = [None, None, _chock_time.monotonic(), {}] try: - decision = _judge(event, judged) + decision = _judge(event, judged, argv) except Exception as exc: # noqa: BLE001 -- any failure here must refuse, never fall through judged[0:2] = ["fault", type(exc).__name__] decision = Decision.deny( "chock could not check this call (%s: %s). Refusing rather than reporting an " "allow it never established." % (type(exc).__name__, exc) ) - context = {"manifests": _CHOCK_PLUGIN_MANIFESTS} - try: - context.update(wire=_chock_wire(event.raw), can_ask=_chock_can_ask(event.raw)) - except Exception: # noqa: BLE001 -- the log's context must never change the decision - pass - if not starting: # a session start's one line is its heartbeat - log_decision(sys.argv[1:], event, decision, judged, context) + if logged: + log_decision(argv, event, decision, judged, context) return decision def _chock_warn_respond(decision, event): # A warn never blocks. agentseam reduces WARN to a silent allow for every agent, which drops @@ -1303,7 +1433,7 @@ def main(stdin=None, stdout=None, exit=True): if text: _emit(out, text) if exit: - sys.exit(code) + _chock_leave(code) return code diff --git a/.chock/bin/gate.py b/.chock/bin/gate.py index 3dbb456..f3af6e6 100644 --- a/.chock/bin/gate.py +++ b/.chock/bin/gate.py @@ -5,6 +5,7 @@ import argparse import contextlib +import contextvars import difflib import fnmatch import hashlib @@ -13,6 +14,7 @@ import queue import re import shutil +import signal import subprocess import sys import threading @@ -56,9 +58,83 @@ ) +MEMBER_DEADLINE = contextvars.ContextVar("chock_member_deadline", default=None) + + def engine_deadline(): - """The monotonic instant this invocation's budget runs out.""" - return time.monotonic() + ENGINE_BUDGET_SECONDS + """The monotonic instant this invocation's budget runs out: the member's own deadline when one is set.""" + member = MEMBER_DEADLINE.get() + return member if member is not None else time.monotonic() + ENGINE_BUDGET_SECONDS + + +def last_state(var): + """This thread's mutable record in the ContextVar `var`: a thread starts with none, so none is shared.""" + state = var.get(None) + if state is None: + state = {} + var.set(state) + return state + + +LIVE_TREES = {} + + +def track_tree(proc): + """Record `proc` (started with `tree_spawn_options`) as a tree to end if the hook leaves while it runs.""" + LIVE_TREES[proc.pid] = proc + + +def untrack_tree(proc): + """Forget `proc`: it ended, or its tree was killed.""" + LIVE_TREES.pop(proc.pid, None) + + +def kill_live_trees(): + """Kill every tree still recorded, whichever thread started it.""" + for proc in tuple(LIVE_TREES.copy().values()): + kill_tree(proc) + untrack_tree(proc) + + +def tree_spawn_options(): + """Popen options that put a child in its own process group (POSIX session; Windows new process group).""" + if os.name == "nt": + return {"creationflags": subprocess.CREATE_NEW_PROCESS_GROUP} + return {"start_new_session": True} + + +def kill_tree(proc): + """Kill `proc` and everything it started: killpg on POSIX, `taskkill /T /F` on Windows.""" + with contextlib.suppress(OSError): + if os.name == "nt": + subprocess.run(["taskkill", "/T", "/F", "/PID", str(proc.pid)], capture_output=True, check=False) # noqa: S603, S607 -- the OS tool that ends a process tree + else: + os.killpg(proc.pid, signal.SIGKILL) + with contextlib.suppress(OSError): + proc.kill() + + +def run_tree(argv, *, timeout=None, **options): + """`subprocess.run` that, on a timeout, kills the child's whole process tree before raising.""" + options.pop("check", None) + stdin_text = options.pop("input", None) + if options.pop("capture_output", False): + options.update(stdout=subprocess.PIPE, stderr=subprocess.PIPE) + if stdin_text is not None: + options["stdin"] = subprocess.PIPE + if "text" in options or "encoding" in options: + options["text"] = True + with subprocess.Popen(argv, **options, **tree_spawn_options()) as proc: # noqa: S603 -- callers pass their own fixed argv + track_tree(proc) + try: + out, err = proc.communicate(stdin_text, timeout=timeout) + except BaseException: + kill_tree(proc) + proc.communicate() + raise + finally: + untrack_tree(proc) + return subprocess.CompletedProcess(argv, proc.returncode, out, err) def engine_remaining(deadline): @@ -98,10 +174,12 @@ def _start_judge(judge): stderr=subprocess.PIPE, text=True, encoding="utf-8", + **tree_spawn_options(), ) lines = queue.Queue() threading.Thread(target=_pump_lines, args=(proc, lines), daemon=True).start() judge["proc"], judge["lines"] = proc, lines + track_tree(proc) try: ready = lines.get(timeout=PATTERN_START_SECONDS) except queue.Empty: @@ -119,8 +197,9 @@ def close_judge(judge): if proc is None: return "" if proc.poll() is None: - proc.kill() # before closing stdout: the reader thread holds it until the child's EOF + kill_tree(proc) # before closing stdout: the reader thread holds it until the child's EOF proc.wait() + untrack_tree(proc) try: spoken = proc.stderr.read() except (OSError, ValueError): @@ -411,7 +490,8 @@ def removed_lines(self, path: str) -> list[str]: def committed_blob(self, path: str) -> str: """HEAD's file, named from `repo_root` (`./`), which may sit below the git top-level.""" - return self._git("show", f"HEAD:./{path}") + shown = _head_show(self.repo_root, f"./{path}") + return "" if shown is None else _text_mode(shown, "replace") def head_blob(self, path: str) -> str: """The baseline: HEAD at the turn's end, else what is on disk now, which this write would replace.""" @@ -591,9 +671,16 @@ def _config_rollout(repo_root: Path) -> str: def _committed_config(repo_root: Path, ref: str) -> str | None: """`.chock/config.yaml` as committed at `ref`; None when git cannot show it.""" + spec = "/".join(_CONFIG_PATH) + if ref == "HEAD": + shown = _head_show(repo_root, spec) + try: + return None if shown is None else _text_mode(shown) + except UnicodeDecodeError: + return None try: shown = subprocess.run( # noqa: S603 -- reading one committed file - ["git", "-C", str(repo_root), "show", f"{ref}:{'/'.join(_CONFIG_PATH)}"], # noqa: S607 + ["git", "-C", str(repo_root), "show", f"{ref}:{spec}"], # noqa: S607 capture_output=True, text=True, encoding="utf-8", @@ -874,7 +961,7 @@ def _kind_test_integrity(ctx: GateContext, params: dict, event: str) -> GateResu def _spawn(script: Path, ctx: GateContext, payload: dict, timeout: float) -> subprocess.CompletedProcess[str]: - return subprocess.run( # noqa: S603 -- the script is the policy's own, named in its manifest + return run_tree( [sys.executable, str(script)], input=json.dumps(payload), capture_output=True, @@ -1247,7 +1334,7 @@ def _reason(result: GateResult, spec: dict, event: str = "commit", policy_id: st def _report_refusal(result: GateResult, spec: dict, judged: str, signal: str | None, policy_id: str | None) -> None: reason = _reason(result, spec, judged, policy_id) print(_encodable(ci_inert(reason) if judged == "ci" else reason, sys.stderr), file=sys.stderr) - if judged == AGENT_COMMIT_EVENT and signal: + if judged == AGENT_COMMIT_EVENT and signal and _waiver_pattern(spec.get("params") or {}, judged): print(_AGENT_COMMIT_NOTE.format(signal=signal), file=sys.stderr) @@ -2453,6 +2540,61 @@ def log_require_safe(path): raise OSError(LOG_UNSAFE) +_HEAD_GIT = shutil.which("git") or "git" + +#: Per process: HEAD resolved once per repo root, and each `git show HEAD:` run once per (root, HEAD, spec). +#: A failure is stored as None and read back as the same failure. +_HEAD_SHA: dict[str, str | None] = {} +_HEAD_SHOWN: dict[tuple[str, str | None, str], bytes | None] = {} + + +def _head_sha(root: str) -> str | None: + if root not in _HEAD_SHA: + try: + proc = subprocess.run( # noqa: S603 -- resolving HEAD once is this cache's key + [_HEAD_GIT, "-C", root, "rev-parse", "--verify", "--quiet", "HEAD^{commit}"], + capture_output=True, + text=True, + check=False, + timeout=10, + ) + sha = proc.stdout.strip() if proc.returncode == 0 else "" + except (OSError, subprocess.SubprocessError, UnicodeError): + sha = "" + _HEAD_SHA[root] = sha or None + return _HEAD_SHA[root] + + +def _head_show(repo_root: Path, spec: str) -> bytes | None: + """The bytes of `git show HEAD:` run from `repo_root`, read once per process; None when git cannot show it.""" + root = str(repo_root) + key = (root, _head_sha(root), spec) + if key not in _HEAD_SHOWN: + try: + proc = subprocess.run( # noqa: S603 -- reading one committed file + [_HEAD_GIT, "-C", root, "show", f"HEAD:{spec}"], + capture_output=True, + check=False, + timeout=10, + ) + shown = proc.stdout if proc.returncode == 0 else None + except (OSError, subprocess.SubprocessError): + shown = None + _HEAD_SHOWN[key] = shown + return _HEAD_SHOWN[key] + + +def _head_forget() -> None: + """Drop what was read, for a process that sees HEAD move.""" + _HEAD_SHA.clear() + _HEAD_SHOWN.clear() + + +def _text_mode(raw: bytes, errors: str = "strict") -> str: + """`raw` as a text-mode pipe reads it: utf-8, universal newlines.""" + return raw.decode("utf-8", errors).replace("\r\n", "\n").replace("\r", "\n") + + #: The git hook a merge's own commit runs: judged as a commit. _MERGE_COMMIT = "pre-merge-commit" diff --git a/.chock/bin/launch.sh b/.chock/bin/launch.sh index d0ec00e..0b9fb10 100644 --- a/.chock/bin/launch.sh +++ b/.chock/bin/launch.sh @@ -13,9 +13,28 @@ configured="$(git config --get chock.python 2>/dev/null)" # The recorded interpreter is probed like the rest: a venv whose base Python was removed # still exists, and exec'ing it exits non-zero without a verdict, which agents let through. # A candidate must also answer the probe's token, so a program that merely exits 0 (`true`) is not taken for Python. +# +# On POSIX the probe is the runtime itself: its first statements (plain Python 3) exit unless Python is >= the +# minimum, then write a start marker to fd 9 (CHOCK_START_FD), which this shell reads back. A candidate with no +# marker (not found, 9009 or 127, a stub, Python too old, a SyntaxError) passes to the next; one that wrote it and +# then failed keeps its own exit. Windows (OS or MSYSTEM set) and `-m` keep the probe. +legacy= +case "${OS:-}|${MSYSTEM:-}" in *Windows_NT*|*"|"?*) legacy=1 ;; esac +[ "$runtime" = "-m" ] && legacy=1 +# Only the marker path sets it (to 9); everywhere else an inherited value is cleared, so it never names an fd. +[ -n "$legacy" ] && { CHOCK_START_FD=; export CHOCK_START_FD; } for candidate in "$configured" python3 python py; do - if [ -n "$candidate" ] && probed="$("$candidate" -c 'import sys; print("chock-python"); sys.exit(sys.version_info < (3, 11,))' /dev/null)" && [ "$probed" = "chock-python" ]; then - exec "$candidate" -X utf8 "$runtime" "$@" + [ -n "$candidate" ] || continue + if [ -n "$legacy" ]; then + if probed="$("$candidate" -c 'import sys; print("chock-python"); sys.exit(sys.version_info < (3, 11,))' /dev/null)" && [ "$probed" = "chock-python" ]; then + exec "$candidate" -X utf8 "$runtime" "$@" + fi + elif command -v "$candidate" >/dev/null 2>&1; then + exec 3>&1 + marker="$(CHOCK_START_FD=9 "$candidate" -X utf8 "$runtime" "$@" 9>&1 1>&3 3>&-)" + status=$? + exec 3>&- + [ "$marker" = "chock-python" ] && exit "$status" fi done echo "chock: no working Python 3.11+ found (tried chock.python, python3, python, py), so this hook cannot check anything. Install Python, or point chock at one: git config chock.python /path/to/python" >&2 diff --git a/README.md b/README.md index 7a63309..247e170 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,7 @@ Tiers: `commit` is a git hook or CI gate that exits non-zero. `in-agent` is the chock is on PyPI, but the release there (0.15.2, 30 Sep 2026) is older than the engine this page describes. Install the frozen engine from its commit (Python 3.11 or newer): ```bash -pip install "chock @ git+https://github.com/open-coder-ai/chock@5a4b6287a46e07f9f856d9bbe10622bd1ff2e021" +pip install "chock @ git+https://github.com/open-coder-ai/chock@a6ec2f3603da832ed43fabace95504e5e13b013b" ``` ### Two ways to adopt it