devcouncil 0.3.0 → 0.4.0

package/src/devcouncil/executors/coding_cli.py

@@ -10,16 +10,26 @@ import time
 import uuid
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import Optional
+from typing import Any, Callable, Optional
 
 from rich.console import Console
 
 from devcouncil.domain.requirement import Requirement
 from devcouncil.domain.task import Task
 from devcouncil.app.config import DevCouncilConfig, load_config
+from devcouncil.utils.json_persist import read_json, write_json
 from devcouncil.execution.executor import Executor, ExecutionResult
 from devcouncil.execution.prompt_builder import PromptBuilder
+from devcouncil.executors.advisor_tool import (
+    advisor_steering_text,
+    advisor_user_cost_trim,
+    claude_supports_append_system_prompt,
+    decide_advisor_attach,
+    strip_duplicate_advisor_args,
+    warn_advisor_preflight,
+)
 from devcouncil.executors.agent_registry import (
+    GEMINI_DEPRECATION_MESSAGE,
     VALID_INPUT_MODES,
     CliAgentSpec,
     get_cli_agent_spec,
@@ -29,6 +39,7 @@ from devcouncil.executors.agent_registry import (
 )
 from devcouncil.repo.gitignore import ensure_gitignore
 from devcouncil.telemetry.traces import TraceLogger
+from devcouncil.telemetry.stages import log_step
 from devcouncil.telemetry.logging_setup import run_log
 from devcouncil.utils.redaction import redact_text
 
@@ -64,11 +75,21 @@ class CodingCliExecutor(Executor):
             self._config = None
         self.client = self._normalize_client(client)
         self.timeout_seconds = timeout_seconds
+        if self.client == "gemini":
+            logger.warning(GEMINI_DEPRECATION_MESSAGE)
+            console.print(f"[yellow]{GEMINI_DEPRECATION_MESSAGE}[/yellow]")
         self.spec = self._resolve_spec()
         self.profile_name = profile or self.spec.default_profile or "default"
         self.profile = load_agent_profiles(project_root).get(self.profile_name)
         self.last_run_id: str | None = None
         self.last_transcript_path: Path | None = None
+        # Claude Code session id for the most recent run (assigned by DevCouncil via
+        # --session-id, or reused via --resume). Lets callers/live-review locate the
+        # native ~/.claude transcript for a headless run and resume it for repairs.
+        self.last_agent_session_id: str | None = None
+        self._pending_claude_session: tuple[Path, str] | None = None
+        # True when this run's argv includes ``--advisor`` (Claude only).
+        self._advisor_attached: bool = False
         self.stream_output = self._resolve_stream_output(stream_output)
 
     def _normalize_client(self, client: str) -> str:
@@ -95,6 +116,10 @@ class CodingCliExecutor(Executor):
             base = self._warp_command()
         elif self.client == "cursor":
             base = self._cursor_command(task_id)
+        elif self.client == "claude":
+            base = self._claude_command(task_id)
+        elif self.client == "grok":
+            base = self._grok_command(task_id)
         else:
             base = self.spec.base_command()
         return self._apply_profile_args(base)
@@ -106,6 +131,7 @@ class CodingCliExecutor(Executor):
         "codex": "--model",
         "gemini": "--model",
         "cursor": "--model",
+        "grok": "-m",
         "qwen": "--model",
         "opencode": "--model",
         "aider": "--model",
@@ -125,12 +151,57 @@ class CodingCliExecutor(Executor):
         result = list(command)
         result = self._apply_permission_mode(result)
         result = self._apply_model_override(result)
+        result = self._apply_advisor(result)
         # NOTE: extra_args are NOT appended here. For argument/prompt-file CLIs the prompt
         # (and sometimes its flag, e.g. warp --prompt / aider --message) is appended last
         # by _invocation; appending extra_args at the tail here would slot them between the
         # prompt flag and its value. _invocation places them correctly instead.
         return result
 
+    def _apply_advisor(self, command: list[str]) -> list[str]:
+        """Attach ``--advisor`` for Claude when the profile opts in and pairing looks safe.
+
+        Soft-skips clear bad main/advisor pairs and non-Anthropic provider envs so Claude
+        does not hard-exit and burn the go-loop repair budget. Non-Claude clients ignore
+        ``advisor_model``.
+        """
+        self._advisor_attached = False
+        if self.client != "claude" or not self.profile:
+            return command
+        advisor = (self.profile.advisor_model or "").strip()
+        if not advisor:
+            return command
+        # Prefer profile env overrides, then process env, for provider soft-skip.
+        env_for_decision: dict[str, str] = {**os.environ}
+        if self.profile.env:
+            env_for_decision.update({str(k): str(v) for k, v in self.profile.env.items()})
+        decision, resolved, reason = decide_advisor_attach(
+            main_model=self.profile.model,
+            advisor_model=advisor,
+            env=env_for_decision,
+        )
+        if decision != "attach" or not resolved:
+            if reason:
+                logger.warning(
+                    "Skipping --advisor %s for profile %s: %s",
+                    advisor,
+                    self.profile_name,
+                    reason,
+                )
+                console.print(
+                    f"[yellow]Skipping --advisor {advisor}: {reason}. "
+                    "Run continues without the advisor tool.[/yellow]"
+                )
+            return command
+        result = list(command)
+        for index, part in enumerate(result):
+            if part == "--advisor" and index + 1 < len(result):
+                result[index + 1] = resolved
+                self._advisor_attached = True
+                return result
+        self._advisor_attached = True
+        return [*result, "--advisor", resolved]
+
     def _apply_model_override(self, command: list[str]) -> list[str]:
         model = (self.profile.model or "").strip() if self.profile else ""
         if not model:
@@ -147,10 +218,27 @@ class CodingCliExecutor(Executor):
 
     def _apply_permission_mode(self, command: list[str]) -> list[str]:
         mode = (self.profile.permission_mode or "").strip() if self.profile else ""
+        if not mode and self.client == "cursor" and self._config is not None:
+            headless_force = self._config.integrations.cursor.headless_force
+            if headless_force is True:
+                return self._apply_cursor_permission_mode(command, "auto")
+            if headless_force is False:
+                return command
         if not mode:
             return command
+        if mode.lower() == "bypasspermissions":
+            logger.warning(
+                "Profile %r uses bypassPermissions — file edits bypass all CLI gates.",
+                self.profile_name,
+            )
         if self.client == "claude":
             return self._apply_claude_permission_mode(command, mode)
+        if self.client == "codex":
+            return self._apply_codex_permission_mode(command, mode)
+        if self.client == "grok":
+            return self._apply_grok_permission_mode(command, mode)
+        if self.client == "cursor":
+            return self._apply_cursor_permission_mode(command, mode)
         return command
 
     @staticmethod
@@ -174,6 +262,73 @@ class CodingCliExecutor(Executor):
                 return result
         return [*result, "--permission-mode", value]
 
+    @staticmethod
+    def _apply_codex_permission_mode(command: list[str], mode: str) -> list[str]:
+        """Translate DevCouncil profiles into current ``codex exec`` flags.
+
+        ``auto`` remains sandboxed to the workspace, ``plan`` is read-only, and
+        only an explicit bypass mode disables both approvals and the sandbox.
+        """
+        normalized = mode.lower()
+        result = list(command)
+        dangerous = "--dangerously-bypass-approvals-and-sandbox"
+        if normalized in {"bypasspermissions", "danger-full-access", "yolo"}:
+            if dangerous not in result:
+                result.append(dangerous)
+            return result
+
+        sandbox = {
+            "auto": "workspace-write",
+            "gated": "workspace-write",
+            "ask": "workspace-write",
+            "prod": "workspace-write",
+            "plan": "read-only",
+            "read-only": "read-only",
+            "workspace-write": "workspace-write",
+        }.get(normalized)
+        if sandbox is None:
+            return result
+        for index, part in enumerate(result):
+            if part in {"--sandbox", "-s"} and index + 1 < len(result):
+                result[index + 1] = sandbox
+                return result
+        return [*result, "--sandbox", sandbox]
+
+    @staticmethod
+    def _apply_grok_permission_mode(command: list[str], mode: str) -> list[str]:
+        """Translate an abstract permission mode into Grok Build's
+        ``--permission-mode`` value."""
+        translation = {
+            "auto": "acceptEdits",
+            "yolo": "acceptEdits",
+            "gated": "dontAsk",
+            "prod": "dontAsk",
+            "ask": "default",
+            "plan": "plan",
+        }
+        value = translation.get(mode.lower(), mode)
+        result = list(command)
+        for index, part in enumerate(result):
+            if part == "--permission-mode" and index + 1 < len(result):
+                result[index + 1] = value
+                return result
+        return [*result, "--permission-mode", value]
+
+    def _apply_cursor_permission_mode(self, command: list[str], mode: str) -> list[str]:
+        """Map profile permission modes to Cursor headless flags."""
+        normalized = mode.lower()
+        result = list(command)
+        if normalized in {"auto", "yolo"}:
+            if "--force" not in result and "--yolo" not in result:
+                result.insert(1, "--force")
+            return result
+        if normalized == "plan":
+            if "--mode=plan" not in result:
+                result.insert(1, "--mode=plan")
+            return result
+        # gated/prod: omit force; trust + verify loop contain edits.
+        return result
+
     def _cursor_command(self, task_id: str | None = None) -> list[str]:
         executable = resolve_cursor_agent_executable()
         if not executable:
@@ -185,12 +340,33 @@ class CodingCliExecutor(Executor):
             "--workspace",
             str(self.project_root),
         ]
