devcouncil 0.1.1 → 0.3.0

package/src/devcouncil/integrations/mcp/server.py

@@ -1,42 +1,93 @@
 import asyncio
+import hashlib
 import json
+import logging
 import os
 import subprocess
 import sys
 from pathlib import Path
 from mcp.server import Server
+from typing import Any, NamedTuple
 from mcp.server.stdio import stdio_server
-from mcp.types import Tool, TextContent
+from mcp.types import (
+    Tool,
+    TextContent,
+    Resource,
+    Prompt,
+    PromptArgument,
+    PromptMessage,
+    GetPromptResult,
+)
+from pydantic import AnyUrl
 from devcouncil.storage.db import get_db
-from devcouncil.storage.repositories import TaskRepository, ArtifactGraphRepository, StateRepository, RequirementRepository
+from devcouncil.storage.repositories import (
+    TaskRepository,
+    ArtifactGraphRepository,
+    StateRepository,
+    RequirementRepository,
+    EvidenceRepository,
+    GapRepository,
+)
+from devcouncil.storage.native import (
+    TaskLeaseRepository,
+    ShellCommandRepository,
+    FileChangeRepository,
+    VerificationRunRepository,
+    CorrectionManifestRepository,
+)
+from devcouncil.domain.evidence import CommandResult, DiffEvidence, DiffCoverageEvidence, TestEvidence
+from devcouncil.verification.next_actions import split_next_actions
 from devcouncil.reporting.report_builder import ReportBuilder
 from devcouncil.integrations.code_review_graph import CodeReviewGraphAdapter
 from devcouncil.execution.hook_policy import HookPolicy
 from devcouncil.execution.prompt_builder import PromptBuilder
+from devcouncil.utils.subprocess_env import clean_subprocess_env
 from devcouncil.telemetry.traces import read_trace_events
 from devcouncil.indexing.ast_matcher import AstMatcher
 from devcouncil.indexing.lsp import LspInspector
 from devcouncil.app.project_status import compute_phase
 from devcouncil.live.cards import filter_cards, get_card, load_cards
 from devcouncil.live.repair_prompt import build_bulk_live_repair_prompt, build_live_repair_prompt
+from devcouncil.integrations.check import integration_status_summary
 from devcouncil.live.summary import live_review_summary
 
+logger = logging.getLogger(__name__)
+
 app = Server("devcouncil")
 _DB_REQUIRED_TOOLS = {
     "devcouncil_status",
     "devcouncil_report",
     "devcouncil_get_task",
     "devcouncil_list_tasks",
+    "devcouncil_get_gaps",
+    "devcouncil_get_next_actions",
+    "devcouncil_get_task_provenance",
+    "devcouncil_list_leases",
+    "devcouncil_renew_lease",
     "devcouncil_get_prompt",
     "devcouncil_tail_trace",
     "devcouncil_policy_check_write",
     "devcouncil_graph_context",
     "devcouncil_prepare_execution",
+    "devcouncil_checkout_task",
+    "devcouncil_release_task",
+    "devcouncil_update_task_scope",
+    "devcouncil_append_evidence",
+    "devcouncil_record_command",
+    "devcouncil_write_file",
+    "devcouncil_apply_patch",
+    "devcouncil_verify_task",
+    "devcouncil_handoff_agent",
+    "devcouncil_get_evidence",
+    "devcouncil_run_command",
+    "devcouncil_next_task",
 }
 _CLI_ALLOWED_ROOTS = {"status", "tasks", "report", "map", "prompt", "show", "trace", "lsp", "ast", "verify"}
 _CLI_FORBIDDEN_FLAGS = {"--project-root", "--github", "--github-pr-comment", "--gitlab-pr-comment"}
 _CLI_TIMEOUT_SECONDS = 120
 _CLI_OUTPUT_LIMIT = 20_000
+# Allowed values for devcouncil_record_command.status (validated, not free-text).
+_RECORD_COMMAND_STATUSES = {"started", "finished", "failed", "blocked"}
 
 
 def _forbidden_cli_flags(args: list[str]) -> list[str]:
@@ -63,6 +114,239 @@ def _json_text(payload: dict[str, object]) -> list[TextContent]:
     return [TextContent(type="text", text=json.dumps(payload, indent=2))]
 
 
+def _is_git_repo(root: Path) -> bool:
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--is-inside-work-tree"],
+            cwd=root, capture_output=True, text=True,
+        )
+        return result.returncode == 0 and result.stdout.strip() == "true"
+    except Exception:
+        return False
+
+
+def _read_log_file(path: str | None) -> str:
+    """Best-effort read of a persisted stdout/stderr log; tolerate a missing file."""
+    if not path:
+        return ""
+    try:
+        return Path(path).read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return ""
+
+
+async def _git_diff(root: Path, paths: list[str], staged: bool) -> dict[str, object]:
+    """Compute a (optionally path-scoped, optionally staged) git diff.
+
+    Returns {ok, files:[{path,status,additions,deletions}], unified_diff (truncated),
+    truncated}. Never raises — a git failure is reported as an empty diff with the
+    stderr in an error field so the agent can act on it."""
+    diff_args = ["git", "diff"]
+    numstat_args = ["git", "diff", "--numstat"]
+    namestatus_args = ["git", "diff", "--name-status"]
+    if staged:
+        for args in (diff_args, numstat_args, namestatus_args):
+            args.append("--cached")
+    if paths:
+        for args in (diff_args, numstat_args, namestatus_args):
+            args.append("--")
+            args.extend(paths)
+
+    def _run(args: list[str]) -> subprocess.CompletedProcess[str]:
+        return subprocess.run(
+            args, cwd=root, capture_output=True, text=True,
+            encoding="utf-8", errors="replace", timeout=_CLI_TIMEOUT_SECONDS,
+        )
+
+    try:
+        loop = asyncio.get_event_loop()
+        diff_proc, numstat_proc, namestatus_proc = await asyncio.gather(
+            loop.run_in_executor(None, _run, diff_args),
+            loop.run_in_executor(None, _run, numstat_args),
+            loop.run_in_executor(None, _run, namestatus_args),
+        )
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        return {"ok": False, "files": [], "unified_diff": "", "truncated": False, "error": str(exc)}
+
+    status_by_path: dict[str, str] = {}
+    for line in namestatus_proc.stdout.splitlines():
+        parts = line.split("\t")
+        if len(parts) >= 2:
+            status_by_path[parts[-1].replace("\\", "/")] = parts[0]
+
+    files: list[dict[str, object]] = []
+    for line in numstat_proc.stdout.splitlines():
+        parts = line.split("\t")
+        if len(parts) < 3:
+            continue
+        added_str, deleted_str, file_path = parts[0], parts[1], parts[-1]
+        file_path = file_path.replace("\\", "/")
+        files.append({
+            "path": file_path,
+            "status": status_by_path.get(file_path, "M"),
+            "additions": int(added_str) if added_str.isdigit() else 0,
+            "deletions": int(deleted_str) if deleted_str.isdigit() else 0,
+        })
+
+    unified_diff, truncated = _truncate_text(diff_proc.stdout)
+    return {"ok": True, "files": files, "unified_diff": unified_diff, "truncated": truncated, "staged": staged}
+
+
+def _within_root(root: Path, rel_or_abs: str) -> Path | None:
+    """Resolve a path against the project root and confirm it stays inside it.
+
+    Returns the absolute resolved path, or None when the path escapes the project
+    (a containment violation — a write tool must refuse it)."""
+    raw = rel_or_abs.strip().strip('"').replace("\\", "/")
+    try:
+        candidate = Path(raw)
+        resolved = candidate.resolve() if candidate.is_absolute() else (root / raw).resolve()
+        resolved.relative_to(root.resolve())
+        return resolved
+    except (OSError, ValueError):
+        return None
+
+
+def _diff_target_paths(unified_diff: str) -> list[str]:
+    """Extract EVERY repo-relative file a unified diff touches — both sides.
+
+    Captures pre- and post-image paths from ``---``/``+++`` hunk headers AND the
+    ``rename from/to`` / ``copy from/to`` lines (a pure rename has no hunk headers, so
+    its source would otherwise escape the policy check — letting a protected file be
+    moved out of scope). Handles paths with spaces and git's C-quoting. Every target is
+    then policy-checked before the patch is applied."""
+    targets: list[str] = []
+    seen: set[str] = set()
+
+    def _clean(token: str) -> str | None:
+        token = token.strip()
+        if len(token) >= 2 and token.startswith('"') and token.endswith('"'):
+            try:
+                token = token[1:-1].encode("utf-8").decode("unicode_escape")
+            except Exception:
+                token = token[1:-1]
+        if not token or token == "/dev/null":
+            return None
+        if token[:2] in ("a/", "b/"):
+            token = token[2:]
+        return token or None
+
+    def _add(path: str | None) -> None:
+        if path and path not in seen:
+            seen.add(path)
+            targets.append(path)
+
+    for line in unified_diff.splitlines():
+        if line.startswith("--- ") or line.startswith("+++ "):
+            _add(_clean(line[4:]))
+        elif line.startswith(("rename from ", "rename to ", "copy from ", "copy to ")):
+            _add(_clean(line.split(" ", 2)[2]))
+        elif line.startswith("diff --git "):
+            # Fallback for metadata-only changes (e.g. mode change) that have no hunk or
+            # rename lines; best-effort split handles the common no-space case.
+            parts = line[len("diff --git "):].split()
+            if len(parts) == 2:
+                _add(_clean(parts[0]))
+                _add(_clean(parts[1]))
+    return targets
+
+
+def _lease_ttl_seconds(root: Path) -> int:
+    """Default MCP lease TTL from config (so a crashed agent's lease auto-expires)."""
+    try:
+        from devcouncil.app.config import load_config
+
+        return max(0, int(load_config(root).execution.lease_ttl_seconds))
+    except Exception:
+        return 1800
+
+
+# Per-resolved-root caches for stateless, construction-heavy objects that several
+# MCP handlers would otherwise rebuild on every request. Keyed by str(root.resolve())
+# so distinct project roots (and distinct test temp dirs) never collide. _reset_caches()
+# clears them for tests that need a clean slate within a single process.
+_ROUTER_CACHE: dict[str, tuple[Any, Any]] = {}
+_AST_MATCHER_CACHE: dict[str, AstMatcher] = {}
+_LSP_INSPECTOR_CACHE: dict[str, LspInspector] = {}
+_GRAPH_ADAPTER_CACHE: dict[str, CodeReviewGraphAdapter] = {}
+
+
+def _reset_caches() -> None:
+    """Drop all per-root MCP caches (router/ast/lsp/graph). For test isolation."""
+    _ROUTER_CACHE.clear()
+    _AST_MATCHER_CACHE.clear()
+    _LSP_INSPECTOR_CACHE.clear()
+    _GRAPH_ADAPTER_CACHE.clear()
+
+
+def _get_ast_matcher(root: Path) -> AstMatcher:
+    key = str(root.resolve())
+    matcher = _AST_MATCHER_CACHE.get(key)
+    if matcher is None:
+        matcher = AstMatcher(root)
+        _AST_MATCHER_CACHE[key] = matcher
+    return matcher
+
+
+def _get_lsp_inspector(root: Path) -> LspInspector:
+    key = str(root.resolve())
+    inspector = _LSP_INSPECTOR_CACHE.get(key)
+    if inspector is None:
+        inspector = LspInspector(root)
+        _LSP_INSPECTOR_CACHE[key] = inspector
+    return inspector
+
+
+def _get_graph_adapter(root: Path) -> CodeReviewGraphAdapter:
+    key = str(root.resolve())
+    adapter = _GRAPH_ADAPTER_CACHE.get(key)
+    if adapter is None:
+        adapter = CodeReviewGraphAdapter(root)
+        _GRAPH_ADAPTER_CACHE[key] = adapter
+    return adapter
+
+
+def _load_router(root: Path):
+    """Build a ModelRouter from project config, or return None when no provider key
+    is configured. When present, the verifier runs DevCouncil's strong compiled
+    per-criterion acceptance checks; when None, it falls back to coarse mode (which
+    the verify response now reports explicitly so the agent is never misled).
+
+    Cached per resolved project root: a verify_task storm would otherwise rebuild the
+    config+provider+router on every call. The cache is invalidated when config.yaml's
+    stat signature changes, so a long-running server picks up a rewritten config (new
+    provider key / model) instead of serving a stale router. Use _reset_caches() to clear
+    in tests."""
+    key = str(root.resolve())
+    try:
+        cfg_stat = (root / ".devcouncil" / "config.yaml").stat()
+        signature: object = (cfg_stat.st_mtime_ns, cfg_stat.st_size, cfg_stat.st_ino)
+    except OSError:
+        signature = None
+    cached = _ROUTER_CACHE.get(key)
+    if cached is not None and cached[0] == signature:
+        return cached[1]
+    router = _build_router(root)
+    _ROUTER_CACHE[key] = (signature, router)
+    return router
+
+
+def _build_router(root: Path):
+    try:
+        from devcouncil.app.config import load_config, get_api_key
+        from devcouncil.llm.provider import create_provider, validate_model_provider
+        from devcouncil.llm.router import ModelRouter
+
+        config = load_config(root)
+        validate_model_provider(config.models.provider)
+        api_key = get_api_key(config.models.provider, root)
+        provider = create_provider(config.models.provider, api_key, project_root=root, provider_prefs=config.provider)
+        role_config = {name: role.model_dump() for name, role in config.models.roles.items()}
+        return ModelRouter(provider, role_config, project_root=root)
+    except Exception:
+        return None
+
+
 def _error_text(message: str, *, code: str = "error", **details: object) -> list[TextContent]:
     return _json_text({"ok": False, "error": message, "code": code, **details})
 
