coderio 0.4.3__tar.gz → 0.4.4__tar.gz

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

@@ -76,13 +76,15 @@ jobs:
 
       - name: Run tests with coverage
         # Enforces a coverage floor so coverage can't silently regress.
-        # The 70% floor is conservative (current baseline is ~75%) — it catches
-        # gross regressions (a module losing its tests) without failing on
-        # minor fluctuations. pyproject.toml's [tool.coverage.report]
-        # fail_under=60 is the local-dev default; CI enforces the stricter 70%.
+        # Measured baseline 2026-08-24: 82% total (weakest: sandbox_runner 43%
+        # — POSIX-only branches skip on Windows). The 75% floor keeps real
+        # headroom for platform variance while catching gross regressions
+        # (a module losing its tests). pyproject.toml's
+        # [tool.coverage.report] fail_under=60 is the local-dev default;
+        # CI enforces the stricter 75%.
         shell: bash
         run: |
-          uv run python -m pytest -q --cov=coderio --cov-report=term-missing --cov-fail-under=70
+          uv run python -m pytest -q --cov=coderio --cov-report=term-missing --cov-fail-under=75
 
       - name: Type check (mypy)
         # HARD GATE for clean modules. pyproject.toml's [[tool.mypy.overrides]]

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

@@ -6,6 +6,49 @@ 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.4] — 2026-08-24
+
+### Added — extensibility & safety-of-agency features (each adversarially reviewed, mutation-verified)
+- **Custom slash commands**: `.coderio/commands/*.md` (project layer overrides user layer)
+  turn prompt templates into `/commands` with `$ARGUMENTS` substitution and optional
+  frontmatter descriptions. Built-ins can never be shadowed — exact matches refused at
+  expansion, case variants dropped at discovery (Windows case-insensitive-FS spoof
+  surface). Bodies route straight to the engine, never re-enter built-in dispatch: a
+  repo file with body `/mode full` cannot flip the permission gate.
+- **Custom subagents**: `.coderio/agents/*.md` define personas invokable via
+  `task(subagent_type=...)`. Persona-only customization — every assembled spec rides
+  the same PLAN-gated read-only middleware stack as the built-in research agent;
+  reserved names dropped at discovery AND re-filtered at wiring time. Adversarially
+  verified end-to-end: write tools physically unbound, nested task() blocked on three
+  independent layers.
+- **File checkpoints + `/undo`**: every structured write (write_file/edit_file/
+  multi_edit) snapshots the target's pre-write state; `/undo` reverts step by step.
+  multi_edit is one undo step; error paths consume no depth; failed restores re-push
+  for retry; bounded at 50 entries / 64MB; deliberately survives /clear. Shell-side
+  writes (redirects) bypass it — OS sandboxing is the layer for that class.
+- **Plan artifact**: the todo list mirrors to `<project>/.coderio/plan.md` after every
+  successful write_todos; user edits between messages are adopted at next turn start
+  (human override wins) with an injected note so the model doesn't execute a stale plan.
+
+### Fixed
+- Three prompt surfaces (PlanGate nudge, CompletionGate force-continue, CODE-workflow)
+  directed the model to coderio's legacy `todo()` tool whose store is an orphan the
+  gates never check — completion instructions could loop forever. All now point at
+  `write_todos`, the canonical surface.
+- Custom-command discovery anchor joined at the caller after a runtime audit caught
+  production loading zero commands while globbing root-level *.md files as agents.
+- Subagent discovery anchors walk up to the project root like skills/config/trust
+  (launching from a repo subdirectory previously missed project-layer definitions).
+- Frontmatter descriptions are truncated to 1024 chars and control-char-stripped —
+  a 90KB description previously reached the main model verbatim every turn.
+
+### Changed
+- CI coverage floor raised 70% → 75% against a measured 82% baseline (gate verified
+  to trip); stale coverage comments corrected.
+- tui.py decomposed (1627 → 1332 lines): input dispatch + session lifecycle extracted
+  to testable TuiRuntime; behavior verified statement-equivalent by AST diff + real
+  Textual input-routing tests.
+
 ## [0.4.3] — 2026-08-21
 
 ### Security — P1/P2 hardening (audit-verified, adversarial + mutation tested)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: coderio