+        if self.stream_output:
+            command.extend(["--output-format", "stream-json", "--stream-partial-output"])
+        else:
+            command.extend(["--output-format", "json"])
         chat_id = self._cursor_resume_chat_id(task_id)
         if chat_id:
             command.extend(["--resume", chat_id])
         command.append("Read and execute the DevCouncil task prompt at {prompt_file}.")
         return command
 
+    def _grok_command(self, task_id: str | None = None) -> list[str]:
+        command = [
+            "grok",
+            "-p",
+            "Read and execute the DevCouncil task prompt at {prompt_file}.",
+            "--directory",
+            str(self.project_root),
+        ]
+        if self.stream_output:
+            command.extend(["--output-format", "stream-json"])
+        else:
+            command.extend(["--output-format", "json"])
+        session_id = self._grok_resume_session_id(task_id)
+        if session_id:
+            command.extend(["--resume", session_id])
+        return command
+
     def _warp_command(self) -> list[str]:
         config = self._load_warp_config()
         command = config.get("command", "oz")
@@ -233,6 +409,12 @@ class CodingCliExecutor(Executor):
 
     def run_task(self, task: Task, requirements: list[Requirement]) -> ExecutionResult:
         logger.info("coding_cli.run_task: client=%s profile=%s task=%s", self.client, self.profile_name, task.id)
