coderio 0.4.4__tar.gz → 0.5.0__tar.gz

{coderio-0.4.4 → coderio-0.5.0}/.github/workflows/ci.yml

@@ -67,9 +67,11 @@ jobs:
 
       - name: Audit dependencies for known vulnerabilities
         # Scans installed packages against the PyPI advisory database.
-        # Non-blocking (continue-on-error) — reports issues without failing CI.
+        # BLOCKING since 2026-08-28 (audit finding: continue-on-error made the
+        # scan decorative — known CVEs could never turn CI red). If a flagged
+        # vuln is a false positive / unfixable, add an explicit --ignore-vuln
+        # with a comment rather than re-adding continue-on-error.
         shell: bash
-        continue-on-error: true
         run: |
           uv pip install pip-audit
           uv run pip-audit
@@ -86,6 +88,20 @@ jobs:
         run: |
           uv run python -m pytest -q --cov=coderio --cov-report=term-missing --cov-fail-under=75
 
+      - name: MCP extra smoke (install + loader import)
+        # The mcp extra was never installed in CI (audit 2026-09-04 P1-17):
+        # `load_mcp_tools_sync` — the code path behind README's "MCP support"
+        # — was never executed anywhere, in tests or CI. Install the extra
+        # from the frozen lock and at least run the loader test module
+        # against the real adapters package. One matrix leg is enough (the
+        # loader is pure Python; this step exists so the import path can't
+        # rot silently).
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
+        run: |
+          uv sync --frozen --extra dev --extra mcp
+          uv run python -c "from coderio.mcp_loader import load_mcp_tools_sync; print('mcp loader import OK')"
+          uv run python -m pytest tests/test_mcp_loader.py -q
+
       - name: Type check (mypy)
         # HARD GATE for clean modules. pyproject.toml's [[tool.mypy.overrides]]
         # lists modules with known type issues (ignore_errors=true) — each is a

{coderio-0.4.4 → coderio-0.5.0}/.github/workflows/release.yml

@@ -28,7 +28,18 @@ jobs:
   # workflow covers pushes/PRs, but a tag could be cut from a commit that
   # predates a fix; this gate makes the release itself fail loudly instead.
   test:
-    runs-on: ubuntu-latest
+    # Runs on ubuntu AND windows: windows-latest is the priority platform and
+    # a tag could otherwise ship a Windows-only regression (2026-08-28 audit).
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    env:
+      # Mirror ci.yml: Windows runners default to cp1252 and CJK output
+      # crashes with UnicodeEncodeError (audit finding #11).
+      PYTHONIOENCODING: utf-8
+      PYTHONUTF8: "1"
     steps:
       - uses: actions/checkout@v7
       - uses: astral-sh/setup-uv@v7
@@ -94,10 +105,30 @@ jobs:
           /tmp/sdist-test-venv/bin/coderio --help
 
       - name: Create GitHub Release + attach artifacts
+        # Restored (2026-08-28 audit #3): the artifact refactor
+        # accidentally dropped Release creation while the header still
+        # promised it. dist/ is still in this job's workspace; the publish
+        # job downloads the same artifacts separately.
         uses: softprops/action-gh-release@v3
         with:
           generate_release_notes: true
