devcouncil 0.3.1 → 0.4.1

package/src/devcouncil/integrations/mcp/handlers/debug.py

@@ -0,0 +1,236 @@
+"""Registry-backed MCP debugger and runtime-trace tools."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Awaitable, Callable
+
+from mcp.types import TextContent, Tool
+
+from devcouncil.codeintel.debug.consent import require_debug_consent, set_debug_consent
+from devcouncil.codeintel.debug.discovery import adapter_by_id, discover_adapters
+from devcouncil.codeintel.debug.session import get_debug_manager
+from devcouncil.codeintel.debug.tracing import NodeCpuProfileProvider, PythonTraceProvider, import_runtime_trace
+from devcouncil.codeintel.service import canonical_project_root
+from devcouncil.integrations.mcp.util import error_text, json_text
+
+Handler = Callable[[Path, dict], Awaitable[list[TextContent]]]
+
+
+def _schema(properties: dict, required: list[str] | None = None) -> dict:
+    schema: dict = {"type": "object", "properties": {
+        "projectPath": {"type": "string", "description": "Explicit repository path."},
+        **properties,
+    }}
+    if required:
+        schema["required"] = required
+    return schema
+
+
+def tools() -> list[Tool]:
+    return [
+        Tool(
+            name="devcouncil_debug_discover",
+            description=(
+                "Discover installed DAP adapters after explicit one-time consent; "
+                "returns paths, versions, hashes, and launch/attach support."
+            ),
+            inputSchema=_schema({"consent": {"type": "boolean", "default": False}}),
+        ),
+        Tool(
+            name="devcouncil_debug_start",
+            description="Launch or attach a capability-negotiated DAP session.",
+            inputSchema=_schema({
+                "adapterId": {"type": "string"},
+                "adapterCommand": {"type": "array", "items": {"type": "string"}},
+                "request": {"type": "string", "enum": ["launch", "attach"], "default": "launch"},
+                "configuration": {"type": "object"},
+                "initialBreakpoints": {
+                    "type": "object",
+                    "additionalProperties": {"type": "array", "items": {"type": "integer"}},
+                },
+                "timeout": {"type": "number", "minimum": 1, "maximum": 120, "default": 30},
+            }),
+        ),
+        Tool(
+            name="devcouncil_debug_breakpoints",
+            description="Replace all breakpoints for one source in a DAP session.",
+            inputSchema=_schema({
+                "sessionId": {"type": "string"},
+                "source": {"type": "string"},
+                "lines": {"type": "array", "items": {"type": "integer"}},
+            }, ["sessionId", "source", "lines"]),
+        ),
+        Tool(
+            name="devcouncil_debug_control",
+            description="Continue, pause, or step a DAP session.",
+            inputSchema=_schema({
+                "sessionId": {"type": "string"},
+                "action": {"type": "string", "enum": ["continue", "pause", "next", "stepIn", "stepOut"]},
+                "threadId": {"type": "integer"},
+            }, ["sessionId", "action"]),
+        ),
+        Tool(
+            name="devcouncil_debug_inspect",
+            description="Inspect threads, stack frames, scopes, variables, source, or disassembly.",
+            inputSchema=_schema({
+                "sessionId": {"type": "string"},
+                "operation": {"type": "string", "enum": ["threads", "stackTrace", "scopes", "variables", "source", "disassemble"]},
+                "arguments": {"type": "object"},
+            }, ["sessionId", "operation"]),
+        ),
+        Tool(
+            name="devcouncil_debug_evaluate",
+            description="Side-effectful DAP evaluate; allowSideEffects must be explicitly true.",
+            inputSchema=_schema({
+                "sessionId": {"type": "string"},
+                "expression": {"type": "string"},
+                "frameId": {"type": "integer"},
+                "allowSideEffects": {"type": "boolean", "const": True},
+            }, ["sessionId", "expression", "allowSideEffects"]),
+        ),
+        Tool(
+            name="devcouncil_debug_trace",
+            description="Capture a DAP stack, run exact Python tracing, or import JSONL/Node CPU profile evidence.",
+            inputSchema=_schema({
+                "provider": {"type": "string", "enum": ["dap-stack", "python", "node", "import"]},
+                "sessionId": {"type": "string"},
+                "threadId": {"type": "integer"},
+                "script": {"type": "string"},
+                "args": {"type": "array", "items": {"type": "string"}},
+                "path": {"type": "string"},
+            }, ["provider"]),
+        ),
+        Tool(
+            name="devcouncil_debug_stop",
+            description="Disconnect a DAP session and optionally leave the debuggee running.",
+            inputSchema=_schema({
+                "sessionId": {"type": "string"},
+                "terminateDebuggee": {"type": "boolean", "default": True},
+            }, ["sessionId"]),
+        ),
+    ]
+
+
+async def _discover(root: Path, arguments: dict) -> list[TextContent]:
+    if arguments.get("consent") is True:
+        set_debug_consent(root, True)
+    require_debug_consent(root)
+    return json_text({"consent": True, "adapters": [adapter.as_dict() for adapter in discover_adapters()]})
+
+
+def _command(arguments: dict) -> list[str]:
+    supplied = arguments.get("adapterCommand")
+    if isinstance(supplied, list) and supplied:
+        return [str(value) for value in supplied]
+    adapter_id = str(arguments.get("adapterId") or "debugpy")
+    adapter = adapter_by_id(adapter_id)
+    if adapter is None:
+        raise ValueError(f"adapter {adapter_id!r} was not discovered")
+    return list(adapter.command)
+
+
+async def _start(root: Path, arguments: dict) -> list[TextContent]:
+    require_debug_consent(root)
+    session = get_debug_manager().start(
+        root,
+        _command(arguments),
+        request=str(arguments.get("request", "launch")),
+        arguments=dict(arguments.get("configuration") or {}),
+        initial_breakpoints={
+            str(source): [int(line) for line in lines]
+            for source, lines in dict(arguments.get("initialBreakpoints") or {}).items()
+        },
+        timeout=float(arguments.get("timeout", 30.0)),
+    )
+    return json_text(session.as_dict())
+
+
+async def _breakpoints(root: Path, arguments: dict) -> list[TextContent]:
+    require_debug_consent(root)
+    return json_text(get_debug_manager().set_breakpoints(
+        str(arguments["sessionId"]), str(arguments["source"]), [int(value) for value in arguments["lines"]]
+    ))
+
+
+async def _control(root: Path, arguments: dict) -> list[TextContent]:
+    require_debug_consent(root)
+    return json_text(get_debug_manager().control(
+        str(arguments["sessionId"]),
+        str(arguments["action"]),
+        thread_id=int(arguments["threadId"]) if arguments.get("threadId") is not None else None,
+    ))
+
+
+async def _inspect(root: Path, arguments: dict) -> list[TextContent]:
+    require_debug_consent(root)
+    return json_text(get_debug_manager().inspect(
+        str(arguments["sessionId"]), str(arguments["operation"]), dict(arguments.get("arguments") or {})
+    ))
+
+
+async def _evaluate(root: Path, arguments: dict) -> list[TextContent]:
+    require_debug_consent(root)
+    if arguments.get("allowSideEffects") is not True:
+        raise PermissionError("debug evaluate requires allowSideEffects=true")
+    return json_text(get_debug_manager().evaluate(
+        str(arguments["sessionId"]),
+        str(arguments["expression"]),
+        frame_id=int(arguments["frameId"]) if arguments.get("frameId") is not None else None,
+        allow_side_effects=True,
+    ))
+
+
+async def _trace(root: Path, arguments: dict) -> list[TextContent]:
+    require_debug_consent(root)
+    provider = str(arguments["provider"])
+    if provider == "dap-stack":
+        return json_text(get_debug_manager().capture_stack(
+            str(arguments["sessionId"]), thread_id=int(arguments["threadId"])
+        ))
+    if provider == "python":
+        return json_text(PythonTraceProvider(root).run(
+            Path(str(arguments["script"])), [str(value) for value in arguments.get("args") or []]
+        ))
+    if provider == "node":
+        return json_text(NodeCpuProfileProvider(root).run(
+            Path(str(arguments["script"])), [str(value) for value in arguments.get("args") or []]
+        ))
+    if provider == "import":
+        return json_text(import_runtime_trace(root, Path(str(arguments["path"]))))
+    raise ValueError(f"unsupported trace provider: {provider}")
+
+
+async def _stop(root: Path, arguments: dict) -> list[TextContent]:
+    require_debug_consent(root)
+    session_id = str(arguments["sessionId"])
+    get_debug_manager().stop(session_id, terminate_debuggee=bool(arguments.get("terminateDebuggee", True)))
+    return json_text({"stopped": session_id})
+
+
+REGISTRY: dict[str, Handler] = {
+    "devcouncil_debug_discover": _discover,
+    "devcouncil_debug_start": _start,
+    "devcouncil_debug_breakpoints": _breakpoints,
+    "devcouncil_debug_control": _control,
+    "devcouncil_debug_inspect": _inspect,
+    "devcouncil_debug_evaluate": _evaluate,
+    "devcouncil_debug_trace": _trace,
+    "devcouncil_debug_stop": _stop,
+}
+
+
+async def dispatch(name: str, default_root: Path, arguments: dict) -> list[TextContent] | None:
+    handler = REGISTRY.get(name)
+    if handler is None:
+        return None
+    explicit = arguments.get("projectPath")
+    root = canonical_project_root(Path(explicit) if isinstance(explicit, str) and explicit else default_root)
+    try:
+        return await handler(root, arguments)
+    except PermissionError as exc:
+        return error_text(str(exc), code="debug_consent_required", tool=name)
+    except FileNotFoundError as exc:
+        return error_text(str(exc), code="not_found", tool=name)
+    except (KeyError, TypeError, ValueError, RuntimeError, TimeoutError) as exc:
+        return error_text(str(exc), code="debug_error", tool=name)

package/src/devcouncil/integrations/mcp/handlers/evidence.py

@@ -0,0 +1,70 @@
+"""Evidence read/write MCP tool handlers."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from mcp.types import TextContent
+
+from devcouncil.integrations.mcp.util import (
+    error_text,
+    int_argument,
+    json_text,
+    optional_string_argument,
+    parse_cli_json,
+    required_string_argument,
+    run_cli_command,
+)
+
+
+async def handle_append_evidence(root: Path, db: object, arguments: dict) -> list[TextContent]:
+    del db  # routed through CLI service layer
+    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")
+    cli_args = [
+        "evidence-append", task_id,
+        "--lease-token", lease_token,
+        "--command", command or "",
+        "--summary", summary_text or "",
+        "--exit-code", str(exit_code),
+        "--json",
+    ]
+    payload, cli_error = parse_cli_json(run_cli_command(cli_args, root))
+    if cli_error:
+        return cli_error
+    assert payload is not None
+    return json_text(payload)
+
+
+async def handle_get_evidence(root: Path, db: object, arguments: dict) -> list[TextContent]:
+    del db  # routed through CLI service layer
+    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)
+    cli_args = ["evidence-list", task_id, "--limit", str(limit), "--json"]
+    if command_filter:
+        cli_args.extend(["--command", command_filter])
+    payload, cli_error = parse_cli_json(run_cli_command(cli_args, root))
+    if cli_error:
+        return cli_error
+    assert payload is not None
+    return json_text(payload)