+        log_step(
+            f"executor/{self.client}: starting task {task.id}",
+            project_root=self.project_root,
+            task_id=task.id,
+            profile=self.profile_name,
+        )
         if self.profile is None:
             logger.error("Unknown agent profile %r for %s; cannot start.", self.profile_name, self.client)
             return ExecutionResult(
@@ -266,23 +448,27 @@ class CodingCliExecutor(Executor):
             )
 
         prompt = PromptBuilder(self.project_root).build_task_prompt(task, requirements)
-        from devcouncil.planning.correction_manifest import load_latest_correction_manifest
-
-        correction = load_latest_correction_manifest(self.project_root, task.id)
-        if correction is not None:
-            prompt = (
-                f"# DevCouncil Correction Manifest\n\n"
-                f"{correction.model_dump_json(indent=2)}\n\n"
-                f"{prompt}"
-            )
+        from devcouncil.planning.correction_manifest import repair_prompt_prefix
+
+        prefix = repair_prompt_prefix(self.project_root, task.id)
+        if prefix:
+            prompt = f"{prefix}{prompt}"
         prompt = self._apply_profile_prompt(prompt)
+        # Claude-only advisor steering (not PromptBuilder — shared by all executors).
+        prompt, advisor_system = self._apply_advisor_steering(prompt, repair=bool(prefix))
         instruction_file = self.project_root / ".devcouncil" / f"{task.id}-{self.client}-task.md"
         instruction_file.parent.mkdir(parents=True, exist_ok=True)
         instruction_file.write_text(prompt, encoding="utf-8")
 
-        custom_env = self.spec.env
-        env = {**dict(os.environ), **custom_env, "DEVCOUNCIL_PROJECT_ROOT": str(self.project_root)}
-        env["DEVCOUNCIL_AGENT_PROFILE"] = self.profile_name
+        env = self._build_env()
+        if self.client == "claude" and self._advisor_attached:
+            for warning in warn_advisor_preflight(
+                env=env,
+                main_model=self.profile.model if self.profile else None,
+                advisor_model=self.profile.advisor_model if self.profile else None,
+            ):
+                logger.warning("%s", warning)
+                console.print(f"[yellow]{warning}[/yellow]")
         log_prefix = f"{task.id}-{self.client}"
         run_id = str(uuid.uuid4())
         self.last_run_id = run_id
@@ -299,6 +485,8 @@ class CodingCliExecutor(Executor):
         started = time.monotonic()
         try:
             invocation, input_text = self._invocation(command, prompt, instruction_file)
+            if advisor_system:
+                invocation = self._inject_append_system_prompt(invocation, advisor_system, prompt)
             display_invocation = self._display_invocation(invocation, prompt)
             # Print the resolved command (placeholders like {prompt_file} already
             # substituted, prompt redacted) rather than the raw template.
@@ -310,6 +498,12 @@ class CodingCliExecutor(Executor):
                 instruction_file,
                 stream=self.stream_output,
             )
+            # Persist the Claude session id now (before the subprocess), so a crashed or
+            # timed-out run still leaves a resumable session, and record it on the manifest.
+            if self.client == "claude":
+                self._persist_claude_session()
+                if self.last_agent_session_id:
+                    self._update_run_manifest(run_id, agent_session_id=self.last_agent_session_id)
             TraceLogger(self.project_root).log_event(
                 "agent_run_started",
                 {
@@ -330,11 +524,72 @@ class CodingCliExecutor(Executor):
             )
             started = time.monotonic()
             logger.info("Launching %s subprocess for %s (timeout=%ss)", self.client, task.id, self._effective_timeout())
-            result = self._run_subprocess(invocation, input_text, env, transcript_path=transcript_path)
+            # Render Claude's NDJSON stream as readable lines while it runs (raw is still
+            # captured to the transcript); other clients print their output verbatim.
+            display_transform = (
+                self._render_claude_stream_event
+                if (self.client == "claude" and self.stream_output)
+                else None
+            )
+            result = self._run_subprocess(
+                invocation, input_text, env,
+                transcript_path=transcript_path,
+                display_transform=display_transform,
+            )
+            # Transient-failure retry: a CLI that died on a network/provider fault
+            # ("API Error: Connection closed mid-response", 429/5xx, overloaded) says
+            # nothing about the task — without a retry the failure ends the task
+            # `blocked`, burns a repair attempt on a non-code problem, and surfaces
+            # as a false negative (seen directly in the benchmark). Only failures
+            # whose output matches a known-transient signature are retried, with a
+            # short backoff; genuine agent errors still fail immediately.
+            retries = 0
+            retry_limit = self._transient_retry_limit()
+            while result.returncode != 0 and retries < retry_limit:
+                reason = self._transient_failure_reason(result)
+                if reason is None:
+                    break
+                retries += 1
+                delay = min(30.0, 5.0 * retries)
+                logger.warning(
+                    "%s failed with a transient error for %s (%s); retrying %d/%d in %.0fs",
+                    self.client, task.id, reason, retries, retry_limit, delay,
+                )
+                TraceLogger(self.project_root).log_event(
+                    "agent_run_transient_retry",
+                    {
+                        "agent": self.client,
+                        "profile": self.profile_name,
+                        "returncode": result.returncode,
+                        "reason": reason,
+                        "attempt": retries,
+                        "limit": retry_limit,
+                    },
+                    run_id=run_id,
+                    task_id=task.id,
+                    summary=f"Transient {self.client} failure ({reason}); retry {retries}/{retry_limit}",
+                )
+                time.sleep(delay)
+                result = self._run_subprocess(
+                    invocation, input_text, env,
+                    transcript_path=transcript_path,
+                    display_transform=display_transform,
+                )
             duration = round(time.monotonic() - started, 3)
             logger.info("%s subprocess for %s exited %s in %.2fs", self.client, task.id, result.returncode, duration)
             finished_at = datetime.now(timezone.utc).isoformat()
             self._write_log(log_prefix, result)
+            # Capture Claude's structured result onto the manifest. Non-stream: parse the one
+            # JSON blob and swap stdout for the human ``result`` text so previews stay readable.
+            # Stream: harvest the terminal result event from the captured NDJSON for telemetry.
+            if self.client == "claude":
+                if self.stream_output:
+                    self._capture_claude_stream_json(run_id, result)
+                else:
+                    result = self._capture_claude_json(run_id, result)
+                self._mirror_claude_transcript()
+            if self.client == "grok":
+                self._capture_grok_session_from_result(task.id, result)
             if transcript_path and transcript_path.exists():
                 self._append_manifest_transcript(run_id, transcript_path)
                 self.last_transcript_path = transcript_path
@@ -379,6 +634,14 @@ class CodingCliExecutor(Executor):
                 task_id=task.id,
                 summary=f"{self.client} finished for {task.id}",
             )