@@ -85,6 +369,15 @@ def _optional_string_argument(arguments: dict, name: str) -> str | None:
     return value if isinstance(value, str) else ""
 
 
+def _optional_string_list_argument(arguments: dict, name: str) -> tuple[list[str], list[TextContent] | None]:
+    value = arguments.get(name)
+    if value is None:
+        return [], None
+    if not isinstance(value, list) or not all(isinstance(item, str) for item in value):
+        return [], _error_text(f"{name} must be a string array", code="invalid_arguments", argument=name)
+    return value, None
+
+
 def _required_string_argument(arguments: dict, name: str) -> tuple[str | None, list[TextContent] | None]:
     value = arguments.get(name)
     if value is None or value == "":
@@ -137,6 +430,103 @@ def _project_root() -> Path:
     return Path(configured).expanduser().resolve() if configured else Path(".")
 
 
+def _knowledge_source_uri(kind: str, name: str) -> str:
+    """Stable, parseable resource URI for one ingested knowledge source.
+
+    The name is percent-encoded so OKF/design source names with spaces or slashes
+    still yield a valid AnyUrl and round-trip cleanly through read_resource."""
+    from urllib.parse import quote
+
+    return f"devcouncil://knowledge/{kind}/{quote(name, safe='')}"
+
+
+def _discover_knowledge_sources(root: Path) -> list:
+    """Best-effort enumeration of ingested OKF/design knowledge for the project.
+
+    A broken or absent knowledge layer must never break resource listing, so any
+    failure degrades to an empty list (mirrors the other optional handlers here).
+
+    Honors the project's ``knowledge`` config (enabled / directory / design_always) so MCP
+    exposes exactly what the planning and task prompts do — otherwise a project that
+    disabled or relocated its knowledge would still leak it through MCP resources."""
+    try:
+        from devcouncil.knowledge.sources import discover_knowledge_sources
+
+        directory, design_always = _knowledge_settings(root)
+        if directory is None:  # explicitly disabled in config
+            return []
+        return discover_knowledge_sources(root, directory=directory, design_always=design_always)
+    except Exception:
+        return []
+
+
+def _knowledge_settings(root: Path) -> tuple[str | None, bool]:
+    """Resolve (directory, design_always) for knowledge exposure from project config.
+
+    Returns ``(None, _)`` when the project explicitly disables knowledge so callers can
+    suppress it. Falls back to defaults when no/invalid config is present (the MCP server
+    must keep working for projects without a full ``.devcouncil/config.yaml``)."""
+    try:
+        from devcouncil.app.config import load_config
+
+        cfg = load_config(root).knowledge
+        return (None if not cfg.enabled else cfg.directory), cfg.design_always
+    except Exception:
+        return ".devcouncil/knowledge", True
+
+
+def _is_secret_path(root: Path, rel_or_abs: str) -> bool:
+    """True when a path matches a protected secret/credential glob.
+
+    Reuses the shared SECRET_PATH_PATTERNS (the single source of truth in the policy
+    engine) so read tools refuse exactly the same files the write gate refuses — an
+    MCP agent must never be able to exfiltrate a credential through a read tool."""
+    from devcouncil.execution.policy_engine import SECRET_PATH_PATTERNS
+
+    normalized = rel_or_abs.strip().strip('"').replace("\\", "/")
+    try:
+        candidate = Path(normalized)
+        if candidate.is_absolute():
+            resolved = candidate.resolve()
+            try:
+                normalized = resolved.relative_to(root.resolve()).as_posix()
+            except ValueError:
+                normalized = resolved.as_posix()
+    except OSError:
+        pass
+    import fnmatch as _fnmatch
+
+    return any(_fnmatch.fnmatch(normalized, pattern) for pattern in SECRET_PATH_PATTERNS)
+
+
+def _allowed_next_tools(status: str, has_blocking_gaps: bool) -> list[str]:
+    """Compute the self-describing next-tool contract from task state.
+
+    Replaces a hardcoded list so an agent is steered by what the task actually
+    needs: a verified task only needs releasing; a blocked/running task gets the
+    full read->edit->test loop; a planned task should check out first."""
+    if status == "verified":
+        return ["devcouncil_release_task"]
+    if status == "done":
+        return []
+    if status in {"running", "blocked"} or has_blocking_gaps:
+        return [
+            "devcouncil_read_file",
+            "devcouncil_get_evidence",
+            "devcouncil_get_diff",
+            "devcouncil_run_command",
+            "devcouncil_apply_patch",
+            "devcouncil_write_file",
+            "devcouncil_verify_task",
+        ]
+    # planned / ready and not yet leased: bootstrap by checking out.
+    return [
+        "devcouncil_checkout_task",
+        "devcouncil_read_file",
+        "devcouncil_get_diff",
+    ]
+
+
 @app.list_tools()
 async def list_tools() -> list[Tool]:
     return [
@@ -148,6 +538,11 @@ async def list_tools() -> list[Tool]:
                 "properties": {}
             }
         ),
+        Tool(
+            name="devcouncil_integration_status",
+            description="Get read-only coding CLI integration status, capability rows, detected clients, and recommended executor.",
+            inputSchema={"type": "object", "properties": {}},
+        ),
         Tool(
             name="devcouncil_report",
             description="Get the full coverage report and a list of all requirements and blocking gaps.",
@@ -170,6 +565,50 @@ async def list_tools() -> list[Tool]:
                 "required": ["task_id"]
             }
         ),
+        Tool(
+            name="devcouncil_get_gaps",
+            description=(
+                "Read the persisted verification gaps for a task WITHOUT re-running "
+                "verification. Cheap and idempotent — use it to resume after a "
+                "reconnect or to inspect outstanding work before deciding to repair."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "task_id": {"type": "string"},
+                    "blocking_only": {"type": "boolean", "default": False},
+                },
+                "required": ["task_id"],
+            },
+        ),
+        Tool(
+            name="devcouncil_get_next_actions",
+            description=(
+                "Get the typed, machine-routable next-actions contract for a task from "
+                "its persisted gaps, WITHOUT re-verifying. Returns blocking next_actions "
+                "plus advisory_actions and the tools allowed next."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {"task_id": {"type": "string"}},
+                "required": ["task_id"],
+            },
+        ),
+        Tool(
+            name="devcouncil_get_task_provenance",
+            description=(
+                "Inspect the recorded audit trail for a task: gated file changes "
+                "(write_file/apply_patch and hook events), verification runs, diff-coverage "
+                "evidence (was the changed code actually exercised), and the latest "
+                "correction manifest. Read-only — lets a developer or agent trust what "
+                "actually happened on disk."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {"task_id": {"type": "string"}},
+                "required": ["task_id"],
+            },
+        ),
         Tool(
             name="devcouncil_live_review",
             description="Get live coding-agent review status, pending signals, critique-card counts, and blockers.",
@@ -245,8 +684,15 @@ async def list_tools() -> list[Tool]:
         ),
         Tool(
             name="devcouncil_list_tasks",
-            description="List DevCouncil tasks with status and requirement mappings.",
-            inputSchema={"type": "object", "properties": {}},
+            description="List DevCouncil tasks with status and requirement mappings. Supports a status filter and limit/offset paging so large projects don't blow the agent's context.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "status": {"type": "string", "description": "Optional status filter (e.g. planned, running, blocked, verified, done)."},
+                    "limit": {"type": "integer", "description": "Max tasks to return (default 100, max 500)."},
+                    "offset": {"type": "integer", "description": "Number of tasks to skip (default 0)."},
+                },
+            },
         ),
         Tool(
             name="devcouncil_get_prompt",
@@ -339,16 +785,600 @@ async def list_tools() -> list[Tool]:
                 "required": ["task_id"],
             },
         ),