package/src/devcouncil/integrations/mcp/handlers/git.py

@@ -0,0 +1,281 @@
+"""Git diff MCP tool handlers."""
+
+from __future__ import annotations
+
+import asyncio
+import subprocess
+from pathlib import Path
+
+from mcp.types import TextContent
+
+from devcouncil.integrations.mcp.util import (
+    CLI_TIMEOUT_SECONDS,
+    error_text,
+    is_git_repo,
+    json_text,
+    optional_string_argument,
+    optional_string_list_argument,
+    truncate_text,
+)
+from devcouncil.storage.db import Database
+from devcouncil.storage.repositories import TaskRepository
+
+_BINARY_PROBE_BYTES = 8192
+
+
+def _run_git(root: Path, 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,
+    )
+
+
+def _parse_name_status_z(data: str) -> dict[str, str]:
+    """Parse ``git diff --name-status -z`` into ``{path: status}``.
+
+    Rename/copy records are ``STATUS\\0OLD\\0NEW\\0``; other records are
+    ``STATUS\\0PATH\\0``. The new path is the authoritative key for renames.
+    """
+    status_by_path: dict[str, str] = {}
+    parts = data.split("\0")
+    i = 0
+    while i < len(parts):
+        status = parts[i]
+        if not status:
+            i += 1
+            continue
+        kind = status[0]
+        if kind in "RC" and i + 2 < len(parts):
+            new_path = parts[i + 2].replace("\\", "/")
+            if new_path:
+                status_by_path[new_path] = status
+            i += 3
+            continue
+        if i + 1 < len(parts):
+            path = parts[i + 1].replace("\\", "/")
+            if path:
+                status_by_path[path] = status
+            i += 2
+            continue
+        break
+    return status_by_path
+
+
+def _format_untracked_file_diff(rel_path: str, full_path: Path) -> tuple[str, int]:
+    """Return ``(unified_diff_fragment, addition_count)`` for a new untracked file."""
+    try:
+        raw = full_path.read_bytes()
+    except OSError:
+        return "", 0
+
+    header = [
+        f"diff --git a/{rel_path} b/{rel_path}",
+        "new file mode 100644",
+        "--- /dev/null",
+        f"+++ b/{rel_path}",
+    ]
+    if b"\0" in raw[:_BINARY_PROBE_BYTES]:
+        return "\n".join([*header, f"Binary files /dev/null and b/{rel_path} differ"]), 0
+
+    text = raw.decode("utf-8", errors="replace")
+    if not text:
+        return "\n".join(header) + "\n", 0
+
+    lines = text.splitlines()
+    if text.endswith(("\n", "\r")):
+        line_count = len(lines)
+    else:
+        line_count = max(len(lines), 1)
+
+    diff_lines = [*header, f"@@ -0,0 +1,{line_count} @@"]
+    diff_lines.extend(f"+{line}" for line in lines)
+    return "\n".join(diff_lines), line_count
+
+
+def _list_untracked(root: Path, paths: list[str]) -> tuple[list[str], str | None]:
+    """List untracked paths; return ``(paths, error)`` when the Git call fails."""
+    args = ["git", "ls-files", "--others", "--exclude-standard", "-z"]
+    if paths:
+        args.append("--")
+        args.extend(paths)
+    try:
+        proc = _run_git(root, args)
+    except (OSError, subprocess.TimeoutExpired) as exc:
+        return [], str(exc)
+    if proc.returncode != 0:
+        detail = (proc.stderr or proc.stdout or f"git ls-files exited {proc.returncode}").strip()
+        return [], detail or f"git ls-files exited {proc.returncode}"
+    return [p.replace("\\", "/") for p in proc.stdout.split("\0") if p.strip()], None
+
+
+def _collect_untracked(
+    root: Path,
+    paths: list[str],
+    *,
+    known_paths: set[str],
+) -> tuple[list[dict[str, object]], str, str | None]:
+    """Build file entries and unified diff for untracked files in scope."""
+    untracked, err = _list_untracked(root, paths)
+    if err is not None:
+        return [], "", err
+
+    files: list[dict[str, object]] = []
+    fragments: list[str] = []
+    for rel in untracked:
+        if rel in known_paths:
+            continue
+        full = root / rel
+        if not full.is_file():
+            continue
+        fragment, additions = _format_untracked_file_diff(rel, full)
+        if not fragment:
+            continue
+        files.append({
+            "path": rel,
+            "status": "A",
+            "additions": additions,
+            "deletions": 0,
+        })
+        fragments.append(fragment.rstrip("\n"))
+    unified = "\n".join(fragments)
+    if unified:
+        unified += "\n"
+    return files, unified, None
+
+
+async def git_diff(root: Path, paths: list[str], staged: bool) -> dict[str, object]:
+    """Compute a (optionally path-scoped, optionally staged) git diff."""
+    diff_args = ["git", "diff"]
+    numstat_args = ["git", "diff", "--numstat"]
+    namestatus_args = ["git", "diff", "--name-status", "-z"]
+    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 _run_git(root, args)
+
+    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)}
+
+    for proc, label in (
+        (diff_proc, "git diff"),
+        (numstat_proc, "git diff --numstat"),
+        (namestatus_proc, "git diff --name-status"),
+    ):
+        if proc.returncode != 0:
+            detail = (proc.stderr or proc.stdout or f"{label} exited {proc.returncode}").strip()
+            return {
+                "ok": False,
+                "files": [],
+                "unified_diff": "",
+                "truncated": False,
+                "error": detail or f"{label} exited {proc.returncode}",
+                "staged": staged,
+            }
+
+    status_by_path = _parse_name_status_z(namestatus_proc.stdout)
+
+    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]
+        # Rename numstat without -z may use "old => new"; prefer the new side.
+        if " => " in file_path:
+            file_path = file_path.split(" => ", 1)[-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_parts = [diff_proc.stdout.rstrip("\n")] if diff_proc.stdout else []
+    if not staged:
+        known = {str(entry["path"]) for entry in files}
+        untracked_files, untracked_diff, untracked_err = await asyncio.get_event_loop().run_in_executor(
+            None,
+            lambda: _collect_untracked(root, paths, known_paths=known),
+        )
+        if untracked_err is not None:
+            return {
+                "ok": False,
+                "files": [],
+                "unified_diff": "",
+                "truncated": False,
+                "error": untracked_err,
+                "staged": staged,
+            }
+        files.extend(untracked_files)
+        if untracked_diff:
+            unified_parts.append(untracked_diff.rstrip("\n"))
+
+    combined = "\n".join(part for part in unified_parts if part)
+    if combined:
+        combined += "\n"
+    unified_diff, truncated = truncate_text(combined)
+    return {"ok": True, "files": files, "unified_diff": unified_diff, "truncated": truncated, "staged": staged}
+
+
+def _empty_diff_payload(staged: bool) -> dict[str, object]:
+    return {"ok": True, "files": [], "unified_diff": "", "truncated": False, "staged": staged}
+
+
+async def handle_get_diff(root: Path, db: Database | None, arguments: dict) -> list[TextContent]:
+    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] = [p.replace("\\", "/") for p in explicit_paths]
+    task_scoped = False
+    if task_id:
+        if db is None:
+            return error_text(
+                "DevCouncil not initialized in this directory.",
+                code="not_initialized",
+            )
+        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)
+        planned = [pf.path.replace("\\", "/") for pf in task.planned_files]
+        planned_set = set(planned)
+        task_scoped = True
+        if explicit_paths:
+            # Intersect only — explicit paths must never broaden task scope.
+            scope_paths = [p for p in scope_paths if p in planned_set]
+        else:
+            scope_paths = planned
+
+    if task_scoped and not scope_paths:
+        # Empty planned scope or empty intersection: fail closed to empty, never full repo.
+        return json_text(_empty_diff_payload(staged_value))
+
+    return json_text(await git_diff(root, scope_paths, staged_value))