+            log_step(
+                f"executor/{self.client}: finished task {task.id}",
+                project_root=self.project_root,
+                task_id=task.id,
+                returncode=result.returncode,
+                duration_s=round(duration, 2),
+                trace=True,
+            )
             # Opt-in pre-verify scope gate: this CLI subprocess wrote directly to disk with
             # no per-write hook, so revert any out-of-scope change now (before it reaches the
             # verify gate or a commit) rather than only flagging it as orphan_diff post-verify.
@@ -435,6 +698,26 @@ class CodingCliExecutor(Executor):
         finally:
             run_log_cm.__exit__(None, None, None)
 
+    def _build_env(self) -> dict[str, str]:
+        """Environment for the agent subprocess.
+
+        Layering (later wins): parent process env → the agent spec's ``env`` (custom
+        agents) → the profile's ``env`` overrides → DevCouncil's own variables. The
+        profile layer is what lets a profile redirect the Claude Code harness at an
+        alternative Anthropic-compatible endpoint (``ANTHROPIC_BASE_URL`` /
+        ``ANTHROPIC_AUTH_TOKEN`` / ``ANTHROPIC_MODEL``, e.g. a local LiteLLM proxy in
+        front of Ollama or OpenRouter) — the same provider-redirection trick DevPrism's
+        loopback proxy uses — without editing the base spec. DevCouncil's variables are
+        applied last so no profile can mask them."""
+        profile_env = dict(self.profile.env) if (self.profile and self.profile.env) else {}
+        return {
+            **dict(os.environ),
+            **self.spec.env,
+            **profile_env,
+            "DEVCOUNCIL_PROJECT_ROOT": str(self.project_root),
+            "DEVCOUNCIL_AGENT_PROFILE": self.profile_name,
+        }
+
     def _scope_enforcement_enabled(self) -> bool:
         try:
             from devcouncil.app.config import load_config
@@ -442,6 +725,58 @@ class CodingCliExecutor(Executor):
         except Exception:
             return False
 
