sid-harness 0.3.0__py3-none-any.whl

sid_harness/_native.py

@@ -0,0 +1,1639 @@
+"""First-party SID coding loop over routed model tool calls (LQ-576).
+
+The agent works on a bounded in-memory workspace. It can inspect and edit only
+that workspace; approved tests execute through the existing sandbox seam. The
+resulting tree is returned to the caller for the existing independent review
+and BellerBuild scan. No external coding-agent UI or SDK is required.
+"""
+from __future__ import annotations
+
+import difflib
+import fnmatch
+import hashlib
+import json
+import os
+import re
+import subprocess
+import threading
+import time
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+from typing import Any
+
+MAX_FILES = 200
+MAX_WORKSPACE_BYTES = 8 * 1024 * 1024
+MAX_FILE_BYTES = 1024 * 1024
+MAX_TURNS = 12
+MAX_TOOL_CALLS = 32
+MAX_TOOL_OUTPUT_CHARS = 6000
+
+# SUB-94: project policy. The workspace's root instruction files and its
+# optional ``.sid/config`` are loaded by the ONE loop, so the CLI, the local
+# bridge, Studio chat and the workbench all obey the same precedence. Rule text
+# is concatenated in this order (nothing is silently overridden); the config
+# supplies run options, and explicit request flags are applied on top of it.
+PROJECT_RULE_FILES: tuple[str, ...] = ("AGENTS.md", "SID.md")
+PROJECT_CONFIG_PATH = ".sid/config"
+PROJECT_RULES_PRECEDENCE = (
+    ".sid/config options < AGENTS.md < SID.md < explicit request flags "
+    "(--skills, --subagent, --plan); a .sid/config that forces plan mode is a "
+    "read-only floor a run cannot loosen"
+)
+MAX_PROJECT_RULE_BYTES = 256 * 1024
+
+# The loop's base contract stays list/read/write/run_approved_tests. The shell
+# tool is a FIFTH, opt-in tool: it is advertised and honored only when the
+# caller supplies an explicitly approved ``ShellPolicy`` with a sandbox root
+# (``run_native_agent(..., shell_policy=...)``). With no policy — the server
+# path — the loop cannot run a shell at all. Everything below is stdlib-only so
+# the module stays vendorable verbatim into the local harness (``_native.py``).
+SHELL_TOOL_NAME = "run_shell"
+SHELL_MODE_ARGV = "argv"
+SHELL_MODE_SHELL = "shell"
+SHELL_MODES = (SHELL_MODE_ARGV, SHELL_MODE_SHELL)
+DEFAULT_SHELL_TIMEOUT_SECONDS = 120.0
+MAX_SHELL_TIMEOUT_SECONDS = 900.0
+MAX_SHELL_OUTPUT_CHARS = 8000
+
+# Programs that are never run, even when a caller allow-lists them: they are
+# destructive, privilege-escalating, network/tunnel, or a second shell (which
+# would defeat the argv/shell policy itself).
+ALWAYS_DENIED_PROGRAMS = frozenset({
+    "at", "bcdedit", "bash", "chattr", "chgrp", "chmod", "chown", "cmd",
+    "command.com", "crontab", "csh", "curl", "dash", "dd", "del", "diskpart",
+    "doas", "erase", "eval", "exec", "fdisk", "firewall-cmd", "fish", "format",
+    "ftp", "halt", "icacls", "init", "ip6tables", "iptables", "kill",
+    "killall", "ksh", "mkfs", "mount", "nc", "ncat", "net", "netcat", "netsh",
+    "nft", "parted", "pkexec", "pkill", "poweroff", "powershell", "pwsh",
+    "reboot", "reg", "regedit", "rm", "rmdir", "rsync", "runas", "sc", "scp",
+    "schtasks", "service", "setfacl", "sftp", "sh", "shred", "shutdown",
+    "socat", "source", "ssh", "su", "sudo", "systemctl", "takeown", "taskkill",
+    "telnet", "ufw", "umount", "wget", "wmic", "wsl", "xargs", "zsh",
+})
+
+# Default allow-list: the build / install / migrate / format / inspect tools
+# this tool exists for. Callers may replace it (``ShellPolicy(allow=...)``);
+# the ALWAYS_DENIED_PROGRAMS set still applies.
+DEFAULT_ALLOWED_PROGRAMS = frozenset({
+    "7z", "ar", "awk", "basename", "black", "cargo", "cat", "cc", "clang",
+    "clang++", "clippy-driver", "cmake", "cmp", "coverage", "coverage3",
+    "c++", "date", "diff", "dir", "dirname", "dotnet", "echo", "env",
+    "eslint", "flake8", "g++", "gcc", "git", "git-lfs", "go", "gofmt",
+    "gradle", "gradlew", "grep", "gunzip", "gzip", "head", "isort", "jar",
+    "java", "javac", "jest", "ld", "ls", "make", "md", "meson", "mkdir",
+    "msbuild", "mvn", "mvnw", "mypy", "ninja", "node", "npm", "npx", "nuget",
+    "objcopy", "pip", "pip3", "pipenv", "pnpm", "poetry", "prettier",
+    "printenv", "printf", "pwd", "py.test", "pytest", "python", "python3",
+    "realpath", "readlink", "rg", "robocopy", "ruff", "rustc", "rustfmt",
+    "sed", "sort", "strip", "tar", "tee", "tox", "tr", "tsc", "type", "uniq",
+    "unzip", "uv", "uvx", "vite", "wc", "webpack", "where", "which",
+    "xcopy", "yarn", "zip",
+})
+
+# Programs whose ``-c``/``-e`` flags run inline code. Refused unless the caller
+# explicitly opts in (``allow_inline_code=True``); ``-m``/script paths still work.
+INLINE_CODE_PROGRAMS = frozenset({
+    "bun", "deno", "node", "nodejs", "perl", "php", "python", "python3",
+    "ruby",
+})
+INLINE_CODE_FLAGS = frozenset({"-c", "-e", "-r", "-p", "--eval", "--print"})
+
+# Token sequences refused even when the executable is allow-listed: publishing
+# and irreversible history operations. The harness never commits or pushes.
+DENIED_ARG_SEQUENCES: tuple[tuple[str, ...], ...] = (
+    ("cargo", "publish"),
+    ("dotnet", "nuget", "push"),
+    ("gem", "push"),
+    ("git", "checkout", "--"),
+    ("git", "clean"),
+    ("git", "commit"),
+    ("git", "config", "--global"),
+    ("git", "config", "--system"),
+    ("git", "filter-branch"),
+    ("git", "push"),
+    ("git", "remote", "add"),
+    ("git", "remote", "set-url"),
+    ("git", "reset", "--hard"),
+    ("npm", "publish"),
+    ("npm", "unpublish"),
+    ("pip", "uninstall"),
+    ("pnpm", "publish"),
+    ("twine", "upload"),
+    ("yarn", "publish"),
+)
+
+# Shell-injection shapes. In argv mode no shell is involved, so these are only
+# refused as tokens (a harmless literal ``>`` is allowed): splitting, pipes,
+# command substitution, and control bytes. In shell mode redirection and
+# backgrounding are refused too.
+INJECTION_ARGV_MARKERS = (";", "|", "`", "$(", "${", "\n", "\r", "\x00")
+INJECTION_SHELL_MARKERS = (*INJECTION_ARGV_MARKERS, "&", ">", "<")
+
+# Process environment kept in sandbox mode. Anything else (tokens, cloud keys,
+# database URLs) never reaches the child.
+SANDBOX_ENV_ALLOW = frozenset({
+    "CONDA_PREFIX", "HOME", "LANG", "LC_ALL", "PATH", "PATHEXT", "PYTHONPATH",
+    "SYSTEMROOT", "TEMP", "TMP", "TMPDIR", "USERPROFILE", "VIRTUAL_ENV",
+    "WINDIR",
+})
+
+_WINDOWS_ABSOLUTE = re.compile(r"^[A-Za-z]:")
+
+
+# SID Studio guardrail: the observed failure mode was a routed model answering
+# a workspace request with generic assistant boilerplate (declining the file as
+# though it had no editor). The loop's system prompt forbids that family
+# outright and requires that any genuine limitation be named precisely. Kept
+# here (not imported from app.policy) so this module stays stdlib-only and
+# vendorable verbatim.
+WORKSPACE_GUARDRAIL = (
+    "You have the project workspace and its tools — the workspace is right "
+    "here. NEVER decline the files or ask the user to paste or upload them: "
+    "read a file with read_file, or find it with list_files. Do not describe "
+    "yourself as a model that has no editor. If a capability you need is "
+    "genuinely unavailable (for example no sandbox is configured to run the "
+    "tests), name exactly what is missing and the safe next step — never a "
+    "generic refusal."
+)
+
+# SUB-81: plan mode. The same loop runs read-only: write_file is not offered,
+# every intended edit is submitted through propose_file_change (recorded, never
+# applied), and the model must close with a step plan. The proposal is returned
+# as a diff + readback so an explicit client-side Approve can apply it through
+# the existing write-back path.
+PLAN_MODE_SYSTEM = (
+    "PLAN MODE — READ-ONLY. You may inspect the workspace, but you cannot write "
+    "it: write_file, apply_patch, delete_file and move_file are disabled. Submit "
+    "every intended edit through propose_file_change(path, content), which "
+    "records a PROPOSAL and writes nothing. Never say a file was written, saved, "
+    "or changed, and never claim the task is done. Finish with a short numbered "
+    "step plan: the steps, the files each step touches, and how to verify the "
+    "result. The user must approve the plan before anything is applied."
+)
+
+PROPOSE_TOOL = {
+    "type": "function",
+    "function": {
+        "name": "propose_file_change",
+        "description": (
+            "Plan mode only: propose new content for a file. Records the proposal "
+            "for the user to approve; writes NOTHING to the workspace."
+        ),
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "path": {"type": "string"},
+                "content": {"type": "string"},
+            },
+            "required": ["path", "content"],
+            "additionalProperties": False,
+        },
+    },
+}
+
+Complete = Callable[[list[dict[str, Any]], list[dict[str, Any]]], Awaitable[dict[str, Any]]]
+RunTests = Callable[[dict[str, str]], Awaitable[dict[str, Any]]]
+# SUB-58: a caller (the local harness) may stop the loop between turns for a
+# clean interrupt. Called with (step, tool_calls_seen); returning True ends the
+# loop with a partial result. Default None keeps the server path unaffected.
+ShouldStop = Callable[[int, int], bool]
+# A caller may supply extra tool schemas plus ONE dispatch seam (the harness's
+# ToolRegistry). Dispatch receives (name, arguments, files, run_tests) and is
+# responsible for routing base tool names back to _tool_result; it must not fork
+# the execution engine. Default None keeps the server path on the base contract.
+Dispatch = Callable[[str, dict[str, Any], dict[str, str], "RunTests"], Any]
+
+TOOLS = [
+    {
+        "type": "function",
+        "function": {
+            "name": "list_files",
+            "description": "List files available in the approved project workspace.",
+            "parameters": {"type": "object", "properties": {}, "additionalProperties": False},
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "read_file",
+            "description": "Read one file from the approved project workspace.",
+            "parameters": {
+                "type": "object",
+                "properties": {"path": {"type": "string"}},
+                "required": ["path"],
+                "additionalProperties": False,
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "write_file",
+            "description": "Create or replace a text file in the approved project workspace.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "path": {"type": "string"},
+                    "content": {"type": "string"},
+                },
+                "required": ["path", "content"],
+                "additionalProperties": False,
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "apply_patch",
+            "description": (
+                "Edit one file by anchored replacements. Each edit supplies the exact "
+                "existing text (old) that must occur exactly once and its replacement "
+                "(new); use a few surrounding lines as the anchor. Returns a unified "
+                "diff of the applied change. Prefer this over write_file: it sends only "
+                "the changed region, not the whole file."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "path": {"type": "string"},
+                    "edits": {
+                        "type": "array",
+                        "minItems": 1,
+                        "items": {
+                            "type": "object",
+                            "properties": {
+                                "old": {"type": "string"},
+                                "new": {"type": "string"},
+                            },
+                            "required": ["old", "new"],
+                            "additionalProperties": False,
+                        },
+                    },
+                },
+                "required": ["path", "edits"],
+                "additionalProperties": False,
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "delete_file",
+            "description": (
+                "Delete one file from the workspace. Requires confirm=true: a deletion "
+                "is never silent, and it is applied to disk only when the caller "
+                "approves the run's diff."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "path": {"type": "string"},
+                    "confirm": {"type": "boolean"},
+                },
+                "required": ["path", "confirm"],
+                "additionalProperties": False,
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "move_file",
+            "description": (
+                "Move or rename one file inside the workspace. Requires confirm=true "
+                "and never overwrites an existing destination."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "from": {"type": "string"},
+                    "to": {"type": "string"},
+                    "confirm": {"type": "boolean"},
+                },
+                "required": ["from", "to", "confirm"],
+                "additionalProperties": False,
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "grep",
+            "description": (
+                "Search file contents across the workspace. Returns path, line number, "
+                "and line text for each match. Honours the shared path denylist and an "
+                "optional exclude list of glob patterns."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "pattern": {"type": "string"},
+                    "path": {
+                        "type": "string",
+                        "description": "Optional file or directory prefix to search.",
+                    },
+                    "regex": {"type": "boolean"},
+                    "case_sensitive": {"type": "boolean"},
+                    "exclude": {"type": "array", "items": {"type": "string"}},
+                    "max_results": {"type": "integer"},
+                },
+                "required": ["pattern"],
+                "additionalProperties": False,
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "glob",
+            "description": (
+                "Find workspace files by glob pattern (for example **/*.py). Honours "
+                "the shared path denylist and an optional exclude list."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "pattern": {"type": "string"},
+                    "exclude": {"type": "array", "items": {"type": "string"}},
+                    "max_results": {"type": "integer"},
+                },
+                "required": ["pattern"],
+                "additionalProperties": False,
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "run_approved_tests",
+            "description": "Run the test command the user approved before this task.",
+            "parameters": {"type": "object", "properties": {}, "additionalProperties": False},
+        },
+    },
+]
+
+# Opt-in fifth tool. NOT part of TOOLS: the base contract is unchanged and the
+# server path never advertises it. A caller that supplies an approved
+# ``ShellPolicy`` gets this schema appended for the run.
+SHELL_TOOL = {
+    "type": "function",
+    "function": {
+        "name": SHELL_TOOL_NAME,
+        "description": (
+            "Run ONE command the user explicitly approved for this task inside "
+            "the sandbox workspace (build, install, migrate, format, or read-only "
+            "git). Pass an argv list when the policy is 'argv' mode; a single "
+            "command line only when the policy is 'shell' mode. The sandbox root "
+            "is the working directory; the command may not escape it."
+        ),
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "argv": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Command as an argv list (preferred; no shell).",
+                },
+                "command": {
+                    "type": "string",
+                    "description": "Command line (only when the policy is 'shell' mode).",
+                },
+                "cwd": {
+                    "type": "string",
+                    "description": "Relative working directory inside the sandbox root.",
+                },
+                "timeout_seconds": {
+                    "type": "number",
+                    "description": "Requested wall-clock timeout; clamped by policy.",
+                },
+            },
+            "additionalProperties": False,
+        },
+    },
+}
+
+# Tools that mutate the workspace. Plan mode disables all of them (SUB-81) and
+# the harness registry gates them behind the approved-plan check (SUB-56).
+MUTATING_TOOL_NAMES = frozenset(
+    {"write_file", "apply_patch", "delete_file", "move_file"}
+)
+
+DEFAULT_MAX_SEARCH_RESULTS = 100
+MAX_SEARCH_RESULTS = 500
+MAX_GREP_LINE_CHARS = 400
+
+
+class NativeAgentError(ValueError):
+    """The first-party agent could not safely complete the requested loop."""
+
+
+class NativeAgentInputError(NativeAgentError):
+    """The submitted workspace is outside the native agent's accepted bounds."""
+
+
+def _safe_path(raw: Any) -> str:
+    if not isinstance(raw, str) or not raw.strip():
+        raise NativeAgentError("tool path must be a non-empty relative path")
+    path = raw.strip().replace("\\", "/")
+    parsed = PurePosixPath(path)
+    if parsed.is_absolute() or any(part in ("", ".", "..") for part in parsed.parts):
+        raise NativeAgentError("tool path must stay inside the project workspace")
+    lowered = [part.lower() for part in parsed.parts]
+    leaf = lowered[-1]
+    if any(part in {".git", "node_modules", ".venv", "venv", "__pycache__"} for part in lowered):
+        raise NativeAgentError("agent tools cannot access dependency or VCS directories")
+    if any(
+        part == ".env" or (part.startswith(".env.") and part != ".env.example")
+        for part in lowered
+    ):
+        raise NativeAgentError("agent tools cannot read or write environment secret files")
+    if leaf.endswith((".pem", ".key", ".p12", ".pfx")):
+        raise NativeAgentError("agent tools cannot read or write private-key files")
+    return str(parsed)
+
+
+def _glob_segments(pattern: str) -> list[str]:
+    return [part for part in pattern.replace("\\", "/").strip("/").split("/") if part]
+
+
+def _match_glob_segments(pattern_parts: list[str], path_parts: list[str]) -> bool:
+    if not pattern_parts:
+        return not path_parts
+    head = pattern_parts[0]
+    if head == "**":
+        return any(
+            _match_glob_segments(pattern_parts[1:], path_parts[index:])
+            for index in range(len(path_parts) + 1)
+        )
+    if not path_parts:
+        return False
+    return fnmatch.fnmatchcase(path_parts[0], head) and _match_glob_segments(
+        pattern_parts[1:], path_parts[1:]
+    )
+
+
+def _glob_match(pattern: str, rel: str) -> bool:
+    """Path-aware glob: ``*``/``?`` stay inside a segment, ``**`` spans them."""
+    if not pattern:
+        return False
+    if "/" not in pattern.replace("\\", "/"):
+        return fnmatch.fnmatchcase(rel.rsplit("/", 1)[-1], pattern)
+    return _match_glob_segments(_glob_segments(pattern), _glob_segments(rel))
+
+
+def _matches_any(patterns: object, rel: str) -> bool:
+    if not isinstance(patterns, (list, tuple)):
+        return False
+    return any(isinstance(item, str) and _glob_match(item, rel) for item in patterns)
+
+
+def _search_path_ok(rel: str, scope: str | None) -> bool:
+    if not scope:
+        return True
+    scope = scope.replace("\\", "/").strip("/")
+    return rel == scope or rel.startswith(scope + "/")
+
+
+def _search_limit(raw: object) -> int:
+    try:
+        value = int(raw)  # type: ignore[arg-type]
+    except (TypeError, ValueError):
+        return DEFAULT_MAX_SEARCH_RESULTS
+    if value <= 0:
+        return DEFAULT_MAX_SEARCH_RESULTS
+    return min(value, MAX_SEARCH_RESULTS)
+
+
+def _file_changed_diff(path: str, before: str, after: str | None) -> str:
+    return "".join(
+        difflib.unified_diff(
+            before.splitlines(True),
+            (after or "").splitlines(True),
+            fromfile=f"a/{path}",
+            tofile=f"b/{path}" if after is not None else "/dev/null",
+        )
+    )
+
+
+def _grep_result(
+    arguments: dict[str, Any],
+    files: dict[str, str],
+    *,
+    max_results: int = DEFAULT_MAX_SEARCH_RESULTS,
+) -> dict[str, Any]:
+    pattern = arguments.get("pattern")
+    if not isinstance(pattern, str) or not pattern:
+        return {"error": "pattern must be a non-empty string"}
+    use_regex = bool(arguments.get("regex", True))
+    case_sensitive = bool(arguments.get("case_sensitive", True))
+    scope = arguments.get("path")
+    if scope is not None and not isinstance(scope, str):
+        return {"error": "path must be a string"}
+    try:
+        rx = re.compile(
+            pattern if use_regex else re.escape(pattern),
+            0 if case_sensitive else re.IGNORECASE,
+        )
+    except re.error as exc:
+        return {"error": f"invalid grep pattern: {exc}"}
+    limit = _search_limit(arguments.get("max_results", max_results))
+    exclude = arguments.get("exclude")
+
+    matches: list[dict[str, Any]] = []
+    truncated = False
+    for path in sorted(files):
+        if not _search_path_ok(path, scope) or _matches_any(exclude, path):
+            continue
+        try:
+            _safe_path(path)
+        except NativeAgentError:
+            continue
+        for number, line in enumerate(files[path].splitlines(), 1):
+            if not rx.search(line):
+                continue
+            if len(matches) >= limit:
+                truncated = True
+                break
+            matches.append(
+                {
+                    "path": path,
+                    "line": number,
+                    "text": line[:MAX_GREP_LINE_CHARS],
+                }
+            )
+        if truncated:
+            break
+    return {"matches": matches, "count": len(matches), "truncated": truncated}
+
+
+def _glob_result(
+    arguments: dict[str, Any],
+    files: dict[str, str],
+    *,
+    max_results: int = DEFAULT_MAX_SEARCH_RESULTS,
+) -> dict[str, Any]:
+    pattern = arguments.get("pattern")
+    if not isinstance(pattern, str) or not pattern:
+        return {"error": "pattern must be a non-empty string"}
+    limit = _search_limit(arguments.get("max_results", max_results))
+    exclude = arguments.get("exclude")
+    matched: list[str] = []
+    truncated = False
+    for path in sorted(files):
+        if _matches_any(exclude, path) or not _glob_match(pattern, path):
+            continue
+        try:
+            _safe_path(path)
+        except NativeAgentError:
+            continue
+        if len(matched) >= limit:
+            truncated = True
+            break
+        matched.append(path)
+    return {"files": matched, "count": len(matched), "truncated": truncated}
+
+
+def _apply_patch_result(
+    arguments: dict[str, Any],
+    files: dict[str, str],
+    *,
+    max_file_bytes: int = MAX_FILE_BYTES,
+    max_workspace_bytes: int = MAX_WORKSPACE_BYTES,
+) -> dict[str, Any]:
+    try:
+        path = _safe_path(arguments.get("path"))
+    except NativeAgentError as exc:
+        return {"error": str(exc)}
+    if path not in files:
+        return {"error": f"file not found: {path}"}
+    edits = arguments.get("edits")
+    if not isinstance(edits, list) or not edits:
+        return {"error": "edits must be a non-empty array of {old, new} anchors"}
+    original = files[path]
+    updated = original
+    for index, edit in enumerate(edits, 1):
+        if not isinstance(edit, dict):
+            return {"error": f"edit {index} must be an object with old/new"}
+        old = edit.get("old")
+        new = edit.get("new")
+        if not isinstance(old, str) or not isinstance(new, str):
+            return {"error": f"edit {index} requires string old and new"}
+        if not old:
+            return {"error": f"edit {index} anchor (old) must be non-empty"}
+        occurrences = updated.count(old)
+        if occurrences == 0:
+            return {
+                "error": f"edit {index} anchor not found in {path}",
+                "anchor": old[:MAX_GREP_LINE_CHARS],
+            }
+        if occurrences > 1:
+            return {
+                "error": (
+                    f"edit {index} anchor is not unique in {path} "
+                    f"({occurrences} occurrences); include more surrounding context"
+                ),
+                "occurrences": occurrences,
+            }
+        updated = updated.replace(old, new, 1)
+    size = len(updated.encode("utf-8"))
+    if size > max_file_bytes:
+        return {"error": f"file exceeds the {max_file_bytes}-byte limit"}
+    projected_size = sum(
+        len(value.encode("utf-8")) for key, value in files.items() if key != path
+    ) + size
+    if projected_size > max_workspace_bytes:
+        return {"error": f"workspace exceeds the {max_workspace_bytes}-byte limit"}
+    files[path] = updated
+    diff = _file_changed_diff(path, original, updated)
+    additions = sum(
+        1 for line in diff.splitlines() if line.startswith("+") and not line.startswith("+++")
+    )
+    deletions = sum(
+        1 for line in diff.splitlines() if line.startswith("-") and not line.startswith("---")
+    )
+    return {
+        "patched": path,
+        "edits": len(edits),
+        "bytes": size,
+        "additions": additions,
+        "deletions": deletions,
+        "diff": diff,
+    }
+
+
+def _delete_file_result(
+    arguments: dict[str, Any], files: dict[str, str]
+) -> dict[str, Any]:
+    try:
+        path = _safe_path(arguments.get("path"))
+    except NativeAgentError as exc:
+        return {"error": str(exc)}
+    if arguments.get("confirm") is not True:
+        return {
+            "error": "delete_file requires explicit approval: pass confirm=true",
+            "path": path,
+            "pending": True,
+        }
+    if path not in files:
+        return {"error": f"file not found: {path}"}
+    removed = files.pop(path)
+    return {
+        "deleted": path,
+        "approved": True,
+        "bytes": len(removed.encode("utf-8")),
+        "diff": _file_changed_diff(path, removed, None),
+    }
+
+
+def _move_file_result(
+    arguments: dict[str, Any], files: dict[str, str]
+) -> dict[str, Any]:
+    try:
+        source = _safe_path(arguments.get("from"))
+        destination = _safe_path(arguments.get("to"))
+    except NativeAgentError as exc:
+        return {"error": str(exc)}
+    if arguments.get("confirm") is not True:
+        return {
+            "error": "move_file requires explicit approval: pass confirm=true",
+            "from": source,
+            "to": destination,
+            "pending": True,
+        }
+    if source not in files:
+        return {"error": f"file not found: {source}"}
+    if source == destination:
+        return {"error": "from and to must be different paths"}
+    if destination in files:
+        return {"error": f"destination already exists: {destination}"}
+    content = files.pop(source)
+    files[destination] = content
+    return {
+        "moved": {"from": source, "to": destination},
+        "approved": True,
+        "bytes": len(content.encode("utf-8")),
+    }
+
+
+def _validate_workspace(
+    files: dict[str, str],
+    *,
+    max_files: int = MAX_FILES,
+    max_workspace_bytes: int = MAX_WORKSPACE_BYTES,
+    max_file_bytes: int = MAX_FILE_BYTES,
+) -> dict[str, str]:
+    if not isinstance(files, dict) or not files:
+        raise NativeAgentInputError("select a non-empty text workspace before running")
+    if len(files) > max_files:
+        raise NativeAgentInputError(f"workspace exceeds the {max_files}-file limit")
+    normalized: dict[str, str] = {}
+    total_bytes = 0
+    for raw_path, content in files.items():
+        try:
+            path = _safe_path(raw_path)
+        except NativeAgentError as exc:
+            raise NativeAgentInputError(str(exc)) from exc
+        if path in normalized:
+            raise NativeAgentInputError(f"workspace contains duplicate normalized path {path!r}")
+        if not isinstance(content, str):
+            raise NativeAgentInputError(f"workspace file {path!r} must contain text")
+        size = len(content.encode("utf-8"))
+        if size > max_file_bytes:
+            raise NativeAgentInputError(f"workspace file {path!r} exceeds the {max_file_bytes}-byte limit")
+        total_bytes += size
+        normalized[path] = content
+    if total_bytes > max_workspace_bytes:
+        raise NativeAgentInputError(f"workspace exceeds the {max_workspace_bytes}-byte limit")
+    return normalized
+
+
+def _project_rule_path(raw: Any) -> str:
+    path = str(raw).replace("\\", "/").strip()
+    while path.startswith("./"):
+        path = path[2:]
+    return path
+
+
+def _sha256_text(text: str) -> str:
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def load_project_rules(workspace_files: dict[str, str] | None) -> dict[str, Any]:
+    """Load the workspace's root project policy in ONE precedence order.
+
+    ``AGENTS.md`` then ``SID.md`` carry the binding instructions; the optional
+    ``.sid/config`` JSON object supplies run options (``skills``,
+    ``skills_root``, ``subagents``, ``plan``). The returned block names every
+    file with its ``sha256`` and a digest over the whole policy, so a receipt
+    can never claim a run that silently ignored project rules. A malformed
+    config fails closed — it is project policy, not a preference.
+    """
+    normalized: dict[str, str] = {}
+    for raw_path, content in (workspace_files or {}).items():
+        if isinstance(content, str):
+            normalized[_project_rule_path(raw_path)] = content
+
+    files: list[dict[str, Any]] = []
+    instructions: list[str] = []
+    config: dict[str, Any] = {}
+    for path in (*PROJECT_RULE_FILES, PROJECT_CONFIG_PATH):
+        content = normalized.get(path)
+        if content is None:
+            continue
+        size = len(content.encode("utf-8"))
+        if size > MAX_PROJECT_RULE_BYTES:
+            raise NativeAgentInputError(
+                f"project policy file {path!r} exceeds the "
+                f"{MAX_PROJECT_RULE_BYTES}-byte limit"
+            )
+        digest = _sha256_text(content)
+        files.append({"path": path, "bytes": size, "sha256": digest})
+        if path == PROJECT_CONFIG_PATH:
+            try:
+                parsed = json.loads(content)
+            except json.JSONDecodeError as exc:
+                raise NativeAgentInputError(
+                    f"project policy {path!r} is not valid JSON "
+                    f"(line {exc.lineno}: {exc.msg}); refusing to run without it"
+                ) from exc
+            if not isinstance(parsed, dict):
+                raise NativeAgentInputError(
+                    f"project policy {path!r} must be a JSON object; "
+                    "refusing to run without it"
+                )
+            config = parsed
+            continue
+        body = content.strip()
+        if body:
+            instructions.append(f"## {path} (sha256 {digest})\n{body}")
+
+    policy_digest = hashlib.sha256()
+    for entry in files:
+        policy_digest.update(entry["path"].encode("utf-8"))
+        policy_digest.update(b"\x00")
+        policy_digest.update(entry["sha256"].encode("ascii"))
+        policy_digest.update(b"\n")
+    return {
+        "precedence": PROJECT_RULES_PRECEDENCE,
+        "files": files,
+        "sources": [entry["path"] for entry in files],
+        "instructions": "\n\n".join(instructions),
+        "config": config,
+        "digest": policy_digest.hexdigest(),
+    }
+
+
+def _tool_result(
+    name: str,
+    arguments: dict[str, Any],
+    files: dict[str, str],
+    run_tests: RunTests,
+    *,
+    max_tool_output_chars: int = MAX_TOOL_OUTPUT_CHARS,
+    max_file_bytes: int = MAX_FILE_BYTES,
+    max_files: int = MAX_FILES,
+    max_workspace_bytes: int = MAX_WORKSPACE_BYTES,
+) -> Awaitable[dict[str, Any]] | dict[str, Any]:
+    if name == "list_files":
+        return {"files": sorted(files)}
+    if name == "read_file":
+        try:
+            path = _safe_path(arguments.get("path"))
+        except NativeAgentError as exc:
+            return {"error": str(exc)}
+        if path not in files:
+            return {"error": f"file not found: {path}"}
+        return {"path": path, "content": files[path][:max_tool_output_chars], "truncated": len(files[path]) > max_tool_output_chars}
+    if name == "write_file":
+        try:
+            path = _safe_path(arguments.get("path"))
+        except NativeAgentError as exc:
+            return {"error": str(exc)}
+        content = arguments.get("content")
+        if not isinstance(content, str):
+            return {"error": "content must be a string"}
+        if len(content.encode("utf-8")) > max_file_bytes:
+            return {"error": f"file exceeds the {max_file_bytes}-byte limit"}
+        if path not in files and len(files) >= max_files:
+            return {"error": f"workspace exceeds the {max_files}-file limit"}
+        projected_size = sum(len(value.encode("utf-8")) for key, value in files.items() if key != path)
+        projected_size += len(content.encode("utf-8"))
+        if projected_size > max_workspace_bytes:
+            return {"error": f"workspace exceeds the {max_workspace_bytes}-byte limit"}
+        files[path] = content
+        return {"written": path, "bytes": len(content.encode("utf-8"))}
+    if name == "apply_patch":
+        return _apply_patch_result(
+            arguments,
+            files,
+            max_file_bytes=max_file_bytes,
+            max_workspace_bytes=max_workspace_bytes,
+        )
+    if name == "delete_file":
+        return _delete_file_result(arguments, files)
+    if name == "move_file":
+        return _move_file_result(arguments, files)
+    if name == "grep":
+        return _grep_result(arguments, files)
+    if name == "glob":
+        return _glob_result(arguments, files)
+    if name == "run_approved_tests":
+        return run_tests(files)
+    return {"error": f"unknown tool: {name}"}
+
+
+@dataclass(frozen=True)
+class ShellPolicy:
+    """The explicit approval and boundary for the ``run_shell`` tool.
+
+    Every field defaults to the refusing state: ``approved=False`` means the
+    tool is never advertised or executed, and a missing ``root`` means there is
+    no sandbox to run in. A caller that wants the tool must opt in with an
+    approved policy, a real sandbox root, and (optionally) its own allow/deny
+    lists — the built-in dangerous-program set is always added to the deny list.
+
+    ``sandbox=True`` is a requirement, not a claim of isolation: every command
+    runs confined to ``root`` with a scrubbed environment and no shell unless
+    ``mode`` says so. The built-in local runner reports ``isolated=False`` so a
+    caller never mistakes it for a microVM boundary.
+    """
+
+    approved: bool = False
+    root: str | None = None
+    sandbox: bool = True
+    mode: str = SHELL_MODE_ARGV
+    allow: tuple[str, ...] | None = None
+    deny: tuple[str, ...] = ()
+    allow_inline_code: bool = False
+    approver: Callable[[str], bool] | None = None
+    max_timeout_seconds: float = DEFAULT_SHELL_TIMEOUT_SECONDS
+    max_output_chars: int = MAX_SHELL_OUTPUT_CHARS
+
+
+def _shell_refusal(command: str, argv: list[str] | None, detail: str) -> dict[str, Any]:
+    return {
+        "tool": SHELL_TOOL_NAME,
+        "command": command,
+        "argv": argv,
+        "cwd": None,
+        "executed": False,
+        "exit_code": None,
+        "passed": None,
+        "timed_out": False,
+        "duration_ms": 0,
+        "output": "",
+        "output_truncated": False,
+        "sandbox": True,
+        "isolated": False,
+        "backend": "none",
+        "detail": detail,
+    }
+
+
+def _program_name(token: str) -> str:
+    """Bare, lower-cased program name for policy matching.
+
+    ``C:\\Python312\\python.exe``, ``python3.12``, and ``python`` all normalise
+    to a name the allow/deny lists can match. Absolute program paths are
+    permitted only because the basename must still be allow-listed.
+    """
+    name = str(token).replace("\\", "/").rsplit("/", 1)[-1].lower()
+    if name.endswith(".exe"):
+        name = name[: -len(".exe")]
+    if re.fullmatch(r"python[0-9.]*", name):
+        return "python"
+    if re.fullmatch(r"pip[0-9.]*", name):
+        return "pip"
+    return name
+
+
+_PARENT_ESCAPE = re.compile(r"\.\.(?:[/\\]|$)")
+
+
+def _escapes_workspace(token: str) -> bool:
+    normalized = str(token).replace("\\", "/")
+    if normalized.startswith(("/", "~")) or _WINDOWS_ABSOLUTE.match(normalized):
+        return True
+    return bool(_PARENT_ESCAPE.search(normalized))
+
+
+def _has_injection(text: str, markers: tuple[str, ...]) -> str | None:
+    for marker in markers:
+        if marker in text:
+            return marker
+    return None
+
+
+def _sandbox_environment() -> dict[str, str]:
+    return {
+        key: value
+        for key, value in os.environ.items()
+        if key.upper() in SANDBOX_ENV_ALLOW
+    }
+
+
+def _capture_shell(
+    invocation: list[str] | str,
+    *,
+    cwd: Path,
+    timeout: float,
+    output_limit: int,
+    use_shell: bool,
+    env: dict[str, str],
+) -> tuple[int | None, bool, bytes, bool]:
+    """Run one bounded command; keep at most ``output_limit`` bytes of output."""
+    process = subprocess.Popen(
+        invocation,
+        cwd=str(cwd),
+        shell=use_shell,
+        stdin=subprocess.DEVNULL,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        env=env,
+    )
+    kept: list[bytes] = []
+    state = {"kept": 0, "truncated": False}
+
+    def drain() -> None:
+        stream = process.stdout
+        if stream is None:
+            return
+        while True:
+            block = stream.read(65536)
+            if not block:
+                break
+            room = output_limit - state["kept"]
+            if room > 0:
+                chunk = block[:room]
+                kept.append(chunk)
+                state["kept"] += len(chunk)
+                if len(chunk) < len(block):
+                    state["truncated"] = True
+            else:
+                state["truncated"] = True
+
+    reader = threading.Thread(target=drain, name="sid-shell-output", daemon=True)
+    reader.start()
+    timed_out = False
+    try:
+        exit_code: int | None = process.wait(timeout=timeout)
+    except subprocess.TimeoutExpired:
+        timed_out = True
+        process.kill()
+        try:
+            exit_code = process.wait(timeout=5)
+        except subprocess.TimeoutExpired:  # pragma: no cover - kill is best-effort
+            exit_code = None
+    reader.join(timeout=10)
+    if process.stdout is not None:
+        try:
+            process.stdout.close()
+        except OSError:
+            pass
+    return exit_code, timed_out, b"".join(kept), state["truncated"]
+
+
+def run_shell_tool(
+    arguments: dict[str, Any] | None,
+    policy: ShellPolicy | None,
+) -> dict[str, Any]:
+    """Validate one ``run_shell`` request against ``policy`` and run it.
+
+    Refusals are returned as a result dict (``executed=False`` plus ``detail``),
+    never raised, so the loop can show the model exactly what the policy
+    refused. The command string and exit code are always in the returned block,
+    which is what the run receipt records.
+    """
+    arguments = arguments if isinstance(arguments, dict) else {}
+    raw_command = arguments.get("command")
+    raw_argv = arguments.get("argv")
+    argv_input = (
+        [str(token) for token in raw_argv]
+        if isinstance(raw_argv, (list, tuple)) and all(isinstance(t, str) for t in raw_argv)
+        else None
+    )
+    display = (
+        str(raw_command)
+        if isinstance(raw_command, str) and raw_command.strip()
+        else (" ".join(argv_input) if argv_input else "")
+    )
+    if policy is None or not policy.approved:
+        return _shell_refusal(
+            display,
+            argv_input,
+            "shell execution requires an explicit approval before this task",
+        )
+    if not policy.sandbox:
+        return _shell_refusal(display, argv_input, "shell execution requires the sandbox")
+    if policy.mode not in SHELL_MODES:
+        return _shell_refusal(display, argv_input, f"unknown shell mode: {policy.mode!r}")
+    if policy.root is None:
+        return _shell_refusal(
+            display, argv_input, "no sandbox root was supplied; refusing to run on the host"
+        )
+    try:
+        root = Path(policy.root).expanduser().resolve()
+    except OSError as exc:
+        return _shell_refusal(display, argv_input, f"invalid sandbox root: {exc}")
+    if not root.is_dir():
+        return _shell_refusal(display, argv_input, f"sandbox root is not a directory: {root}")
+
+    if policy.mode == SHELL_MODE_ARGV:
+        if isinstance(raw_command, str) and raw_command.strip():
+            return _shell_refusal(
+                display, argv_input, "argv mode: a shell command string is refused; pass argv"
+            )
+        if not argv_input:
+            return _shell_refusal(display, argv_input, "argv mode requires a non-empty argv list")
+        if any(not token for token in argv_input):
+            return _shell_refusal(display, argv_input, "argv must not contain empty tokens")
+        argv = list(argv_input)
+        detail_markers = INJECTION_ARGV_MARKERS
+        use_shell = False
+        invocation: list[str] | str = argv
+    else:
+        if argv_input is not None:
+            return _shell_refusal(
+                display, argv_input, "shell mode takes one command line, not an argv list"
+            )
+        if not isinstance(raw_command, str) or not raw_command.strip():
+            return _shell_refusal(display, argv_input, "shell mode requires a command string")
+        command = raw_command.strip()
+        display = command
+        detail_markers = INJECTION_SHELL_MARKERS
+        argv = command.split()
+        use_shell = True
+        invocation = command
+
+    if any("\x00" in token for token in argv):
+        return _shell_refusal(display, argv, "command must not contain NUL bytes")
+    marker = _has_injection(display, detail_markers)
+    if marker is not None:
+        return _shell_refusal(
+            display, argv, f"command shape is refused (contains {marker!r})"
+        )
+
+    program = _program_name(argv[0])
+    allowed = DEFAULT_ALLOWED_PROGRAMS if policy.allow is None else frozenset(policy.allow)
+    denied = ALWAYS_DENIED_PROGRAMS | frozenset(policy.deny)
+    if program in denied:
+        return _shell_refusal(display, argv, f"program is denied by policy: {program!r}")
+    if program not in allowed:
+        return _shell_refusal(display, argv, f"program is not allow-listed: {program!r}")
+    if (
+        not policy.allow_inline_code
+        and program in INLINE_CODE_PROGRAMS
+        and any(token in INLINE_CODE_FLAGS for token in argv[1:])
+    ):
+        return _shell_refusal(
+            display, argv, "inline code execution (-c/-e) is not approved by policy"
+        )
+    lowered = [token.lower() for token in argv]
+    for sequence in DENIED_ARG_SEQUENCES:
+        if any(
+            tuple(lowered[index : index + len(sequence)]) == sequence
+            for index in range(len(lowered) - len(sequence) + 1)
+        ):
+            return _shell_refusal(
+                display, argv, "command shape is denied by policy: " + " ".join(sequence)
+            )
+    for token in argv[1:]:
+        if _escapes_workspace(token):
+            return _shell_refusal(
+                display, argv, f"command must stay inside the sandbox: {token!r}"
+            )
+    if policy.approver is not None:
+        try:
+            approved = bool(policy.approver(display))
+        except Exception as exc:  # an approver bug must fail closed
+            return _shell_refusal(
+                display, argv, f"approval check failed: {type(exc).__name__}: {exc}"
+            )
+        if not approved:
+            return _shell_refusal(display, argv, "command was not approved")
+
+    raw_cwd = arguments.get("cwd") or "."
+    if not isinstance(raw_cwd, str) or not raw_cwd.strip():
+        return _shell_refusal(display, argv, "cwd must be a non-empty relative path")
+    if _escapes_workspace(raw_cwd):
+        return _shell_refusal(display, argv, "cwd must stay inside the sandbox root")
+    try:
+        cwd = (root / raw_cwd.replace("\\", "/").strip("/")).resolve()
+    except OSError as exc:
+        return _shell_refusal(display, argv, f"invalid cwd: {exc}")
+    if cwd != root and root not in cwd.parents:
+        return _shell_refusal(display, argv, "cwd escapes the sandbox root")
+    if not cwd.is_dir():
+        return _shell_refusal(display, argv, f"cwd is not a directory: {raw_cwd}")
+
+    try:
+        timeout = float(arguments.get("timeout_seconds") or policy.max_timeout_seconds)
+    except (TypeError, ValueError):
+        timeout = policy.max_timeout_seconds
+    if timeout <= 0:
+        timeout = policy.max_timeout_seconds
+    timeout = min(timeout, MAX_SHELL_TIMEOUT_SECONDS)
+    output_limit = max(1, min(int(policy.max_output_chars), MAX_SHELL_OUTPUT_CHARS))
+
+    started = time.monotonic()
+    try:
+        exit_code, timed_out, raw, truncated = _capture_shell(
+            invocation,
+            cwd=cwd,
+            timeout=timeout,
+            output_limit=output_limit,
+            use_shell=use_shell,
+            env=_sandbox_environment(),
+        )
+    except FileNotFoundError:
+        return _shell_refusal(display, argv, f"command not found: {argv[0]!r}")
+    except OSError as exc:
+        return _shell_refusal(
+            display, argv, f"could not start command: {type(exc).__name__}: {exc}"
+        )
+    duration_ms = int((time.monotonic() - started) * 1000)
+    output = raw.decode("utf-8", errors="replace")[:output_limit]
+    if len(raw) > output_limit:
+        truncated = True
+    return {
+        "tool": SHELL_TOOL_NAME,
+        "command": display,
+        "argv": argv,
+        "mode": policy.mode,
+        "cwd": str(cwd),
+        "executed": True,
+        "exit_code": exit_code,
+        "passed": exit_code == 0,
+        "timed_out": timed_out,
+        "duration_ms": duration_ms,
+        "output": output,
+        "output_truncated": truncated,
+        "sandbox": True,
+        "isolated": False,
+        "backend": "local",
+        "sandbox_root": str(root),
+        "detail": (
+            f"command timed out after {timeout:g}s"
+            if timed_out
+            else ("command passed" if exit_code == 0 else f"command exited {exit_code}")
+        ),
+    }
+
+
+def _propose_result(
+    arguments: dict[str, Any],
+    files: dict[str, str],
+    proposed: dict[str, str],
+    *,
+    max_file_bytes: int = MAX_FILE_BYTES,
+    max_files: int = MAX_FILES,
+    max_workspace_bytes: int = MAX_WORKSPACE_BYTES,
+) -> dict[str, Any]:
+    """Record a plan-mode file proposal. Same bounds as write_file, no mutation
+    of the workspace: the proposal lives in ``proposed`` until the user
+    approves it through the readback path."""
+    try:
+        path = _safe_path(arguments.get("path"))
+    except NativeAgentError as exc:
+        return {"error": str(exc)}
+    content = arguments.get("content")
+    if not isinstance(content, str):
+        return {"error": "content must be a string"}
+    if len(content.encode("utf-8")) > max_file_bytes:
+        return {"error": f"file exceeds the {max_file_bytes}-byte limit"}
+    known = (set(files) | set(proposed)) - {path}
+    if path not in files and len(known) >= max_files:
+        return {"error": f"workspace exceeds the {max_files}-file limit"}
+    projected_size = sum(len(value.encode("utf-8")) for key, value in files.items() if key != path)
+    projected_size += sum(
+        len(value.encode("utf-8")) for key, value in proposed.items() if key != path
+    )
+    projected_size += len(content.encode("utf-8"))
+    if projected_size > max_workspace_bytes:
+        return {"error": f"workspace exceeds the {max_workspace_bytes}-byte limit"}
+    proposed[path] = content
+    return {"proposed": path, "bytes": len(content.encode("utf-8")), "written": False}
+
+
+def artifact_hash(files: dict[str, bytes]) -> str:
+    """Stable digest over the tested tree: sorted unique relative paths +
+    bytes. Same construction as the scanner's payload attestation
+    (api/services/bc_build_upload.py payload_artifact_sha256) so the join is
+    exact. Owned here — the loop is what produces ``tested_artifact_hash``; the
+    server's ``agent_service`` re-exports it so there is one construction, and
+    the module stays stdlib-only so it can be vendored verbatim into the local
+    harness with no monorepo import."""
+    unique: dict[str, bytes] = {}
+    for rel, data in files.items():
+        unique[rel.replace("\\", "/")] = data
+    digest = hashlib.sha256()
+    for rel in sorted(unique):
+        digest.update(rel.encode("utf-8"))
+        digest.update(b"\x00")
+        digest.update(unique[rel])
+        digest.update(b"\x00")
+    return digest.hexdigest()
+
+
+def _diff(before: dict[str, str], after: dict[str, str]) -> str:
+    chunks: list[str] = []
+    for path in sorted(set(before) | set(after)):
+        old = before.get(path, "")
+        new = after.get(path, "")
+        if old == new:
+            continue
+        chunks.extend(
+            difflib.unified_diff(
+                old.splitlines(True),
+                new.splitlines(True),
+                fromfile=f"a/{path}" if path in before else "/dev/null",
+                tofile=f"b/{path}" if path in after else "/dev/null",
+            )
+        )
+    return "".join(chunks)
+
+
+async def run_native_agent(
+    *,
+    task: str,
+    workspace_files: dict[str, str],
+    acceptance_criteria: list[str],
+    out_of_scope: list[str],
+    test_argv: list[str],
+    complete: Complete,
+    run_tests: RunTests,
+    max_turns: int = MAX_TURNS,
+    max_tool_calls: int = MAX_TOOL_CALLS,
+    max_tool_output_chars: int = MAX_TOOL_OUTPUT_CHARS,
+    max_files: int = MAX_FILES,
+    max_workspace_bytes: int = MAX_WORKSPACE_BYTES,
+    max_file_bytes: int = MAX_FILE_BYTES,
+    should_stop: ShouldStop | None = None,
+    tool_schemas: list[dict[str, Any]] | None = None,
+    tool_dispatch: Dispatch | None = None,
+    plan_only: bool = False,
+    shell_policy: ShellPolicy | None = None,
+) -> dict[str, Any]:
+    """Run a bounded first-party tool loop and test only inside the sandbox.
+
+    SUB-58: the bounds are parameters defaulting to the module constants, which
+    are kept and never removed. ``should_stop`` lets a caller end the loop
+    between turns for a clean interrupt; the returned result then carries
+    ``interrupted`` plus the partial trace, and the final approved test is not
+    run (an interrupted run is never reported as tested or verified).
+
+    ``tool_schemas``/``tool_dispatch`` let a caller (the local harness) extend
+    the tool set through ONE registry seam. When ``tool_schemas`` is given the
+    loop advertises those schemas to the model; ``tool_dispatch`` then handles
+    every call (base names must still route to ``_tool_result``). Both default to
+    None, which keeps the server path on the base four-tool contract.
+
+    ``plan_only`` (SUB-81) runs the same loop READ-ONLY: ``write_file`` is never
+    advertised or honored, ``propose_file_change`` records intentions, no tests
+    run (nothing changed), and the result carries the model's step plan plus the
+    diff/readback of the proposal. Nothing is written anywhere; approval happens
+    later through the caller's existing readback path.
+
+    ``shell_policy`` is the ONE opt-in seam for the fifth tool, ``run_shell``.
+    With no policy (the server path) the tool is never advertised or honored.
+    An approved policy advertises the schema and runs each request through
+    ``run_shell_tool`` (allow/deny lists, argv-or-shell mode, sandbox root,
+    bounded timeout/output). Every request — executed or refused — is recorded
+    in the result's ``shell`` list with its command and exit code, which is what
+    the run receipt reports.
+    """
+    files = _validate_workspace(
+        dict(workspace_files),
+        max_files=max_files,
+        max_workspace_bytes=max_workspace_bytes,
+        max_file_bytes=max_file_bytes,
+    )
+    # SUB-94: load project policy from the workspace the loop is about to edit.
+    # This is the ONE loader every run path reaches (CLI, bridge, Studio chat,
+    # workbench), so precedence cannot drift between surfaces.
+    project_rules = load_project_rules(files)
+    config_plan = project_rules["config"].get("plan")
+    if config_plan is not None and not isinstance(config_plan, bool):
+        raise NativeAgentInputError(
+            "project policy .sid/config field 'plan' must be true or false"
+        )
+    if config_plan:
+        # Project policy can force the one loop read-only on every surface; an
+        # explicit caller plan flag can never loosen it (precedence is additive).
+        plan_only = True
+    original = dict(files)
+    base_tools = tool_schemas if tool_schemas is not None else TOOLS
+    if plan_only:
+        base_tools = [
+            schema
+            for schema in base_tools
+            if (schema.get("function") or {}).get("name") not in MUTATING_TOOL_NAMES
+        ]
+        if not any((s.get("function") or {}).get("name") == "propose_file_change" for s in base_tools):
+            base_tools = [*base_tools, PROPOSE_TOOL]
+    elif shell_policy is not None and shell_policy.approved:
+        # Explicit approval gate: the fifth tool is advertised only for a caller
+        # that approved it. Plan mode never gets it (read-only run).
+        if not any((s.get("function") or {}).get("name") == SHELL_TOOL_NAME for s in base_tools):
+            base_tools = [*base_tools, SHELL_TOOL]
+    active_tools = base_tools
+    criteria = "\n".join(f"- {criterion}" for criterion in acceptance_criteria)
+    exclusions = "\n".join(f"- {item}" for item in out_of_scope) or "- None stated"
+    posture = (
+        "You are SID, working inside a first-party, bounded coding workstation. "
+        "Use only the supplied project tools. The user's approved criteria are "
+        "binding; do not broaden scope. Inspect before editing, make the smallest "
+        "change, run the approved tests, and report honestly. You cannot publish. "
+        "Do not read secrets, private keys, dependency directories, or VCS data. "
+        "Finish only after tests pass or explain the exact blocker."
+    )
+    system_parts = [posture, WORKSPACE_GUARDRAIL]
+    if project_rules["instructions"]:
+        system_parts.append(
+            "PROJECT RULES — binding project policy loaded from the workspace. "
+            "Apply every rule to what you inspect, edit, and run. If a rule "
+            "cannot be satisfied, name that as a blocker; never silently ignore "
+            "project policy.\n\n"
+            f"Precedence: {project_rules['precedence']}\n\n"
+            + project_rules["instructions"]
+        )
+    if plan_only:
+        system_parts.append(PLAN_MODE_SYSTEM)
+    elif shell_policy is not None and shell_policy.approved:
+        system_parts.append(
+            "SHELL — the user explicitly approved run_shell for this task. Use one "
+            "command at a time, stay inside the sandbox root, and never try to "
+            "escape it or chain commands. Refusals are policy, not failures to route "
+            "around: report the blocker instead."
+        )
+    system_parts.extend(
+        [
+            f"APPROVED ACCEPTANCE CRITERIA:\n{criteria}\n\nOUT OF SCOPE:\n{exclusions}",
+            f"APPROVED TEST ARGV: {json.dumps(test_argv)}",
+        ]
+    )
+    system = "\n\n".join(system_parts)
+    messages: list[dict[str, Any]] = [
+        {"role": "system", "content": system},
+        {
+            "role": "user",
+            "content": (
+                f"Task: {task.strip()}\nWorkspace files: {len(files)}\n"
+                + (
+                    "Inspect with list_files/read_file, propose edits with "
+                    "propose_file_change (nothing is written), and finish with a "
+                    "numbered step plan."
+                    if plan_only
+                    else "Use list_files/read_file/grep/glob to inspect relevant code, "
+                    "apply_patch (preferred) or write_file to edit, and "
+                    "run_approved_tests to run the approved command. delete_file and "
+                    "move_file require confirm=true."
+                )
+            ),
+        },
+    ]
+    final_response = ""
+    last_test: dict[str, Any] | None = None
+    route_calls: list[dict[str, Any]] = []
+    proposed: dict[str, str] = {}
+    # Every run_shell request (executed or refused), in call order. The receipt
+    # reports the command and exit code from here.
+    shell_runs: list[dict[str, Any]] = []
+    patches: list[dict[str, Any]] = []
+    # Per-turn trace: what the model actually did (tool names, arg sizes,
+    # finish reason) so a run receipt explains its own loop behavior — the
+    # batch-1 debugging needed this and the receipt had nothing to show.
+    turn_trace: list[dict[str, Any]] = []
+    tool_calls_seen = 0
+    interrupted = False
+
+    for step in range(1, max_turns + 1):
+        if should_stop is not None and should_stop(step, tool_calls_seen):
+            interrupted = True
+            final_response = (
+                f"Agent interrupted by the caller at step {step - 1} "
+                f"({len(turn_trace)} turn(s) completed)."
+            )
+            break
+        response = await complete(messages, active_tools)
+        route_calls.append({
+            "model": response.get("model"),
+            "routing": response.get("routing"),
+        })
+        try:
+            message = response["choices"][0]["message"]
+        except (KeyError, IndexError, TypeError) as exc:
+            raise NativeAgentError("SID model returned an invalid tool-loop response") from exc
+        calls = message.get("tool_calls") or []
+        content = message.get("content") or ""
+        if not isinstance(content, str):
+            content = str(content)
+        turn_trace.append({
+            "step": step,
+            "finish_reason": response["choices"][0].get("finish_reason"),
+            "content_chars": len(content),
+            "tool_calls": [str((c.get("function") or {}).get("name") or "?") for c in calls],
+            "usage": response.get("usage") or {},
+        })
+        if not calls:
+            final_response = content
+            break
+        # Thinking-mode upstreams (deepseek) require the assistant turn's
+        # reasoning_content to be passed back on subsequent turns; dropping it
+        # hard-400s every continuation after the first tool call ("The
+        # reasoning_content in the thinking mode must be passed back to the
+        # API"). Carry it verbatim through the loop's history.
+        assistant_msg: dict[str, Any] = {"role": "assistant", "content": content or None, "tool_calls": calls}
+        reasoning = message.get("reasoning_content")
+        if isinstance(reasoning, str) and reasoning:
+            assistant_msg["reasoning_content"] = reasoning
+        messages.append(assistant_msg)
+        for call in calls:
+            tool_calls_seen += 1
+            if tool_calls_seen > max_tool_calls:
+                raise NativeAgentError(f"agent exceeded the {max_tool_calls}-tool-call limit")
+            call_id = str(call.get("id") or f"sid_tool_{tool_calls_seen}")
+            function = call.get("function") or {}
+            name = str(function.get("name") or "")
+            try:
+                arguments = json.loads(function.get("arguments") or "{}")
+                if not isinstance(arguments, dict):
+                    raise ValueError("tool arguments must be an object")
+                if plan_only and name in MUTATING_TOOL_NAMES:
+                    # Hard zero-write floor: even a model that hallucinates a
+                    # disabled mutating tool cannot mutate the workspace in plan
+                    # mode.
+                    result = {
+                        "error": (
+                            "plan mode is read-only: "
+                            f"{name} is disabled. Submit the intended edit with "
+                            "propose_file_change."
+                        ),
+                        "written": False,
+                    }
+                elif plan_only and name == "propose_file_change":
+                    result = _propose_result(
+                        arguments,
+                        files,
+                        proposed,
+                        max_file_bytes=max_file_bytes,
+                        max_files=max_files,
+                        max_workspace_bytes=max_workspace_bytes,
+                    )
+                elif plan_only and name == "run_approved_tests":
+                    result = {
+                        "skipped": True,
+                        "reason": (
+                            "plan mode is read-only: nothing is written, so no tests "
+                            "run. Name the verification step in the plan."
+                        ),
+                    }
+                elif plan_only and name == SHELL_TOOL_NAME:
+                    result = {
+                        "tool": SHELL_TOOL_NAME,
+                        "executed": False,
+                        "exit_code": None,
+                        "skipped": True,
+                        "reason": "plan mode is read-only: shell is not available",
+                    }
+                elif name == SHELL_TOOL_NAME:
+                    # The fifth tool is owned by the loop, not the extension
+                    # registry: an approved ShellPolicy is the one way in, and
+                    # the policy refuses every request when it is absent.
+                    result = run_shell_tool(arguments, shell_policy)
+                elif tool_dispatch is not None:
+                    # A caller-supplied registry routes EVERY call (base and
+                    # extension) through one seam; base names still land in
+                    # _tool_result via the registry, so the contract keeps one
+                    # owner and there is no second engine.
+                    result = tool_dispatch(name, arguments, files, run_tests)
+                else:
+                    result = _tool_result(
+                        name,
+                        arguments,
+                        files,
+                        run_tests,
+                        max_tool_output_chars=max_tool_output_chars,
+                        max_file_bytes=max_file_bytes,
+                        max_files=max_files,
+                        max_workspace_bytes=max_workspace_bytes,
+                    )
+                if hasattr(result, "__await__"):
+                    result = await result
+                if name == "run_approved_tests":
+                    last_test = result
+                elif name == SHELL_TOOL_NAME:
+                    shell_runs.append(result)
+                if (
+                    name == "apply_patch"
+                    and isinstance(result, dict)
+                    and result.get("diff")
+                ):
+                    patches.append(
+                        {
+                            "path": result.get("patched"),
+                            "edits": result.get("edits"),
+                            "diff": result["diff"],
+                        }
+                    )
+            except Exception as exc:
+                result = {"error": f"tool failed: {type(exc).__name__}: {exc}"}
+            payload = json.dumps(result, ensure_ascii=False, default=str)
+            messages.append({"role": "tool", "tool_call_id": call_id, "content": payload[:max_tool_output_chars]})
+    else:
+        final_response = "Agent stopped at the bounded turn limit before returning a final answer."
+
+    # Always run the exact approved test command once on the final file set,
+    # even if the model forgot or ran tests before its last edit. A clean
+    # interrupt (SUB-58) skips this: the caller stopped the run, so it is not
+    # tested and never reported as tested or verified. Plan mode (SUB-81) has
+    # nothing to test: it never wrote the workspace.
+    if not interrupted and not plan_only:
+        final_test = await run_tests(files)
+        last_test = final_test
+    elif plan_only:
+        last_test = {
+            "backend": None,
+            "isolated": False,
+            "exit_code": None,
+            "passed": False,
+            "skipped": True,
+            "reason": "plan mode is read-only: nothing was written, so no tests were run",
+            "stdout": "",
+            "stderr": "",
+        }
+    if plan_only:
+        proposed = {path: content for path, content in proposed.items() if files.get(path) != content}
+        changes = sorted(proposed)
+        readback = {path: proposed[path] for path in changes}
+        diff_text = _diff(original, {**files, **proposed})
+    else:
+        changes = sorted(path for path in set(original) | set(files) if original.get(path) != files.get(path))
+        readback = {path: files[path] for path in changes if path in files}
+        diff_text = _diff(original, files)
+    artifact_files = {path: content.encode("utf-8") for path, content in files.items()}
+    return {
+        "final_response": final_response,
+        "project_rules": project_rules,
+        "plan": final_response if plan_only else None,
+        "plan_mode": plan_only,
+        "writes": 0 if plan_only else len(changes),
+        "test": last_test,
+        "tests": last_test,
+        "readback": readback,
+        "artifact_files": artifact_files,
+        "tested_artifact_hash": artifact_hash(artifact_files),
+        "diff": diff_text or None,
+        "patches": patches,
+        "changed": changes,
+        "isolated": bool(last_test and last_test.get("isolated")),
+        "backend": last_test.get("backend") if last_test else None,
+        "model": route_calls[-1]["model"] if route_calls else "auto",
+        "route_calls": route_calls,
+        "turn_trace": turn_trace,
+        "shell": shell_runs,
+        "steps": step if "step" in locals() else 0,
+        "tool_calls": tool_calls_seen,
+        "interrupted": interrupted,
+    }