package/src/devcouncil/integrations/mcp/handlers/graph.py

@@ -0,0 +1,34 @@
+"""Code-review graph context MCP tool handlers."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from mcp.types import TextContent
+
+from devcouncil.integrations.mcp.util import (
+    json_text,
+    parse_cli_json,
+    run_cli_command,
+)
+
+
+async def handle_graph_context(root: Path, arguments: dict) -> list[TextContent]:
+    files = arguments.get("files", [])
+    if not isinstance(files, list):
+        files = []
+    file_args: list[str] = []
+    for item in files:
+        if isinstance(item, str) and item:
+            file_args.extend(["--file", item])
+    payload, _cli_error = parse_cli_json(
+        run_cli_command(["graph-context", "--json", *file_args], root, truncate=False),
+    )
+    if payload is not None:
+        return json_text(payload)
+    from devcouncil.integrations.code_review_graph import CodeReviewGraphAdapter
+
+    context = CodeReviewGraphAdapter(root).get_context(
+        [file for file in files if isinstance(file, str)]
+    )
+    return [TextContent(type="text", text=context.model_dump_json(indent=2))]

package/src/devcouncil/integrations/mcp/handlers/handoff.py

@@ -0,0 +1,53 @@
+"""Agent handoff MCP tool handler."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from mcp.types import TextContent
+
+from devcouncil.integrations.mcp.util import (
+    json_text,
+    parse_cli_json,
+    required_string_argument,
+    run_cli_command,
+)
+
+
+async def handle_handoff_agent(root: Path, db: object, arguments: dict) -> list[TextContent]:
+    del db  # routed through CLI service layer
+    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
+    cli_args = [
+        "handoff-leased", task_id,
+        "--lease-token", lease_token,
+        "--from", from_agent or "",
+        "--to", to_agent or "",
+        "--json",
+    ]
+    instruction = str(arguments.get("instruction") or "")
+    if instruction:
+        cli_args.extend(["--instruction", instruction])
+    payload, cli_error = parse_cli_json(run_cli_command(cli_args, root))
+    if cli_error:
+        return cli_error
+    assert payload is not None
+    if not payload.get("ok"):
+        from devcouncil.integrations.mcp.util import error_text
+        return error_text(
+            str(payload.get("error") or "handoff failed"),
+            code=str(payload.get("code") or "handoff_failed"),
+            task_id=task_id,
+        )
+    return json_text(payload)