+    # Output signatures of failures caused by the NETWORK/PROVIDER, not the task.
+    # Matched case-insensitively against stderr plus the tail of stdout. Deliberately
+    # phrase-based (no bare status-code numbers) so code/diff content in stdout cannot
+    # spuriously classify a genuine agent failure as transient.
+    _TRANSIENT_FAILURE_MARKERS = (
+        "connection closed",
+        "connection reset",
+        "connection refused",
+        "connection error",
+        "connection aborted",
+        "econnreset",
+        "econnrefused",
+        "etimedout",
+        "socket hang up",
+        "mid-response",
+        "network error",
+        "fetch failed",
+        "temporarily unavailable",
+        "service unavailable",
+        "internal server error",
+        "bad gateway",
+        "gateway timeout",
+        "overloaded",
+        "rate limit",
+        "too many requests",
+        "request timed out",
+        "timeout awaiting",
+        "tls handshake",
+        "dns",
+    )
+
+    def _transient_failure_reason(self, result: "subprocess.CompletedProcess[str]") -> str | None:
+        """The matched transient marker when a failed run looks network/provider-caused,
+        else None. Scans stderr fully and only the TAIL of stdout (where CLIs print
+        their final error) so large code output cannot trigger a false match."""
+        haystack = f"{result.stderr or ''}\n{(result.stdout or '')[-4000:]}".lower()
+        for marker in self._TRANSIENT_FAILURE_MARKERS:
+            if marker in haystack:
+                return marker
+        return None
+
+    def _transient_retry_limit(self) -> int:
+        """Max transient-failure retries from ``execution.transient_retry_attempts``.
+
+        Defaults conservatively (2) when config is unavailable; 0 disables retry."""
+        try:
+            from devcouncil.app.config import load_config
+
+            return max(0, int(load_config(self.project_root).execution.transient_retry_attempts))
+        except Exception:
+            return 2
+
     def _enforce_file_scope(self, task: Task) -> list[tuple[str, str]]:
         """Revert any file this task's subprocess changed that the task does not authorize.
 
@@ -453,8 +788,14 @@ class CodingCliExecutor(Executor):
             from devcouncil.verification.verifier import Verifier
 
             changed = Verifier(self.project_root).get_task_changed_files(task.id)
-        except Exception:
-            return []
+        except Exception as exc:
+            logger.exception(
+                "Scope enforcement failed for %s: could not load changed files",
+                task.id,
+            )
+            raise RuntimeError(
+                f"Scope enforcement failed for {task.id}: could not determine changed files ({exc})."
+            ) from exc
         engine = TaskPolicyEngine(self.project_root)
         reverted: list[tuple[str, str]] = []
         for path in changed:
@@ -465,31 +806,43 @@ class CodingCliExecutor(Executor):
             try:
                 decision = engine.evaluate_file_change(path, task, "write")
             except Exception:
+                logger.warning(
+                    "Scope enforcement skipped policy check for %s on %s",
+                    task.id,
+                    path,
+                    exc_info=True,
+                )
                 continue
             if decision.action == "deny" and self._revert_path(path):
                 reverted.append((path, decision.reason))
         return reverted
 
+    _GIT_REVERT_TIMEOUT_SECONDS = 120
+
     def _revert_path(self, rel_path: str) -> bool:
         """Undo an out-of-scope change. A file that exists in HEAD is restored to HEAD; a
         file the task newly added (absent from HEAD, or no HEAD at all) is unstaged and
         deleted. Best-effort — a failed revert returns False so the path is not reported as
         cleanly gated (and the caller does not claim it was reverted)."""
+        timeout = self._GIT_REVERT_TIMEOUT_SECONDS
         try:
             in_head = subprocess.run(
                 ["git", "cat-file", "-e", f"HEAD:{rel_path}"],
                 cwd=self.project_root, capture_output=True, text=True,
+                timeout=timeout,
             ).returncode == 0
             if in_head:
                 return subprocess.run(
                     ["git", "checkout", "HEAD", "--", rel_path],
                     cwd=self.project_root, capture_output=True, text=True,
+                    timeout=timeout,
                 ).returncode == 0
             # New file (incl. the no-HEAD case): unstage if staged, then remove the working
             # copy so it cannot be committed by the next repair attempt.
             subprocess.run(
                 ["git", "rm", "-f", "--cached", "--ignore-unmatch", rel_path],
                 cwd=self.project_root, capture_output=True, text=True,
+                timeout=timeout,
             )
             full = self.project_root / rel_path
             if full.is_file():
@@ -541,6 +894,7 @@ class CodingCliExecutor(Executor):
         input_text: str | None,
         env: dict[str, str],
         transcript_path: Path | None = None,
+        display_transform: Callable[[str], str | None] | None = None,
     ) -> subprocess.CompletedProcess[str]:
         timeout = self._effective_timeout()
         invocation = self._resolve_invocation(invocation, env)
@@ -625,7 +979,17 @@ class CodingCliExecutor(Executor):
                     continue
                 if line is None:
                     break
-                self._emit_stream_line(line)
+                # Display may be transformed (e.g. Claude NDJSON → a readable line, or
+                # suppressed for noise), but capture and transcript always keep the raw
+                # bytes so post-run parsing and forensics see the full stream.
+                display: str | None = line
+                if display_transform is not None:
+                    try:
+                        display = display_transform(line)
+                    except Exception:
+                        display = line
+                if display:
+                    self._emit_stream_line(display)
                 captured.append(line)
                 if transcript_handle is not None:
                     transcript_handle.write(redact_text(line))
@@ -655,6 +1019,18 @@ class CodingCliExecutor(Executor):
             return "off"
         return mode
 
+    def _grok_resume_mode(self) -> str:
+        try:
+            if self._config is None:
+                mode = "off"
+            else:
+                mode = (self._config.execution.grok_resume_mode or "off").strip().lower()
+        except Exception:
+            mode = "off"
+        if mode not in {"off", "project", "task"}:
+            return "off"
+        return mode
+
     def _cursor_session_path(self, task_id: str | None = None) -> Path:
         if self._cursor_resume_mode() == "task" and task_id:
             return self.project_root / ".devcouncil" / "sessions" / f"{task_id}-cursor.json"
@@ -667,7 +1043,7 @@ class CodingCliExecutor(Executor):
         path = self._cursor_session_path(task_id if mode == "task" else None)
         if path.exists():
             try:
-                data = json.loads(path.read_text(encoding="utf-8")) or {}
+                data = read_json(path) or {}
             except json.JSONDecodeError:
                 data = {}
             existing_chat_id = str(data.get("chat_id") or "").strip()
@@ -677,7 +1053,7 @@ class CodingCliExecutor(Executor):
         if not ensured_chat_id:
             return None
         path.parent.mkdir(parents=True, exist_ok=True)
-        path.write_text(json.dumps({"chat_id": ensured_chat_id}, indent=2) + "\n", encoding="utf-8")
+        write_json(path, {"chat_id": ensured_chat_id})
         return ensured_chat_id
 
     def _ensure_cursor_chat_id(self) -> str | None:
@@ -701,6 +1077,292 @@ class CodingCliExecutor(Executor):
         chat_id = (result.stdout or result.stderr or "").strip().splitlines()[-1].strip()
         return chat_id or None
 
+    def _grok_session_path(self, task_id: str | None = None) -> Path:
+        if self._grok_resume_mode() == "task" and task_id:
+            return self.project_root / ".devcouncil" / "sessions" / f"{task_id}-grok.json"
+        return self.project_root / ".devcouncil" / "integrations" / "grok-session.json"
+
+    def _grok_resume_session_id(self, task_id: str | None) -> str | None:
+        mode = self._grok_resume_mode()
+        if mode == "off":
+            return None
+        path = self._grok_session_path(task_id if mode == "task" else None)
+        if path.exists():
+            try:
+                data = read_json(path) or {}
+            except json.JSONDecodeError:
+                data = {}
+            existing = str(data.get("session_id") or "").strip()
+            if existing:
+                return existing
+        return None
+
+    def _persist_grok_session(self, session_id: str, task_id: str | None) -> None:
+        mode = self._grok_resume_mode()
+        if mode == "off" or not session_id:
+            return
+        path = self._grok_session_path(task_id if mode == "task" else None)
+        try:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            write_json(path, {"session_id": session_id})
+        except OSError:
+            pass
+
+    def _capture_grok_session_from_result(
+        self, task_id: str, result: subprocess.CompletedProcess[str]
+    ) -> None:
+        """Best-effort harvest of Grok session id from JSON output for resume."""
+        if self._grok_resume_mode() == "off":
+            return
+        raw = (result.stdout or "").strip()
+        if not raw:
+            return
+        payload: dict | None = None
+        for line in reversed(raw.splitlines()):
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                candidate = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if isinstance(candidate, dict):
+                payload = candidate
+                break
+        if payload is None:
+            try:
+                loaded = json.loads(raw)
+            except json.JSONDecodeError:
+                return
+            payload = loaded if isinstance(loaded, dict) else None
+        if payload is None:
+            return
+        session_id = str(payload.get("session_id") or payload.get("sessionId") or "").strip()
+        if session_id:
+            self.last_agent_session_id = session_id
+            self._persist_grok_session(session_id, task_id)
+
+    def _claude_command(self, task_id: str | None = None) -> list[str]:
+        """Build Claude Code's headless command with a stable session identity.
+
+        A fresh task run is pinned to a new UUID via ``--session-id`` so DevCouncil
+        knows, up front, which native ``~/.claude`` transcript the run will write —
+        making headless evidence and live review locatable without scraping stdout.
+        A re-run of the SAME task (e.g. a repair iteration) instead ``--resume``\\s the
+        prior session so the model keeps the context of what it already tried, rather
+        than restarting cold from a re-prepended correction manifest. The chosen id is
+        stashed in ``_pending_claude_session`` and persisted once the run launches."""
+        base = list(self.spec.base_command())
+        # Capture Claude's structured result either way. Non-stream: one JSON blob parsed
+        # after exit. Stream: NDJSON events rendered live (readable lines, not raw JSON) and
+        # the terminal result event harvested for telemetry. ``--verbose`` is required by
+        # Claude for stream-json.
+        if self.stream_output:
+            base = [*base, "--output-format", "stream-json", "--verbose"]
+        else:
+            base = [*base, "--output-format", "json"]
+        session_path = self._claude_session_path(task_id)
+        prior = self._read_claude_session_id(session_path)
+        if prior:
+            self._pending_claude_session = (session_path, prior)
+            return [*base, "--resume", prior]
+        new_id = str(uuid.uuid4())
+        self._pending_claude_session = (session_path, new_id)
+        return [*base, "--session-id", new_id]
+
+    def _claude_session_path(self, task_id: str | None) -> Path:
+        name = f"{task_id}-claude.json" if task_id else "claude-session.json"
+        return self.project_root / ".devcouncil" / "sessions" / name
+
+    @staticmethod
+    def _read_claude_session_id(path: Path) -> str | None:
+        if not path.exists():
+            return None
+        try:
+            data = read_json(path) or {}
+        except json.JSONDecodeError:
+            return None
+        session_id = str(data.get("session_id") or "").strip()
+        return session_id or None
+
+    def _persist_claude_session(self) -> None:
+        """Record the run's Claude session id so a later re-run of the task resumes it.
+
+        Persisted after the subprocess launches (not on exit) so even a crashed or
+        timed-out run leaves a resumable session behind. Also exposes the id via
+        ``last_agent_session_id`` for the caller and the run manifest."""
+        pending = self._pending_claude_session
+        if not pending:
+            return
+        path, session_id = pending
+        self.last_agent_session_id = session_id
+        try:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            write_json(path, {"session_id": session_id})
+        except OSError:
+            # A non-persisted session only costs a cold repair next time; never fail the run.
+            pass
+
+    def _mirror_claude_transcript(self) -> None:
+        """Best-effort copy of Claude's native JSONL into the project for live review."""
+        session_id = self.last_agent_session_id
+        if not session_id:
+            return
+        try:
+            from devcouncil.live.transcripts import mirror_claude_transcript
+
+            mirror_claude_transcript(self.project_root, session_id)
+        except Exception as exc:
+            logger.debug("Claude transcript mirror failed: %s", exc)
+
+    def _capture_claude_json(
+        self, run_id: str, result: subprocess.CompletedProcess[str]
+    ) -> subprocess.CompletedProcess[str]:
+        """Parse Claude Code's ``--output-format json`` result blob.
+
+        Records the reported session id, cost, and token usage on the run manifest, then
+        returns a copy of ``result`` with stdout replaced by the human-readable ``result``
+        text so downstream logs/previews/diagnostics read like the old text mode. On any
+        parse failure the original ``result`` is returned unchanged — a telemetry miss must
+        never turn a successful run into a reported failure."""
+        raw = (result.stdout or "").strip()
+        if not raw:
+            return result
+        payload: dict | None = None
+        # Tolerate any leading noise: scan lines from the last back for a JSON object.
+        for line in reversed(raw.splitlines()):
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                candidate = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if isinstance(candidate, dict):
+                payload = candidate
+                break
+        if payload is None:
+            try:
+                loaded = json.loads(raw)
+            except json.JSONDecodeError:
+                return result
+            payload = loaded if isinstance(loaded, dict) else None
+        if payload is None:
+            return result
+
+        self._record_claude_result_meta(run_id, payload)
+        text = payload.get("result")
+        if isinstance(text, str) and text.strip():
+            return subprocess.CompletedProcess(
+                result.args, result.returncode, stdout=text, stderr=result.stderr
+            )
+        return result
+
+    def _record_claude_result_meta(self, run_id: str, payload: dict) -> None:
+        """Record session id, cost, and token usage from a Claude ``result`` payload.
+
+        Shared by the non-stream JSON path and the stream-json path; both surface the same
+        terminal ``result`` object, just delivered as one blob vs. the last NDJSON line."""
+        raw_usage = payload.get("usage")
+        usage: dict[Any, Any] = raw_usage if isinstance(raw_usage, dict) else {}
+        session_id = str(payload.get("session_id") or "").strip() or None
+        if session_id:
+            self.last_agent_session_id = session_id
+            self._update_run_manifest(run_id, agent_session_id=session_id)
+            # Keep the persisted resume pointer authoritative: if Claude reported a session
+            # id different from the one we assigned, a later --resume must target the real
+            # one, so rewrite the session file to what actually ran.
+            pending = self._pending_claude_session
+            if pending is not None and pending[1] != session_id:
+                self._pending_claude_session = (pending[0], session_id)
+                self._persist_claude_session()
+        meta = {
+            "session_id": session_id,
+            "total_cost_usd": payload.get("total_cost_usd"),
+            "num_turns": payload.get("num_turns"),
+            "is_error": payload.get("is_error"),
+            "input_tokens": usage.get("input_tokens"),
+            "output_tokens": usage.get("output_tokens"),
+            "cache_read_input_tokens": usage.get("cache_read_input_tokens"),
+        }
+        self._update_run_manifest(run_id, agent_result={k: v for k, v in meta.items() if v is not None})
+
+    def _capture_claude_stream_json(self, run_id: str, result: subprocess.CompletedProcess[str]) -> None:
+        """Record telemetry from a streamed NDJSON run by finding the terminal result event.
+
+        The streaming path already rendered readable lines live; here we only harvest the
+        last ``result`` event for the manifest. Best-effort — never raises into the run."""
+        payload: dict | None = None
+        for line in (result.stdout or "").splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                event = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if isinstance(event, dict) and event.get("type") == "result":
+                payload = event  # keep scanning; the last result event wins
+        if payload is not None:
+            self._record_claude_result_meta(run_id, payload)
+
+    @staticmethod
+    def _render_claude_stream_event(line: str) -> str | None:
+        """Turn one Claude stream-json NDJSON line into a concise console line.
+
+        Returns the text to display, or None to suppress the event (system/thinking/rate-
+        limit noise). Non-JSON lines pass through verbatim so nothing is silently dropped."""
+        stripped = line.strip()
+        if not stripped:
+            return None
+        try:
+            event = json.loads(stripped)
+        except json.JSONDecodeError:
+            return line
+        if not isinstance(event, dict):
+            return line
+        etype = event.get("type")
+        if etype == "assistant":
+            raw_message = event.get("message")
+            message: dict[Any, Any] = raw_message if isinstance(raw_message, dict) else {}
+            parts: list[str] = []
+            for block in (message.get("content") or []):
+                if not isinstance(block, dict):
+                    continue
+                btype = block.get("type")
+                if btype == "text" and str(block.get("text") or "").strip():
+                    parts.append(str(block["text"]).strip())
+                elif btype in {"tool_use", "server_tool_use"}:
+                    name = str(block.get("name") or "tool")
+                    if name == "advisor" or (
+                        btype == "server_tool_use" and "advisor" in name.lower()
+                    ):
+                        raw_input = block.get("input")
+                        tool_input: dict[Any, Any] = raw_input if isinstance(raw_input, dict) else {}
+                        model = str(
+                            tool_input.get("model")
+                            or block.get("model")
+                            or ""
+                        ).strip()
+                        parts.append(f"Advising{f' ({model})' if model else ''}")
+                        continue
+                    raw_input = block.get("input")
+                    tool_input = raw_input if isinstance(raw_input, dict) else {}
+                    target = tool_input.get("file_path") or tool_input.get("path") or tool_input.get("command") or ""
+                    parts.append(f"→ {name} {str(target)[:80]}".rstrip())
+            text = "\n".join(p for p in parts if p)
+            return text + "\n" if text else None
+        if etype == "result":
+            bits: list[str] = []
+            if event.get("num_turns") is not None:
+                bits.append(f"{event['num_turns']} turns")
+            cost = event.get("total_cost_usd")
+            if isinstance(cost, (int, float)):
+                bits.append(f"${cost:.4f}")
+            return ("✓ " + ", ".join(bits) + "\n") if bits else None
+        # system / user / tool_result / rate_limit_event: keep the console quiet.
+        return None
+
     def _effective_timeout(self) -> int:
         if self.profile and self.profile.timeout_seconds:
             return int(self.profile.timeout_seconds)