+        Tool(
+            name="devcouncil_checkout_task",
+            description="Acquire a task lease and return scope for MCP write tools.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "task_id": {"type": "string"},
+                    "client_id": {"type": "string"},
+                    "agent": {"type": "string"},
+                    "force": {"type": "boolean", "default": False},
+                },
+                "required": ["task_id", "client_id"],
+            },
+        ),
+        Tool(
+            name="devcouncil_release_task",
+            description="Release a task lease using its token.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "task_id": {"type": "string"},
+                    "lease_token": {"type": "string"},
+                },
+                "required": ["task_id", "lease_token"],
+            },
+        ),
+        Tool(
+            name="devcouncil_renew_lease",
+            description=(
+                "Extend a held task lease's TTL so a long-running agent does not lose it "
+                "to expiry. Returns the new expires_at."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "task_id": {"type": "string"},
+                    "lease_token": {"type": "string"},
+                    "ttl_seconds": {"type": "integer"},
+                },
+                "required": ["task_id", "lease_token"],
+            },
+        ),
+        Tool(
+            name="devcouncil_list_leases",
+            description=(
+                "List task leases for fleet supervision — task_id, owner, agent, "
+                "expires_at, and whether each is expired. Defaults to active leases."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {"active_only": {"type": "boolean", "default": True}},
+            },
+        ),
+        Tool(
+            name="devcouncil_update_task_scope",
+            description="Append unique expected tests or allowed commands for a leased task.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "task_id": {"type": "string"},
+                    "lease_token": {"type": "string"},
+                    "expected_tests": {"type": "array", "items": {"type": "string"}},
+                    "allowed_commands": {"type": "array", "items": {"type": "string"}},
+                },
+                "required": ["task_id", "lease_token"],
+            },
+        ),
+        Tool(
+            name="devcouncil_append_evidence",
+            description="Append command evidence for a leased task.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "task_id": {"type": "string"},
+                    "lease_token": {"type": "string"},
+                    "command": {"type": "string"},
+                    "exit_code": {"type": "integer"},
+                    "summary": {"type": "string"},
+                },
+                "required": ["task_id", "lease_token", "command", "exit_code", "summary"],
+            },
+        ),
+        Tool(
+            name="devcouncil_record_command",
+            description="Record a shell command event for a leased task.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "task_id": {"type": "string"},
+                    "lease_token": {"type": "string"},
+                    "command": {"type": "string"},
+                    "status": {"type": "string", "enum": ["started", "finished", "failed", "blocked"]},
+                    "exit_code": {"type": "integer"},
+                    "reason": {"type": "string"},
+                },
+                "required": ["task_id", "lease_token", "command", "status"],
+            },
+        ),
+        Tool(
+            name="devcouncil_write_file",
+            description=(
+                "Write a file for a leased task through DevCouncil's policy gate. The write "
+                "is checked against the task's scope BEFORE it lands (out-of-scope or "
+                "protected paths are rejected), applied atomically, and recorded as a "
+                "FileChangeEvent. Returns applied_files and rejected_files."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "task_id": {"type": "string"},
+                    "lease_token": {"type": "string"},
+                    "path": {"type": "string"},
+                    "content": {"type": "string"},
+                },
+                "required": ["task_id", "lease_token", "path", "content"],
+            },
+        ),
+        Tool(
+            name="devcouncil_apply_patch",
+            description=(
+                "Apply a unified diff for a leased task through DevCouncil's policy gate. "
+                "EVERY target file is policy-checked first; if any is out of scope the whole "
+                "patch is rejected (never partially applied). Applied atomically via git and "
+                "each file recorded as a FileChangeEvent. Returns applied_files/rejected_files."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "task_id": {"type": "string"},
+                    "lease_token": {"type": "string"},
+                    "unified_diff": {"type": "string"},
+                },
+                "required": ["task_id", "lease_token", "unified_diff"],
+            },
+        ),
+        Tool(
+            name="devcouncil_verify_task",
+            description="Run verification for a leased task (local sandbox).",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "task_id": {"type": "string"},
+                    "lease_token": {"type": "string"},
+                    "sandbox": {"type": "string", "enum": ["local"], "default": "local", "description": "Only 'local' is supported in this build."},
+                },
+                "required": ["task_id", "lease_token"],
+            },
+        ),
+        Tool(
+            name="devcouncil_handoff_agent",
+            description="Hand off a task between coding CLI agents.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "task_id": {"type": "string"},
+                    "lease_token": {"type": "string"},
+                    "from_agent": {"type": "string"},
+                    "to_agent": {"type": "string"},
+                    "instruction": {"type": "string"},
+                },
+                "required": ["task_id", "lease_token", "from_agent", "to_agent"],
+            },
+        ),
+        Tool(
+            name="devcouncil_read_file",
+            description=(
+                "Read a repository file (read-only, no lease required) so an MCP-only "
+                "agent can inspect content before constructing a diff or overwriting it. "
+                "Containment-checked against the project root and refuses secret/credential "
+                "paths. Supports offset/limit or line_range windowing. Returns content "
+                "(truncated), sha256, and line_count."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "path": {"type": "string", "description": "Repository-relative or absolute path inside the project."},
+                    "offset": {"type": "integer", "minimum": 0, "description": "0-based line offset to start from."},
+                    "limit": {"type": "integer", "minimum": 1, "description": "Max number of lines to return."},
+                    "line_range": {
+                        "type": "string",
+                        "description": "Inclusive 1-based line range like '10-40' (overrides offset/limit).",
+                    },
+                },
+                "required": ["path"],
+            },
+        ),
+        Tool(
+            name="devcouncil_get_diff",
+            description=(
+                "Return the working-tree diff for the project (requires a git repo). When "
+                "task_id is given the diff is scoped to that task's planned/changed files. "
+                "Set staged=true to include the staged (git diff --cached) changes. Returns "
+                "per-file status with additions/deletions and the truncated unified diff."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "task_id": {"type": "string", "description": "Optional task to scope the diff to its files."},
+                    "paths": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "Optional explicit repo-relative paths to scope the diff to.",
+                    },
+                    "staged": {"type": "boolean", "default": False, "description": "Include staged changes."},
+                },
+            },
+        ),
+        Tool(
+            name="devcouncil_get_evidence",
+            description=(
+                "Read persisted CommandResult evidence for a task and inline the truncated "
+                "stdout/stderr from the stored log files (best-effort; tolerates missing "
+                "files). Pairs with verification to close the diagnose leg of the loop."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "task_id": {"type": "string"},
+                    "command": {"type": "string", "description": "Optional substring filter on the recorded command."},
+                    "limit": {"type": "integer", "minimum": 1, "maximum": 100, "default": 20},
+                },
+                "required": ["task_id"],
+            },
+        ),
+        Tool(
+            name="devcouncil_run_command",
+            description=(
+                "Run a command for a leased task through DevCouncil's allowlist gate. The "
+                "command must pass the task's allowed_commands policy (same gate as the "
+                "hooks); otherwise it is refused and nothing runs. Executed with a clean "
+                "subprocess env and a timeout, recorded as a ShellCommandEvent. Returns "
+                "exit_code and truncated stdout/stderr."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "task_id": {"type": "string"},
+                    "lease_token": {"type": "string"},
+                    "command": {"type": "string"},
+                },
+                "required": ["task_id", "lease_token", "command"],
+            },
+        ),
+        Tool(
+            name="devcouncil_list_agent_runs",
+            description=(
+                "List recorded coding-agent runs (from .devcouncil/runs/*/agent-run.json), "
+                "newest first. Each entry includes run_id, task, agent, profile, status, "
+                "started time, and an orphaned flag for runs still marked running whose "
+                "manifest has gone stale (executor likely crashed). Read-only."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "status": {"type": "string", "description": "Optional status filter (e.g. running, finished, failed, timeout)."},
+                    "limit": {"type": "integer", "minimum": 1, "maximum": 500, "default": 20},
+                },
+            },
+        ),
+        Tool(
+            name="devcouncil_get_run",
+            description=(
+                "Get the full manifest for a single coding-agent run plus a redacted "
+                "transcript tail when a transcript/log file exists in the run directory. "
+                "Includes the resolved CLI invocation and an orphaned flag. Read-only."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "run_id": {"type": "string", "description": "The run id to inspect."},
+                },
+                "required": ["run_id"],
+            },
+        ),
+        Tool(
+            name="devcouncil_next_task",
+            description=(
+                "Return the highest-priority task that is unblocked (its depends_on are "
+                "satisfied) and has no active lease, so an autonomous agent can bootstrap "
+                "deterministically instead of racing list_tasks. Includes a blocking-gap "
+                "summary and a ready_to_checkout flag."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "client_id": {"type": "string", "description": "Optional client id (informational)."},
+                    "status": {"type": "string", "description": "Optional status filter (default planned/ready)."},
+                },
+            },
+        ),
+        Tool(
+            name="devcouncil_select_knowledge",
+            description=(
+                "Select the ingested project knowledge (OKF documents and the design "
+                "system) that applies to a goal and return it as a ready-to-inject "
+                "markdown preamble, so a coding agent can ask 'what project knowledge "
+                "applies to <goal>?'. Always-on design knowledge is included; OKF "
+                "documents are matched on goal keywords. Returns the matched sources "
+                "and the rendered preamble."
+            ),
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "goal": {"type": "string", "description": "The task or goal to find applicable knowledge for."},
+                },
+                "required": ["goal"],
+            },
+        ),
+    ]
+
+@app.list_resources()
+async def list_resources() -> list[Resource]:
+    """Expose the DevCouncil corpus as browsable/subscribable MCP resources, so a host
+    can read the report, task graph, gaps, and live-review state without a tool call."""
+    root = _project_root()
+    resources: list[Resource] = [
+        Resource(uri=AnyUrl("devcouncil://report"), name="DevCouncil report",
+                 description="Coverage report, requirement/task mapping, and blocking gaps.",
+                 mimeType="text/markdown"),
+        Resource(uri=AnyUrl("devcouncil://tasks"), name="Tasks",
+                 description="All planned tasks with scope and status.", mimeType="application/json"),
+        Resource(uri=AnyUrl("devcouncil://gaps"), name="Gaps",
+                 description="All open verification gaps.", mimeType="application/json"),
+        Resource(uri=AnyUrl("devcouncil://cards"), name="Live review",
+                 description="Live-review summary: cards, signals, and blockers.",
+                 mimeType="application/json"),
+    ]
+    db = get_db(root)
+    if db:
+        with db.get_session() as session:
+            for task in TaskRepository(session).get_all():
+                resources.append(Resource(
+                    uri=AnyUrl(f"devcouncil://task/{task.id}"),
+                    name=f"Task {task.id}: {task.title}",
+                    description=f"Scope, status, and gaps for {task.id}.",
+                    mimeType="application/json",
+                ))
+    # Project knowledge (ingested OKF + design.md) — surfaced only when something has
+    # actually been ingested, so hosts without a knowledge layer see no empty entries.
+    knowledge_sources = _discover_knowledge_sources(root)
+    if knowledge_sources:
+        resources.append(Resource(
+            uri=AnyUrl("devcouncil://knowledge"),
+            name="Project knowledge",
+            description="Index of ingested OKF and design knowledge for this project.",
+            mimeType="text/markdown",
+        ))
+        for source in knowledge_sources:
+            resources.append(Resource(
+                uri=AnyUrl(_knowledge_source_uri(source.kind, source.name)),
+                name=f"Knowledge ({source.kind}): {source.description or source.name}",
+                description=source.description or source.name,
+                mimeType="text/markdown",
+            ))
+    return resources
+
+
+@app.read_resource()
+async def read_resource(uri: AnyUrl) -> str:
+    root = _project_root()
+    db = get_db(root)
+    key = str(uri).rstrip("/")
+
+    if key == "devcouncil://report":
+        if not db:
+            return "DevCouncil is not initialized in this directory."
+        with db.get_session() as session:
+            graph = ArtifactGraphRepository(session).load_graph()
+        return ReportBuilder.build_markdown(graph, live_review=live_review_summary(root))
+    if key == "devcouncil://tasks":
+        if not db:
+            return json.dumps({"tasks": []})
+        with db.get_session() as session:
+            tasks = [t.model_dump() for t in TaskRepository(session).get_all()]
+        return json.dumps({"tasks": tasks}, indent=2)
+    if key == "devcouncil://gaps":
+        if not db:
+            return json.dumps({"gaps": []})
+        with db.get_session() as session:
+            gaps = [g.model_dump() for g in GapRepository(session).get_all()]
+        return json.dumps({"gaps": gaps}, indent=2)
+    if key == "devcouncil://cards":
+        return json.dumps(live_review_summary(root), indent=2)
+    if key.startswith("devcouncil://task/"):
+        task_id = key.rsplit("/", 1)[-1]
+        if not db:
+            return json.dumps({"ok": False, "error": "not initialized"})
+        with db.get_session() as session:
+            task = TaskRepository(session).get_by_id(task_id)
+            if not task:
+                return json.dumps({"ok": False, "error": f"Task {task_id} not found."})
+            gaps = [g.model_dump() for g in GapRepository(session).get_for_task(task_id)]
+        return json.dumps({"task": task.model_dump(), "gaps": gaps}, indent=2)
+
+    if key == "devcouncil://knowledge":
+        # Markdown index linking each ingested source to its per-source resource URI.
+        sources = _discover_knowledge_sources(root)
+        if not sources:
+            return "# Project knowledge\n\nNo OKF or design knowledge has been ingested for this project."
+        lines = ["# Project knowledge", "", "Ingested OKF and design knowledge for this project.", ""]
+        for kind in ("design", "okf"):
+            kind_sources = [s for s in sources if s.kind == kind]
+            if not kind_sources:
+                continue
+            lines.append(f"## {kind.upper() if kind == 'okf' else kind.capitalize()}")
+            lines.append("")
+            for source in kind_sources:
+                link = _knowledge_source_uri(source.kind, source.name)
+                desc = source.description or source.name
+                lines.append(f"- [{desc}]({link})")
+            lines.append("")
+        return "\n".join(lines).strip()
+    if key.startswith("devcouncil://knowledge/"):
+        # Match the requested URI back to a discovered source and render its markdown.
+        for source in _discover_knowledge_sources(root):
+            if _knowledge_source_uri(source.kind, source.name) == key:
+                return source.render() or source.body
+        return f"Knowledge source not found: {key}"
+
+    raise ValueError(f"Unknown resource: {uri}")
+
+
+# --- MCP prompts ---------------------------------------------------------------
+# Exposed prompts surface in MCP hosts (Claude Code, Codex, ...) as slash commands
+# (e.g. /mcp__devcouncil__implement_next_task). Each renders an actionable, DevCouncil-
+# aware instruction block — injecting a live status snapshot when the project is
+# initialized, and degrading to pure guidance when it is not. They steer a coding agent
+# through the lease -> read -> edit -> verify -> release loop using the devcouncil_* tools.
+
+class _PromptSpec(NamedTuple):
+    name: str
+    description: str
+    arguments: list[PromptArgument]
+
+
+_PROMPT_SPECS: list[_PromptSpec] = [
+    _PromptSpec(
+        name="devcouncil_implement_next_task",
+        description="Pick up the next unblocked DevCouncil task and implement it through the policy-gated MCP loop.",
+        arguments=[
+            PromptArgument(name="client_id", description="Optional stable client id used for the task lease.", required=False),
+        ],
+    ),
+    _PromptSpec(
+        name="devcouncil_repair_task",
+        description="Repair the blocking verification gaps for a task (defaults to the active running task).",
+        arguments=[
+            PromptArgument(name="task_id", description="Task id, e.g. TASK-001. Defaults to the active task.", required=False),
+        ],
+    ),
+    _PromptSpec(
+        name="devcouncil_verify_task",
+        description="Run DevCouncil verification for a task and report blocking gaps.",
+        arguments=[
+            PromptArgument(name="task_id", description="Task id, e.g. TASK-001. Defaults to the active task.", required=False),
+        ],
+    ),
+    _PromptSpec(
+        name="devcouncil_review_live",
+        description="Review pending live-review critique cards and resolve the blocking ones.",
+        arguments=[
+            PromptArgument(name="task_id", description="Optional task scope for the live-review cards.", required=False),
+        ],
+    ),
+    _PromptSpec(
+        name="devcouncil_project_status",
+        description="Summarize the current DevCouncil project phase, tasks, and blocking gaps.",
+        arguments=[],
+    ),
+    _PromptSpec(
+        name="devcouncil_apply_knowledge",
+        description="Select the ingested project knowledge (OKF + design) that applies to a goal and inject it.",
+        arguments=[
+            PromptArgument(name="goal", description="The task or goal to find applicable project knowledge for.", required=True),
+        ],
+    ),
+]
+
+
+def _status_snapshot(root: Path) -> str:
+    """A short live status block for prompt bodies, or an init hint when uninitialized."""
+    db = get_db(root)
+    if not db:
+        return "DevCouncil is not initialized here yet — run `dev init` first."
+    try:
+        with db.get_session() as session:
+            graph = ArtifactGraphRepository(session).load_graph()
+            summary = graph.coverage_summary()
+            state = StateRepository(session).get_state()
+            phase = compute_phase(graph, state.current_phase if state else None)
+        return (
+            f"Phase: {phase} | "
+            f"tasks: {summary['total_tasks']} | "
+            f"gaps: {summary['total_gaps']} ({summary['blocking_gaps']} blocking)"
+        )
+    except Exception:
+        return "DevCouncil status unavailable."
+
+
+def _render_prompt_text(name: str, arguments: dict, root: Path) -> str:
+    snapshot = _status_snapshot(root)
+    if name == "devcouncil_implement_next_task":
+        client_id = arguments.get("client_id") or "claude-code"
+        return (
+            "You are implementing the next DevCouncil task under policy enforcement.\n\n"
+            f"Project status: {snapshot}\n\n"
+            "Do exactly this:\n"
+            "1. Call `devcouncil_next_task` to get the highest-priority unblocked task.\n"
+            f"2. Call `devcouncil_checkout_task` with that task_id and client_id='{client_id}' to acquire a lease.\n"
+            "3. Read the task scope with `devcouncil_get_task` and `devcouncil_get_prompt`; inspect files with `devcouncil_read_file` and `devcouncil_get_diff`.\n"
+            "4. Make changes ONLY through `devcouncil_write_file` / `devcouncil_apply_patch` (the policy gate rejects out-of-scope or protected paths) and run tests with `devcouncil_run_command`.\n"
+            "5. Call `devcouncil_verify_task`; if it reports blocking gaps, fix them and re-verify.\n"
+            "6. When verified, call `devcouncil_release_task` with the lease token.\n\n"
+            "Never edit files outside the task scope. If a write is rejected, call `devcouncil_update_task_scope` only when the change is legitimately in-scope."
+        )
+    if name == "devcouncil_repair_task":
+        task_id = arguments.get("task_id") or "(the active task)"
+        return (
+            f"Repair the blocking verification gaps for {task_id}.\n\n"
+            f"Project status: {snapshot}\n\n"
+            "1. Call `devcouncil_get_gaps` (blocking_only=true) and `devcouncil_get_next_actions` for the task.\n"
+            "2. Inspect the relevant files and evidence with `devcouncil_read_file` and `devcouncil_get_evidence`.\n"
+            "3. Apply minimal fixes via `devcouncil_apply_patch` / `devcouncil_write_file`.\n"
+            "4. Re-run `devcouncil_verify_task` until no blocking gaps remain, then `devcouncil_release_task`."
+        )
+    if name == "devcouncil_verify_task":
+        task_id = arguments.get("task_id") or "(the active task)"
+        return (
+            f"Run DevCouncil verification for {task_id} and report the result.\n\n"
+            f"Project status: {snapshot}\n\n"
+            "Call `devcouncil_verify_task` (you must hold the task lease via `devcouncil_checkout_task`). "
+            "Summarize the blocking gaps and proposed next actions; do not mark work complete while blocking gaps remain."
+        )
+    if name == "devcouncil_review_live":
+        scope = arguments.get("task_id")
+        scope_line = f" scoped to {scope}" if scope else ""
+        return (
+            f"Review the pending live-review critique cards{scope_line}.\n\n"
+            "1. Call `devcouncil_live_review` for the blocker count and `devcouncil_live_cards` (status='open') for the cards.\n"
+            "2. For each blocking card, call `devcouncil_live_repair_prompt` (or `devcouncil_live_repair_all`) to get a ready-to-apply repair.\n"
+            "3. Apply the fixes through the policy-gated write tools and re-verify."
+        )
+    if name == "devcouncil_project_status":
+        return (
+            "Summarize the DevCouncil project state for the user.\n\n"
+            f"Live snapshot: {snapshot}\n\n"
+            "Call `devcouncil_status` and `devcouncil_report` for the full coverage report, then give a concise "
+            "phase / tasks / blocking-gaps summary and recommend the next action."
+        )
+    if name == "devcouncil_apply_knowledge":
+        goal = arguments.get("goal") or ""
+        return (
+            f"Find and apply the project knowledge that applies to this goal: {goal!r}.\n\n"
+            "Call `devcouncil_select_knowledge` with the goal, then treat the returned preamble as authoritative "
+            "project context (design system + OKF docs) for any code you write toward this goal."
+        )
+    return f"Unknown DevCouncil prompt: {name}"
+
+
+@app.list_prompts()
+async def list_prompts() -> list[Prompt]:
+    return [
+        Prompt(name=spec.name, description=spec.description, arguments=list(spec.arguments))
+        for spec in _PROMPT_SPECS
     ]
 