-          files: dist/*.whl dist/*.tar.gz
+          files: |
+            dist/*.whl
+            dist/*.tar.gz
+
+      - name: Upload verified artifacts for publishing
+        # Pass the EXACT artifacts that were verified in the clean venvs to
+        # the publish job — the old flow REBUILT in publish-pypi, so PyPI
+        # could receive a different byte stream than the one verified above
+        # (2026-08-28 audit: non-deterministic build gap).
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: |
+            dist/*.whl
+            dist/*.tar.gz
+          if-no-files-found: error
+          retention-days: 3
 
   publish-pypi:
     # PyPI via Trusted Publishing (OIDC) — no API token to manage or leak.
@@ -108,14 +139,13 @@ jobs:
     permissions:
       id-token: write  # OIDC token for Trusted Publishing
     steps:
-      - uses: actions/checkout@v7
-      - uses: actions/setup-python@v7
+      - name: Download verified artifacts
+        # No rebuild: publish EXACTLY the wheel/sdist verified in the release
+        # job (2026-08-28 audit fix). No checkout needed either.
+        uses: actions/download-artifact@v4
         with:
-          python-version: "3.12"
-      - name: Build (same commit as the verified artifacts)
-        run: |
-          pip install build
-          python -m build
+          name: dist
+          path: dist
       - name: Publish to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
         with:

coderio-0.5.0/.gitignore

@@ -0,0 +1,64 @@
+# OS
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# IDE / Editor
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Node
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+*.egg-info/
+build/
+dist/
+
+# Testing / linting
+.pytest_cache/
+.mypy_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# coderio user data (project-local layer)
+.coderio/
+
+# Misc
+*.log
+.tmp/
+tmp/
+.zcode/
+
+# zcode workspace instructions — local only, not part of the project
+/AGENTS.md
+/AGENTS_EXAMPLE.md
+
+# Local audit/analysis artifacts — single-maintainer working notes (2026-09-02
+# review: 34 untracked items at repo root). Files stay on disk; git just
+# stops listing them. Delete manually when no longer wanted.
+/coderio-*analysis*.md
+/coderio-optimization-checklist-*.md
+/coderio-latest-test-report-*.md
+/coderio-detailed-analysis-*.md
+/coderio-project-analysis.md
+/coderio-vs-mainstream-agents-*.md
+/juejin-post-*.md
+/_test_subagent/
+/docs/blog/
+/hello.py
+/test.py
+
+# Local screenshots / assets at the repo root (not shipped docs images)
+/*.png
+!/docs/images/*.png

{coderio-0.4.4 → coderio-0.5.0}/CHANGELOG.md

@@ -6,6 +6,216 @@ All notable changes to coderio are documented here. The format follows
 `pyproject.toml`'s `[project].version` — `coderio.__version__` reads it via
 `importlib.metadata`.
 
+## [0.5.0] — 2026-09-04
+
+### Security — 2026-09-04 third-party audit batch (P0; each fix re-verified by an independent adversarial round, mutation-tested, and runtime-audited)
+
+An external third-party audit (report committed as `PROJECT_REVIEW_2026-09-04.md`)
+found five confirmed issues and three seam breaks where the implementation was
+weaker than the documentation's promise. All fixed and double-checked:
+
+- **P0-1 · command blacklist leaked plain (non-obfuscated) footguns.**
+  `${HOME}` brace expansion, any drive letter (`Remove-Item -Recurse D:\`,
+  `rd /s /q D:\data`) and UNC targets, PowerShell home spellings
+  (`$USERPROFILE` / `$env:USERPROFILE` / `%USERPROFILE%`), the documented
+  symbolic chmod modes (`a+rwx`, `ugo+rwx`) plus `7777`/`1777` supersets,
+  PowerShell `Stop-Computer`/`Restart-Computer`, `diskutil partitionDisk` /
+  `apfs delete*`, the `cp`/`shred`/`wipefs` raw-device family, named-function
+  fork bombs (`bomb(){ bomb|bomb & }; bomb`, newline-call variant), and the
+  `Remove-Item` pipeline form (`ls D:\ | ri -r`) — all blocked now. One false
+  positive fixed in the same pass: `git rm -r D:\proj` was caught by an alias
+  match at any token position; the PowerShell branch now matches only at the
+  segment head.
+- **P0-2 · web_fetch SSRF: shared-address ranges leaked.** `is_global`
+  depends on the CPython version (CVE-2024-4032 reclassified several ranges in
+  3.11.9/3.12.3), so on older 3.11 patch releases the Aliyun internal metadata
+  service (`100.100.200.200`, the classic SSRF payout) was fetchable. Explicit
+  CIDR blocks for 100.64/10, 192.0.0.0/24, 192.88.99.0/24, 198.18.0.0/15 —
+  version-independent — plus the `is_global` catch-all for everything else.
+- **P0-3 · VerifyGate counted `echo foo.py` as verification.** The
+  file-reference branch required only that the command MENTION a written file.
+  Now the segment must actually run it: an interpreter/runner head
+  (`python src/foo.py`, `uv run …`), the file itself as the command
+  (`./foo.py`), or a known verifier — with shell wrappers unwrapped first
+  (`bash -c 'echo foo.py'` is an echo), inline-code flags closing the segment
+  (`python -c "print('foo.py')"`, incl. `python -u -c`), and Windows
+  `.exe` spellings normalized. `cat`/`git diff`/`ls` mentions never verify.
+- **P0-4 · credentials: non-atomic write + corrupt file silently wiped keys.**
+  A crash mid-write truncated the TOML, `read_credentials` treated corrupt
+  files as empty, and the next save persisted that emptiness — every stored
+  key gone. Writes are now atomic (PID-unique temp file, permission-
+  restricted before key bytes land, `os.replace`); a corrupt file is backed up
+  to `.corrupt` before being rebuilt; `UnicodeDecodeError` (non-UTF-8
+  corruption) is caught explicitly — it previously crashed /setup outright.
+- **P0-5 · the Windows session lock was not mutually exclusive.**
+  `msvcrt.locking` locks at the current position and an append-mode handle
+  starts at open-time EOF — a holder appending under the lock grew the file,
+  so a later opener locked a different byte and both processes "held" the
+  lock (reproduced before the fix). The mutex is now byte [0,1) via
+  `seek(0)`; appends still land at the never-locked EOF; unlock targets the
+  range actually held.
+- **P0-6 · default-config execute could hang forever (Windows).** The plain
+  path used `subprocess.run(timeout=...)`, whose Windows timeout kills only
+  the direct child — grandchildren kept the pipes open and `communicate()`
+  waited for EOF indefinitely (the exact bug `tools/bash.py` had fixed; the
+  production path regressed it). Now Popen + `taskkill /T /F` tree kill (Job
+  fallback) + bounded reap, returning exit 124 at ~timeout; the old Job-at-
+  kill-time approach in `win_job` never contained pre-existing grandchildren.
+- **P0-7 · the documented `Z_API_KEY` path guaranteed an auth failure.**
+  Onboarding skip and the headless error both say "set Z_API_KEY", but
+  `_pick_api_key("anthropic")` read only `ANTHROPIC_API_KEY` — and every
+  coding-plan provider is anthropic-kind. `Z_API_KEY` now falls through
+  (Anthropic's own variable keeps precedence).
+
+### Fixed — P1 behavior defects + P2 hygiene (2026-09-04, same audit)
+
+- **P1-8** the bash probe cache was one class-level value: the first
+  instance's result shadowed every other instance's `[tools].bash_shell`
+  config for the whole process. Now keyed by the configured shell.
+- **P1-9** `activate_skill` returned only "Activated skill: X" — the playbook
+  body reached the system prompt one turn LATER (the docstring's
+  `on_activate_skill` callback never existed). The body now rides the tool
+  result (same-turn context), and re-activation re-supplies it (recovery
+  after context compaction).
+- **P1-10** PLAN mode wrote files: every successful `write_todos` mirrored
+  arbitrary todo content to `<project>/.coderio/plan.md` — bypassing the
+  read-only contract and `/undo`. Suppressed under a PLAN gate (todos still
+  work in memory); the PlanGate nudge no longer advertises the mirror there.
+- **P1-11** sandbox degradation is visible and honest: a degraded run
+  (Linux without bubblewrap) prefixes `[sandbox unavailable: …]` to the tool
+  output, and `auto_allow_if_sandboxed` now works only where the sandbox
+  actually provides a boundary — on macOS / Linux-without-bwrap / Linux job
+  mode it is disabled with a printed reason instead of yielding "zero
+  isolation + zero confirmation".
+- **P1-12** checkpoint `/undo` could silently restore an OLDER state: budget
+  eviction had no floor, so a newest snapshot over budget evicted itself.
+  The newest entry is now eviction-proof; files over the whole budget are
+  skipped with a warning; the multi-instance lost-update boundary is
+  documented.
+- **P1-13** TUI wedge: `worker.cancel()` landing between submit and thread
+  start finished the worker without running its `finally`, leaving
+  `_is_running` stuck True (every submit refused until restart). The stale
+  state is now detected and cleared (one resubmit); the in-flight guard is
+  not weakened, and `action_interrupt` no longer claims cancel() can unblock
+  a running thread.
+- **P1-14** the repo trust gate now covers `.coderio/commands/` and
+  `.coderio/agents/` — prompt templates injected into the model verbatim
+  deserve the same first-use confirmation as skills. NOTE for existing users:
+  repos that ship these directories will re-prompt once (trust is
+  content-keyed).
+- **P1-15** explicit sync-only middleware contract: all four production
+  middlewares inherit `SyncOnlyMiddleware`, and a contract test pins that no
+  async surface is defined (an overriding `aafter_model` was tested and
+  breaks even the sync path — langgraph wires the node differently).
+- **P1-18** multimodal prompts were `str(list)`'d in three places — hook
+  rejection persisted base64 garbage into the session (prompt text lost),
+  `/export` leaked image blobs into markdown, and the TUI encoded every
+  image twice per message. New `session.message.text_of_content` is the
+  single text view; `build_user_content` accepts pre-extracted images.
+- **P1-19** `win_sandbox` now checks `assign_to_job`'s return value (a
+  failure previously meant no resource caps and a dead timeout tree-kill,
+  silently); the `cmd /c` quoting/`$VAR` divergence between sandboxed and
+  plain runs is documented in the module docstring and README. Found during
+  the release gate itself: when the restricted-token launch dies during
+  initialization (NTSTATUS 0xC0000142 family with zero output — observed on
+  a windows-latest runner image roll), `run_sandboxed` now degrades to a
+  visibly-marked plain run instead of returning a mysterious crash code.
+- **P2 hygiene**: `neutralize_base_prompt` removed (deepagents 0.7.6
+  deprecated `BASE_AGENT_PROMPT` with zero internal consumption — the call
+  was a no-op that raised a LangChainDeprecationWarning every startup);
+  dead `render_markdown`/`render_error`/`render_tool_call` and the ghost
+  `on_truncated` protocol method removed; factory's duplicate custom-provider
+  branch collapsed; `HookSpec` caches its compiled matcher (was a fresh
+  re.compile per tool call per hook); hook `communicate` failures kill and
+  reap the child; model-facing `timeout` args bounded (web_fetch ≤ 600s,
+  bash ≤ 3600s).
+- **docs**: the architecture doc no longer describes the removed hand-written
+  loop (`run_step`/`_execute_turn` pseudocode), the deleted `[context]`
+  config section, or the `_invoke_tool` error-grading table; the data-flow
+  chapter follows the real deepagents middleware path; README/README_en
+  dropped the "auto-compaction (60% window trigger)" claim (no such knob);
+  the third-party report itself is committed as
+  `PROJECT_REVIEW_2026-09-04.md`.
+- **CI**: new `MCP extra smoke` leg (ubuntu/py3.12) installs the mcp extra
+  from the frozen lock and runs the loader tests against real adapters —
+  `load_mcp_tools_sync` had never been executed by any test or CI job.
+  Surfaced (and fixed) a pre-existing mypy error that only appears with the
+  py.typed adapters installed.
+
+### Added — 2026-09-03 review batch
+- **Confirm diff preview**: CONFIRM-mode prompts for write_file / edit_file /
+  multi_edit render a unified diff of the change (matching the real tool
+  semantics: replace_all, multi-match failure, multi_edit all-or-nothing).
+- **hooks environment whitelist**: hook subprocesses get CODERIO_* +
+  exec-resolution + temp/locale vars instead of the full os.environ.
+- **credentials hardening**: ACL-restricted before key bytes hit the disk;
+  icacls failures logged; corrupt credentials file no longer crashes /setup.
+- **AGENTS.md walk boundary**: falls back to the enclosing GIT root for
+  repos without coderio config (subdirectory launches keep nearest-wins).
+- **concurrent-submission guard** + interruptible permission wait + escaped
+  model-name retry in onboarding (`m` = change model) + `--version` flag.
+- ROADMAP.md / ROADMAP_en.md added (maintenance status, Now/Next/Later,
+  non-goals).
+
+### Fixed — audit-driven hardening (2026-08-28 + 2026-09-02 review batches)
+- **Command blacklist**: rebuilt segment/token parsing (multi-line, wrapper
+  shells incl. path-qualified and sudo-prefixed, PowerShell/cmd variants);
+  xargs-into-recursive-rm with flags in any position; `find -delete`/
+  `-exec rm` dangerous-root set widened to any absolute path, ~, $HOME, globs
+  (the `rm -rf /etc` blocked / `find /etc -delete` leaked double standard).
+- **Instruction injection**: the AGENTS.md walk is bounded at the launch dir
+  even when no workspace_root is configured (a parent directory's AGENTS.md
+  could previously leak into every project launched from below it).
+- **Hooks**: subprocess environment is now a whitelist (CODERIO_* + exec
+  resolution + temp/locale) instead of a full os.environ copy — repo hooks
+  can no longer read environment secrets; hooks stdout contract documented
+  (raw stdout injects for SessionStart/UserPromptSubmit, no JSON parsing).
+- **Credentials**: the file is created and ACL-restricted BEFORE any key
+  bytes hit the disk (write-then-restrict window closed); icacls failures
+  are logged; a missing Windows username skips inheritance-stripping
+  instead of producing a file nobody can read.
+- **TUI/engine**: a turn in flight no longer accepts a second submission
+  (concurrent engine threads interleaved session writes); Esc now breaks a
+  pending permission-prompt wait (previously blocked up to 120s); interrupt
+  drops the thread checkpoint (dangling tool_calls state) — now regression
+  tested.
+- **run**: timeout path logs why the daemon thread survives and how
+  `[tools].sandbox_mode = "job"` reaps the process tree; headless stdout
+  writes survive interpreter teardown.
+
+### Changed — structure (P2 decomposition, behavior-preserving)
+- `run_deep_agent` decomposed: `TurnSpec` dataclass (15 kwargs → 1 spec),
+  `build_middleware/build_backend/build_subagents` builders, module-level
+  `make_shell_backend` factory; body ≤80 lines, behavior pinned by the
+  existing suite + adversarial equivalence review.
+- `CoderioTUI` (1380 → 983 lines): StreamHandler protocol, agent-thread
+  state, render queue and confirmation wait extracted to
+  `cli/stream_controller.py`; every bare `except: pass` in tui.py now logs.
+- `build_turn_spec` in cli/repl.py is the single CommandPolicy/TurnSpec
+  construction path for headless and TUI runs (was two field-identical
+  copies).
+- Tool-name registry (`tools/taxonomy.py`) is now the literal single source:
+  web_search registered, permission/harness literals re-pointed, the two
+  bash→execute prose regexes merged, the shim removed.
+- tests/e2e filled (5 black-box CLI tests); app.py coverage 36%→95%,
+  tui_runtime.py 35%→96%.
+
+### Added
+- AGENTS.md / CLAUDE.md project instructions injected into the system
+  prompt (nearest-wins, bounded at the project root / git root).
+- Tool-name registry `tools/taxonomy.py` — one definition of engine/harness
+  names and categories (was 6+ drifting ad-hoc copies, the root cause of
+  several recorded P0s).
+- `--version` flag.
+- docs/CONFIG.md — full config.toml field reference, hooks syntax,
+  .mcp.json fields, custom agents/commands, trust mechanism.
+
+### Deprecated / Removed
+- Removed half-demolished relics: [context] config section, RichStream,
+  phase-timeline dead branches, to_langchain_tools passthrough (P2-8 batch).
+- README: removed the Claude Code / aider comparison table; honest
+  macOS-sandbox disclosure added to Known limitations.
+
 ## [0.4.4] — 2026-08-24
 
 ### Added — extensibility & safety-of-agency features (each adversarially reviewed, mutation-verified)
@@ -606,7 +816,13 @@ All notable changes to coderio are documented here. The format follows
 - Rich stream UI + Textual TUI with foldable thinking.
 - jsonl session persistence with compression truncation.
 
-[Unreleased]: https://github.com/Lion-1209/coderio/compare/v0.3.0...HEAD
+[Unreleased]: https://github.com/Lion-1209/coderio/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/Lion-1209/coderio/compare/v0.4.4...v0.5.0
+[0.4.4]: https://github.com/Lion-1209/coderio/releases/tag/v0.4.4
+[0.4.3]: https://github.com/Lion-1209/coderio/releases/tag/v0.4.3
+[0.4.2]: https://github.com/Lion-1209/coderio/releases/tag/v0.4.2
+[0.4.1]: https://github.com/Lion-1209/coderio/releases/tag/v0.4.1
+[0.4.0]: https://github.com/Lion-1209/coderio/releases/tag/v0.4.0
 [0.3.0]: https://github.com/Lion-1209/coderio/releases/tag/v0.3.0
 [0.2.0]: https://github.com/Lion-1209/coderio/releases/tag/v0.2.0
 [0.1.0]: https://github.com/Lion-1209/coderio/releases/tag/v0.1.0

{coderio-0.4.4 → coderio-0.5.0}/CONTRIBUTING.md

@@ -6,16 +6,22 @@ Thanks for your interest in contributing! This guide covers the basics.
 
 ## Development setup
 
+The project uses [uv](https://docs.astral.sh/uv/) for dependency management
+(locked via `uv.lock`, same as CI). Python 3.11+ required.
+
 ```bash
 git clone <repo-url> coderio
 cd coderio
-python -m venv .venv
+uv sync --frozen                 # creates .venv from the lockfile
+uv run pytest -q                 # run anything inside the managed venv
+```
 
-# Windows (Git Bash)
-.venv/Scripts/python.exe -m pip install -e ".[dev]"
+With the venv activated (`.venv/Scripts/activate` on Windows,
+`.venv/bin/activate` elsewhere) the plain commands work too:
 
-# Linux / macOS
-.venv/bin/python -m pip install -e ".[dev]"
+```bash
+python -m pytest -q
+python -m ruff check src tests
 ```
 
 Set your API key:

{coderio-0.4.4 → coderio-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: coderio
-Version: 0.4.4
+Version: 0.5.0
 Summary: A skill-driven coding agent — structural harness, foldable thinking TUI, deepagents engine.
 Author: coderio contributors
 License-Expression: MIT
@@ -15,18 +15,17 @@ Classifier: Operating System :: POSIX :: Linux
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Code Generators
 Requires-Python: >=3.11
 Requires-Dist: ddgs>=4.0
-Requires-Dist: deepagents>=0.6
+Requires-Dist: deepagents<0.8,>=0.7.6
 Requires-Dist: httpx>=0.27
 Requires-Dist: langchain-anthropic>=0.2
 Requires-Dist: langchain-core>=0.3
 Requires-Dist: langchain-openai>=0.2
-Requires-Dist: langchain>=0.3
+Requires-Dist: langchain>=1.0
 Requires-Dist: langgraph-checkpoint-sqlite>=2.0
-Requires-Dist: langgraph>=0.2
+Requires-Dist: langgraph>=1.0
 Requires-Dist: pydantic>=2
 Requires-Dist: rich>=13
 Requires-Dist: textual>=0.40
@@ -47,8 +46,8 @@ Description-Content-Type: text/markdown
 
 [中文](README.md) | **English**
 
-> The agent claims "done" without running the tests? coderio's harness stops it.
-> A local coding agent with **native Zhipu GLM & StepFun Step coding-plan support** — four-tier permissions, layered sandbox, MCP, lifecycle hooks, and an interactive TUI.
+> The agent claims "done" without running the tests? coderio's harness stops it — system-level enforcement, not prompt politeness.
+> A fully open-source local coding agent that runs on **your** endpoint: native Zhipu GLM & StepFun coding-plan support, any Anthropic-protocol or OpenAI-compatible API, four-tier permissions, a layered sandbox, MCP, lifecycle hooks, and an interactive TUI.
 
 ![demo](demo.gif)
 
@@ -61,46 +60,87 @@ coderio    # onboarding wizard on first launch (pick provider, paste API key, au
 
 Requires Python 3.11+; Git Bash on Windows. Linux / macOS supported.
 
+Optional: MCP external tools (`.mcp.json`) need an extra — `pip install "coderio[mcp]"`; without it MCP tools stay disabled (a notice appears at startup).
+
 ## Why coderio
 
-The shared weakness of coding agents: **the model says "I'm done" and you just have to trust it**. coderio turns that sentence into a structural constraint—
+The shared weakness of coding agents: **the model says "I'm done" and you just have to trust it**. Most agents treat that as a prompting problem — coderio treats it as an enforcement problem. The harness holds the termination decision and checks tool-call ground truth (what actually ran, what actually got read) before a turn is allowed to end.
 
-### The Four Gates: the agent can't lie to you
+### The Four Gates: the agent can't talk its way past the harness
 
 | Gate | Behavior |
 |---|---|
-| **VerifyGate** | Wrote code, never ran it, wants to finish → intercepted, forced to continue. Parses real exit codes — **a failing test run does NOT count as verified** |
+| **VerifyGate** | Wrote code, never ran it, wants to finish → intercepted, forced to continue. Parses real exit codes — **a failing test run does NOT count as verified**, and `echo app.py` doesn't count as "running it" |
 | **CompletionGate** | Declares done with pending todos → intercepted |
-| **GroundingGate** | Cites files it never read → intercepted |
+| **GroundingGate** | Cites files it never actually read → intercepted |
 | **PlanGate** | Writes code without a todo list → soft nudge |
 
-Not a prompt-level soft rule — a system-level control based on tool-call ground truth. Claude Code and Codex don't have this.
+Not prompt-level soft rules — a system-level control based on tool-call ground truth, with escalating enforcement: the agent is force-continued twice, then released with a loud warning. Never infinite, never silent.
+
+![harness intercept: the model claims done, unverified](docs/images/harness-warn.svg)
 
-### Native Chinese coding-plan support
+### Where coderio fits
 
-Zhipu **GLM Coding Plan** and StepFun **Step Plan** work out of the box (direct Anthropic-protocol connection) — your subscription quota runs a local agent, no proxies, no middle layer. Also supports OpenAI / Anthropic / Ollama / any OpenAI-compatible endpoint, with multi-profile switching.
+- **Your endpoint, no middleman.** Bring the API you already pay for: Zhipu **GLM Coding Plan** and StepFun **Step Plan** connect directly over the Anthropic protocol (subscription quota runs a local agent — no proxy layer), and OpenAI / Anthropic / Ollama / any OpenAI-compatible endpoint work the same way, with multi-profile switching.
+- **Enforcement, not vibes.** Verified completion, trust-gated repo config, four-tier permissions, a command blacklist for accident prevention, SSRF-protected web_fetch — each layer isolated in its own module.
+- **A reference you can actually read.** A layered monolith (~16k lines of Python) where harness, permissions, sandbox and trust are separate, individually tested modules — built as a working reference for people building their own agents.
 
 ### Layered security, honestly stated
 
 - Four permission tiers (plan read-only / confirm per-action / auto_edit / full)
 - Command blacklist + whitelist (accident prevention); Linux bubblewrap OS sandbox (boundary enforcement)
-- First-use repo-config trust confirmation (hostile-repo protection); web_fetch SSRF protection
+- First-use repo-config trust confirmation — `config.toml`, `.mcp.json`, skills, **custom commands and custom agents** are all gated (hostile-repo protection); web_fetch SSRF protection
 - The blacklist/whitelist are **accident prevention, not adversarial defense** — adversarial protection comes from the sandbox + permissions; use a VM for hostile code
 
+In confirm mode, every write is one keystroke away from allow / deny / custom reply:
+
+![confirm mode's vertical permission menu](docs/images/confirm-menu.svg)
+
+## First task in 3 minutes
+
+After install + onboarding, launch the TUI and just talk:
+
+```bash
+coderio
+```
+
+Try this:
+
+```
+Find the failing test under tests/, fix it, and run the suite to confirm
+```
+
+What you'll see:
+
+1. **Thinking streaming live** (Ctrl+O folds/unfolds each round)
+2. **Every tool call on its own line** — files read, commands run, output capped to one summary line
+3. A live **TODO panel** whenever the agent plans with write_todos:
+
+![TODO panel](docs/images/todo-panel.svg)
+
+4. The final answer in a blue **coderio** panel, plus a one-line "files changed this turn" summary; in confirm mode, every disk write goes through the vertical menu above
+5. Skeptical? `/undo` rolls the agent's writes back step by step; `/think` unfolds what it was thinking
+
+No TUI? Headless works the same:
+
+```bash
+coderio run "count the Python lines under src/ and summarize" --quiet
+```
+
 ## Feature highlights
 
 - **Interactive TUI**: streaming output, foldable thinking (Ctrl+O), collapsible TODO panel, vertical permission menu, task interruption (Esc), slash-command autocomplete, session management
 - **Custom slash commands**: `.coderio/commands/*.md` (project/user layers) turn prompt templates into `/commands` with `$ARGUMENTS` substitution; built-ins can never be shadowed
 - **Custom subagents**: `.coderio/agents/*.md` define personas invokable via `task(subagent_type=...)` — you customize WHO the agent is, its capabilities stay on the read-only stack
 - **File rollback**: every structured agent write is auto-checkpointed; `/undo` reverts step by step (a bad edit is one command from gone)
-- **Plan artifact**: the task list auto-mirrors to `.coderio/plan.md`; edit it by hand and the agent adopts your version at the next turn
+- **Plan artifact**: the task list auto-mirrors to `.coderio/plan.md`; edit it by hand and the agent adopts your version at the next turn (read-only PLAN mode doesn't write it)
 - **Headless mode**: `coderio run "task"` one-shot execution (CI / scripts / benchmarks) with graded exit codes
 - **MCP support**: connect external tools via `.mcp.json` (Claude Code-compatible format), managed with `coderio mcp`
 - **Lifecycle hooks**: `[[hooks]]` run your commands at PreToolUse / PostToolUse / UserPromptSubmit (exit 2 = block) — IO contract compatible with Claude Code
 - **Three-layer skills**: bundled + user + project, progressive disclosure saves context
-- **Context governance**: auto-compaction (60% window trigger), large-block offload, sqlite checkpoints across turns
+- **Context governance**: deepagents auto-summarization + large-block offload, sqlite checkpoints across turns
 - **Subagents**: research (read-only, double-enforced) + general-purpose (inherits the main agent's full security stack)
-- **Engineering discipline**: 950+ tests, 82% coverage (CI floor 75%), mypy hard gate, uv.lock, 3 OS × 2 Python CI matrix
+- **Engineering discipline**: 1280+ tests, coverage gated at 75% in CI, mypy hard gate, uv.lock, 3 OS × 2 Python CI matrix
 
 <details>
 <summary><b>Config example</b> (click to expand)</summary>
@@ -122,7 +162,7 @@ matcher = "write_file|edit_file"
 command = "python .hooks/protect.py"   # JSON on stdin; exit 2 = block
 ```
 
-MCP, the sandbox 4-tuple, and more: [docs/coderio-architecture.md](docs/coderio-architecture.md).
+Every config field — MCP, hooks, the sandbox 4-tuple — is documented in [docs/CONFIG.md](docs/CONFIG.md); architecture design in [docs/coderio-architecture.md](docs/coderio-architecture.md).
 
 </details>
 
@@ -140,12 +180,13 @@ Type `/` inside the TUI for all commands (/resume sessions, /mode permissions, /
 
 ## Known limitations
 
-- The Windows write-sandbox currently equals job mode (true isolation awaits the ACL work — documented honestly)
+- The Windows write-sandbox currently equals job mode (true isolation awaits the ACL work — documented honestly); sandboxed commands run through `cmd /c`, so quoting/`$VAR` semantics differ from the Git Bash plain path; **macOS has no OS-level sandbox** (bubblewrap is Linux-only) — use a VM for adversarial scenarios
+- Where a sandbox can't deliver (Linux without bubblewrap), degradation is explicit: tool output is marked `[sandbox unavailable: …]`, and `auto_allow_if_sandboxed` is disabled — execute prompts per command instead of running with "zero isolation + zero confirmation"
 - Blacklist/whitelist are accident-prevention by design (regex can be bypassed by obfuscation); use the sandbox / a VM for adversarial scenarios
 
 ## Origin
 
-A spare-time project, open-sourced as a working reference for developers building their own coding agents. The name is **code + rio** (the author's English name is Lion; "codelion" sounded odd).
+A spare-time project, open-sourced as a working reference for developers building their own coding agents. The name is **code + rio** (the author's English name is Lion; "codelion" sounded odd). Project direction and maintenance status: [ROADMAP_en.md](ROADMAP_en.md).
 
 ## Contributing & License