@@ -713,6 +1375,9 @@ class CodingCliExecutor(Executor):
             for part in command
         ]
         extra = list(self.profile.extra_args) if (self.profile and self.profile.extra_args) else []
+        # Avoid a second --advisor when DevCouncil already attached one from advisor_model.
+        if self._advisor_attached and extra:
+            extra = strip_duplicate_advisor_args(extra)
 
         def _place(base: list[str]) -> list[str]:
             """Insert profile extra_args after the base flags but before a trailing prompt
@@ -743,6 +1408,30 @@ class CodingCliExecutor(Executor):
     def _display_invocation(self, invocation: list[str], prompt: str) -> list[str]:
         return [part.replace(prompt, "<task prompt>") for part in invocation]
 
+    @staticmethod
+    def _inject_append_system_prompt(
+        invocation: list[str], system_prompt: str, user_prompt: str
+    ) -> list[str]:
+        """Insert ``--append-system-prompt`` without splitting a trailing prompt value."""
+        if invocation and invocation[-1] == user_prompt:
+            return [*invocation[:-1], "--append-system-prompt", system_prompt, user_prompt]
+        return [*invocation, "--append-system-prompt", system_prompt]
+
+    def _apply_advisor_steering(self, prompt: str, *, repair: bool) -> tuple[str, str | None]:
+        """Claude-only advisor steering. Prefer ``--append-system-prompt``; else prompt prefix.
+
+        Injects steering **only** when ``--advisor`` actually attached. Soft-skipped and
+        non-Claude clients get no nudge. Returns ``(prompt, append_system_or_none)``.
+        """
+        if self.client != "claude" or not self.profile or not self._advisor_attached:
+            return prompt, None
+        steer = advisor_steering_text(repair=repair)
+        cost_trim = advisor_user_cost_trim()
+        # Prefer system append when the flag is available; keep soft cost trim in user prompt.
+        if claude_supports_append_system_prompt():
+            return f"{cost_trim}\n\n{prompt}", steer
+        return f"# DevCouncil Advisor\n{steer}\n\n{cost_trim}\n\n{prompt}", None
+
     def _apply_profile_prompt(self, prompt: str) -> str:
         if not self.profile:
             return prompt
@@ -759,11 +1448,21 @@ class CodingCliExecutor(Executor):
         """Resolved per-profile CLI overrides recorded in the manifest so a
         supervisor can see exactly how the profile constrained the invocation."""
         if not self.profile:
-            return {"extra_args": [], "permission_mode": None, "model": None}
+            return {
+                "extra_args": [],
+                "permission_mode": None,
+                "model": None,
+                "advisor_model": None,
+                "env_keys": [],
+            }
         return {
             "extra_args": list(self.profile.extra_args or []),
             "permission_mode": self.profile.permission_mode,
             "model": self.profile.model,
+            "advisor_model": self.profile.advisor_model,
+            # KEY NAMES only — profile env values may carry provider tokens and must
+            # never land in the manifest.
+            "env_keys": sorted((self.profile.env or {}).keys()),
         }
 
     def _update_run_manifest(self, run_id: str, **updates: object) -> None:
@@ -771,11 +1470,11 @@ class CodingCliExecutor(Executor):
         if not manifest_path.exists():
             return
         try:
-            manifest = json.loads(manifest_path.read_text(encoding="utf-8")) or {}
+            manifest = read_json(manifest_path) or {}
         except json.JSONDecodeError:
             return
         manifest.update(updates)
-        manifest_path.write_text(json.dumps(manifest, indent=2) + "\n", encoding="utf-8")
+        write_json(manifest_path, manifest)
 
     def _preview_lines(self, value: str | None, *, limit: int = 20) -> list[str]:
         lines = redact_text(value or "").splitlines()
@@ -821,7 +1520,7 @@ class CodingCliExecutor(Executor):
             "finished_at": None,
             "duration_seconds": None,
         }
-        manifest_path.write_text(json.dumps(manifest, indent=2) + "\n", encoding="utf-8")
+        write_json(manifest_path, manifest)
         return manifest_path
 
     def _write_log(self, task_client: str, result: subprocess.CompletedProcess[str]) -> None:
@@ -855,10 +1554,10 @@ class CodingCliExecutor(Executor):
         should_write = not path.exists()
         if path.exists():
             try:
-                existing = json.loads(path.read_text(encoding="utf-8")) or {}
+                existing = read_json(path) or {}
             except json.JSONDecodeError:
                 existing = {}
             should_write = "mcpServers" in existing and "devcouncil" not in existing
         if should_write:
-            path.write_text(json.dumps(desired, indent=2) + "\n", encoding="utf-8")
+            write_json(path, desired)
         return path