tsugite-cc-driver 0.18.0__tar.gz

tsugite_cc_driver-0.18.0/.gitignore

@@ -0,0 +1,184 @@
+# ---> Python
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+.env
+.env
+benchmark_results/
+test_output/
+.claude/settings.local.json
+std*.txt
+secrets/*
+
+
+# TODO: temp - I need to clean up the docs
+docs-old/
+docs/design/
+examples/*
+!examples/tsugite-example-plugin/
+agents/
+.claude/
+.tsugite/
+benchmarks/
+docker-compose.test.yml
+#### TODO ^^^

tsugite_cc_driver-0.18.0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: tsugite-cc-driver
+Version: 0.18.0
+Summary: Tsugite plugin: drive interactive Claude Code sessions as verified jobs via HTTP hooks (daemon-only)
+Author: Justyn Shull
+Requires-Python: >=3.11
+Requires-Dist: tsugite-cli==0.18.0
+Requires-Dist: tsugite-daemon==0.18.0
+Requires-Dist: tsugite-pty==0.18.0

tsugite_cc_driver-0.18.0/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "tsugite-cc-driver"
+version = "0.18.0"
+description = "Tsugite plugin: drive interactive Claude Code sessions as verified jobs via HTTP hooks (daemon-only)"
+authors = [{ name = "Justyn Shull" }]
+requires-python = ">=3.11"
+dependencies = [
+  "tsugite-cli==0.18.0",
+  "tsugite-daemon==0.18.0",
+  "tsugite-pty==0.18.0",
+]
+
+[project.entry-points."tsugite.adapters"]
+cc_driver = "tsugite_cc_driver.adapter:create_adapter"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["tsugite_cc_driver"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "/tsugite_cc_driver",
+  "/pyproject.toml",
+]
+
+[tool.uv.sources]
+tsugite-cli = { workspace = true }
+tsugite-daemon = { workspace = true }
+tsugite-pty = { workspace = true }

tsugite_cc_driver-0.18.0/tsugite_cc_driver/__init__.py

@@ -0,0 +1,7 @@
+"""tsugite-cc-driver: run interactive Claude Code sessions as verified tsugite jobs.
+
+A job with executor="cc" is driven by an interactive `claude` process in a PTY.
+HTTP Stop hooks decide whether the attempt is finished (completion marker or
+continue-budget exhausted) or should be nudged onward; completion routes into the
+existing job verifier/AC/retry machinery. See README.md.
+"""

tsugite_cc_driver-0.18.0/tsugite_cc_driver/adapter.py

@@ -0,0 +1,204 @@
+"""CCDriverAdapter: the adapter-plugin entry point.
+
+Exposes ONE public HTTP route (the per-job hook receiver, token-in-path, no daemon
+auth) and ONE job executor ("cc"). The gateway mounts the route under
+/api/plugins/cc_driver and registers the executor on the jobs orchestrator, handing
+this adapter the orchestrator via set_jobs_orchestrator so the hook route can call
+complete_worker/fail_worker.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Optional
+
+from pydantic import BaseModel
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+from starlette.routing import Route
+from tsugite_daemon.adapters.base import BaseAdapter
+from tsugite_daemon.job_store import JobState
+
+from tsugite_cc_driver.executor import CCExecutor, DriveStateStore
+from tsugite_cc_driver.hooks import decide_stop, decide_stop_failure, notification_attention
+
+logger = logging.getLogger(__name__)
+
+
+class CCDriverConfig(BaseModel):
+    enabled: bool = False
+    claude_binary: str = "claude"
+    # Default model the driven claude runs with (alias sonnet/opus/haiku or a full
+    # name). A per-job `model` overrides it; set to null to use claude's own default.
+    model: Optional[str] = "sonnet"
+    permission_mode: str = "bypassPermissions"
+    # Autonomous default is sandboxed: filesystem isolation pairs with the
+    # bypass/skip-permissions trust workaround so a driven claude can't write
+    # outside the job workspace. Network stays on (it needs the API).
+    sandbox: bool = True
+    # Auto-provision Claude Code trust for a job's workspace (writes
+    # projects[cwd].hasTrustDialogAccepted into ~/.claude.json) so cc jobs are
+    # self-service. Off = require the user to pre-trust each workspace once.
+    provision_trust: bool = True
+    max_consecutive_continues: int = 5
+    completion_marker: str = "CCDRIVER_GOAL_COMPLETE"
+    # Marker the driven claude emits when it is blocked on supervisor input;
+    # pauses the job in awaiting_input instead of nudging it to guess.
+    needs_input_marker: str = "CCDRIVER_NEED_INPUT"
+    # Opt-in: render flat, screen-reader-friendly PTY output (no decorative
+    # borders or animations) via --ax-screen-reader. Cleaner failure-tail capture
+    # and fewer xterm escape edge cases, but off by default so the live terminal
+    # viewer keeps the normal TUI; the real state signal is the hook markers.
+    ax_screen_reader: bool = False
+    # Default reasoning effort (low/medium/high/xhigh/max) for the driven claude;
+    # a per-job `effort` overrides it, None uses claude's own default.
+    effort: Optional[str] = None
+    base_url: str = "http://127.0.0.1:8374"
+    state_dir: Optional[str] = None
+
+
+def _resolve_state_dir(state_dir: Optional[str]) -> str:
+    """Where per-job settings.json files live. Defaults to the XDG data path, same
+    as every other tsugite subsystem (see tsugite.config.get_xdg_data_path)."""
+    if state_dir:
+        return str(Path(state_dir).expanduser())
+    from tsugite.config import get_xdg_data_path
+
+    return str(get_xdg_data_path("cc-driver"))
+
+
+class CCDriverAdapter(BaseAdapter):
+    """Not tied to a single agent - it's a job executor + hook receiver, so it
+    skips BaseAdapter's agent/workspace init and sets only what the gateway wiring
+    touches."""
+
+    def __init__(self, config: CCDriverConfig, session_store=None, identity_map=None):
+        self.agent_name = "cc_driver"
+        self.session_store = session_store
+        self._identity_map = identity_map or {}
+        self.event_bus = None  # set by attach_plugin_http
+        self.config = config
+        self.config.state_dir = _resolve_state_dir(config.state_dir)
+        self._drive_state = DriveStateStore()
+        self._executor = CCExecutor(self.config, self._drive_state)
+        self._orchestrator = None
+
+    # ── plugin wiring ──
+
+    def get_public_http_routes(self) -> list:
+        # Unauthenticated: Claude Code can't send a daemon bearer token. Access is
+        # gated by the random per-job token in the path (unknown token -> 404).
+        return [Route("/hook/{token}", self._hook, methods=["POST"])]
+
+    def get_job_executors(self) -> dict:
+        return {"cc": self._executor}
+
+    def set_jobs_orchestrator(self, orchestrator) -> None:
+        """Injected by the gateway at executor registration so the hook route and
+        the executor can report job outcomes."""
+        self._orchestrator = orchestrator
+        self._executor.orchestrator = orchestrator
+
+    async def start(self) -> None:  # BaseAdapter contract - nothing to run
+        return None
+
+    async def stop(self) -> None:
+        return None
+
+    # ── hook receiver ──
+
+    async def _hook(self, request: Request) -> JSONResponse:
+        token = request.path_params["token"]
+        state = self._drive_state.by_token(token)
+        if state is None:
+            # Orphaned/stale claude (daemon restarted, job gone) -> 404 so it just stops.
+            return JSONResponse({"error": "unknown job token"}, status_code=404)
+
+        job_id = state.job_id
+        orch = self._orchestrator
+        job = orch.get_job(job_id) if orch is not None else None
+
+        try:
+            payload = await request.json()
+        except Exception:
+            payload = {}
+
+        if job is not None and job.state == JobState.AWAITING_INPUT.value and payload.get("hook_event_name") == "Stop":
+            # A Stop while paused means someone answered directly in the live
+            # TUI (claude only runs a turn when typed at). Resume the job and
+            # grade the turn normally instead of dropping it - otherwise a
+            # human take-over could never re-grade the attempt.
+            job = await orch.resume_worker(job_id)
+
+        if job is None or job.state != JobState.RUNNING.value:
+            # Not RUNNING (verifying/terminal): allow claude to stop; the verifier
+            # or a retry drives the next attempt.
+            return JSONResponse({})
+
+        # Every payload carries the session id; record it so a respawn can --resume.
+        if payload.get("session_id"):
+            state.cc_session_id = payload["session_id"]
+
+        event = payload.get("hook_event_name")
+        if event == "Stop":
+            if state.attention_flagged:
+                # Claude finished a turn, so the permission prompt that set the
+                # flag was answered - tell the UI to drop its persistent marker.
+                state.attention_flagged = False
+                self._emit("attention_cleared", {"job_id": job_id, "parent_session_id": job.parent_session_id})
+            decision = decide_stop(
+                payload,
+                consecutive_continues=state.consecutive_continues,
+                max_consecutive_continues=self.config.max_consecutive_continues,
+                completion_marker=self.config.completion_marker,
+                needs_input_marker=self.config.needs_input_marker,
+            )
+            state.consecutive_continues = decision.new_consecutive_continues
+            if decision.complete:
+                await orch.complete_worker(job_id, decision.summary or "")
+            elif decision.needs_input:
+                await orch.pause_worker(job_id, decision.needs_input)
+            return JSONResponse(decision.response)
+
+        if event == "StopFailure":
+            await orch.fail_worker(job_id, decide_stop_failure(payload))
+            return JSONResponse({})
+
+        if event == "Notification":
+            message = notification_attention(payload)
+            if message:
+                state.attention_flagged = True
+                self._emit(
+                    "needs_attention",
+                    {"job_id": job_id, "parent_session_id": job.parent_session_id, "message": message},
+                )
+            return JSONResponse({})
+
+        # Unknown/other events: acknowledge without driving.
+        return JSONResponse({})
+
+    def _emit(self, event: str, payload: dict) -> None:
+        if self.event_bus is None:
+            return
+        try:
+            self.event_bus.emit(event, payload)
+        except Exception:
+            logger.debug("cc-driver: %s emit failed for job '%s'", event, payload.get("job_id"))
+
+
+def create_adapter(*, config, agents_config, session_store, identity_map):
+    """Adapter-plugin factory (tsugite.adapters entry point).
+
+    `config` is the daemon.yaml plugins.cc_driver dict; agents_config is unused
+    (cc-driver is not agent-scoped).
+
+    Returns None (the gateway loop skips it) unless `enabled` is truthy - cc-driver
+    spawns claude with skip-permissions, so it must be explicit opt-in rather than
+    silently activated just by being installed.
+    """
+    cfg = CCDriverConfig(**(config or {}))
+    if not cfg.enabled:
+        logger.info("cc-driver plugin installed but disabled (set plugins.cc_driver.enabled: true to activate)")
+        return None
+    return CCDriverAdapter(cfg, session_store=session_store, identity_map=identity_map)

tsugite_cc_driver-0.18.0/tsugite_cc_driver/executor.py

@@ -0,0 +1,478 @@
+"""CCExecutor: the non-agent job executor that drives an interactive `claude`.
+
+Implements the orchestrator's executor contract (async start/cancel) and reports
+outcomes via complete_worker/fail_worker (called from the hook route in adapter.py
+and, on an unexpected PTY exit, from here).
+
+DriveState is in-memory per active job; it dies with the daemon (orphaned jobs are
+recovered as ERRORED by the existing restart machinery - no new persistence).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import re
+import shlex
+import shutil
+import tempfile
+import threading
+import traceback
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+from tsugite_cc_driver.hooks import build_initial_prompt
+from tsugite_cc_driver.settings import build_settings, cleanup, write_run_settings
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class DriveState:
+    """In-memory driving state for one active cc job."""
+
+    job_id: str
+    token: str
+    terminal_id: Optional[str] = None
+    cc_session_id: Optional[str] = None
+    consecutive_continues: int = 0
+    # True while an un-actioned permission prompt is (probably) on screen: set
+    # on a permission_prompt Notification, cleared on the next Stop (claude
+    # finishing a turn proves the prompt was answered). Drives the UI's
+    # persistent needs-your-input marker via needs_attention/attention_cleared.
+    attention_flagged: bool = False
+
+
+class DriveStateStore:
+    """Keyed by job_id, with a token index for the public hook route."""
+
+    def __init__(self):
+        self._by_job: dict[str, DriveState] = {}
+        self._token_to_job: dict[str, str] = {}
+
+    def create(self, job_id: str, token: str) -> DriveState:
+        state = DriveState(job_id=job_id, token=token)
+        self._by_job[job_id] = state
+        self._token_to_job[token] = job_id
+        return state
+
+    def get(self, job_id: str) -> Optional[DriveState]:
+        return self._by_job.get(job_id)
+
+    def by_token(self, token: str) -> Optional[DriveState]:
+        job_id = self._token_to_job.get(token)
+        return self._by_job.get(job_id) if job_id else None
+
+    def remove(self, job_id: str) -> None:
+        state = self._by_job.pop(job_id, None)
+        if state is not None:
+            self._token_to_job.pop(state.token, None)
+
+
+_EXIT_CODE_HINTS = {
+    126: "claude binary is not executable",
+    127: "claude binary not found (PATH, or missing from the sandbox binds)",
+    130: "interrupted (SIGINT)",
+}
+
+# ANSI escape sequences (CSI colors/cursor, OSC title) to strip from a captured tail.
+_ANSI_RE = re.compile(r"\x1b\[[0-9;?]*[ -/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)")
+
+
+def describe_exit(exit_code) -> str:
+    hint = _EXIT_CODE_HINTS.get(exit_code)
+    return f"code {exit_code} - {hint}" if hint else f"code {exit_code}"
+
+
+def pty_tail(buffer: bytes, *, max_bytes: int = 4096, max_lines: int = 40) -> Optional[str]:
+    """ANSI-stripped, blank-trimmed tail of a PTY buffer, or None if empty."""
+    text = bytes(buffer)[-max_bytes:].decode("utf-8", errors="replace")
+    lines = [ln.rstrip() for ln in _ANSI_RE.sub("", text).splitlines() if ln.strip()]
+    return "\n".join(lines[-max_lines:]) or None
+
+
+def build_claude_command(
+    claude_binary: str,
+    settings_path: str,
+    permission_mode: str,
+    prompt: str,
+    *,
+    model: Optional[str] = None,
+    resume_session_id: Optional[str] = None,
+    effort: Optional[str] = None,
+    ax_screen_reader: bool = False,
+) -> str:
+    """Build the shell command for spawn_terminal (which wraps it in `sh -c`).
+
+    Everything is shlex.quoted so a goal/followup containing quotes or newlines
+    can't break out of the argument.
+    """
+    parts = [claude_binary, "--settings", str(settings_path), "--permission-mode", permission_mode]
+    if model:
+        parts += ["--model", model]
+    if effort:
+        parts += ["--effort", effort]
+    if ax_screen_reader:
+        parts.append("--ax-screen-reader")
+    if resume_session_id:
+        parts += ["--resume", resume_session_id]
+    parts.append(prompt)
+    return shlex.join(parts)
+
+
+# Serializes the ~/.claude.json read-modify-write so two concurrent trust
+# provisions can't clobber each other's merge.
+_trust_config_lock = threading.Lock()
+
+
+def _default_trust_config_path() -> Path:
+    base = os.environ.get("CLAUDE_CONFIG_DIR") or os.path.expanduser("~")
+    return Path(base) / ".claude.json"
+
+
+def is_workspace_trusted(cwd, config_path=None) -> bool:
+    """Whether Claude Code already trusts `cwd`, so an unattended spawn won't hang
+    on the fresh-cwd "Is this a project you trust?" dialog.
+
+    A dir is trusted when itself OR any ancestor has
+    projects["<abs path>"].hasTrustDialogAccepted == true in the config Claude
+    reads. Claude Code treats a subdir of a trusted project as trusted (verified
+    against claude 2.1.207) - a `--repo` Job's worker runs in a fresh worktree at
+    <repo>/.tsugite-jobs/<id> whose exact path is never trusted, so the ancestor
+    check is what lets those jobs launch.
+
+    config_path defaults to <CLAUDE_CONFIG_DIR>/.claude.json (or ~/.claude.json).
+    Tolerant: a missing / unreadable / malformed config means "not trusted".
+    """
+    if config_path is None:
+        config_path = _default_trust_config_path()
+    try:
+        data = json.loads(Path(config_path).read_text())
+    except Exception:
+        return False
+    if not isinstance(data, dict):
+        return False
+    projects = data.get("projects") or {}
+    resolved = Path(cwd).resolve()
+    for path in (resolved, *resolved.parents):
+        project = projects.get(str(path))
+        if isinstance(project, dict) and project.get("hasTrustDialogAccepted") is True:
+            return True
+    return False
+
+
+def ensure_workspace_trusted(cwd, config_path=None) -> bool:
+    """Provision Claude Code trust for `cwd` by setting
+    projects["<abs cwd>"].hasTrustDialogAccepted = true in the config Claude
+    reads, so an unattended spawn skips the trust dialog (a minimal entry with
+    just this flag is enough - verified against claude 2.1.207). Returns True on
+    success (including when already trusted), False if the config couldn't be
+    provisioned.
+
+    Read-modify-write, preserving every other key and project entry, then an
+    atomic replace so a crash mid-write can't truncate the config. A malformed
+    existing config is left untouched (we won't destroy recoverable user data);
+    a missing config is created. Serialized across concurrent cc spawns via
+    _trust_config_lock. claude itself also writes this file at runtime; the
+    provision happens before we spawn claude for this job, so it can't race our
+    own worker.
+    """
+    if config_path is None:
+        config_path = _default_trust_config_path()
+    config_path = Path(config_path)
+    resolved = str(Path(cwd).resolve())
+    with _trust_config_lock:
+        if config_path.exists():
+            try:
+                data = json.loads(config_path.read_text())
+            except Exception:
+                logger.warning("cc-driver: %s is not valid JSON; not provisioning trust for %s", config_path, cwd)
+                return False
+            if not isinstance(data, dict):
+                logger.warning("cc-driver: %s is not a JSON object; not provisioning trust for %s", config_path, cwd)
+                return False
+        else:
+            data = {}
+        projects = data.setdefault("projects", {})
+        if not isinstance(projects, dict):
+            logger.warning("cc-driver: %s 'projects' is not an object; not provisioning trust", config_path)
+            return False
+        entry = projects.setdefault(resolved, {})
+        if not isinstance(entry, dict):
+            entry = projects[resolved] = {}
+        entry["hasTrustDialogAccepted"] = True
+        try:
+            config_path.parent.mkdir(parents=True, exist_ok=True)
+            fd, tmp = tempfile.mkstemp(dir=str(config_path.parent), prefix=".claude.json.")
+            with os.fdopen(fd, "w") as f:
+                json.dump(data, f)
+            os.replace(tmp, config_path)
+        except Exception:
+            logger.exception("cc-driver: failed to write trust for %s into %s", cwd, config_path)
+            return False
+    logger.info("cc-driver: provisioned Claude Code trust for %s", resolved)
+    return True
+
+
+def trust_provision_target(cwd) -> Path:
+    """The path to provision trust for when `cwd` needs it: the main repo root
+    when cwd is a linked git worktree living under it (tsugite's --repo
+    worktrees are <repo>/.tsugite-jobs/<id>), else cwd itself.
+
+    Trusting the repo root instead of the ephemeral worktree keeps
+    ~/.claude.json from accumulating one dead entry per --repo job - the
+    ancestor rule then covers every future worktree under that root. An
+    external worktree (outside the repo root) still gets its own entry, since
+    the ancestor rule wouldn't reach it.
+
+    A linked worktree's `.git` is a *file* containing
+    `gitdir: <repo>/.git/worktrees/<name>`; anything else means cwd is not a
+    worktree.
+    """
+    cwd = Path(cwd).resolve()
+    gitfile = cwd / ".git"
+    if not gitfile.is_file():
+        return cwd
+    try:
+        m = re.match(r"gitdir:\s*(.+)", gitfile.read_text().strip())
+    except OSError:
+        return cwd
+    if m is None:
+        return cwd
+    gitdir = Path(m.group(1))
+    if not gitdir.is_absolute():
+        gitdir = cwd / gitdir
+    gitdir = gitdir.resolve()
+    if gitdir.parent.name != "worktrees" or gitdir.parent.parent.name != ".git":
+        return cwd
+    root = gitdir.parent.parent.parent
+    return root if cwd.is_relative_to(root) else cwd
+
+
+def build_sandbox_ctx(sandbox: bool, cwd: Optional[str], *, claude_binary: str = "claude", settings_dir=None):
+    """Sandbox policy for a cc job: None (unsandboxed) unless `sandbox` is set.
+
+    When set: filesystem isolation to cwd, network ON (no_network=False - the
+    driven claude needs the API), and ~/.claude bound rw so credentials refresh.
+
+    bwrap does --clearenv and mounts only a fixed set of dirs (/usr /lib /bin
+    /sbin, the venv, the workspace, and our extra binds), so we MUST also bind
+    everything the driven claude touches by absolute path - each one, if missing
+    from the jail, is a hard failure at launch:
+    - the claude binary's dirs, or PATH points at a file that isn't there and
+      claude dies with `claude: command not found` (exit 127);
+    - the per-job settings dir holding settings.json, or `--settings <path>`
+      errors with "Settings file not found";
+    - ~/.claude.json, or claude can't see the workspace-trusted flag and hangs
+      on the trust prompt inside the jail (the exact hang the pre-check prevents).
+      Bound read-WRITE: claude persists per-run session metadata (numStartups,
+      lastCost) into it on shutdown and errors on a read-only mount.
+    """
+    if not sandbox:
+        return None
+    from tsugite.agent_runner.helpers import SandboxContext
+
+    ro: list[Path] = []
+    resolved = shutil.which(claude_binary)
+    if resolved:
+        # The PATH entry is usually a symlink into a per-version install dir; bind
+        # both so the symlink resolves AND the real files are present in the jail.
+        for d in (Path(resolved).parent, Path(os.path.realpath(resolved)).parent):
+            if d not in ro:
+                ro.append(d)
+    if settings_dir:
+        ro.append(Path(settings_dir))
+
+    rw: list[Path] = [Path.home() / ".claude"]
+    config_json = _default_trust_config_path()
+    if config_json.exists():
+        rw.append(config_json)
+
+    return SandboxContext(
+        no_network=False,
+        extra_ro_binds=ro,
+        extra_rw_binds=rw,
+        workspace_dir=Path(cwd) if cwd else None,
+    )
+
+
+class CCExecutor:
+    """Drives interactive claude sessions toward job goals. One instance, shared
+    across all cc jobs; per-job state lives in the DriveStateStore."""
+
+    def __init__(self, config, drive_state: DriveStateStore):
+        self.config = config
+        self.drive_state = drive_state
+        # Injected by the gateway at plugin-executor registration so the executor
+        # can report an unexpected PTY exit via fail_worker.
+        self.orchestrator = None
+
+    async def start(self, job, followup: Optional[str] = None) -> None:
+        """Executor contract entry point. followup=None on the initial attempt; on
+        a retry, drive the SAME live session (write_stdin) when the PTY is alive,
+        else respawn (with --resume when the cc session id is known)."""
+        from tsugite_pty.tools import get_terminal_runtime
+
+        state = self.drive_state.get(job.id)
+        if followup is not None and state is not None and state.terminal_id:
+            pty_manager, _store, _cb = get_terminal_runtime()
+            proc = pty_manager.get(state.terminal_id) if pty_manager else None
+            if proc is not None and proc.exit_code is None:
+                # claude's Ink TUI submits on carriage return, not newline, and
+                # debounces paste, so the text and the \r must be sent separately.
+                pty_manager.write_stdin(state.terminal_id, followup.strip().encode())
+                await asyncio.sleep(0.2)
+                pty_manager.write_stdin(state.terminal_id, b"\r")
+                state.consecutive_continues = 0
+                return
+        await self._spawn(job, followup)
+
+    async def _spawn(self, job, followup: Optional[str]) -> None:
+        import secrets
+
+        from tsugite_pty.terminal_runtime import spawn_terminal
+        from tsugite_pty.tools import get_terminal_runtime
+
+        claude = self.config.claude_binary
+        if shutil.which(claude) is None:
+            await self._fail(job.id, f"claude binary not found on PATH: {claude!r}")
+            return
+
+        cwd = job.worktree_path or job.workspace_path
+        if not cwd or not Path(cwd).is_dir():
+            await self._fail(job.id, f"cc job workspace does not exist: {cwd!r}")
+            return
+
+        # An untrusted cwd hangs forever on the trust dialog (no CLI flag skips
+        # it), so we provision the flag ourselves, or fail fast if that's disabled.
+        if not await asyncio.to_thread(is_workspace_trusted, cwd):
+            if self.config.provision_trust:
+                target = await asyncio.to_thread(trust_provision_target, cwd)
+                if not await asyncio.to_thread(ensure_workspace_trusted, target):
+                    await self._fail(
+                        job.id,
+                        f"cc-driver: could not provision Claude Code trust for {target} "
+                        f"(check the config at ~/.claude.json is writable and valid JSON).",
+                    )
+                    return
+            else:
+                await self._fail(
+                    job.id,
+                    f"cc-driver: workspace {cwd} is not trusted by Claude Code, so an unattended "
+                    f"session would hang on the trust prompt. Trust it once (run `claude` in {cwd} and "
+                    f"accept the prompt), or enable plugins.cc_driver.provision_trust to auto-trust it.",
+                )
+                return
+
+        pty_manager, store, on_state_change = get_terminal_runtime()
+        if pty_manager is None or store is None:
+            await self._fail(job.id, "PTY runtime not available (daemon terminal viewer not wired)")
+            return
+
+        state = self.drive_state.get(job.id)
+        if state is None:
+            state = self.drive_state.create(job.id, secrets.token_urlsafe(32))
+
+        hook_url = f"{self.config.base_url.rstrip('/')}/api/plugins/cc_driver/hook/{state.token}"
+        settings_path = write_run_settings(self.config.state_dir, job.id, build_settings(hook_url))
+
+        prompt = (
+            followup
+            if followup is not None
+            else build_initial_prompt(
+                job.prompt, self.config.completion_marker, needs_input_marker=self.config.needs_input_marker
+            )
+        )
+        cmd = build_claude_command(
+            claude,
+            str(settings_path),
+            self.config.permission_mode,
+            prompt,
+            model=(getattr(job, "model", None) or self.config.model),
+            effort=getattr(job, "effort", None) or self.config.effort,
+            ax_screen_reader=self.config.ax_screen_reader,
+            resume_session_id=state.cc_session_id if followup is not None else None,
+        )
+
+        try:
+            session = spawn_terminal(
+                store=store,
+                manager=pty_manager,
+                cmd=cmd,
+                cwd=cwd,
+                parent_session_id=None,
+                on_state_change=on_state_change,
+                sandbox_ctx=build_sandbox_ctx(
+                    self.config.sandbox, cwd, claude_binary=claude, settings_dir=settings_path.parent
+                ),
+            )
+        except Exception as e:
+            logger.exception("cc-driver: failed to spawn claude PTY for job '%s'", job.id)
+            await self._fail(job.id, f"failed to spawn claude PTY: {e}", detail=traceback.format_exc())
+            return
+
+        state.terminal_id = session.id
+        state.consecutive_continues = 0
+        self._set_worker_terminal(job.id, session.id)
+
+        proc = pty_manager.get(session.id)
+        if proc is not None:
+            loop = asyncio.get_running_loop()
+            proc.on_exit(lambda p: self._on_pty_exit(job.id, p, loop))
+
+    async def cancel(self, job) -> None:
+        """Tear down the driven session on any terminal finalize (best-effort). A
+        resolved job (done/cancelled) drops all state; a parked one (stuck/errored)
+        still kills the PTY but keeps DriveState so a retry can `--resume`."""
+        from tsugite_pty.tools import get_terminal_runtime
+
+        state = self.drive_state.get(job.id)
+        if state is not None and state.terminal_id:
+            pty_manager, _store, _cb = get_terminal_runtime()
+            if pty_manager is not None:
+                try:
+                    pty_manager.kill(state.terminal_id)
+                except Exception:
+                    logger.exception("cc-driver: failed to kill PTY for job '%s'", job.id)
+            state.terminal_id = None
+        if getattr(job, "state", None) in ("stuck", "errored"):
+            return
+        cleanup(self.config.state_dir, job.id)
+        self.drive_state.remove(job.id)
+
+    def _on_pty_exit(self, job_id: str, proc, loop) -> None:
+        """PTY-exit callback. A deliberate kill sets proc.killed and is ignored;
+        any other exit fails the worker. The buffer tail rides along as the detail
+        because the exit code alone can't convey the real error (missing binary,
+        auth failure, ...)."""
+        if getattr(proc, "killed", False):
+            return
+        reason = f"claude session exited ({describe_exit(proc.exit_code)}) before completing the task"
+        try:
+            detail = pty_tail(proc.buffer)
+        except Exception:
+            detail = None
+        if self.orchestrator is None:
+            return
+        loop.call_soon_threadsafe(
+            lambda: loop.create_task(self.orchestrator.fail_worker(job_id, reason, detail=detail))
+        )
+
+    def _set_worker_terminal(self, job_id: str, terminal_id: str) -> None:
+        """Stamp job.worker_terminal_id so the existing job tile embeds the live
+        terminal (the orchestrator prefers this field over a terminal_store lookup)."""
+        if self.orchestrator is None:
+            return
+        try:
+            self.orchestrator.attach_worker_terminal(job_id, terminal_id)
+        except Exception:
+            logger.debug("cc-driver: could not stamp worker_terminal_id for job '%s'", job_id)
+
+    async def _fail(self, job_id: str, reason: str, detail: Optional[str] = None) -> None:
+        if self.orchestrator is None:
+            logger.warning("cc-driver: no orchestrator to report failure for job '%s': %s", job_id, reason)
+            return
+        await self.orchestrator.fail_worker(job_id, reason, detail=detail)

tsugite_cc_driver-0.18.0/tsugite_cc_driver/hooks.py

@@ -0,0 +1,128 @@
+"""Pure hook-decision functions (no I/O) for the cc-driver.
+
+Each function maps a Claude Code hook payload (see hook-payloads-reference.md) to
+a decision, so the adapter's HTTP route stays a thin dispatcher and the driving
+logic is unit-testable in isolation.
+
+Driving protocol:
+  - The completion marker and "a supervisor may give follow-ups" note are baked
+    into the initial prompt (SessionStart hooks do not fire from --settings).
+  - Injected/continue text is phrased as natural task guidance. Claude refuses
+    injection-shaped instructions ("output exactly X and nothing else").
+  - `stop_hook_active` is True only on a turn we drove. False marks a fresh
+    human/CLI turn, which resets the continue budget.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+def build_initial_prompt(goal: str, completion_marker: str, *, needs_input_marker: str) -> str:
+    """The first-arg goal seed. Bakes the completion AND needs-input protocol
+    into the prompt since SessionStart can't inject it. Phrased as natural
+    guidance."""
+    return (
+        f"{goal}\n\n"
+        f"When the task is fully complete, end your reply with the token "
+        f"{completion_marker} so your supervisor knows you are done. A supervisor "
+        f"may give you follow-up instructions after you stop; keep working until "
+        f"the task genuinely meets its goal. If you are blocked on information or "
+        f"a decision you cannot obtain yourself, do not guess - end your reply "
+        f"with the line {needs_input_marker}: <your question> and stop; your "
+        f"supervisor will answer."
+    )
+
+
+def continue_instruction(completion_marker: str, needs_input_marker: str) -> str:
+    """Natural-language nudge injected via a Stop `additionalContext` block to
+    drive another turn. Never phrased as 'output exactly X' (Claude refuses that)."""
+    return (
+        "You do not appear to be finished with the task yet. Please keep working "
+        "toward the goal. When the task is genuinely complete, end your reply with "
+        f"the token {completion_marker} so your supervisor knows you are done. If "
+        f"you are blocked on something only your supervisor can answer, end your "
+        f"reply with the line {needs_input_marker}: <your question> instead of guessing."
+    )
+
+
+@dataclass
+class StopDecision:
+    """Outcome of a Stop hook: the JSON body to return to Claude plus whether the
+    attempt is finished, an optional needs-input question (a within-attempt
+    pause), and the updated continue budget the caller must persist."""
+
+    response: dict
+    complete: bool
+    summary: Optional[str]
+    new_consecutive_continues: int
+    needs_input: Optional[str] = None
+
+
+def decide_stop(
+    payload: dict,
+    *,
+    consecutive_continues: int,
+    max_consecutive_continues: int,
+    completion_marker: str,
+    needs_input_marker: str,
+) -> StopDecision:
+    """Decide what to do when Claude stops.
+
+    A fresh (human/CLI) turn resets the budget; the completion marker ends the
+    attempt (the verifier then grades it); the needs-input marker pauses the
+    attempt - checked BEFORE budget exhaustion, or a blocked worker near the
+    nudge cap would be force-completed into a verification it already knows it
+    can't pass; an exhausted continue budget also ends the attempt (maybe it IS
+    done - let the verifier decide); otherwise return a `decision: block` that
+    drives one more turn.
+    """
+    last_msg = payload.get("last_assistant_message") or ""
+    stop_hook_active = bool(payload.get("stop_hook_active"))
+    # A turn we did not drive (human/CLI) resets the continue budget.
+    count = consecutive_continues if stop_hook_active else 0
+
+    if completion_marker and completion_marker in last_msg:
+        return StopDecision(response={}, complete=True, summary=last_msg, new_consecutive_continues=count)
+
+    if needs_input_marker and needs_input_marker in last_msg:
+        question = last_msg.split(needs_input_marker, 1)[1].lstrip(":").strip()[:500]
+        return StopDecision(
+            response={},
+            complete=False,
+            summary=None,
+            new_consecutive_continues=count,
+            needs_input=question or "the worker asked for supervisor input (no question text)",
+        )
+
+    if count >= max_consecutive_continues:
+        return StopDecision(response={}, complete=True, summary=last_msg, new_consecutive_continues=count)
+
+    block = {
+        "decision": "block",
+        "hookSpecificOutput": {
+            "hookEventName": "Stop",
+            "additionalContext": continue_instruction(completion_marker, needs_input_marker),
+        },
+    }
+    return StopDecision(response=block, complete=False, summary=None, new_consecutive_continues=count + 1)
+
+
+def decide_stop_failure(payload: dict) -> str:
+    """Extract a failure reason from a StopFailure payload (a Stop hook / turn that
+    errored). The caller routes this into fail_worker."""
+    return (
+        payload.get("error")
+        or payload.get("message")
+        or payload.get("last_assistant_message")
+        or "Claude Code reported a Stop failure"
+    )
+
+
+def notification_attention(payload: dict) -> Optional[str]:
+    """Return a human-readable attention message when a Notification is a
+    permission prompt (the job may be blocked awaiting input), else None."""
+    if payload.get("notification_type") == "permission_prompt":
+        return payload.get("message") or "Claude Code needs attention"
+    return None

tsugite_cc_driver-0.18.0/tsugite_cc_driver/settings.py

@@ -0,0 +1,40 @@
+"""Per-job Claude Code settings.json builder + on-disk lifecycle.
+
+The settings file registers the three HTTP hooks the driver needs (Stop,
+StopFailure, Notification), all pointing at the plugin's per-job hook URL.
+SessionStart does not fire from --settings, so it is intentionally absent; the
+driving protocol is baked into the initial prompt instead (see hooks.py).
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+from pathlib import Path
+
+# The hook events the driver registers. Order is irrelevant to Claude Code but
+# kept stable for deterministic tests.
+HOOK_EVENTS = ("Stop", "StopFailure", "Notification")
+
+
+def build_settings(hook_url: str) -> dict:
+    """Build the Claude Code settings dict registering the driver's HTTP hooks.
+
+    Every event points at the same per-job hook URL; the receiver dispatches on
+    the payload's `hook_event_name`.
+    """
+    return {"hooks": {event: [{"hooks": [{"type": "http", "url": hook_url}]}] for event in HOOK_EVENTS}}
+
+
+def write_run_settings(state_dir: str | Path, job_id: str, settings: dict) -> Path:
+    """Write `settings` to `<state_dir>/<job_id>/settings.json` and return its path."""
+    run_dir = Path(state_dir) / job_id
+    run_dir.mkdir(parents=True, exist_ok=True)
+    path = run_dir / "settings.json"
+    path.write_text(json.dumps(settings, indent=2))
+    return path
+
+
+def cleanup(state_dir: str | Path, job_id: str) -> None:
+    """Remove the job's settings directory. Best-effort; never raises."""
+    shutil.rmtree(Path(state_dir) / job_id, ignore_errors=True)