-Version: 0.4.3
+Version: 0.4.4
 Summary: A skill-driven coding agent — structural harness, foldable thinking TUI, deepagents engine.
 Author: coderio contributors
 License-Expression: MIT
@@ -90,13 +90,17 @@ Zhipu **GLM Coding Plan** and StepFun **Step Plan** work out of the box (direct
 ## 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
 - **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
 - **Subagents**: research (read-only, double-enforced) + general-purpose (inherits the main agent's full security stack)
-- **Engineering discipline**: 850+ tests, 80% coverage, mypy hard gate, uv.lock, 3 OS × 2 Python CI matrix
+- **Engineering discipline**: 950+ tests, 82% coverage (CI floor 75%), mypy hard gate, uv.lock, 3 OS × 2 Python CI matrix
 
 <details>
 <summary><b>Config example</b> (click to expand)</summary>
@@ -132,7 +136,7 @@ coderio mcp add github --type http --url ...          # manage MCP
 coderio skills install                               # install skill suites
 ```
 
-Type `/` inside the TUI for all commands (/resume sessions, /mode permissions, /profile configs, /think unfold reasoning).
+Type `/` inside the TUI for all commands (/resume sessions, /mode permissions, /undo file writes, /think unfold reasoning).
 
 ## Known limitations
 

{coderio-0.4.3 → coderio-0.4.4}/README.md

@@ -45,13 +45,17 @@ coderio    # 首次启动进入 onboarding 向导（选 provider、填 API key
 ## 特性一览
 
 - **交互式 TUI**：流式输出、思考折叠（Ctrl+O）、可折叠 TODO 面板、纵向权限菜单、任务中断（Esc）、slash 命令补全、会话管理
+- **自定义 slash 命令**：`.coderio/commands/*.md`（项目级/用户级）把提示词模板变成 `/命令`，`$ARGUMENTS` 占位符替换，内置命令不可被遮蔽
+- **自定义子代理**：`.coderio/agents/*.md` 定义 `task(subagent_type=...)` 可调的专属人格——只定制"是谁"，能力恒为只读栈
+- **文件回滚**：agent 的每次结构化写盘自动快照，`/undo` 一键逐级恢复（改坏文件不再可怕）
+- **计划产物**：任务清单自动镜像到 `.coderio/plan.md`，你手动编辑它，下一轮 agent 自动采纳你的版本
 - **headless 模式**：`coderio run "任务"` 单次运行（CI / 脚本 / benchmark），退出码分级
 - **MCP 支持**：`.mcp.json`（Claude Code 兼容格式）接入外部工具，`coderio mcp` 命令行管理
 - **生命周期 hooks**：`[[hooks]]` 在 PreToolUse / PostToolUse / UserPromptSubmit 等事件执行你的命令（exit 2 = 阻断），IO 契约与 Claude Code 兼容
 - **skills 三层加载**：bundled + 用户 + 项目层，渐进披露省上下文
 - **上下文治理**：自动压缩（60% 窗口触发）、大块 offload、sqlite 检查点跨轮持久化
 - **子 agent**：research（只读，双重强制）+ general-purpose（继承主 agent 全部安全层）
-- **工程纪律**：850+ 测试、80% 覆盖率、mypy 硬门、uv.lock 锁定、3 OS × 2 Python CI 矩阵
+- **工程纪律**：950+ 测试、82% 覆盖率（CI 卡 75% 下限）、mypy 硬门、uv.lock 锁定、3 OS × 2 Python CI 矩阵
 
 <details>
 <summary><b>配置示例</b>（点击展开）</summary>
@@ -87,7 +91,7 @@ coderio mcp add github --type http --url ...          # 管理 MCP
 coderio skills install                               # 安装 skill 套件
 ```
 
-TUI 内输入 `/` 查看全部命令（/resume 恢复会话、/mode 切权限、/profile 切配置、/think 展开思考）。
+TUI 内输入 `/` 查看全部命令（/resume 恢复会话、/mode 切权限、/undo 回滚文件写入、/think 展开思考）。
 
 ## 已知限制
 

{coderio-0.4.3 → coderio-0.4.4}/README_en.md

@@ -45,13 +45,17 @@ Zhipu **GLM Coding Plan** and StepFun **Step Plan** work out of the box (direct
 ## 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
 - **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
 - **Subagents**: research (read-only, double-enforced) + general-purpose (inherits the main agent's full security stack)
-- **Engineering discipline**: 850+ tests, 80% coverage, mypy hard gate, uv.lock, 3 OS × 2 Python CI matrix
+- **Engineering discipline**: 950+ tests, 82% coverage (CI floor 75%), mypy hard gate, uv.lock, 3 OS × 2 Python CI matrix
 
 <details>
 <summary><b>Config example</b> (click to expand)</summary>
@@ -87,7 +91,7 @@ coderio mcp add github --type http --url ...          # manage MCP
 coderio skills install                               # install skill suites
 ```
 
-Type `/` inside the TUI for all commands (/resume sessions, /mode permissions, /profile configs, /think unfold reasoning).
+Type `/` inside the TUI for all commands (/resume sessions, /mode permissions, /undo file writes, /think unfold reasoning).
 
 ## Known limitations
 

{coderio-0.4.3 → coderio-0.4.4}/docs/coderio-architecture.md

@@ -39,12 +39,12 @@ coderio 是一个**技能驱动的编程 agent**：它的"骨架"是 Lion-Skills
 
 | 模块 | 行数 | 职责 | 关键文件 |
 |------|------|------|----------|
-| `agent/` | ~2500 | deepagents 引擎、harness/permission middleware、提示词构建、流式协议 | deep_loop.py, harness_middleware.py, permission_middleware.py, harness.py, prompts.py |
-| `cli/` | ~3800 | Typer 应用、Textual TUI、Rich 流式 UI、slash 命令、凭证/onboarding | tui.py, repl.py, stream.py, app.py, onboarding.py |
-| `tools/` | ~1100 | 工具集 + 权限门 + langchain 适配（路径隔离由 deepagents virtual_mode 处理） | bash.py, permission.py, base.py |
-| `config/` | ~400 | 三层 TOML 配置合并 + 用户目录 bootstrap | loader.py, models.py |
-| `skills/` | ~220 | SkillStore 三层加载（bundled < user < project） | store.py, parser.py, models.py |
-| `session/` | 260 | jsonl 追加式会话存储 + resume + 压缩截断 | store.py, message.py |
+| `agent/` | ~3600 | deepagents 引擎、harness/permission middleware、计划产物、自定义子代理、提示词构建、流式协议 | deep_loop.py, harness_middleware.py, permission_middleware.py, harness.py, plan_artifact.py, custom_agents.py, prompts.py |
+| `cli/` | ~5300 | Typer 应用、Textual TUI（渲染）+ TuiRuntime（输入分发/会话生命周期）、自定义 slash 命令、Rich 流式 UI、凭证/onboarding | tui.py, tui_runtime.py, repl.py, stream.py, app.py, commands.py, custom_commands.py, tui_onboarding.py |
+| `tools/` | ~3000 | 工具集 + 文件写入 checkpoint + 权限门 + 命令黑名单 + OS 沙箱 + langchain 适配 | bash.py, permission.py, command_policy.py, checkpoint.py, base.py |
+| `config/` | ~900 | 三层 TOML 配置合并 + 仓库信任门 + 用户目录 bootstrap | loader.py, models.py, trust.py |
+| `skills/` | ~255 | SkillStore 三层加载（bundled < user < project）+ 共享 frontmatter 解析 | store.py, parser.py, models.py |
+| `session/` | ~330 | jsonl 追加式会话存储 + resume + 压缩截断 | store.py, message.py |
 | `llm/` | 320 | 模型工厂 + provider context window 探测 | factory.py, probe.py |
 
 ### 依赖方向（关键约束）
@@ -268,12 +268,13 @@ is_interrupted()（用户中断检查，agent 线程在每轮开头调用）
 
 `NullStream` 全空实现，用于测试/headless。
 
-### 6.5 TUI 交互（`cli/tui.py`）
+### 6.5 TUI 交互（`cli/tui.py` + `cli/tui_runtime.py`）
 
 Textual 8.x App，核心设计：
 
-- **线程模型**：agent 在 Textual Worker 后台线程跑，UI 更新通过 `_render_q`（thread-safe deque）+ 60ms 定时器排空
-- **流式渲染**：dict 分派表（`_RENDER_DISPATCH`）映射 action → handler，每个 handler返回 streaming/final/none 决定滚动策略
+- **渲染与分发分离**（S3 拆分）：`CoderioTUI` 只管 widget 树与流式渲染；输入路由、slash 处理、会话生命周期在 `TuiRuntime`（两阶段构造：先建 runtime，`bind()` 时把带 TUI 引用的 gate 接上——confirm 模式否则会在 Textual 接管终端后死于 input() 死锁）
+- **线程模型**：agent 在后台线程跑，UI 更新通过 `_render_q`（thread-safe deque）+ 定时器排空
+- **流式渲染**：dict 分派表映射 action → handler，每个 handler 返回 streaming/final/none 决定滚动策略
 - **中断**：`Esc` / `⏹ 中断` 按钮 → `_interrupted` 标志位，agent 流循环检查 `is_interrupted()` → `InterruptedError` → 黄色"已中断"面板
 - **confirm 模式**：`TuiPermissionGate` 用 `ConfirmMenu`（纵向选择菜单）+ `threading.Event` 跨线程同步，↑↓ 选择 + Enter 确认
 - **可视化选择器**：`/mode`（ModePickerScreen）、`/profile`（ProfilePickerScreen）、`/resume`（SessionPickerScreen）
@@ -290,14 +291,18 @@ Textual 8.x App，核心设计：
 | 类别 | 工具 |
 |------|------|
 | 读 | read_file, list_dir, glob, grep |
-| 写 | write_file, edit_file, multi_edit |
+| 写 | write_file, edit_file, multi_edit（写前自动 checkpoint，`/undo` 可回滚）|
 | 执行 | bash（Git Bash，Windows 自动探测，.venv 自动激活，进程树超时杀）|
-| 计划 | todo（TodoStore，harness 读它）|
+| 计划 | write_todos（deepagents 原生，镜像到 `.coderio/plan.md` 供用户编辑）|
 | 外部 | web_search, web_fetch |
 | 记忆 | note（跨会话长期记忆）|
 
 **权限门**（`permission.py`）：plan / confirm / auto_edit / full 四模式。`DESTRUCTIVE_TOOLS`（write_file/edit_file/multi_edit/execute/web_fetch/note）在 plan 模式全挡、confirm 模式逐个问、auto_edit 自动放行文件编辑但仍问高危工具、full 全放。
 
+**文件 checkpoint**（`checkpoint.py`，S4）：三个结构化写工具落盘前快照进内存栈（50 条 / 64MB 上限），`/undo` 逐级回滚；bash 重定向等 shell 路径不覆盖——OS 级沙箱才是那一层的答案。
+
+**计划产物**（`plan_artifact.py`，S5）：write_todos 成功后任务清单镜像到 `<project>/.coderio/plan.md`；用户在两轮之间手改它，下一轮开始自动采纳其版本并注入提示。
+
 **命令审查层**（`command_review.py` + `command_policy.py`）：权限门只管"哪个工具能执行"，不管"命令内容是什么"。shell（execute）不受 virtual_mode 约束，所以额外加了一层 `CommandReviewMiddleware`——内置黑名单挡住 `rm -rf /`、`mkfs`、fork bomb、`dd of=/dev/`、`shutdown` 等破坏性命令。即使 FULL 模式也挡（安全优先于"full=全放行"字面语义）。用户可在 config.toml `[tools].blocked_commands` 追加正则黑名单。`network_allowed=false` 可禁用 web_fetch/web_search（离线模式）。
 
   **这不是真 OS 沙箱**：混淆命令（base64 解码、变量展开）可绕过正则。目标是挡住意外/粗心的破坏（占真实事故绝大多数），不是对抗性模型。真隔离需要容器/seccomp（未来工作）。

{coderio-0.4.3 → coderio-0.4.4}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "coderio"
-version = "0.4.3"
+version = "0.4.4"
 description = "A skill-driven coding agent — structural harness, foldable thinking TUI, deepagents engine."
 readme = "README_en.md"
 license = "MIT"
@@ -190,10 +190,11 @@ asyncio_mode = "auto"
 source = ["coderio"]
 
 [tool.coverage.report]
-# Local-dev coverage floor. CI enforces a stricter 70% via --cov-fail-under
+# Local-dev coverage floor. CI enforces a stricter 75% via --cov-fail-under
 # (see .github/workflows/ci.yml). This 60% is the "running tests in your
 # editor" safety net — lower than CI so local runs don't fail on partial
-# test selection. Current baseline: ~75% total, deep_loop 75%, middleware 80%+.
+# test selection. Measured baseline 2026-08-24: 82% total; known weakest
+# sandbox_runner 43% (POSIX-only branches skip on Windows).
 fail_under = 60
 
 [tool.mypy]

coderio-0.4.4/src/coderio/agent/custom_agents.py

@@ -0,0 +1,94 @@
+"""Custom subagents: ``.coderio/agents/*.md`` (project) + ``~/.coderio/agents/*.md`` (user).
+
+A file's filename (minus .md) is the subagent NAME used via
+``task(subagent_type="<name>")``; optional frontmatter ``description`` tells
+the MAIN model when to delegate; the body is the subagent's SYSTEM PROMPT.
+
+SECURITY MODEL — this is persona customization only, never tool escalation.
+Every discovered agent is assembled onto the SAME read-only middleware stack
+as the built-in research subagent (hooks + PermissionMiddleware(PLAN) +
+CommandReviewMiddleware): it can read and search, never write or execute,
+regardless of what its prompt says or which permission mode the caller runs
+in. A hostile repo can therefore at worst add a misleading persona/prompt —
+the same trust surface as SKILL.md bodies.
+
+Names colliding with built-in subagent types ("research", "general-purpose")
+are dropped at discovery — exact AND case variants — so a repo file can't
+hijack or spoof a trusted type (same near-miss logic as custom commands).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from coderio.skills.parser import sanitize_description, split_frontmatter
+
+# Subagent types coderio itself provides. Discovered files with these names
+# (any casing) are ignored — task(subagent_type=...) is matched by deepagents
+# verbatim, so an exact-collision file would shadow trusted behavior, and on
+# Windows's case-insensitive FS a case variant is reachable while looking like
+# the trusted type in transcripts.
+RESERVED_AGENT_NAMES = frozenset({"research", "general-purpose"})
+RESERVED_CI = frozenset(n.lower() for n in RESERVED_AGENT_NAMES)
+
+MAX_AGENT_BYTES = 128 * 1024  # system prompts are small; bigger = junk/bomb
+
+
+@dataclass(frozen=True)
+class CustomAgent:
+    """One discovered custom subagent definition."""
+
+    name: str  # task(subagent_type=...) value, without leading slash
+    description: str  # shown to the MAIN model for delegation decisions
+    system_prompt: str  # the subagent's persona/instructions
+    source_layer: str  # "user" | "project" — for /help-style listings
+
+
+def _load_layer(layer_dir: Path | None, layer_name: str) -> dict[str, CustomAgent]:
+    out: dict[str, CustomAgent] = {}
+    if not layer_dir:
+        return out
+    layer_dir = Path(layer_dir)
+    if not layer_dir.is_dir():
+        return out
+    for md in sorted(layer_dir.glob("*.md")):
+        # Name from FILENAME (not frontmatter) — mirrors custom commands: the
+        # tree the user sees must match the string they pass to task().
+        name = md.stem
+        if not name or any(ch.isspace() for ch in name):
+            continue  # task() takes a bare token; spaced names are unreachable
+        try:
+            if md.stat().st_size > MAX_AGENT_BYTES:
+                continue
+            raw = md.read_text(encoding="utf-8", errors="replace")
+        except OSError:
+            continue
+        raw = raw.replace("\x00", "")  # providers 400 on NUL
+        fm, body = split_frontmatter(raw)
+        body = body.strip()
+        if not body:
+            continue  # empty persona would send the subagent in blind
+        out[name] = CustomAgent(
+            name=name,
+            description=sanitize_description(fm.get("description", "")),
+            system_prompt=body,
+            source_layer=layer_name,
+        )
+    return out
+
+
+def discover_custom_agents(
+    project_dir: Path | str | None = None,
+    user_dir: Path | str | None = None,
+) -> dict[str, CustomAgent]:
+    """Discover custom subagent definitions from both layers.
+
+    Both params are LAYER DIRECTORIES whose immediate ``*.md`` children define
+    agents (e.g. ``<project>/.coderio/agents``) — NOT a project root; callers
+    join the anchor themselves (same convention as load_skill_store). Project
+    layer overrides user layer on conflict. Reserved names are dropped.
+    """
+    merged = _load_layer(Path(user_dir) if user_dir else None, "user")
+    merged.update(_load_layer(Path(project_dir) if project_dir else None, "project"))
+    return {k: v for k, v in merged.items() if k.lower() not in RESERVED_CI and k not in RESERVED_AGENT_NAMES}

{coderio-0.4.3 → coderio-0.4.4}/src/coderio/agent/deep_loop.py

@@ -298,22 +298,18 @@ def _build_extra_tools(tools, skill_store, active_skills):
     return extra
 
 
-def _build_research_subagent(command_policy=None, hook_runner=None):
-    """Return the research subagent spec (read-only, physically isolated).
-
-    Tool exclusion uses the compat layer (_deepagents_compat) so that a
-    deepagents API change degrades gracefully instead of crashing.
-
-    HooksMiddleware (2026-08-14 v3 audit #12): without it, ``task()``-delegated
-    work bypassed the user's PreToolUse/PostToolUse hooks entirely. The runner
-    is shared with the main agent (stateless across fire() calls).
-
-    Permission + CommandReview: execution-time enforcement on top of the
+def _readonly_subagent_middleware(command_policy=None, hook_runner=None) -> list:
+    """Assemble the READ-ONLY middleware stack shared by the research subagent
+    and every user-defined custom subagent (hooks → PermissionMiddleware(PLAN)
+    → CommandReviewMiddleware). One function so the two can never drift: if a
+    custom agent got a weaker stack, task(subagent_type=...) would be a
+    privilege-escalation primitive dressed as a feature.
+
+    Permission + CommandReview are execution-time enforcement on top of the
     model-visibility whitelist. The whitelist filters what the model SEES,
-    these middlewares gate what actually RUNS. This subagent uses its own
-    hardcoded PLAN gate so it can never be upgraded to write access via the
-    caller's permission mode (an FULL/auto caller must not turn the "read-only"
-    subagent into a writing one).
+    these middlewares gate what actually RUNS. The hardcoded PLAN gate means a
+    FULL/auto caller cannot upgrade the subagent to write access, and neither
+    can anything written in a custom .md system prompt.
     """
     from coderio.agent._deepagents_compat import make_research_subagent_middleware
 
@@ -331,6 +327,19 @@ def _build_research_subagent(command_policy=None, hook_runner=None):
 
     policy = command_policy or CommandPolicy.default()
     middleware.append(CommandReviewMiddleware(policy))
+    return middleware
+
+
+def _build_research_subagent(command_policy=None, hook_runner=None):
+    """Return the research subagent spec (read-only, physically isolated).
+
+    Tool exclusion uses the compat layer (_deepagents_compat) so that a
+    deepagents API change degrades gracefully instead of crashing.
+
+    HooksMiddleware (2026-08-14 v3 audit #12): without it, ``task()``-delegated
+    work bypassed the user's PreToolUse/PostToolUse hooks entirely. The runner
+    is shared with the main agent (stateless across fire() calls).
+    """
     return {
         "name": "research",
         "description": (
@@ -355,7 +364,40 @@ def _build_research_subagent(command_policy=None, hook_runner=None):
             "- The calling agent only sees your final message, not your "
             "intermediate tool calls — make sure your answer is complete."
         ),
-        "middleware": middleware,
+        "middleware": _readonly_subagent_middleware(command_policy, hook_runner),
+    }
+
+
+def _drop_trusted_name_collisions(custom_specs: list[dict], trusted_specs: list[dict]) -> list[dict]:
+    """Defense-in-depth name filter applied at WIRING time (see call site).
+
+    deepagents builds {name: spec} LAST-WINS and custom specs sit at the END
+    of the subagents list — if discovery's reserved-name drop ever regressed,
+    a repo file named research.md would silently REPLACE the trusted spec.
+    This second filter makes a single-layer regression non-escalating
+    (adversarial-review recommendation). Case-insensitive to mirror the
+    discovery-layer rule even though the engine matches exactly.
+    """
+    trusted_lower = {s["name"].lower() for s in trusted_specs}
+    return [s for s in custom_specs if s["name"].lower() not in trusted_lower]
+
+
+def _build_custom_subagent(agent, command_policy=None, hook_runner=None):
+    """Wrap a discovered CustomAgent (.coderio/agents/*.md) as a subagent spec.
+
+    Persona comes from the file; the SECURITY STACK always comes from
+    _readonly_subagent_middleware — custom definitions customize WHO the agent
+    pretends to be, never WHAT it can do.
+    """
+    description = agent.description or (
+        f"Custom read-only research agent ({agent.source_layer} layer, "
+        f".coderio/agents/{agent.name}.md). Reads and searches only."
+    )
+    return {
+        "name": agent.name,
+        "description": description,
+        "system_prompt": agent.system_prompt,
+        "middleware": _readonly_subagent_middleware(command_policy, hook_runner),
     }
 
 
@@ -425,14 +467,17 @@ def _build_general_purpose_subagent(gate, command_policy, stream=None, hook_runn
     }
 
 
-def _build_inputs(checkpointer, user_input: str, session: Session) -> dict:
+def _build_inputs(checkpointer, user_input: str | list[dict[str, Any]], session: Session) -> dict:
     """Build the messages input for the agent stream.
 
     With a checkpointer: only pass the new user message (deepagents restores
     prior state from sqlite). Without: pass full conversation history.
     """
     if checkpointer is not None:
-        return {"messages": [HumanMessage(content=user_input)]}
+        # langchain declares list[str | dict] while we carry list[dict[str, Any]];
+        # list invariance flags the narrower list even though every element
+        # satisfies the wider union at runtime.
+        return {"messages": [HumanMessage(content=user_input)]}  # type: ignore[arg-type]
     return {"messages": _build_history_messages(session.messages)}
 
 
@@ -455,7 +500,9 @@ def _run_stream(agent, inputs, thread_id, recursion_limit, stream, session, seen
 
 
 def run_deep_agent(
-    user_input: str,
+    # str OR multimodal content-block list (docstring below) — build_user_content
+    # returns either depending on whether images are attached.
+    user_input: str | list[dict[str, Any]],
     model,
     session: Session,
     stream=None,
@@ -547,6 +594,40 @@ def run_deep_agent(
         if ups.context:
             user_input = f"{prompt_text}\n\n[hook context]\n{ups.context}"
 
+    # Plan artifact (.coderio/plan.md, S5): the harness's todo list mirrored to
+    # an editable file. Anchor walks up like skills/config/trust (SA-4 lesson —
+    # a literal runtime dir would miss project plans when launched from a
+    # subdirectory). The SAME TodoStore instance feeds both the middleware
+    # mirror and the artifact, so write_todos → materialize and turn-start
+    # adopt stay in sync. Subagent HarnessMiddleware gets neither: the plan has
+    # exactly one owner. Adoption runs BEFORE the hooks/session append below so
+    # the injected note lands inside this turn's user message.
+    from coderio.agent.plan_artifact import AdoptionNote, PlanArtifact
+    from coderio.config.loader import _find_project_dir
+    from coderio.tools.todo import TodoStore
+
+    plan_artifact = None
+    adoption_note = ""
+    if harness_enabled:
+        plan_artifact = PlanArtifact(
+            anchor=_find_project_dir(project_dir) / ".coderio",
+            store=TodoStore(),
+        )
+        adopted = plan_artifact.adopt_if_edited()
+        if adopted:
+            adoption_note = AdoptionNote(count=adopted, path=plan_artifact.path).render()
+
+    # Plan artifact adoption (S5): if the user edited .coderio/plan.md between
+    # turns, their version already replaced the todo store above — tell the
+    # model so it doesn't keep executing a stale plan.
+    if adoption_note:
+        if isinstance(user_input, str):
+            user_input = f"{user_input}\n\n{adoption_note}"
+        else:
+            # Multimodal content blocks: append as an extra text block so
+            # attached images survive (same concern as the hook context above).
+            user_input = [*user_input, {"type": "text", "text": adoption_note}]
+
     session.append(Message.user(user_input))
 
     sp = _resolve_system_prompt(system_prompt, skill_store, active_skills)
@@ -557,7 +638,15 @@ def run_deep_agent(
         from coderio.agent.hooks import HooksMiddleware
 
         middleware.append(HooksMiddleware(hook_runner))
-    middleware.append(HarnessMiddleware(stream=stream, enabled=harness_enabled))
+
+    middleware.append(
+        HarnessMiddleware(
+            stream=stream,
+            enabled=harness_enabled,
+            todos=plan_artifact.store if plan_artifact is not None else None,
+            plan_artifact=plan_artifact,
+        )
+    )
     if gate is not None:
         middleware.append(PermissionMiddleware(gate))
     # Command-content review: always active (even in FULL mode). Blocks rm -rf /,
@@ -581,16 +670,42 @@ def run_deep_agent(
         bash_shell=bash_shell,
     )
 
+    # Custom user/project subagents (.coderio/agents/*.md). Layer dirs joined
+    # HERE (not inside discovery) mirroring load_skill_store's caller-joins
+    # convention — passing the bare project root would glob every root *.md
+    # into an agent definition (same trap the custom-commands audit caught).
+    #
+    # ANCHOR PARITY (seam SA-4): skills/config/trust all anchor at
+    # _find_project_dir(search_from) which WALKS UP to the project root;
+    # agents used to anchor at the literal runtime dir (workdir or cwd), so a
+    # launch from a repo subdirectory silently loaded zero project-layer
+    # agents while project-layer skills still loaded — the exact
+    # discovery-vs-loading scope asymmetry of incident #3. Walk up with the
+    # same rule; workspace_root stays the starting point when set.
+    from coderio.agent.custom_agents import discover_custom_agents
+    from coderio.config.loader import _find_project_dir
+
+    trusted_specs = [
+        _build_research_subagent(command_policy=command_policy, hook_runner=hook_runner),
+        _build_general_purpose_subagent(gate, command_policy, stream=stream, hook_runner=hook_runner),
+    ]
+    custom_specs = [
+        _build_custom_subagent(ca, command_policy=command_policy, hook_runner=hook_runner)
+        for ca in discover_custom_agents(
+            project_dir=_find_project_dir(project_dir) / ".coderio" / "agents",
+            user_dir=Path.home() / ".coderio" / "agents",
+        ).values()
+    ]
+    # Defense in depth at wiring time — see _drop_trusted_name_collisions.
+    custom_specs = _drop_trusted_name_collisions(custom_specs, trusted_specs)
+
     extra_lc_tools = _build_extra_tools(tools, skill_store, active_skills)
 
     build_kwargs: dict[str, Any] = {
         "model": model,
         "middleware": middleware,
         "backend": backend,
-        "subagents": [
-            _build_research_subagent(command_policy=command_policy, hook_runner=hook_runner),
-            _build_general_purpose_subagent(gate, command_policy, stream=stream, hook_runner=hook_runner),
-        ],
+        "subagents": [*trusted_specs, *custom_specs],
     }
     if sp:
         build_kwargs["system_prompt"] = sp

{coderio-0.4.3 → coderio-0.4.4}/src/coderio/agent/harness.py

@@ -526,8 +526,10 @@ class Harness:
         self.state.plan_nudged = True
         return (
             "\n[nudge] You're writing code but have no task list yet. For non-trivial "
-            'work, call todo(action="add", ...) first to decompose the task into '
-            "verifiable steps. (Trivial fixes like a typo can ignore this.)"
+            "work, decompose the task into verifiable steps via the write_todos tool "
+            "first. Your task list is mirrored to .coderio/plan.md — the user may "
+            "edit that file between messages, and edits are adopted automatically. "
+            "(Trivial fixes like a typo can ignore this.)"
         )
 
     # ------------------------------------------------------ check_termination (hard gates)
@@ -628,9 +630,9 @@ class Harness:
         return (
             True,
             f"[harness] Your task list has {len(pending)} unfinished item(s). Mark "
-            'them complete via todo(action="update", status="completed") only if '
-            "truly done, or finish the remaining work. Do not claim overall "
-            "completion with pending todos.",
+            'them complete via write_todos (status="completed") only if truly '
+            "done, or finish the remaining work. Do not claim overall completion "
+            "with pending todos.",
             None,
         )