coderio 0.4.0__py3-none-any.whl

coderio/agent/harness_middleware.py

@@ -0,0 +1,293 @@
+"""Harness as a deepagents AgentMiddleware.
+
+This ports coderio's structural harness (the "wrote code but never verified →
+block done" hard constraint) into deepagents' middleware layer. The existing
+Harness/HarnessState logic in agent/harness.py is reused unchanged; this module
+is the adapter that wires it into deepagents' after_model / wrap_tool_call hooks.
+
+Why this exists: deepagents is a batteries-included harness (planning tool,
+filesystem, subagents, context management) but it does NOT enforce verification
+before "done" — it trusts the agent. coderio's harness is the one structural
+constraint that must survive the migration. As a middleware, it intercepts:
+  - wrap_tool_call: observe writes/executions (ground truth) + nudge (PlanGate)
+  - after_model:    decide whether the model's "no tool_calls" (want-to-end) is
+                    allowed, or force-continue via jump_to='model' (VerifyGate)
+
+CRITICAL: after_model MUST be decorated with @hook_config(can_jump_to=["model"]).
+Without it, langchain's factory sees can_jump_to=[] and does NOT build the
+conditional edge for this middleware, so jump_to='model' silently does nothing —
+the agent ends despite the harness wanting to force-continue. This was a latent
+bug in the original version (verified against langchain factory.py
+_get_can_jump_to, which reads method.__can_jump_to__).
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from langchain.agents.middleware.types import AgentMiddleware, hook_config
+from langchain_core.messages import AIMessage, HumanMessage
+
+from coderio.agent._deepagents_compat import get_state_todos
+from coderio.agent.harness import Harness, HarnessState
+from coderio.tools.todo import TodoStore
+
+# deepagents tool-name mapping. deepagents uses 'execute' for shell (coderio
+# used 'bash'), and write_file/edit_file (no multi_edit). We translate so the
+# existing Harness logic works without modification.
+_DEEP_VERIFY_TOOL = "execute"
+_DEEP_WRITE_TOOLS = frozenset({"write_file", "edit_file"})
+# deepagents' planning tool is 'write_todos' (coderio used 'todo'). The
+# CompletionGate checks for pending todos — map deepagents' todo tool too.
+_DEEP_TODO_TOOL = "write_todos"
+
+# Translate "bash" → "execute" in harness injection prose. Word-boundary regex
+# (robust to prose changes) instead of a chain of literal .replace() calls that
+# silently no-op when harness.py rewords a phrase.
+_BASH_TO_EXECUTE = re.compile(r"\bbash\b", re.IGNORECASE)
+
+
+def _stream_supports_phase(stream: Any) -> bool:
+    """Does this stream consumer actually display phase changes?
+
+    Avoids paying AgentStateTracker overhead (and polluting the session jsonl
+    timeline) when no one is watching: NullStream (headless tests) and ad-hoc
+    stubs without on_phase_change return False. The real TUI StreamHandler and
+    the live-verify PrintStream opt in by defining on_phase_change.
+    """
+    return stream is not None and hasattr(stream, "on_phase_change")
+
+
+def _to_coderio_name(name: str) -> str:
+    """Translate a deepagents tool name to the coderio name Harness expects."""
+    if name == _DEEP_VERIFY_TOOL:
+        return "bash"
+    if name == _DEEP_TODO_TOOL:
+        return "todo"
+    return name
+
+
+def _result_to_text(result: Any) -> str:
+    """Normalize a deepagents tool result (ToolMessage/str/object) to text for
+    the harness success/failure heuristic.
+
+    For ExecuteResponse (deepagents shell results), appends the exit_code as
+    ``[exit_code: N]`` so the harness's VerifyGate can parse it. Without this,
+    a failed test run (exit != 0) would be treated as "verified" because the
+    raw output text doesn't contain the exit code marker.
+    """
+    if isinstance(result, str):
+        return result
+    # deepagents ReadResult has an `error` attr for failed reads, and `file_data`
+    # for successful ones. Extract the error so the harness's not-found detection
+    # (harness.py: "not found" in result) works.
+    error = getattr(result, "error", None)
+    if isinstance(error, str) and error:
+        return error
+    # Build the text from content/output fields.
+    text = ""
+    content = getattr(result, "content", None)
+    if isinstance(content, str):
+        text = content
+    elif isinstance(content, list):
+        text = "".join(b.get("text", "") for b in content if isinstance(b, dict))
+    else:
+        output = getattr(result, "output", None)
+        if isinstance(output, str):
+            text = output
+        elif result is not None:
+            text = str(result)
+    # Append exit_code marker if the result has one (ExecuteResponse). This
+    # lets _parse_exit_code in harness.py extract it for VerifyGate.
+    exit_code = getattr(result, "exit_code", None)
+    if exit_code is not None and "[exit_code:" not in text:
+        text = f"{text}\n[exit_code: {exit_code}]"
+    return text
+
+
+class HarnessMiddleware(AgentMiddleware):
+    """Enforces coderio's verification harness inside a deepagents agent loop.
+
+    Holds a Harness instance (with its own TodoStore). Observes every tool call
+    to track writes-since-verify, and intercepts the model's termination to block
+    "done" when code was written but never run (escalating: force-continue twice,
+    then release with a warning — never silent, never infinite).
+
+    Harness signals (force-continue / escalation-warn) are emitted via
+    runtime.stream_writer so the TUI's StreamHandler can show them. This is the
+    'custom' stream channel — distinct from 'messages' (token stream) and
+    'updates' (complete messages).
+    """
+
+    def __init__(self, stream=None, enabled: bool = True) -> None:
+        # Wire the phase-observation tracker when a stream consumer is present.
+        # The display pipeline (TUI StatusBar / stream.on_phase_change) already
+        # exists; without a tracker, Harness._track_phase is a no-op and the
+        # status bar's phase slot stays empty. We instantiate the tracker
+        # whenever the stream declares on_phase_change support — that's the
+        # signal a real UI is listening (NullStream and test stubs don't).
+        from coderio.agent.state import AgentStateTracker
+
+        tracker = AgentStateTracker() if _stream_supports_phase(stream) else None
+        self.harness = Harness(
+            state=HarnessState(),
+            todos=TodoStore(),
+            enabled=enabled,
+            state_tracker=tracker,
+            stream=stream,
+        )
+        self.stream = stream
+        self._runtime = None  # captured in wrap_tool_call / after_model
+
+    def _emit(self, runtime: Any, payload: dict) -> None:
+        """Send a custom stream event (harness_continue / harness_warn).
+
+        Uses runtime.stream_writer so the stream consumer (deep_loop.py) picks
+        it up via stream_mode='custom'. Falls back to the legacy stream callback
+        if no runtime (e.g. in unit tests without a real graph).
+        """
+        try:
+            if runtime is not None and hasattr(runtime, "stream_writer"):
+                runtime.stream_writer(payload)
+                return
+        except Exception:  # noqa: S110 — stream_writer may not be available in tests; fall back
+            pass
+        # Fallback: direct stream callback (for tests / non-graph contexts).
+        if self.stream is not None:
+            t = payload.get("type")
+            if t == "harness_continue" and hasattr(self.stream, "on_harness_continue"):
+                self.stream.on_harness_continue(payload.get("reason", ""))
+            elif t == "harness_warn" and hasattr(self.stream, "on_harness_warn"):
+                self.stream.on_harness_warn(payload.get("message", ""))
+
+    # ------------------------------------------------------- observe tool calls
+    def wrap_tool_call(self, request, handler):
+        """Observe every tool execution (ground truth) + apply PlanGate nudge.
+
+        Also captures the runtime reference for after_model's stream_writer use.
+        """
+        self._runtime = getattr(request, "runtime", None) or self._runtime
+        tc = getattr(request, "tool_call", None) or {}
+        name = tc.get("name", "")
+        args = dict(tc.get("args", {}) or {})
+        # deepagents uses 'file_path' for write/edit tools; coderio's harness
+        # expects 'path'. Normalize so observe() records the right path.
+        if "file_path" in args and "path" not in args:
+            args["path"] = args["file_path"]
+
+        result = handler(request)
+        result_text = _result_to_text(result)
+
+        # Feed ground truth to the harness (translate deepagents → coderio names).
+        coderio_name = _to_coderio_name(name)
+        self.harness.observe(coderio_name, args, result_text)
+
+        # Sync deepagents' write_todos into the harness's TodoStore so
+        # CompletionGate can check for pending todos. Only sync when the tool
+        # actually succeeded — a failed write_todos (Error result) means the
+        # graph state wasn't updated, so syncing args would create a mismatch.
+        if name == "write_todos" and "todos" in args and not result_text.startswith("Error"):
+            from coderio.tools.todo import Todo
+
+            todos_data = args["todos"]
+            if isinstance(todos_data, list):
+                self.harness.todos.todos = [
+                    Todo(content=t.get("content", ""), status=t.get("status", "pending"))
+                    for t in todos_data
+                    if isinstance(t, dict)
+                ]
+
+        # Subagent delegation: the task tool returns a subagent's findings,
+        # which may cite files the subagent read but the MAIN agent didn't.
+        # Without this, GroundingGate would flag those citations as ungrounded
+        # and force-continue — turning a complete analysis into a "correction".
+        # We extract file paths from the subagent's result and add them to the
+        # main agent's read set, so the gate treats them as "read via subagent".
+        if name == "task" and result_text:
+            from coderio.agent.harness import _cited_files, _norm_path
+
+            for cited in _cited_files(result_text):
+                # Strip :line suffix, normalize.
+                clean = cited.rsplit(":", 1)[0] if ":" in cited else cited
+                self.harness.state.content_read_files.add(_norm_path(clean))
+
+        # PlanGate: nudge if writing without a todo list (soft, appends to result).
+        aug = self.harness.after_tool_call(coderio_name, args, result_text)
+        if aug and isinstance(result, str):
+            result = result + aug
+        elif aug:
+            # result is a ToolMessage-like object; append to its content if possible
+            try:
+                result.content = _result_to_text(result) + aug
+            except (AttributeError, TypeError):
+                pass
+        return result
+
+    # ------------------------------------------------------- intercept termination
+    @hook_config(can_jump_to=["model"])
+    def after_model(self, state, runtime):
+        """The model produced output. If it wants to end (no tool_calls) but the
+        harness says verification is missing, force the loop to continue.
+
+        Returns a state update dict: {'jump_to':'model','messages':[...]} to
+        force-continue, or None to let the agent end normally. On escalation
+        release, emits a harness_warn signal via stream_writer.
+
+        The @hook_config(can_jump_to=["model"]) decorator is REQUIRED — without
+        it, langchain's factory doesn't build the conditional edge and jump_to
+        silently fails (the agent ends anyway).
+        """
+        self._runtime = runtime or self._runtime
+        messages = state.get("messages", []) if hasattr(state, "get") else getattr(state, "messages", [])
+        last = messages[-1] if messages else None
+        # Only intercept when the model returned final text (no tool calls).
+        if not isinstance(last, AIMessage) or getattr(last, "tool_calls", None):
+            return None
+
+        # Sync todos from graph state before checking termination. This covers
+        # the case where write_todos was called in a PREVIOUS turn (restored
+        # from checkpoint) but the HarnessMiddleware's TodoStore was reset (it's
+        # recreated each run_deep_agent call). Without this, CompletionGate
+        # would see an empty todo list even though graph state has pending todos.
+        state_todos = get_state_todos(state)
+        if state_todos and isinstance(state_todos, list):
+            from coderio.tools.todo import Todo
+
+            self.harness.todos.todos = [
+                Todo(content=t.get("content", ""), status=t.get("status", "pending"))
+                for t in state_todos
+                if isinstance(t, dict)
+            ]
+
+        text = ""
+        content = getattr(last, "content", "")
+        if isinstance(content, str):
+            text = content
+        elif isinstance(content, list):
+            text = "".join(b.get("text", "") for b in content if isinstance(b, dict))
+
+        cont, inject, warn = self.harness.check_termination(text)
+        if cont and inject:
+            # The shared harness.py writes tool-name-agnostic prose that happens
+            # to say "bash" (its original engine's name for the shell tool).
+            # deepagents' shell tool is named 'execute'. Translate the standalone
+            # word "bash" → "execute" so the model calls the right tool.
+            # Word-boundary regex (not literal phrase replace) is robust to
+            # harness.py prose changes: "use bash", "call bash now", "run with
+            # bash" all map correctly without a per-phrase .replace() chain.
+            inject = _BASH_TO_EXECUTE.sub("execute", inject)
+            # Emit a visible signal so the TUI explains why the agent keeps running.
+            self._emit(runtime, {"type": "harness_continue", "reason": inject})
+            # Force-continue: inject the harness demand as a user message.
+            return {"jump_to": "model", "messages": [HumanMessage(content=inject)]}
+        if warn:
+            self._emit(runtime, {"type": "harness_warn", "message": warn})
+        # Fire the final phase transition (COMPLETE) when the turn is truly
+        # ending — either a clean finish or an escalation release. The TUI's
+        # on_phase_change clears the status bar's phase slot on 'complete'.
+        if self.harness.state_tracker is not None:
+            self.harness.state_tracker.finish(hint="turn end")
+            if self.stream is not None and hasattr(self.stream, "on_phase_change"):
+                self.stream.on_phase_change("complete", 0, "turn end")
+        return None

coderio/agent/permission_middleware.py

@@ -0,0 +1,52 @@
+"""Permission gate as a deepagents AgentMiddleware.
+
+Wraps coderio's PermissionGate (the 4-tier access system: plan/confirm/
+auto_edit/full) so it runs BEFORE every tool execution inside a deepagents
+agent loop.
+
+No path translation or WorkspacePolicy — file path isolation is handled by
+deepagents' backend virtual_mode (/foo.py → {root}/foo.py, forced
+relative_to(root) check). This middleware only controls WHICH tool types
+may execute based on the permission mode.
+"""
+
+from __future__ import annotations
+
+from langchain.agents.middleware.types import AgentMiddleware
+from langchain_core.messages import ToolMessage
+
+
+class PermissionMiddleware(AgentMiddleware):
+    """Enforces coderio's permission gate inside a deepagents agent loop.
+
+    Intercepts every tool call via wrap_tool_call. Calls gate.check() with
+    the tool name + args BEFORE execution. The gate decides based on tool
+    type + permission mode (FULL/CONFIRM/AUTO_EDIT/PLAN).
+
+    Tool names are passed as-is (deepagents native names like 'execute',
+    'write_file', 'edit_file'). The tool classification sets in base.py
+    use these same native names.
+    """
+
+    def __init__(self, gate) -> None:
+        self.gate = gate
+
+    def wrap_tool_call(self, request, handler):
+        """Check permission before executing; block if denied."""
+        tc = getattr(request, "tool_call", None) or {}
+        name = tc.get("name", "")
+        args = dict(tc.get("args", {}) or {})
+
+        decision = self.gate.check(name, args)
+        if decision is True:
+            return handler(request)
+
+        # Denied (False) or custom reply (str). Build a ToolMessage so the model
+        # gets a clear, actionable result it can react to.
+        tool_call_id = tc.get("id", "")
+        if decision is False:
+            content = f"Permission denied: tool {name!r} blocked in {self.gate.mode} mode."
+        else:
+            # str — user's custom reply. Deny execution but feed the instruction.
+            content = f"Permission denied by user: {decision}"
+        return ToolMessage(content=content, tool_call_id=tool_call_id, name=name)

coderio/agent/prompts.py

@@ -0,0 +1,304 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from coderio.skills.store import SkillStore
+
+
+@dataclass
+class ActiveSkills:
+    """Tracks currently-active skills for the session (spec §2.4)."""
+
+    _active: dict = field(default_factory=dict)  # name -> Skill
+
+    def activate(self, skill) -> bool:
+        """Activate a skill (load its body into context). Idempotent: if the
+        skill is already active, does nothing and returns False (avoids
+        re-reading the file on duplicate activation). Returns True if newly activated."""
+        if skill is None:
+            return False
+        if skill.name in self._active:
+            return False  # already active — skip the redundant load_body()
+        skill.load_body()
+        self._active[skill.name] = skill
+        return True
+
+    def deactivate(self, name: str) -> bool:
+        return self._active.pop(name, None) is not None
+
+    def is_active(self, name: str) -> bool:
+        return name in self._active
+
+    def all(self) -> list:
+        return list(self._active.values())
+
+    def clear(self) -> None:
+        self._active.clear()
+
+    def active_tools(self) -> list:
+        """Aggregate executable tools carried by all active skills.
+
+        Each skill may ship a tools.py with a TOOLS list (see Skill.load_tools).
+        When a skill is activated, its tools are added here so the agent loop
+        can bind them to the model. Deactivation removes them (naturally — the
+        skill is dropped from _active). Deduplicates by tool name (first wins).
+        """
+        tools: list = []
+        seen: set[str] = set()
+        for skill in self._active.values():
+            for t in skill.load_tools():
+                t_name = getattr(t, "name", "")
+                if t_name and t_name not in seen:
+                    tools.append(t)
+                    seen.add(t_name)
+        return tools
+
+
+def _os_context() -> str:
+    """Build an OS-specific context clause for the system prompt.
+
+    The bash tool's behavior differs by platform (Git Bash on Windows, native
+    bash on Linux/macOS). Telling the model the wrong OS causes it to emit
+    wrong path styles or platform-specific idioms."""
+    import sys
+
+    if sys.platform == "win32":
+        return (
+            "You are coderio, a coding agent working in the user's project on Windows.\n"
+            "You have tools to read/write/edit files, run bash commands (Git Bash), search, manage"
+        )
+    return (
+        "You are coderio, a coding agent working in the user's project.\n"
+        "You have tools to read/write/edit files, run bash commands, search, manage"
+    )
+
+
+_BASE_INSTRUCTIONS = """\
+{os_context}
+todos, and fetch the web. You serve TWO kinds of requests — recognize which one and behave
+accordingly. Getting this wrong (running the heavy coding workflow on a quick question, or
+answering a coding task with chat alone) is a failure mode.
+
+## 0. Core behavior
+
+  • Be concise and direct. Don't over-explain unless asked. Lead with the answer or action,
+    not with "I'll now..." or "Let me..." — just do it.
+  • Professional objectivity: prioritize accuracy over validating the user's beliefs.
+    Disagree respectfully when the user is incorrect. Avoid unnecessary superlatives,
+    praise, or emotional validation.
+  • When something fails repeatedly, STOP and analyze WHY — don't keep retrying the same
+    approach. If you're blocked, tell the user what's wrong and ask for guidance.
+  • Keep working until the task is fully complete. Don't stop partway and describe what you
+    would do — just do it. Only yield back when done or genuinely blocked.
+  • For longer tasks, give brief progress updates at reasonable intervals (one sentence
+    recapping what's done and what's next). Don't narrate every tool call.
+  • Prefer small, verifiable changes over large rewrites. Make a change, test it, then
+    move on. If a change turns out wrong, revert and try a different approach — don't
+    stack patches on a broken foundation.
+
+## 1. First, classify the intent
+
+Every user message is ONE of these. Decide before acting:
+
+  • CODE  — the user wants code written/changed/created/deleted, a bug fixed, a feature
+    built, a file refactored, a command run that mutates state. Signals:
+    "实现/写/改/修/加/重构/跑一下/构建/部署" (CN) or
+    "implement/write/fix/modify/add/refactor/build/deploy/create" (EN) —
+    any request that should end with files or commands changing.
+  • QA    — the user wants knowledge or an explanation:
+    "X 是什么 / 为什么 / 怎么理解 / 有什么区别 / 对比一下 / 解释一下" (CN) or
+    "what is / why / how does / explain / difference between / compare" (EN).
+    No file should change. You MAY use read-only tools
+    (list_dir/read_file/grep/web_search/web_fetch) to ground your answer, but you must NOT
+    write/edit files or build a todo list.
+  • ANALYZE — the user wants a judgment or assessment of existing code/design/architecture:
+    "这样设计好不好 / 哪个方案更合适 / 帮我评审 / 这个实现有什么问题 / 怎么优化" (CN) or
+    "is this design good / which approach is better / review this / what's wrong with /
+    how to improve / assess" (EN). You MUST
+    read the relevant code first, then answer with EVIDENCE (cite what you read), separate
+    fact from speculation, and present trade-offs rather than dogmatic conclusions.
+
+If a message mixes intents (e.g. "explain X and then implement it"), handle the QA/ANALYZE
+part conversationally FIRST, then switch to CODE mode for the implementation.
+
+## 2. CODE mode — the coding workflow (MANDATORY when writing code)
+
+For ANY code task, follow this workflow. Each step has a corresponding skill playbook —
+the step summaries below are ALWAYS in effect (they are your skeleton); the FULL playbook
+for a step is loaded on-demand via activate_skill(step_name) when you reach that step and
+need its detailed guidance. Do not load a playbook unless you are at that step.
+
+  0. EXPLORE FIRST — before proposing anything, use list_dir / read_file / grep to look at
+     the current directory and relevant files. Build an accurate picture of the project
+     (structure, conventions, what already exists) BEFORE you ask questions or write code.
+     NEVER generate code based on assumptions about files you haven't read. If the task
+     touches existing code, read that code first.
+  1. clarifying-questions — AFTER exploring, if the request has ANY ambiguity (tech stack
+     unspecified, scope unclear, hidden assumptions, possible X-Y problem), ask clarifying
+     questions FIRST and WAIT for the user's answers.
+  2. spec-writing — for non-trivial features, write a short design/spec.
+  3. task-breakdown — break the work into verifiable, ordered tasks (use the todo tool).
+     Batch all edits for one task before updating the todo list — don't call
+     write_todos after every single edit. Update todos when a task STATUS
+     changes (pending → in_progress → completed), not after each file edit.
+     Each write_todos call costs a full model round-trip, so updating 5 times
+     for 5 small edits wastes 4 unnecessary calls.
+  4. executing-plans — implement task-by-task, verify each step, commit frequently.
+     Read a file ONCE per task — don't re-read it after every edit. You already
+     know its contents from the first read; trust your memory within the same
+     task. Re-read only if you're switching to a DIFFERENT task or if edits by
+     another tool may have changed lines you need.
+     EXECUTION STAGE — while/after implementing, bring in the right skill (call
+     activate_skill to load one when it matches):
+       • testing       — turn the task's "完成定义" into a repeatable test.
+       • debugging     — when a bug/error/crash appears, locate the ROOT CAUSE first
+         (observe → hypothesize → experiment → narrow), THEN fix — don't guess-edit.
+       • code-review   — before committing, review correctness/security first, then
+         readability (leave style to linters). Issues found flow into verify-and-fix.
+  5. verify-and-fix — turn "done" into "verified done"; fix root causes not symptoms.
+     (The harness will BLOCK you from declaring done if you wrote code but never ran it.)
+  6. commit-message — write proper commit messages when committing.
+
+Only a truly trivial, single-action CODE task (e.g. "fix this one typo", "rename this
+variable") may skip clarification. If you are about to CREATE a file or WRITE multiple
+lines of code, the task is NOT trivial — clarify first. When unsure whether to clarify,
+ALWAYS clarify. It is better to ask one question than to build the wrong thing.
+
+### Large files (avoid truncation)
+Your single response has a token limit (~16k). A large file (e.g. a 500-line game in one
+HTML file) will be TRUNCATED if written in one write_file call, producing a broken file.
+For large files: write the skeleton first (write_file with the structure/stubs), then fill
+in sections with edit_file/multi_edit or note append. Prefer multiple smaller files over one
+giant file. If a file needs >300 lines, split the work across several tool calls.
+
+## 3. QA / ANALYZE mode — the general-agent guarantees
+
+When the intent is NOT code-writing, you are a capable general assistant. These guarantees
+apply (they are what make you a usable agent, not just a code-spitter):
+
+  • **Match effort to the question.** A greeting ("你好"/"hello"), small talk, or a simple
+    factual question gets a direct text reply — NO tools, NO exploration, NO "let me first
+    look at the project." Only reach for tools when the user's question actually requires
+    reading files or running commands. If you can answer from your own knowledge, do so.
+  • Be direct and concise. Answer the actual question in the user's language (Chinese in,
+    Chinese out). Do not pad, do not preface, do not apologize. Lead with the answer.
+  • Ground answers in the project. If the question is about THIS codebase, READ the relevant
+    files first (read_file/grep) — never explain "your" code from assumption. Quote the
+    specific lines/functions you base your answer on.
+  • Separate fact from speculation. State what you verified by reading vs. what you infer.
+    For ANALYZE especially: present trade-offs and alternatives, not a single dogmatic take.
+    "It depends on X; if Y then A is better, if Z then B" beats "always do A".
+  • **Never cite a file you haven't read this turn.** A claim like "loader.py:81 does X"
+    is only valid if you opened loader.py. Documentation and memory go stale; the source
+    is ground truth. If you find yourself about to assert something about a file's
+    contents, read it FIRST — otherwise you risk confidently stating things that are
+    wrong. (This is enforced structurally: the harness blocks ungrounded citations.
+    Don't fight it — read the file and ground your analysis.)
+  • Use tools to be accurate, not to perform. web_search/web_fetch when the user asks about
+    something external; read_file/grep when about the repo. But don't tool-call for show on a
+    question you can answer directly.
+  • **Activate the matching skill for non-trivial ANALYZE tasks.** Skills are your playbooks —
+    loading one gives you a structured methodology instead of freestyling. Trigger rules:
+      - **First contact with a project in a new conversation** (no prior context about its
+        structure, tech stack, or conventions): activate_skill("onboarding-unknown-codebase")
+        as your VERY FIRST action, before any list_dir/read_file. This is mandatory — you
+        cannot meaningfully analyze or review a codebase you haven't systematically mapped.
+        "分析这个项目" / "看看这个目录" / "有哪些值得优化的点" (CN) or
+        "analyze this project" / "look at this directory" / "what can be improved" (EN)
+        in a fresh conversation ALL qualify as first-contact → start with onboarding.
+      - **Already familiar with the project** (this conversation has established context),
+        user asks for quality assessment: activate_skill("code-review").
+      - "这段代码有什么 bug/怎么调试" (CN) / "what's the bug / how to debug" (EN)
+        → activate_skill("debugging").
+      - "这段代码怎么改进/有什么问题" (CN) / "how to improve / what's wrong" (EN)
+        (project already understood) → activate_skill("code-review").
+    Do this BEFORE you start analyzing. Simple factual questions ("这个函数返回什么") don't
+    need a skill — they're answered by reading one file.
+  • One unified clarification principle across BOTH modes: when genuinely unsure what the
+    user needs, ask ONE focused question rather than guessing. In QA/ANALYZE this is light
+    (a quick clarifying reply); in CODE it is the structured clarifying-questions skill.
+
+## 4. Tools (reference)
+
+  read_file / ls / glob / grep — read the project (always allowed)
+  write_file / edit_file — mutate files (CODE mode; permission-gated)
+  execute — run shell commands, verify code (CODE mode; permission-gated)
+  write_todos — manage a task list (CODE mode, for non-trivial work)
+  web_search / web_fetch — external info (any mode)
+  activate_skill(name) — load an optional playbook (naming, debugging, error-handling,
+    onboarding-unknown-codebase, etc.) when a task matches it.
+
+### Path conventions (OVERRIDES the framework's default examples)
+
+  The framework's built-in prompt may show macOS-style paths like `/Users/name/...` —
+  IGNORE those examples. This project uses **virtual paths** rooted at `/`:
+  - `/AGENTS.md`, `/src/coderio/agent/deep_loop.py`, `/pyproject.toml` — always leading `/`
+  - NEVER use Windows paths (C:\\... or E:\\...) or macOS paths (/Users/...) with read_file/ls/etc.
+  - If a path doesn't exist, it's not a system error — the file just isn't there.
+
+  **IMPORTANT: execute (shell) paths differ from file-tool paths.**
+  - File tools (read_file, write_file, edit_file, ls, glob, grep) use virtual paths
+    like `/foo.py` — the leading `/` maps to the project root.
+  - The `execute` tool runs REAL shell commands. Virtual paths like `/foo.py` do NOT
+    work in shell — `python /foo.py` will fail because the OS interprets `/foo.py`
+    as an absolute OS path (e.g. `C:\foo.py` on Windows), not the project root.
+  - In `execute`, use RELATIVE paths instead: `python foo.py`, `cat foo.py`, `ls -la`.
+  - The shell's working directory is already the project root — relative paths work
+    correctly without any prefix.
+
+### Tool failure recovery (CRITICAL)
+
+  When a tool call fails, DO NOT immediately conclude "the environment is broken" or
+  "the file doesn't exist". Investigate using other tools first:
+
+  • read_file returns "file not found" → the path is likely wrong (relative paths resolve
+    from the project root, not the current file's directory). Use glob("**/filename") or
+    grep to find the actual location, then retry with the correct path.
+  • bash `python -m pytest` fails with "No module named X" → the `python` on PATH may be
+    the wrong interpreter (e.g. Python 2.7 on Windows). Check `.venv/Scripts/python.exe`
+    (Windows) or `venv/bin/python` (Linux/macOS) — if the project has a virtual environment,
+    use that interpreter directly. Run `which -a python python3` to see what's available.
+  • bash command not found → some tools differ between platforms (rg vs grep, py vs python3).
+    Use `which <tool>` to check availability before assuming it exists.
+  • Any tool error → retry with a corrected approach. The first failure is a signal to
+    investigate, not a conclusion. The harness will not penalize you for extra discovery
+    calls, but it WILL penalize you for claiming "done" based on a failed verification.
+"""
+
+# The core workflow chain — these are injected as runtime rules by default, NOT
+# left to the LLM to optionally activate. Cross-cutting skills remain opt-in.
+CORE_CHAIN_SKILLS = (
+    "clarifying-questions",
+    "spec-writing",
+    "task-breakdown",
+    "executing-plans",
+    "verify-and-fix",
+    "commit-message",
+)
+
+
+def build_system_prompt(store: SkillStore, active: ActiveSkills) -> str:
+    parts = [_BASE_INSTRUCTIONS.format(os_context=_os_context())]
+
+    # All skills (core chain + cross-cutting) are listed by DESCRIPTION only — the
+    # full playbook body is loaded on-demand via activate_skill() when the model
+    # judges it relevant. This is the "progressive disclosure" pattern (matches
+    # Anthropic Agent Skills / Claude Code): keep the system prompt small (~tens of
+    # descriptions, not thousands of chars of body text) and load bodies lazily.
+    # Previously CORE_CHAIN_SKILLS bodies were all injected at once (~20K chars /
+    # 75% of the prompt) regardless of relevance — slow, costly, attention-diluting.
+    descs = store.descriptions_for_prompt()
+    if descs:
+        parts.append(
+            "Available skills — ACTIVATE the matching one before starting non-trivial work "
+            "(call activate_skill(name) to load its full playbook). Skills give you a "
+            "structured methodology; without one you're freestyling and likely missing "
+            "systemic issues. Match by the task, not by guessing:\n" + descs
+        )
+
+    # Explicitly user/model-activated skills: their bodies ARE injected (the model
+    # asked for them, so they're now in context).
+    active_bodies = [s.body for s in active.all()]
+    if active_bodies:
+        parts.append("Active skill playbooks (loaded into context):\n\n" + "\n\n---\n\n".join(active_bodies))
+    return "\n\n".join(parts)