+
+@app.get_prompt()
+async def get_prompt(name: str, arguments: dict | None) -> GetPromptResult:
+    spec = next((spec for spec in _PROMPT_SPECS if spec.name == name), None)
+    if spec is None:
+        raise ValueError(f"Unknown prompt: {name}")
+    args = _normalize_arguments(arguments)
+    root = _project_root()
+    text = _render_prompt_text(name, args, root)
+    return GetPromptResult(
+        description=spec.description,
+        messages=[PromptMessage(role="user", content=TextContent(type="text", text=text))],
+    )
+
+
 @app.call_tool()
 async def call_tool(name: str, arguments: dict) -> list[TextContent]:
     arguments = _normalize_arguments(arguments)
+    logger.info("MCP call_tool: %s args=%s", name, sorted(arguments) if isinstance(arguments, dict) else arguments)
     root = _project_root()
     db = get_db(root)
     if name in _DB_REQUIRED_TOOLS and not db:
+        logger.warning("MCP tool %s rejected: project not initialized at %s", name, root)
         return _error_text("DevCouncil not initialized in this directory.", code="not_initialized")
 
+    if name == "devcouncil_integration_status":
+        return _json_text(integration_status_summary(root))
+
     if name == "devcouncil_status":
         assert db is not None
         with db.get_session() as session:
@@ -397,15 +1427,15 @@ async def call_tool(name: str, arguments: dict) -> list[TextContent]:
                 return _error_text(f"{arg_name} must be a string", code="invalid_arguments", argument=arg_name)
 
         limit = _int_argument(arguments, "limit", 20, minimum=1, maximum=200)
-        filtered, error, argument = filter_cards(
+        filtered, filter_error, argument = filter_cards(
             load_cards(root),
             task_id=task_id,
             status=status,
             verdict=verdict,
             client=client,
         )
-        if error:
-            return _error_text(error, code="invalid_arguments", argument=argument)
+        if filter_error:
+            return _error_text(filter_error, code="invalid_arguments", argument=argument)
 
         total = len(filtered)
         return [TextContent(
@@ -424,9 +1454,10 @@ async def call_tool(name: str, arguments: dict) -> list[TextContent]:
         )]
 
     elif name == "devcouncil_live_repair_prompt":
-        card_id, error = _required_string_argument(arguments, "card_id")
-        if error:
-            return error
+        card_id, arg_error = _required_string_argument(arguments, "card_id")
+        if arg_error:
+            return arg_error
+        assert card_id is not None
         card = get_card(root, card_id)
         if not card:
             return _error_text(f"Critique card {card_id} not found.", code="not_found", card_id=card_id)
@@ -448,21 +1479,22 @@ async def call_tool(name: str, arguments: dict) -> list[TextContent]:
             for item in summary["blocking_cards"]
             if isinstance(item.get("id"), str)
         ]
-        cards = [card for card in cards if card is not None]
+        resolved_cards = [card for card in cards if card is not None]
         return [TextContent(
             type="text",
             text=json.dumps({
                 "scope_task_id": summary["scope_task_id"],
-                "cards": [card.model_dump() for card in cards],
-                "prompt": build_bulk_live_repair_prompt(root, cards),
+                "cards": [card.model_dump() for card in resolved_cards],
+                "prompt": build_bulk_live_repair_prompt(root, resolved_cards),
             }, indent=2),
         )]
             
     elif name == "devcouncil_get_task":
         assert db is not None
-        task_id, error = _required_string_argument(arguments, "task_id")
-        if error:
-            return error
+        task_id, arg_error = _required_string_argument(arguments, "task_id")
+        if arg_error:
+            return arg_error
+        assert task_id is not None
             
         with db.get_session() as session:
             task_repo = TaskRepository(session)
@@ -472,19 +1504,96 @@ async def call_tool(name: str, arguments: dict) -> list[TextContent]:
             
             return [TextContent(type="text", text=task.model_dump_json(indent=2))]
 
-    elif name == "devcouncil_list_tasks":
+    elif name == "devcouncil_get_gaps":
         assert db is not None
+        task_id, arg_error = _required_string_argument(arguments, "task_id")
+        if arg_error:
+            return arg_error
+        assert task_id is not None  # _required_string_argument returns a value when arg_error is None
+        blocking_only = bool(arguments.get("blocking_only", False))
         with db.get_session() as session:
-            task_repo = TaskRepository(session)
-            tasks = [task.model_dump() for task in task_repo.get_all()]
+            gaps = GapRepository(session).get_for_task(task_id)
+        if blocking_only:
+            gaps = [g for g in gaps if g.blocking]
+        return _json_text({
+            "ok": True,
+            "task_id": task_id,
+            "gaps": [g.model_dump() for g in gaps],
+            "blocking_count": sum(1 for g in gaps if g.blocking),
+        })
 
-            return [TextContent(type="text", text=json.dumps({"tasks": tasks}, indent=2))]
+    elif name == "devcouncil_get_next_actions":
+        assert db is not None
+        task_id, arg_error = _required_string_argument(arguments, "task_id")
+        if arg_error:
+            return arg_error
+        assert task_id is not None
+        with db.get_session() as session:
+            gaps = GapRepository(session).get_for_task(task_id)
+            task = TaskRepository(session).get_by_id(task_id)
+        blocking_actions, advisory_actions = split_next_actions(gaps)
+        has_blocking = any(g.blocking for g in gaps)
+        return _json_text({
+            "ok": True,
+            "task_id": task_id,
+            "next_actions": [a.model_dump() for a in blocking_actions],
+            "advisory_actions": [a.model_dump() for a in advisory_actions],
+            # Self-describing loop: computed from the task's status + blocking gaps so
+            # the agent is steered toward what this task actually needs next.
+            "allowed_next_tools": _allowed_next_tools(task.status if task else "planned", has_blocking),
+        })
+
+    elif name == "devcouncil_get_task_provenance":
+        assert db is not None
+        task_id, arg_error = _required_string_argument(arguments, "task_id")
+        if arg_error:
+            return arg_error
+        assert task_id is not None
+        with db.get_session() as session:
+            file_changes = [r.model_dump() for r in FileChangeRepository(session).list_for_task(task_id)]
+            verification_runs = [r.model_dump() for r in VerificationRunRepository(session).list_for_task(task_id)]
+            coverage = [
+                ev.model_dump()
+                for ev in EvidenceRepository(session).get_all()
+                if isinstance(ev, DiffCoverageEvidence) and ev.task_id == task_id
+            ]
+            correction_manifest = CorrectionManifestRepository(session).latest_for_task(task_id)
+        return _json_text({
+            "ok": True,
+            "task_id": task_id,
+            "file_changes": file_changes,
+            "verification_runs": verification_runs,
+            "diff_coverage": coverage,
+            "latest_correction_manifest": correction_manifest.model_dump() if correction_manifest else None,
+        })
+
+    elif name == "devcouncil_list_tasks":
+        assert db is not None
+        status_filter = _optional_string_argument(arguments, "status")
+        if status_filter == "":
+            return _error_text("status must be a string", code="invalid_arguments", argument="status")
+        limit = _int_argument(arguments, "limit", 100, minimum=1, maximum=500)
+        offset = _int_argument(arguments, "offset", 0, minimum=0, maximum=1_000_000)
+        with db.get_session() as session:
+            all_tasks = TaskRepository(session).get_all()
+        if status_filter:
+            all_tasks = [t for t in all_tasks if t.status == status_filter]
+        total = len(all_tasks)
+        window = all_tasks[offset:offset + limit]
+        return _json_text({
+            "tasks": [task.model_dump() for task in window],
+            "total": total,
+            "offset": offset,
+            "limit": limit,
+            "returned": len(window),
+        })
 
     elif name == "devcouncil_get_prompt":
         assert db is not None
-        task_id, error = _required_string_argument(arguments, "task_id")
-        if error:
-            return error
+        task_id, arg_error = _required_string_argument(arguments, "task_id")
+        if arg_error:
+            return arg_error
+        assert task_id is not None
 
         with db.get_session() as session:
             task_repo = TaskRepository(session)
@@ -506,9 +1615,10 @@ async def call_tool(name: str, arguments: dict) -> list[TextContent]:
 
     elif name == "devcouncil_policy_check_write":
         assert db is not None
-        path, error = _required_string_argument(arguments, "path")
-        if error:
-            return error
+        path, arg_error = _required_string_argument(arguments, "path")
+        if arg_error:
+            return arg_error
+        assert path is not None
         task_id = _optional_string_argument(arguments, "task_id")
         if task_id == "":
             return _error_text("task_id must be a string", code="invalid_arguments", argument="task_id")
@@ -532,11 +1642,11 @@ async def call_tool(name: str, arguments: dict) -> list[TextContent]:
         files = arguments.get("files", [])
         if not isinstance(files, list):
             files = []
-        context = CodeReviewGraphAdapter(root).get_context([file for file in files if isinstance(file, str)])
+        context = _get_graph_adapter(root).get_context([file for file in files if isinstance(file, str)])
         return [TextContent(type="text", text=context.model_dump_json(indent=2))]
 
     elif name == "devcouncil_lsp_status":
-        return [TextContent(type="text", text=LspInspector(root).summary_json())]
+        return [TextContent(type="text", text=_get_lsp_inspector(root).summary_json())]
 
     elif name == "devcouncil_ast_match":
         query = _optional_string_argument(arguments, "query")
@@ -546,7 +1656,7 @@ async def call_tool(name: str, arguments: dict) -> list[TextContent]:
             if value == "":
                 return _error_text(f"{arg_name} must be a string", code="invalid_arguments", argument=arg_name)
         limit = _int_argument(arguments, "limit", 100, minimum=1, maximum=500)
-        matches = AstMatcher(root).match(
+        matches = _get_ast_matcher(root).match(
             query=query or "",
             language=language,
             kind=kind,
@@ -570,9 +1680,10 @@ async def call_tool(name: str, arguments: dict) -> list[TextContent]:
 
     elif name == "devcouncil_prepare_execution":
         assert db is not None
-        task_id, error = _required_string_argument(arguments, "task_id")
-        if error:
-            return error
+        task_id, arg_error = _required_string_argument(arguments, "task_id")
+        if arg_error:
+            return arg_error
+        assert task_id is not None
         with db.get_session() as session:
             task_repo = TaskRepository(session)
             req_repo = RequirementRepository(session)
@@ -588,6 +1699,807 @@ async def call_tool(name: str, arguments: dict) -> list[TextContent]:
                 "expected_tests": task.expected_tests,
             }, indent=2))]
 
+    elif name == "devcouncil_checkout_task":
+        assert db is not None
+        task_id, arg_error = _required_string_argument(arguments, "task_id")
+        if arg_error:
+            return arg_error
+        client_id, arg_error = _required_string_argument(arguments, "client_id")
+        if arg_error:
+            return arg_error
+        assert task_id is not None and client_id is not None
+        agent = _optional_string_argument(arguments, "agent")
+        if agent == "":
+            return _error_text("agent must be a string", code="invalid_arguments", argument="agent")
+        force_value = arguments.get("force", False)
+        if not isinstance(force_value, bool):
+            return _error_text("force must be a boolean", code="invalid_arguments", argument="force")
+        force = force_value
+        with db.get_session() as session:
+            task_repo = TaskRepository(session)
+            task = task_repo.get_by_id(task_id)
+            if not task:
+                return _error_text(f"Task {task_id} not found.", code="not_found", task_id=task_id)
+            lease_repo = TaskLeaseRepository(session)
+            try:
+                lease = lease_repo.acquire(
+                    task_id,
+                    owner=f"mcp:{client_id}",
+                    agent=agent,
+                    client_id=client_id,
+                    ttl_seconds=_lease_ttl_seconds(root),
+                    force=force,
+                )
+            except ValueError as exc:
+                return _error_text(str(exc), code="lease_conflict", task_id=task_id)
+            prompt = PromptBuilder(root).build_task_prompt(task, RequirementRepository(session).get_all())
+            semantic = None
+            semantic_path = root / ".devcouncil" / "semantic" / task_id / "before.json"
+            if semantic_path.exists():
+                semantic = json.loads(semantic_path.read_text(encoding="utf-8"))
+            return _json_text({
+                "ok": True,
+                "lease_token": lease.lease_token,
+                "task_id": task.id,
+                "status": task.status,
+                "expires_at": lease.expires_at,
+                "prompt": prompt,
+                "planned_files": [f.model_dump() for f in task.planned_files],
+                "allowed_commands": task.allowed_commands,
+                "expected_tests": task.expected_tests,
+                "semantic_context": semantic,
+                # The task is now leased and running-ready: surface the inner-loop tools.
+                "allowed_next_tools": _allowed_next_tools(
+                    "running",
+                    bool(GapRepository(session).get_blocking_for_task(task_id)),
+                ),
+            })
+
+    elif name == "devcouncil_release_task":
+        assert db is not None
+        task_id, arg_error = _required_string_argument(arguments, "task_id")
+        if arg_error:
+            return arg_error
+        lease_token, arg_error = _required_string_argument(arguments, "lease_token")
+        if arg_error:
+            return arg_error
+        assert task_id is not None and lease_token is not None
+        with db.get_session() as session:
+            released = TaskLeaseRepository(session).release(task_id, lease_token)
+            if not released:
+                return _error_text("Invalid lease token.", code="invalid_lease", task_id=task_id)
+            return _json_text({"ok": True, "task_id": task_id, "released": True})
+
+    elif name == "devcouncil_renew_lease":
+        assert db is not None
+        task_id, arg_error = _required_string_argument(arguments, "task_id")
+        if arg_error:
+            return arg_error
+        lease_token, arg_error = _required_string_argument(arguments, "lease_token")
+        if arg_error:
+            return arg_error
+        assert task_id is not None and lease_token is not None
+        ttl_value = arguments.get("ttl_seconds")
+        if ttl_value is not None and (not isinstance(ttl_value, int) or isinstance(ttl_value, bool)):
+            return _error_text("ttl_seconds must be an integer", code="invalid_arguments", argument="ttl_seconds")
+        ttl_seconds = ttl_value if isinstance(ttl_value, int) and not isinstance(ttl_value, bool) else _lease_ttl_seconds(root)
+        with db.get_session() as session:
+            renewed_lease = TaskLeaseRepository(session).renew(task_id, lease_token, ttl_seconds)
+            if renewed_lease is None:
+                return _error_text("Invalid or expired lease.", code="invalid_lease", task_id=task_id)
+            return _json_text({
+                "ok": True,
+                "task_id": task_id,
+                "expires_at": renewed_lease.expires_at,
+                "ttl_seconds": ttl_seconds,
+            })
+
+    elif name == "devcouncil_list_leases":
+        assert db is not None
+        active_only = arguments.get("active_only", True)
+        if not isinstance(active_only, bool):
+            return _error_text("active_only must be a boolean", code="invalid_arguments", argument="active_only")
+        with db.get_session() as session:
+            pairs = TaskLeaseRepository(session).list_leases(active_only=active_only)
+        leases = [
+            {
+                "task_id": lease.task_id,
+                "owner": lease.owner,
+                "agent": lease.agent,
+                "status": lease.status,
+                "expires_at": lease.expires_at,
+                "expired": expired,
+            }
+            for lease, expired in pairs
+        ]
+        return _json_text({"ok": True, "leases": leases, "count": len(leases)})
+
+    elif name == "devcouncil_update_task_scope":
+        assert db is not None
+        task_id, arg_error = _required_string_argument(arguments, "task_id")
+        if arg_error:
+            return arg_error
+        lease_token, arg_error = _required_string_argument(arguments, "lease_token")
+        if arg_error:
+            return arg_error
+        assert task_id is not None and lease_token is not None
+        expected_tests, arg_error = _optional_string_list_argument(arguments, "expected_tests")
+        if arg_error:
+            return arg_error
+        allowed_commands, arg_error = _optional_string_list_argument(arguments, "allowed_commands")
+        if arg_error:
+            return arg_error
+        with db.get_session() as session:
+            lease_repo = TaskLeaseRepository(session)
+            if not lease_repo.validate(task_id, lease_token):
+                return _error_text("Invalid lease token.", code="invalid_lease", task_id=task_id)
+            task_repo = TaskRepository(session)
+            task = task_repo.get_by_id(task_id)
+            if not task:
+                return _error_text(f"Task {task_id} not found.", code="not_found", task_id=task_id)
+            for cmd in allowed_commands:
+                if cmd not in task.allowed_commands:
+                    task.allowed_commands.append(cmd)
+            for test in expected_tests:
+                if test not in task.expected_tests:
+                    task.expected_tests.append(test)
+            task_repo.save(task)
+            return _json_text({
+                "ok": True,
+                "task_id": task_id,
+                "allowed_commands": task.allowed_commands,
+                "expected_tests": task.expected_tests,
+            })
+
+    elif name == "devcouncil_append_evidence":
+        assert db is not None
+        task_id, arg_error = _required_string_argument(arguments, "task_id")
+        if arg_error:
+            return arg_error
+        lease_token, arg_error = _required_string_argument(arguments, "lease_token")
+        if arg_error:
+            return arg_error
+        command, arg_error = _required_string_argument(arguments, "command")
+        if arg_error:
+            return arg_error
+        summary_text, arg_error = _required_string_argument(arguments, "summary")
+        if arg_error:
+            return arg_error
+        assert task_id is not None and lease_token is not None
+        exit_code = arguments.get("exit_code", 0)
+        if not isinstance(exit_code, int) or isinstance(exit_code, bool):
+            return _error_text("exit_code must be an integer", code="invalid_arguments")
+        with db.get_session() as session:
+            if not TaskLeaseRepository(session).validate(task_id, lease_token):
+                return _error_text("Invalid lease token.", code="invalid_lease", task_id=task_id)
+            EvidenceRepository(session).save_command_result(
+                task_id,
+                CommandResult(
+                    command=command or "",
+                    exit_code=exit_code,
+                    stdout_path="",
+                    stderr_path="",
+                    summary=summary_text or "",
+                ),
+            )
+            return _json_text({"ok": True, "task_id": task_id, "recorded": True})
+
+    elif name == "devcouncil_record_command":
+        assert db is not None
+        task_id, arg_error = _required_string_argument(arguments, "task_id")
+        if arg_error:
+            return arg_error
+        lease_token, arg_error = _required_string_argument(arguments, "lease_token")
+        if arg_error:
+            return arg_error
+        command, arg_error = _required_string_argument(arguments, "command")
+        if arg_error:
+            return arg_error
+        status, arg_error = _required_string_argument(arguments, "status")
+        if arg_error:
+            return arg_error
+        assert task_id is not None and lease_token is not None
+        if status not in _RECORD_COMMAND_STATUSES:
+            return _error_text(
+                f"status must be one of {sorted(_RECORD_COMMAND_STATUSES)}",
+                code="invalid_arguments", argument="status",
+            )
+        with db.get_session() as session:
+            if not TaskLeaseRepository(session).validate(task_id, lease_token):
+                return _error_text("Invalid lease token.", code="invalid_lease", task_id=task_id)
+            exit_code = arguments.get("exit_code")
+            if exit_code is not None and (not isinstance(exit_code, int) or isinstance(exit_code, bool)):
+                return _error_text("exit_code must be an integer", code="invalid_arguments")
+            ShellCommandRepository(session).record(
+                task_id,
+                command or "",
+                status or "finished",
+                exit_code=exit_code if isinstance(exit_code, int) else None,
+                reason=str(arguments.get("reason") or ""),
+            )
+            return _json_text({"ok": True, "task_id": task_id, "recorded": True})
+
+    elif name == "devcouncil_write_file":
+        assert db is not None
+        task_id, arg_error = _required_string_argument(arguments, "task_id")
+        if arg_error:
+            return arg_error
+        lease_token, arg_error = _required_string_argument(arguments, "lease_token")
+        if arg_error:
+            return arg_error
+        rel_path, arg_error = _required_string_argument(arguments, "path")
+        if arg_error:
+            return arg_error
+        content = arguments.get("content")
+        if not isinstance(content, str):
+            return _error_text("content must be a string", code="invalid_arguments", argument="content")
+        assert task_id is not None and lease_token is not None and rel_path is not None
+        with db.get_session() as session:
+            lease_record = TaskLeaseRepository(session).active_for_task(task_id)
+            if lease_record is None or lease_record.lease_token != lease_token:
+                return _error_text("Invalid lease token.", code="invalid_lease", task_id=task_id)
+            task = TaskRepository(session).get_by_id(task_id)
+            if not task:
+                return _error_text(f"Task {task_id} not found.", code="not_found", task_id=task_id)
+
+            decision = HookPolicy(project_root=root).evaluate_file_write(rel_path, task, content=content)
+            target = _within_root(root, rel_path)
+            if target is None:
+                FileChangeRepository(session).record(
+                    rel_path, "write", False, task_id=task_id, lease_id=lease_record.id,
+                    reason="path escapes the project root",
+                )
+                return _json_text({
+                    "ok": False, "task_id": task_id, "applied_files": [],
+                    "rejected_files": [{"path": rel_path, "reason": "path escapes the project root"}],
+                })
+            if not decision.allowed:
+                FileChangeRepository(session).record(
+                    rel_path, "write", False, task_id=task_id, lease_id=lease_record.id, reason=decision.reason,
+                )
+                return _json_text({
+                    "ok": False, "task_id": task_id, "applied_files": [],
+                    "rejected_files": [{"path": rel_path, "reason": decision.reason}],
+                })
+            # Atomic write: stage to a sibling temp file, then replace.
+            try:
+                target.parent.mkdir(parents=True, exist_ok=True)
+                tmp = target.with_name(target.name + ".devcouncil-tmp")
+                tmp.write_text(content, encoding="utf-8")
+                os.replace(tmp, target)
+            except OSError as exc:
+                return _error_text(f"Write failed: {exc}", code="write_failed", task_id=task_id)
+            FileChangeRepository(session).record(
+                rel_path, "write", True, task_id=task_id, lease_id=lease_record.id, reason=decision.reason,
+            )
+            return _json_text({
+                "ok": True, "task_id": task_id, "applied_files": [rel_path], "rejected_files": [],
+            })
+
+    elif name == "devcouncil_apply_patch":
+        assert db is not None
+        task_id, arg_error = _required_string_argument(arguments, "task_id")
+        if arg_error:
+            return arg_error
+        lease_token, arg_error = _required_string_argument(arguments, "lease_token")
+        if arg_error:
+            return arg_error
+        unified_diff = arguments.get("unified_diff")
+        if not isinstance(unified_diff, str) or not unified_diff.strip():
+            return _error_text("unified_diff must be a non-empty string", code="invalid_arguments", argument="unified_diff")
+        assert task_id is not None and lease_token is not None
+        if not _is_git_repo(root):
+            return _error_text(
+                "apply_patch requires a git repository. Use devcouncil_write_file instead.",
+                code="not_a_git_repo", task_id=task_id,
+            )
+        targets = _diff_target_paths(unified_diff)
+        if not targets:
+            return _error_text("No target files found in the diff.", code="empty_patch", task_id=task_id)
+        with db.get_session() as session:
+            lease_record = TaskLeaseRepository(session).active_for_task(task_id)
+            if lease_record is None or lease_record.lease_token != lease_token:
+                return _error_text("Invalid lease token.", code="invalid_lease", task_id=task_id)
+            task = TaskRepository(session).get_by_id(task_id)
+            if not task:
+                return _error_text(f"Task {task_id} not found.", code="not_found", task_id=task_id)
+
+            # Policy-check EVERY target before touching the tree. Any rejection aborts
+            # the whole patch — never a partial apply.
+            policy = HookPolicy(project_root=root)
+            rejected: list[dict[str, str]] = []
+            for path in targets:
+                if _within_root(root, path) is None:
+                    rejected.append({"path": path, "reason": "path escapes the project root"})
+                    continue
+                d = policy.evaluate_file_write(path, task)
+                if not d.allowed:
+                    rejected.append({"path": path, "reason": d.reason})
+            if rejected:
+                for item in rejected:
+                    FileChangeRepository(session).record(
+                        item["path"], "apply_patch", False, task_id=task_id, lease_id=lease_record.id, reason=item["reason"],
+                    )
+                return _json_text({
+                    "ok": False, "task_id": task_id, "applied_files": [], "rejected_files": rejected,
+                })
+
+            # Validate then apply atomically (git apply is all-or-nothing).
+            patch_path = root / ".devcouncil" / f"mcp-apply-{lease_record.id}.patch"
+            patch_path.parent.mkdir(parents=True, exist_ok=True)
+            patch_path.write_text(unified_diff, encoding="utf-8")
+            try:
+                check = subprocess.run(
+                    ["git", "apply", "--check", "--ignore-whitespace", str(patch_path)],
+                    cwd=root, capture_output=True, text=True,
+                )
+                if check.returncode != 0:
+                    return _error_text(
+                        f"Patch does not apply cleanly: {check.stderr.strip()}",
+                        code="patch_rejected", task_id=task_id,
+                    )
+                applied = subprocess.run(
+                    ["git", "apply", "--ignore-whitespace", str(patch_path)],
+                    cwd=root, capture_output=True, text=True,
+                )
+                if applied.returncode != 0:
+                    return _error_text(
+                        f"Patch apply failed: {applied.stderr.strip()}",
+                        code="patch_failed", task_id=task_id,
+                    )
+            finally:
+                try:
+                    patch_path.unlink()
+                except OSError:
+                    pass
+            for path in targets:
+                FileChangeRepository(session).record(
+                    path, "apply_patch", True, task_id=task_id, lease_id=lease_record.id, reason="policy allowed",
+                )
+            return _json_text({
+                "ok": True, "task_id": task_id, "applied_files": targets, "rejected_files": [],
+            })
+
+    elif name == "devcouncil_verify_task":
+        assert db is not None
+        task_id, arg_error = _required_string_argument(arguments, "task_id")
+        if arg_error:
+            return arg_error
+        lease_token, arg_error = _required_string_argument(arguments, "lease_token")
+        if arg_error:
+            return arg_error
+        assert task_id is not None and lease_token is not None
+        sandbox = _optional_string_argument(arguments, "sandbox") or "local"
+        if sandbox in {"docker", "nix"}:
+            return _json_text({
+                "ok": False,
+                "code": "unsupported_sandbox",
+                "reason": f"Sandbox {sandbox} is not available in this build.",
+                "sandbox": sandbox,
+            })
+        with db.get_session() as session:
+            if not TaskLeaseRepository(session).validate(task_id, lease_token):
+                return _error_text("Invalid lease token.", code="invalid_lease", task_id=task_id)
+            task_repo = TaskRepository(session)
+            task = task_repo.get_by_id(task_id)
+            if not task:
+                return _error_text(f"Task {task_id} not found.", code="not_found", task_id=task_id)
+            from devcouncil.verification.verifier import Verifier
+
+            GapRepository(session).delete_for_task(task_id)
+            EvidenceRepository(session).delete_for_task(task_id)
+            # Run the STRONG gate when a provider key is configured (compiled
+            # per-criterion checks); otherwise fall back to coarse mode and report it.
+            verifier = Verifier(root, router=_load_router(root))
+            evidence_gaps, evidence = await verifier.verify_task(
+                task, RequirementRepository(session).get_all()
+            )
+            gaps = evidence_gaps
+            for gap in gaps:
+                GapRepository(session).save(gap)
+            for ev in evidence:
+                if isinstance(ev, CommandResult):
+                    EvidenceRepository(session).save_command_result(task_id, ev)
+                elif isinstance(ev, DiffCoverageEvidence):
+                    EvidenceRepository(session).save_diff_coverage_evidence(ev)
+                elif isinstance(ev, DiffEvidence):
+                    EvidenceRepository(session).save_diff_evidence(ev)
+                elif isinstance(ev, TestEvidence):
+                    EvidenceRepository(session).save_test_evidence(ev, task_id)
+            task.status = "blocked" if any(g.blocking for g in gaps) else "verified"
+            task_repo.save(task)
+            blocking = [g.model_dump() for g in gaps if g.blocking]
+            # The typed next-actions contract: structured, routable steps the agent
+            # can act on to self-repair and re-verify without a human pasting prose.
+            # blocking_actions must be cleared to pass; advisory_actions (e.g. the
+            # diff↔coverage "tests passed but new code never ran" signal) are quality
+            # signals the agent can act on without confusing them with the gate.
+            blocking_actions, advisory_actions = split_next_actions(gaps)
+            outcome = verifier.last_outcome
+            return _json_text({
+                "ok": True,
+                "task_id": task_id,
+                "status": task.status,
+                "sandbox": sandbox,
+                "blocking_gaps": blocking,
+                "next_actions": [a.model_dump() for a in blocking_actions],
+                "advisory_actions": [a.model_dump() for a in advisory_actions],
+                # Computed from the post-verify status: verified -> release only,
+                # blocked -> the read/edit/test repair loop.
+                "allowed_next_tools": _allowed_next_tools(task.status, len(blocking) > 0),
+                "passed": len(blocking) == 0,
+                # Rigor of this run so the agent never reads passed==True as proven
+                # when the gate could not actually check.
+                "verification_mode": outcome.mode if outcome else "unknown",
+                "compiler_active": outcome.compiler_active if outcome else False,
+                "diff_empty": outcome.diff_empty if outcome else False,
+                "coverage_measured": outcome.coverage_measured if outcome else False,
+                "coverage_skipped_reason": outcome.coverage_skipped_reason if outcome else None,
+            })
+
+    elif name == "devcouncil_handoff_agent":
+        assert db is not None
+        task_id, arg_error = _required_string_argument(arguments, "task_id")
+        if arg_error:
+            return arg_error
+        lease_token, arg_error = _required_string_argument(arguments, "lease_token")
+        if arg_error:
+            return arg_error
+        from_agent, arg_error = _required_string_argument(arguments, "from_agent")
+        if arg_error:
+            return arg_error
+        to_agent, arg_error = _required_string_argument(arguments, "to_agent")
+        if arg_error:
+            return arg_error
+        assert task_id is not None and lease_token is not None
+        with db.get_session() as session:
+            if not TaskLeaseRepository(session).validate(task_id, lease_token):
+                return _error_text("Invalid lease token.", code="invalid_lease", task_id=task_id)
+        try:
+            from devcouncil.execution.handoff import HandoffService
+
+            manifest, handoff_path, run_id = HandoffService(root).create(
+                task_id,
+                from_agent or "",
+                to_agent or "",
+                instruction=str(arguments.get("instruction") or ""),
+            )
+            return _json_text({
+                "ok": True,
+                "task_id": task_id,
+                "manifest_path": str(handoff_path),
+                "run_id": run_id,
+                "manifest": manifest.model_dump(),
+            })
+        except ValueError as exc:
+            return _error_text(str(exc), code="handoff_failed", task_id=task_id)
+
+    elif name == "devcouncil_read_file":
+        rel_path, arg_error = _required_string_argument(arguments, "path")
+        if arg_error:
+            return arg_error
+        assert rel_path is not None
+        if _is_secret_path(root, rel_path):
+            return _error_text(
+                "Refusing to read a secret/credential path.",
+                code="secret_path", path=rel_path,
+            )
+        target = _within_root(root, rel_path)
+        if target is None:
+            return _error_text("path escapes the project root", code="path_escape", path=rel_path)
+        if not target.exists() or not target.is_file():
+            return _error_text(f"File not found: {rel_path}", code="not_found", path=rel_path)
+        try:
+            raw = target.read_bytes()
+        except OSError as exc:
+            return _error_text(f"Read failed: {exc}", code="read_failed", path=rel_path)
+        sha256 = hashlib.sha256(raw).hexdigest()
+        text = raw.decode("utf-8", errors="replace")
+        all_lines = text.splitlines()
+        line_count = len(all_lines)
+        # Optional windowing: line_range ('10-40', 1-based inclusive) wins over offset/limit.
+        line_range = _optional_string_argument(arguments, "line_range")
+        if line_range == "":
+            return _error_text("line_range must be a string", code="invalid_arguments", argument="line_range")
+        selected = all_lines
+        if line_range:
+            try:
+                start_str, _, end_str = line_range.partition("-")
+                start = max(1, int(start_str))
+                end = int(end_str) if end_str else line_count
+            except ValueError:
+                return _error_text("line_range must look like '10-40'", code="invalid_arguments", argument="line_range")
+            selected = all_lines[start - 1:end]
+        else:
+            offset = _int_argument(arguments, "offset", 0, minimum=0, maximum=10_000_000)
+            limit_value = arguments.get("limit")
+            if isinstance(limit_value, int) and not isinstance(limit_value, bool):
+                limit = max(1, limit_value)
+                selected = all_lines[offset:offset + limit]
+            elif offset:
+                selected = all_lines[offset:]
+        windowed = "\n".join(selected)
+        content, truncated = _truncate_text(windowed)
+        return _json_text({
+            "ok": True,
+            "path": rel_path.replace("\\", "/"),
+            "content": content,
+            "sha256": sha256,
+            "line_count": line_count,
+            "truncated": truncated,
+        })
+
+    elif name == "devcouncil_get_diff":
+        if not _is_git_repo(root):
+            return _error_text("get_diff requires a git repository.", code="not_a_git_repo")
+        task_id = _optional_string_argument(arguments, "task_id")
+        if task_id == "":
+            return _error_text("task_id must be a string", code="invalid_arguments", argument="task_id")
+        explicit_paths, arg_error = _optional_string_list_argument(arguments, "paths")
+        if arg_error:
+            return arg_error
+        staged_value = arguments.get("staged", False)
+        if not isinstance(staged_value, bool):
+            return _error_text("staged must be a boolean", code="invalid_arguments", argument="staged")
+        scope_paths: list[str] = list(explicit_paths)
+        if task_id and db:
+            with db.get_session() as session:
+                task = TaskRepository(session).get_by_id(task_id)
+            if task is None:
+                return _error_text(f"Task {task_id} not found.", code="not_found", task_id=task_id)
+            for planned in task.planned_files:
+                p = planned.path.replace("\\", "/")
+                if p not in scope_paths:
+                    scope_paths.append(p)
+        return _json_text(await _git_diff(root, scope_paths, staged_value))
+
+    elif name == "devcouncil_get_evidence":
+        assert db is not None
+        task_id, arg_error = _required_string_argument(arguments, "task_id")
+        if arg_error:
+            return arg_error
+        assert task_id is not None
+        command_filter = _optional_string_argument(arguments, "command")
+        if command_filter == "":
+            return _error_text("command must be a string", code="invalid_arguments", argument="command")
+        limit = _int_argument(arguments, "limit", 20, minimum=1, maximum=100)
+        with db.get_session() as session:
+            results = EvidenceRepository(session).get_command_results_for_task(task_id)
+        evidence_rows: list[dict[str, object]] = []
+        for result in results:
+            if command_filter and command_filter not in result.command:
+                continue
+            stdout, stdout_truncated = _truncate_text(_read_log_file(result.stdout_path))
+            stderr, stderr_truncated = _truncate_text(_read_log_file(result.stderr_path))
+            evidence_rows.append({
+                "command": result.command,
+                "exit_code": result.exit_code,
+                "summary": result.summary,
+                "stdout": stdout,
+                "stderr": stderr,
+                "truncated": stdout_truncated or stderr_truncated,
+            })
+            if len(evidence_rows) >= limit:
+                break
+        return _json_text({"ok": True, "task_id": task_id, "evidence": evidence_rows})
+
+    elif name == "devcouncil_run_command":
+        assert db is not None
+        task_id, arg_error = _required_string_argument(arguments, "task_id")
+        if arg_error:
+            return arg_error
+        lease_token, arg_error = _required_string_argument(arguments, "lease_token")
+        if arg_error:
+            return arg_error
+        command, arg_error = _required_string_argument(arguments, "command")
+        if arg_error:
+            return arg_error
+        assert task_id is not None and lease_token is not None and command is not None
+        normalized = " ".join(command.split())
+        with db.get_session() as session:
+            if not TaskLeaseRepository(session).validate(task_id, lease_token):
+                return _error_text("Invalid lease token.", code="invalid_lease", task_id=task_id)
+            task = TaskRepository(session).get_by_id(task_id)
+            if not task:
+                return _error_text(f"Task {task_id} not found.", code="not_found", task_id=task_id)
+            from devcouncil.execution.policy_engine import TaskPolicyEngine
+
+            policy_decision = TaskPolicyEngine(root).evaluate_command(normalized, task)
+            if policy_decision.action == "deny":
+                # Record nothing executed; the gate refused before any side effect.
+                ShellCommandRepository(session).record(
+                    task_id, normalized, "blocked", reason=policy_decision.reason,
+                )
+                return _error_text(
+                    policy_decision.reason or "Command is not in the task allowlist.",
+                    code="command_not_allowed", task_id=task_id, command=normalized,
+                )
+            try:
+                import shlex
+
+                args = shlex.split(normalized, posix=(os.name != "nt"))
+                completed = subprocess.run(
+                    args,
+                    cwd=root,
+                    capture_output=True,
+                    text=True,
+                    encoding="utf-8",
+                    errors="replace",
+                    env=clean_subprocess_env(),
+                    timeout=_CLI_TIMEOUT_SECONDS,
+                )
+                exit_code = completed.returncode
+                stdout, stdout_truncated = _truncate_text(completed.stdout)
+                stderr, stderr_truncated = _truncate_text(completed.stderr)
+                timed_out = False
+            except subprocess.TimeoutExpired as exc:
+                exit_code = None
+                stdout, stdout_truncated = _truncate_text(exc.output)
+                stderr, stderr_truncated = _truncate_text(exc.stderr)
+                timed_out = True
+            except (FileNotFoundError, OSError, ValueError) as exc:
+                ShellCommandRepository(session).record(
+                    task_id, normalized, "failed", reason=str(exc),
+                )
+                return _error_text(f"Could not run command: {exc}", code="run_failed", task_id=task_id)
+            ShellCommandRepository(session).record(
+                task_id,
+                normalized,
+                "finished" if exit_code == 0 else "failed",
+                exit_code=exit_code,
+            )
+            return _json_text({
+                "ok": exit_code == 0,
+                "task_id": task_id,
+                "exit_code": exit_code,
+                "stdout": stdout,
+                "stderr": stderr,
+                "truncated": stdout_truncated or stderr_truncated,
+                "timed_out": timed_out,
+            })
+
+    elif name == "devcouncil_next_task":
+        assert db is not None
+        status_filter = _optional_string_argument(arguments, "status")
+        if status_filter == "":
+            return _error_text("status must be a string", code="invalid_arguments", argument="status")
+        client_id = _optional_string_argument(arguments, "client_id")
+        if client_id == "":
+            return _error_text("client_id must be a string", code="invalid_arguments", argument="client_id")
+        with db.get_session() as session:
+            tasks = TaskRepository(session).get_all()
+            leased_task_ids = {
+                lease.task_id
+                for lease, expired in TaskLeaseRepository(session).list_leases(active_only=True)
+                if not expired
+            }
+            blocking_by_task: dict[str, int] = {}
+            for gap in GapRepository(session).get_all():
+                if gap.blocking and gap.task_id:
+                    blocking_by_task[gap.task_id] = blocking_by_task.get(gap.task_id, 0) + 1
+        done_ids = {t.id for t in tasks if t.status in {"verified", "done"}}
+        # Candidate set: not finished, not actively leased, deps satisfied, matching the
+        # optional status filter (default to planned/ready bootstrap states).
+        wanted_statuses = {status_filter} if status_filter else {"planned", "ready"}
+        candidates = []
+        for task in tasks:
+            if task.status not in wanted_statuses:
+                continue
+            if task.id in leased_task_ids:
+                continue
+            if any(dep not in done_ids for dep in task.depends_on):
+                continue
+            candidates.append(task)
+        if not candidates:
+            return _json_text({
+                "ok": True,
+                "task": None,
+                "reason": "No unblocked, unleased task is available.",
+            })
+        # Deterministic "highest priority": fewest unmet deps, then task id order, so the
+        # same task is chosen on every call (no race with list_tasks ordering).
+        candidates.sort(key=lambda t: (len(t.depends_on), t.id))
+        chosen = candidates[0]
+        blocking_count = blocking_by_task.get(chosen.id, 0)
+        return _json_text({
+            "ok": True,
+            "task": chosen.model_dump(),
+            "blocking_gap_count": blocking_count,
+            "ready_to_checkout": blocking_count == 0,
+            "allowed_next_tools": _allowed_next_tools(chosen.status, blocking_count > 0),
+        })
+
+    elif name == "devcouncil_list_agent_runs":
+        from devcouncil.cli.commands.runs import _collect_runs, _orphan_after_seconds
+
+        status_filter = _optional_string_argument(arguments, "status")
+        if status_filter == "":
+            return _error_text("status must be a string", code="invalid_arguments", argument="status")
+        limit = _int_argument(arguments, "limit", 20, minimum=1, maximum=500)
+        run_rows = _collect_runs(root, orphan_after=_orphan_after_seconds(root))
+        if status_filter:
+            run_rows = [row for row in run_rows if row.get("status") == status_filter]
+        total = len(run_rows)
+        run_window = run_rows[:limit]
+        return _json_text({"ok": True, "runs": run_window, "total": total, "returned": len(run_window)})
+
+    elif name == "devcouncil_get_run":
+        from devcouncil.cli.commands.runs import (
+            _find_transcript,
+            _is_orphaned,
+            _load_manifest,
+            _orphan_after_seconds,
+            _runs_dir,
+            _transcript_tail,
+        )
+        import time as _time
+
+        target_run_id, arg_error = _required_string_argument(arguments, "run_id")
+        if arg_error:
+            return arg_error
+        assert target_run_id is not None
+        run_dir = _runs_dir(root) / target_run_id
+        manifest_path = run_dir / "agent-run.json"
+        run_manifest = _load_manifest(manifest_path)
+        if run_manifest is None:
+            return _error_text(f"Run {target_run_id} not found.", code="not_found", run_id=target_run_id)
+        orphaned = _is_orphaned(
+            run_manifest, manifest_path, orphan_after=_orphan_after_seconds(root), now=_time.time()
+        )
+        transcript_path = _find_transcript(run_dir, run_manifest)
+        transcript_tail = _transcript_tail(transcript_path) if transcript_path else ""
+        tail, truncated = _truncate_text(transcript_tail)
+        return _json_text({
+            "ok": True,
+            "run_id": target_run_id,
+            "manifest": run_manifest,
+            "orphaned": orphaned,
+            "transcript_path": str(transcript_path) if transcript_path else None,
+            "transcript_tail": tail,
+            "transcript_truncated": truncated,
+        })
+
+    elif name == "devcouncil_select_knowledge":
+        # No DB needed: knowledge lives on disk. Best-effort — a knowledge failure
+        # degrades to an empty preamble rather than crashing the server.
+        goal, arg_error = _required_string_argument(arguments, "goal")
+        if arg_error:
+            return arg_error
+        assert goal is not None
+        try:
+            from devcouncil.knowledge.sources import (
+                render_knowledge_preamble,
+                select_knowledge_sources,
+            )
+
+            # Honor the project's knowledge config so MCP selection matches the prompts.
+            directory, design_always = _knowledge_settings(root)
+            if directory is None:  # explicitly disabled
+                sources = []
+            else:
+                sources = select_knowledge_sources(
+                    goal, root, directory=directory, design_always=design_always
+                )
+            preamble = render_knowledge_preamble(sources)
+            return _json_text({
+                "ok": True,
+                "goal": goal,
+                "sources": [
+                    {"name": s.name, "kind": s.kind, "description": s.description}
+                    for s in sources
+                ],
+                "preamble": preamble,
+            })
+        except Exception as exc:
+            return _json_text({
+                "ok": True,
+                "goal": goal,
+                "sources": [],
+                "preamble": "",
+                "note": f"knowledge unavailable: {exc}",
+            })
+
+    logger.warning("MCP unknown tool requested: %s", name)
     return _error_text(f"Unknown tool: {name}", code="unknown_tool", tool=name)
 
 async def run():