zettcode-code-agents 0.4.6__tar.gz

zettcode_code_agents-0.4.6/.gitignore

@@ -0,0 +1,42 @@
+**/.venv/
+**/__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.smoke/
+.coverage
+**/.pytest_cache/
+**/.ruff_cache/
+.zett-tool-output/
+.env
+.DS_Store
+
+# viztracer writes its trace here by default.
+/result.json
+
+# The docs site: dependencies, build output, and VitePress' cache.
+node_modules/
+docs/.vitepress/dist/
+docs/.vitepress/cache/
+docs/.vitepress/.temp/
+
+# The TypeScript client is built from its sources; only dist/ is published.
+clients/typescript/dist/
+
+# The gateway's page is built from clients/gateway into the package when a distribution is made (`make gateway-ui`);
+# the build output is not kept in the repository. pyproject's `artifacts` puts it in the wheel all the same.
+packages/zettcode-gateway/src/zettcode/gateway/static/
+
+# The palette gallery is generated by `make palettes`: every widget painted in
+# every palette, written by docs/scripts/palette_gallery.py. Regenerate it
+# rather than committing a 2 MB copy that goes stale the moment a colour moves.
+docs/internal/palettes.html
+
+# The release order is generated from the pyproject.toml files (`make order`); it is not kept in git.
+packages/order.txt
+
+# The desktop and phone apps build the gateway's page into their own folders, and electron-builder writes its
+# installers under release/.
+clients/desktop/renderer/
+clients/desktop/release/

zettcode_code_agents-0.4.6/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chang-LeHung
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

zettcode_code_agents-0.4.6/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.5
+Name: zettcode-code-agents
+Version: 0.4.6
+Summary: Gateway plugins that run Codex and Claude Code as persistent external agents
+Project-URL: Repository, https://github.com/Chang-LeHung/zettcode/tree/main/packages/zettcode-code-agents
+Project-URL: Issues, https://github.com/Chang-LeHung/zettcode/issues
+Author: Chang-LeHung
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,claude,codex,gateway,zettcode
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Software Development :: User Interfaces
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: zettcode-broker<0.5,>=0.4.6
+Requires-Dist: zettcode-gateway<0.5,>=0.4.6
+Description-Content-Type: text/markdown
+
+# zettcode-code-agents
+
+Gateway plugins that run **Codex** and **Claude Code** as external agents. Each is a persistent CLI session: the
+session id is kept in `~/.zettcode/code-agents/` (or `$ZETTCODE_CODE_AGENTS_DIR`), so every message continues the same
+conversation.
+
+Install the package beside the gateway and restart it:
+
+```bash
+pip install zettcode-code-agents
+```
+
+The New page then offers **Codex** and **Claude Code**. Both register as `kind="external"` sessions; the gateway owner can add one to a
+group, and it can then receive and write there.
+
+The gateway only starts an agent. Where it works, how far it is trusted and which command it runs are this plugin's
+settings, kept in its own file and read again **for every message, when its turn starts**, so an edit applies to the
+next message of every agent that is already running, a queued one included. Nothing has to be restarted.
+
+## Settings
+
+`~/.zettcode/code-agents/config.json` (or the file `$ZETTCODE_CODE_AGENTS_CONFIG` names). Every key is optional:
+
+```json
+{
+  "cwd": "~/work",
+  "permission": "full",
+  "timeout": 900,
+  "codex": { "cwd": "~/work/api", "permission": "workspace" },
+  "claude": { "bin": "/opt/bin/claude" }
+}
+```
+
+A key inside `"codex"` or `"claude"` wins over the same key at the top, which wins over the environment variable of the
+same setting, which wins over the default. `bin`, `args` and `resume_args` belong to one tool and are set only inside its
+section.
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `cwd` | the gateway process's directory | The folder the CLI runs in. It must exist. A relative path is taken from the gateway process's folder, not from this file's. |
+| `permission` | `full` | How far the agent is trusted: `full`, `workspace` or `read`. |
+| `timeout` | `900` | Seconds one turn may take before it is stopped. |
+| `bin`, `args`, `resume_args` | see below | The command, per tool. |
+
+### Permission
+
+The default is `full`: the agent runs on its own and may do anything you may, because nobody is there to answer a
+prompt. **That is the plugin's choice, not the gateway's**: starting the gateway with `--no-full` limits the daemons it
+starts and does not limit these agents. Set `"permission"` to `workspace` or `read` to narrow them.
+
+| `permission` | Codex | Claude Code |
+| --- | --- | --- |
+| `full` | `--dangerously-bypass-approvals-and-sandbox` | `--permission-mode bypassPermissions` |
+| `workspace` | `--sandbox workspace-write` | `--permission-mode acceptEdits` |
+| `read` | `--sandbox read-only` | `--permission-mode plan` |
+
+`codex exec resume` takes no `--sandbox` (checked against `codex-cli 0.160.1`: it answers "unexpected argument"), so a
+resumed Codex turn is given the same choice as a configuration override, `-c sandbox_mode="workspace-write"` (or
+`"read-only"`). That flag is **accepted** by the CLI; that it **limits** a resumed run the way `--sandbox` limits the
+first one has not been verified. If you rely on `workspace` or `read` for Codex, send a second message that tries to
+write outside the folder and see that it is refused, before you trust it.
+
+A setting that cannot be used (invalid JSON, a folder that does not exist, an unknown level, a command that names
+a word it is not given, or `{permission}` written inside another word such as `--sandbox={permission}`) fails that
+message with a sentence naming the file and the key, in the agent's reply. Mend the file and send again.
+
+## Commands
+
+The commands are also configurable from the environment, which the `args` and `resume_args` keys override:
+
+| Variable | Default |
+| --- | --- |
+| `ZETTCODE_CODEX_BIN` | `codex` |
+| `ZETTCODE_CODEX_ARGS` | `exec --json --skip-git-repo-check {permission} {prompt}` |
+| `ZETTCODE_CODEX_RESUME_ARGS` | `exec resume {session} --json {permission} {prompt}` |
+| `ZETTCODE_CLAUDE_BIN` | `claude` |
+| `ZETTCODE_CLAUDE_ARGS` | `{permission} -p {prompt} --output-format json --session-id {session}` |
+| `ZETTCODE_CLAUDE_RESUME_ARGS` | `{permission} -p {prompt} --output-format json --resume {session}` |
+| `ZETTCODE_CODE_AGENTS_CWD` | the gateway process's directory |
+| `ZETTCODE_CODE_AGENTS_DIR` | `~/.zettcode/code-agents` |
+| `ZETTCODE_CODE_AGENTS_CONFIG` | `config.json` in that directory |
+| `ZETTCODE_CODE_AGENTS_QUEUE` | `4` turns waiting (read when the agent starts) |
+| `ZETTCODE_CODE_AGENTS_TIMEOUT` | `900` seconds |
+
+Arguments are split with `shlex`, never run by a shell, and receive `{prompt}`, `{session}` and `{cwd}`. The word
+`{permission}` on its own stands for the arguments of the chosen level; a command you write without it is run exactly
+as written, with no trust arguments added.
+
+The CLIs must be installed and signed in for the user running the gateway.

zettcode_code_agents-0.4.6/README.md

@@ -0,0 +1,89 @@
+# zettcode-code-agents
+
+Gateway plugins that run **Codex** and **Claude Code** as external agents. Each is a persistent CLI session: the
+session id is kept in `~/.zettcode/code-agents/` (or `$ZETTCODE_CODE_AGENTS_DIR`), so every message continues the same
+conversation.
+
+Install the package beside the gateway and restart it:
+
+```bash
+pip install zettcode-code-agents
+```
+
+The New page then offers **Codex** and **Claude Code**. Both register as `kind="external"` sessions; the gateway owner can add one to a
+group, and it can then receive and write there.
+
+The gateway only starts an agent. Where it works, how far it is trusted and which command it runs are this plugin's
+settings, kept in its own file and read again **for every message, when its turn starts**, so an edit applies to the
+next message of every agent that is already running, a queued one included. Nothing has to be restarted.
+
+## Settings
+
+`~/.zettcode/code-agents/config.json` (or the file `$ZETTCODE_CODE_AGENTS_CONFIG` names). Every key is optional:
+
+```json
+{
+  "cwd": "~/work",
+  "permission": "full",
+  "timeout": 900,
+  "codex": { "cwd": "~/work/api", "permission": "workspace" },
+  "claude": { "bin": "/opt/bin/claude" }
+}
+```
+
+A key inside `"codex"` or `"claude"` wins over the same key at the top, which wins over the environment variable of the
+same setting, which wins over the default. `bin`, `args` and `resume_args` belong to one tool and are set only inside its
+section.
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `cwd` | the gateway process's directory | The folder the CLI runs in. It must exist. A relative path is taken from the gateway process's folder, not from this file's. |
+| `permission` | `full` | How far the agent is trusted: `full`, `workspace` or `read`. |
+| `timeout` | `900` | Seconds one turn may take before it is stopped. |
+| `bin`, `args`, `resume_args` | see below | The command, per tool. |
+
+### Permission
+
+The default is `full`: the agent runs on its own and may do anything you may, because nobody is there to answer a
+prompt. **That is the plugin's choice, not the gateway's**: starting the gateway with `--no-full` limits the daemons it
+starts and does not limit these agents. Set `"permission"` to `workspace` or `read` to narrow them.
+
+| `permission` | Codex | Claude Code |
+| --- | --- | --- |
+| `full` | `--dangerously-bypass-approvals-and-sandbox` | `--permission-mode bypassPermissions` |
+| `workspace` | `--sandbox workspace-write` | `--permission-mode acceptEdits` |
+| `read` | `--sandbox read-only` | `--permission-mode plan` |
+
+`codex exec resume` takes no `--sandbox` (checked against `codex-cli 0.160.1`: it answers "unexpected argument"), so a
+resumed Codex turn is given the same choice as a configuration override, `-c sandbox_mode="workspace-write"` (or
+`"read-only"`). That flag is **accepted** by the CLI; that it **limits** a resumed run the way `--sandbox` limits the
+first one has not been verified. If you rely on `workspace` or `read` for Codex, send a second message that tries to
+write outside the folder and see that it is refused, before you trust it.
+
+A setting that cannot be used (invalid JSON, a folder that does not exist, an unknown level, a command that names
+a word it is not given, or `{permission}` written inside another word such as `--sandbox={permission}`) fails that
+message with a sentence naming the file and the key, in the agent's reply. Mend the file and send again.
+
+## Commands
+
+The commands are also configurable from the environment, which the `args` and `resume_args` keys override:
+
+| Variable | Default |
+| --- | --- |
+| `ZETTCODE_CODEX_BIN` | `codex` |
+| `ZETTCODE_CODEX_ARGS` | `exec --json --skip-git-repo-check {permission} {prompt}` |
+| `ZETTCODE_CODEX_RESUME_ARGS` | `exec resume {session} --json {permission} {prompt}` |
+| `ZETTCODE_CLAUDE_BIN` | `claude` |
+| `ZETTCODE_CLAUDE_ARGS` | `{permission} -p {prompt} --output-format json --session-id {session}` |
+| `ZETTCODE_CLAUDE_RESUME_ARGS` | `{permission} -p {prompt} --output-format json --resume {session}` |
+| `ZETTCODE_CODE_AGENTS_CWD` | the gateway process's directory |
+| `ZETTCODE_CODE_AGENTS_DIR` | `~/.zettcode/code-agents` |
+| `ZETTCODE_CODE_AGENTS_CONFIG` | `config.json` in that directory |
+| `ZETTCODE_CODE_AGENTS_QUEUE` | `4` turns waiting (read when the agent starts) |
+| `ZETTCODE_CODE_AGENTS_TIMEOUT` | `900` seconds |
+
+Arguments are split with `shlex`, never run by a shell, and receive `{prompt}`, `{session}` and `{cwd}`. The word
+`{permission}` on its own stands for the arguments of the chosen level; a command you write without it is run exactly
+as written, with no trust arguments added.
+
+The CLIs must be installed and signed in for the user running the gateway.

zettcode_code_agents-0.4.6/pyproject.toml

@@ -0,0 +1,61 @@
+[project]
+name = "zettcode-code-agents"
+description = "Gateway plugins that run Codex and Claude Code as persistent external agents"
+readme = "README.md"
+requires-python = ">=3.10"
+dynamic = ["version"]
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "Chang-LeHung"}]
+keywords = ["zettcode", "gateway", "codex", "claude", "agents"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: 3.15",
+  "Topic :: Software Development :: User Interfaces",
+  "Typing :: Typed",
+]
+dependencies = [
+  "zettcode-broker>=0.4.6,<0.5",
+  "zettcode-gateway>=0.4.6,<0.5",
+]
+
+[project.urls]
+Repository = "https://github.com/Chang-LeHung/zettcode/tree/main/packages/zettcode-code-agents"
+Issues = "https://github.com/Chang-LeHung/zettcode/issues"
+
+[project.entry-points."zettcode.gateway.external"]
+codex = "zettcode.code_agents:CodexAgent"
+claude = "zettcode.code_agents:ClaudeCodeAgent"
+
+[tool.zettcode]
+# A gateway plugin: installed beside the program, released on the plugin line.
+plugin = true
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "src/zettcode/code_agents/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/zettcode"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/tests", "/README.md", "/LICENSE", "/pyproject.toml"]
+
+[dependency-groups]
+# What the tests import beyond the plugin itself; the release workflow installs exactly this into the fresh environment it
+# tests the built plugin in, so a name missing here passes `make test` (the workspace has it) and fails the release. The
+# turns are `async def`, which needs pytest-asyncio.
+dev = ["pytest>=8,<9", "pytest-asyncio>=0.26,<2"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

zettcode_code_agents-0.4.6/src/zettcode/code_agents/__init__.py

@@ -0,0 +1,343 @@
+"""Codex and Claude Code as persistent gateway agents.
+
+Each is an :class:`~zettcode.broker.external.ExternalSession` of its own whose handler runs the tool's own CLI.
+The CLI's session id is kept in ``~/.zettcode/code-agents`` (or ``$ZETTCODE_CODE_AGENTS_DIR``), so the next message
+continues the same conversation. The gateway only sees ordinary external sessions; nothing here re-implements a
+model, a tool loop or a conversation store.
+
+The commands can be changed without changing this package, and so can where the agents work and how far they are
+trusted: see :mod:`zettcode.code_agents.config`. Those settings live in ``~/.zettcode/code-agents/config.json`` and are
+read again for every message, so an edit applies to the next one with no restart. The environment variables still work
+for the command itself:
+
+* ``ZETTCODE_CODEX_ARGS`` / ``ZETTCODE_CODEX_RESUME_ARGS``
+* ``ZETTCODE_CLAUDE_ARGS`` / ``ZETTCODE_CLAUDE_RESUME_ARGS``
+
+They are split with :mod:`shlex` and receive ``{prompt}``, ``{session}`` and ``{cwd}``; they are never run by a shell.
+The word ``{permission}`` on its own stands for the arguments of the trust level the settings choose.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import json
+import math
+import os
+import shlex
+import signal
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from zettcode.broker.external import ExternalSession
+from zettcode.broker.models import Incoming, Receipt
+from zettcode.broker.protocol import KIND_EXTERNAL
+from zettcode.code_agents.config import (
+    TIMEOUT,
+    ConfigError,
+    Settings,
+    Tool,
+    resolve,
+    state_directory,
+    work_directory,
+)
+from zettcode.gateway.agents import AgentPlugin
+
+#: The one place this plugin's version is written.
+__version__ = "0.4.6"
+
+
+def _timeout() -> float:
+    """Return how long one turn may run without a setting, read from the environment and checked before use."""
+    raw = os.environ.get("ZETTCODE_CODE_AGENTS_TIMEOUT", str(TIMEOUT))
+    try:
+        value = float(raw)
+    except ValueError:
+        raise RuntimeError(f"ZETTCODE_CODE_AGENTS_TIMEOUT must be a number of seconds, not {raw!r}") from None
+    if not math.isfinite(value) or value <= 0:
+        raise RuntimeError("ZETTCODE_CODE_AGENTS_TIMEOUT must be a positive number of seconds")
+    return value
+
+
+def _logo(name: str) -> str:
+    """Return one of the package's brand marks as a data URL."""
+    path = Path(__file__).with_name("logos") / name
+    try:
+        return "data:image/svg+xml;base64," + base64.b64encode(path.read_bytes()).decode()
+    except OSError:
+        return ""
+
+
+@dataclass(frozen=True, slots=True)
+class Command:
+    """One tool's command line, new and resumed."""
+
+    binary: str
+    new_args: str
+    resume_args: str
+
+    def argv(
+        self, prompt: str, session: str, cwd: Path, *, resume: bool = True, permission: tuple[str, ...] = ()
+    ) -> list[str]:
+        """Return the command to run. The word ``{permission}``, alone, becomes the arguments of the trust level.
+
+        A template without that word is the person's own command line and is run exactly as written.
+        """
+        template = self.resume_args if resume and session and "{session}" in self.resume_args else self.new_args
+        values = {"prompt": prompt, "session": session, "cwd": str(cwd)}
+        argv = [self.binary]
+        for part in shlex.split(template):
+            if part == "{permission}":
+                argv.extend(permission)
+            else:
+                argv.append(part.format(**values))
+        return argv
+
+
+@dataclass(frozen=True, slots=True)
+class Launch:
+    """What one turn runs with: the command, where, for how long, and the trust arguments for a new and a resumed turn."""
+
+    command: Command
+    cwd: Path
+    timeout: float
+    new_flags: tuple[str, ...]
+    resume_flags: tuple[str, ...]
+
+
+def _events(stdout: str) -> tuple[str, str]:
+    """Return the last text and session id in a JSON or JSONL answer."""
+    text = ""
+    session = ""
+    for line in stdout.splitlines():
+        try:
+            event = json.loads(line)
+        except ValueError:
+            continue
+        if not isinstance(event, dict):
+            continue
+        for key in ("session_id", "thread_id"):
+            value = event.get(key)
+            if isinstance(value, str) and value:
+                session = value
+        for key in ("result", "text", "message", "content"):
+            value = event.get(key)
+            if isinstance(value, str) and value.strip():
+                text = value
+        item = event.get("item")
+        if isinstance(item, dict) and isinstance(item.get("text"), str):
+            text = item["text"]
+    return text, session
+
+
+class CliAgent(ExternalSession):
+    """An external session whose one handler runs a CLI and keeps its session id."""
+
+    def __init__(self, session_id: str, title: str, source: Tool | Command) -> None:
+        self._turns: set[asyncio.Task[None]] = set()
+        self._limit = max(1, int(os.environ.get("ZETTCODE_CODE_AGENTS_QUEUE", "4")))
+        super().__init__(session_id, title, kind=KIND_EXTERNAL, on_message=self._start_turn)
+        #: A tool's settings are read again for every turn; a bare command (a caller's own) is run as it is given.
+        self.source = source
+        self.state = state_directory() / f"{session_id}.json"
+        self._lock = asyncio.Lock()
+        self._process: asyncio.subprocess.Process | None = None
+
+    def _start_turn(self, message: Incoming) -> Receipt:
+        """Answer the broker now and run one CLI turn on a task."""
+        if len(self._turns) >= self._limit:
+            return Receipt(False, reason=f"{self.title} has {self._limit} turns waiting", busy=True)
+        task = asyncio.ensure_future(self._turn(message))
+        self._turns.add(task)
+        task.add_done_callback(self._turns.discard)
+        return Receipt(True, disposition="queued")
+
+    async def _turn(self, message: Incoming) -> None:
+        async with self._lock:
+            await self.set_status("working")
+            try:
+                answer = await self._run(message.text)
+            except Exception as error:  # noqa: BLE001 - the person gets the reason, the agent stays alive
+                answer = f"{self.title} failed: {error}"
+            finally:
+                await self.set_status("idle")
+            if message.group:
+                await self.send_group(message.group, answer)
+            else:
+                await self.reply(message, answer)
+
+    def _resolve(self) -> Launch:
+        """Return what this turn runs with, read now: a person's edit of the settings applies from the next message."""
+        source = self.source
+        if isinstance(source, Command):
+            return Launch(source, work_directory(), _timeout(), (), ())
+        settings: Settings = resolve(source, timeout=_timeout())
+        command = Command(settings.binary, settings.args, settings.resume_args)
+        return Launch(
+            command,
+            settings.cwd,
+            settings.timeout,
+            source.flags[settings.permission],
+            source.resume_flags[settings.permission],
+        )
+
+    async def _run(self, prompt: str) -> str:
+        launch = self._resolve()
+        command, timeout = launch.command, launch.timeout
+        session = self._session()
+        resumed = bool(session)
+        if not session and "session-id" in command.new_args:
+            session = str(uuid.uuid4())
+        # The trust arguments follow the template that is used: a resume template without {session} is the new one.
+        continuing = resumed and "{session}" in command.resume_args
+        argv = command.argv(
+            prompt,
+            session,
+            launch.cwd,
+            resume=resumed,
+            permission=launch.resume_flags if continuing else launch.new_flags,
+        )
+        options: dict[str, Any] = {}
+        if os.name != "nt":
+            options["start_new_session"] = True
+        self._process = await asyncio.create_subprocess_exec(
+            *argv,
+            cwd=str(launch.cwd),
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            **options,
+        )
+        process = self._process
+        try:
+            stdout, stderr = await asyncio.wait_for(process.communicate(), timeout)
+        except asyncio.TimeoutError:
+            self._kill(process)
+            await process.wait()
+            raise RuntimeError(f"the {self.title} command did not finish in {timeout:g} seconds") from None
+        finally:
+            self._process = None
+        output = stdout.decode(errors="replace")
+        error = stderr.decode(errors="replace").strip()
+        if process.returncode not in (None, 0):
+            raise RuntimeError(error or f"exit code {process.returncode}")
+        text, found = _events(output)
+        if found:
+            self._save(found)
+        if text:
+            return text
+        if output.strip():
+            return output.strip()
+        raise RuntimeError(error or "the command said nothing")
+
+    async def close(self) -> None:
+        """Stop a running CLI process before closing the session."""
+        process, self._process = self._process, None
+        tasks, self._turns = list(self._turns), set()
+        for task in tasks:
+            task.cancel()
+        if tasks:
+            await asyncio.gather(*tasks, return_exceptions=True)
+        if process is not None and process.returncode is None:
+            self._kill(process)
+            await process.wait()
+        await super().close()
+
+    @staticmethod
+    def _kill(process: asyncio.subprocess.Process) -> None:
+        """Kill the CLI and the children it forked, when the platform gives the process a session."""
+        if os.name == "nt":
+            process.kill()
+            return
+        try:
+            os.killpg(os.getpgid(process.pid), signal.SIGKILL)
+        except (ProcessLookupError, PermissionError):
+            process.kill()
+
+    def _session(self) -> str:
+        try:
+            data = json.loads(self.state.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            return ""
+        value = data.get("session") if isinstance(data, dict) else None
+        return value if isinstance(value, str) else ""
+
+    def _save(self, session: str) -> None:
+        self.state.parent.mkdir(parents=True, exist_ok=True)
+        temporary = self.state.with_suffix(".tmp")
+        temporary.write_text(json.dumps({"session": session}), encoding="utf-8")
+        os.replace(temporary, self.state)
+
+
+_CODEX_FULL = ("--dangerously-bypass-approvals-and-sandbox",)
+
+#: Codex. ``exec`` takes ``--sandbox``; ``exec resume`` does not, and takes the same choice as a config override.
+CODEX = Tool(
+    name="codex",
+    env="ZETTCODE_CODEX",
+    binary="codex",
+    args="exec --json --skip-git-repo-check {permission} {prompt}",
+    resume_args="exec resume {session} --json {permission} {prompt}",
+    flags={
+        "full": _CODEX_FULL,
+        "workspace": ("--sandbox", "workspace-write"),
+        "read": ("--sandbox", "read-only"),
+    },
+    resume_flags={
+        "full": _CODEX_FULL,
+        "workspace": ("-c", 'sandbox_mode="workspace-write"'),
+        "read": ("-c", 'sandbox_mode="read-only"'),
+    },
+)
+
+_CLAUDE_FLAGS = {
+    "full": ("--permission-mode", "bypassPermissions"),
+    "workspace": ("--permission-mode", "acceptEdits"),
+    "read": ("--permission-mode", "plan"),
+}
+
+#: Claude Code, which takes the same ``--permission-mode`` for a new conversation and a resumed one.
+CLAUDE = Tool(
+    name="claude",
+    env="ZETTCODE_CLAUDE",
+    binary="claude",
+    args="{permission} -p {prompt} --output-format json --session-id {session}",
+    resume_args="{permission} -p {prompt} --output-format json --resume {session}",
+    flags=_CLAUDE_FLAGS,
+    resume_flags=_CLAUDE_FLAGS,
+)
+
+
+class CodexAgent(AgentPlugin):
+    name = CODEX.name
+    title = "Codex"
+    description = "OpenAI Codex CLI, in the same session every time"
+    avatar = _logo("codex.svg")
+
+    def create(self, session_id: str, title: str) -> ExternalSession:
+        return CliAgent(session_id, title, CODEX)
+
+
+class ClaudeCodeAgent(AgentPlugin):
+    name = CLAUDE.name
+    title = "Claude Code"
+    description = "Anthropic Claude Code, in the same session every time"
+    avatar = _logo("claude.svg")
+
+    def create(self, session_id: str, title: str) -> ExternalSession:
+        return CliAgent(session_id, title, CLAUDE)
+
+
+__all__ = [
+    "CLAUDE",
+    "CODEX",
+    "ClaudeCodeAgent",
+    "CliAgent",
+    "CodexAgent",
+    "Command",
+    "ConfigError",
+    "Launch",
+    "state_directory",
+    "work_directory",
+]

zettcode_code_agents-0.4.6/src/zettcode/code_agents/config.py

@@ -0,0 +1,199 @@
+"""The settings of the Codex and Claude Code agents, which belong to this plugin and not to the gateway.
+
+The gateway only starts an agent. Where it works, how far it is trusted and which command it runs are written in one
+JSON file, ``~/.zettcode/code-agents/config.json`` (``$ZETTCODE_CODE_AGENTS_CONFIG`` names another), and the file is
+read again when each message arrives, so an edit applies to the next message of every agent that is already running::
+
+    {
+      "cwd": "~/work",
+      "permission": "full",
+      "timeout": 900,
+      "codex": {"cwd": "~/work/api", "permission": "workspace"},
+      "claude": {"bin": "/opt/bin/claude"}
+    }
+
+A key inside ``"codex"`` or ``"claude"`` wins over the same key at the top; that wins over the environment variable
+this plugin read before there was a file; that wins over the default. ``bin``, ``args`` and ``resume_args`` belong to
+one tool and have no top-level form. A relative ``cwd`` is taken from the gateway process's folder, not the file's.
+
+``permission`` is how far the agent is trusted, and the plugin turns it into the arguments each CLI takes:
+
+* ``full`` (the default): the agent may do anything the user may, with nothing asked.
+* ``workspace``: it may write inside its folder; the rest of the machine is read-only or closed.
+* ``read``: it may look and not change.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import os
+import shlex
+import string
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+#: The trust levels, safest last. Each tool maps every one of them to its own arguments.
+PERMISSIONS = ("full", "workspace", "read")
+
+#: What an agent is trusted with when nothing says otherwise: it runs on its own, and nobody is there to answer a prompt.
+DEFAULT_PERMISSION = "full"
+
+#: How long one CLI turn may take before it is stopped.
+TIMEOUT = 900.0
+
+
+class ConfigError(RuntimeError):
+    """The settings cannot be used. The sentence names the file and the key, so it can be shown to the person as is."""
+
+
+def state_directory() -> Path:
+    """Return where the CLI session ids and the settings are kept."""
+    return Path(os.environ.get("ZETTCODE_CODE_AGENTS_DIR", str(Path.home() / ".zettcode" / "code-agents"))).expanduser()
+
+
+def work_directory() -> Path:
+    """Return the directory the CLI runs in when the settings do not name one."""
+    return Path(os.environ.get("ZETTCODE_CODE_AGENTS_CWD", str(Path.cwd()))).expanduser()
+
+
+def config_path() -> Path:
+    """Return the settings file."""
+    return Path(os.environ.get("ZETTCODE_CODE_AGENTS_CONFIG", str(state_directory() / "config.json"))).expanduser()
+
+
+@dataclass(frozen=True, slots=True)
+class Tool:
+    """What is known about one CLI before any settings: its name, its default command and what each trust level adds."""
+
+    name: str
+    #: The prefix of the environment variables that set this tool's command (``ZETTCODE_CODEX`` for ``_BIN``...).
+    env: str
+    binary: str
+    args: str
+    resume_args: str
+    #: The arguments each permission adds to a new conversation, and to a resumed one (a CLI may differ).
+    flags: Mapping[str, tuple[str, ...]]
+    resume_flags: Mapping[str, tuple[str, ...]]
+
+
+@dataclass(frozen=True, slots=True)
+class Settings:
+    """Everything one CLI turn runs with, resolved from the file, the environment and the defaults at that moment."""
+
+    cwd: Path
+    permission: str
+    timeout: float
+    binary: str
+    args: str
+    resume_args: str
+
+
+def read_config() -> dict[str, Any]:
+    """Read the settings file now. A missing or empty file is no settings; one that cannot be used is a ConfigError."""
+    path = config_path()
+    try:
+        text = path.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        return {}
+    except OSError as error:
+        raise ConfigError(f"{path} cannot be read: {error.strerror or error}") from error
+    if not text.strip():
+        return {}
+    try:
+        data = json.loads(text)
+    except ValueError as error:
+        raise ConfigError(f"{path} is not valid JSON: {error}") from None
+    if not isinstance(data, dict):
+        raise ConfigError(f"{path} must hold one JSON object")
+    return data
+
+
+def _text(key: str, value: object) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise ConfigError(f'"{key}" in {config_path()} must be a non-empty string')
+    return value
+
+
+#: The words a command template may name besides ``{permission}``, which must stand alone.
+_FIELDS = frozenset({"prompt", "session", "cwd"})
+
+
+def _template(key: str, value: object) -> str:
+    """Return a command template, refusing one that would fail on every message.
+
+    ``{permission}`` becomes several arguments, so it can only be a word of its own (``--sandbox={permission}`` cannot
+    work); any other word it names must be one the command is given. Both are caught here, once, naming the key.
+    """
+    text = _text(key, value)
+    where = f'"{key}" in {config_path()}'
+    try:
+        parts = shlex.split(text)
+    except ValueError as error:
+        raise ConfigError(f"{where} is not a command line: {error}") from None
+    for part in parts:
+        if part == "{permission}":
+            continue
+        try:
+            names = [name for _, name, _, _ in string.Formatter().parse(part) if name is not None]
+        except ValueError as error:
+            raise ConfigError(f"{where} has a word that cannot be filled in, {part!r}: {error}") from None
+        for name in names:
+            field = name.split(".")[0].split("[")[0]
+            if field == "permission":
+                raise ConfigError(f"{where}: {{permission}} must be a word of its own, not part of {part!r}")
+            if field not in _FIELDS:
+                raise ConfigError(
+                    f"{where} names {{{field}}}, which is not one of {{prompt}}, {{session}}, {{cwd}} or {{permission}}"
+                )
+    return text
+
+
+def resolve(tool: Tool, *, timeout: float = TIMEOUT) -> Settings:
+    """Return the settings of one tool as they are now.
+
+    Args:
+        tool: The CLI.
+        timeout: The timeout when neither the file nor the tool's section sets one.
+
+    Raises:
+        ConfigError: The file cannot be read or parsed, a value has the wrong type, ``permission`` is not a level, or
+            ``cwd`` is not a folder.
+    """
+    data = read_config()
+    section = data.get(tool.name, {})
+    if not isinstance(section, dict):
+        raise ConfigError(f'"{tool.name}" in {config_path()} must be an object')
+
+    def value(key: str, fallback: object, *, shared: bool = True) -> object:
+        if key in section:
+            return section[key]
+        if shared and key in data:
+            return data[key]
+        return fallback
+
+    folder = Path(_text("cwd", value("cwd", str(work_directory())))).expanduser().resolve()
+    if not folder.is_dir():
+        raise ConfigError(f'the folder {folder} ("cwd" in {config_path()}) does not exist')
+
+    permission = _text("permission", value("permission", DEFAULT_PERMISSION))
+    if permission not in tool.flags:
+        raise ConfigError(f'"permission" in {config_path()} is full, workspace or read, not {permission!r}')
+
+    limit = value("timeout", timeout)
+    if isinstance(limit, bool) or not isinstance(limit, (int, float)) or not math.isfinite(limit) or limit <= 0:
+        raise ConfigError(f'"timeout" in {config_path()} must be a positive number of seconds')
+
+    return Settings(
+        cwd=folder,
+        permission=permission,
+        timeout=float(limit),
+        binary=_text("bin", value("bin", os.environ.get(f"{tool.env}_BIN", tool.binary), shared=False)),
+        args=_template("args", value("args", os.environ.get(f"{tool.env}_ARGS", tool.args), shared=False)),
+        resume_args=_template(
+            "resume_args",
+            value("resume_args", os.environ.get(f"{tool.env}_RESUME_ARGS", tool.resume_args), shared=False),
+        ),
+    )

zettcode_code_agents-0.4.6/src/zettcode/code_agents/logos/claude.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
+  <title>Claude</title>
+  <rect width="24" height="24" rx="5" fill="#F0EEE6"/>
+  <path d="M4.709 15.955l4.72-2.647.08-.23-.08-.128H9.2l-.79-.048-2.698-.073-2.339-.097-2.266-.122-.571-.121L0 11.784l.055-.352.48-.321.686.06 1.52.103 2.278.158 1.652.097 2.449.255h.389l.055-.157-.134-.098-.103-.097-2.358-1.596-2.552-1.688-1.336-.972-.724-.491-.364-.462-.158-1.008.656-.722.881.06.225.061.893.686 1.908 1.476 2.491 1.833.365.304.145-.103.019-.073-.164-.274-1.355-2.446-1.446-2.49-.644-1.032-.17-.619a2.97 2.97 0 01-.104-.729L6.283.134 6.696 0l.996.134.42.364.62 1.414 1.002 2.229 1.555 3.03.456.898.243.832.091.255h.158V9.01l.128-1.706.237-2.095.23-2.695.08-.76.376-.91.747-.492.584.28.48.685-.067.444-.286 1.851-.559 2.903-.364 1.942h.212l.243-.242.985-1.306 1.652-2.064.73-.82.85-.904.547-.431h1.033l.76 1.129-.34 1.166-1.064 1.347-.881 1.142-1.264 1.7-.79 1.36.073.11.188-.02 2.856-.606 1.543-.28 1.841-.315.833.388.091.395-.328.807-1.969.486-2.309.462-3.439.813-.042.03.049.061 1.549.146.662.036h1.622l3.02.225.79.522.474.638-.079.485-1.215.62-1.64-.389-3.829-.91-1.312-.329h-.182v.11l1.093 1.068 2.006 1.81 2.509 2.33.127.578-.322.455-.34-.049-2.205-1.657-.851-.747-1.926-1.62h-.128v.17l.444.649 2.345 3.521.122 1.08-.17.353-.608.213-.668-.122-1.374-1.925-1.415-2.167-1.143-1.943-.14.08-.674 7.254-.316.37-.729.28-.607-.461-.322-.747.322-1.476.389-1.924.315-1.53.286-1.9.17-.632-.012-.042-.14.018-1.434 1.967-2.18 2.945-1.726 1.845-.414.164-.717-.37.067-.662.401-.589 2.388-3.036 1.44-1.882.93-1.086-.006-.158h-.055L4.132 18.56l-1.13.146-.487-.456.061-.746.231-.243 1.908-1.312-.006.006z" fill="#D97757" fill-rule="nonzero"/>
+</svg>

zettcode_code_agents-0.4.6/src/zettcode/code_agents/logos/codex.svg

@@ -0,0 +1,12 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
+  <title>Codex</title>
+  <rect width="24" height="24" rx="5" fill="#ffffff"/>
+  <path d="M9.064 3.344a4.578 4.578 0 012.285-.312c1 .115 1.891.54 2.673 1.275.01.01.024.017.037.021a.09.09 0 00.043 0 4.55 4.55 0 013.046.275l.047.022.116.057a4.581 4.581 0 012.188 2.399c.209.51.313 1.041.315 1.595a4.24 4.24 0 01-.134 1.223.123.123 0 00.03.115c.594.607.988 1.33 1.183 2.17.289 1.425-.007 2.71-.887 3.854l-.136.166a4.548 4.548 0 01-2.201 1.388.123.123 0 00-.081.076c-.191.551-.383 1.023-.74 1.494-.9 1.187-2.222 1.846-3.711 1.838-1.187-.006-2.239-.44-3.157-1.302a.107.107 0 00-.105-.024c-.388.125-.78.143-1.204.138a4.441 4.441 0 01-1.945-.466 4.544 4.544 0 01-1.61-1.335c-.152-.202-.303-.392-.414-.617a5.81 5.81 0 01-.37-.961 4.582 4.582 0 01-.014-2.298.124.124 0 00.006-.056.085.085 0 00-.027-.048 4.467 4.467 0 01-1.034-1.651 3.896 3.896 0 01-.251-1.192 5.189 5.189 0 01.141-1.6c.337-1.112.982-1.985 1.933-2.618.212-.141.413-.251.601-.33.215-.089.43-.164.646-.227a.098.098 0 00.065-.066 4.51 4.51 0 01.829-1.615 4.535 4.535 0 011.837-1.388zm3.482 10.565a.637.637 0 000 1.272h3.636a.637.637 0 100-1.272h-3.636zM8.462 9.23a.637.637 0 00-1.106.631l1.272 2.224-1.266 2.136a.636.636 0 101.095.649l1.454-2.455a.636.636 0 00.005-.64L8.462 9.23z" fill="url(#codex-gradient)"/>
+  <defs>
+    <linearGradient id="codex-gradient" gradientUnits="userSpaceOnUse" x1="12" x2="12" y1="3" y2="21">
+      <stop stop-color="#B1A7FF"/>
+      <stop offset=".5" stop-color="#7A9DFF"/>
+      <stop offset="1" stop-color="#3941FF"/>
+    </linearGradient>
+  </defs>
+</svg>

zettcode_code_agents-0.4.6/tests/test_code_agents.py

@@ -0,0 +1,305 @@
+"""The CLI command shape and the two gateway plugins."""
+
+from __future__ import annotations
+
+import asyncio
+import dataclasses
+import json
+import os
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from zettcode.code_agents import (
+    CLAUDE,
+    CODEX,
+    ClaudeCodeAgent,
+    CliAgent,
+    CodexAgent,
+    Command,
+    ConfigError,
+    _events,
+    _timeout,
+)
+from zettcode.code_agents.config import DEFAULT_PERMISSION, resolve
+
+
+class _Done:
+    """A finished child process, as ``asyncio.create_subprocess_exec`` hands one back."""
+
+    returncode = 0
+
+    def __init__(self, stdout: str) -> None:
+        self._stdout = stdout
+
+    async def communicate(self) -> tuple[bytes, bytes]:
+        return self._stdout.encode(), b""
+
+    async def wait(self) -> int:
+        return 0
+
+
+@pytest.fixture
+def cli(monkeypatch) -> Callable[[Callable[[list[str], Path], str]], None]:
+    """Replace starting a program with a function from ``(argv, cwd)`` to what the program prints.
+
+    The plugin's own work is building the command line, choosing the folder, and keeping the session the CLI names. None of
+    that needs a real program, and a script cannot stand in for one on every platform (Windows will not run a file that is
+    not an executable), so the tests that are about those things use this; one test below runs a real child on POSIX.
+    """
+
+    def install(program: Callable[[list[str], Path], str]) -> None:
+        async def start(*argv: str, cwd: str, **_: Any) -> _Done:
+            return _Done(program(list(argv), Path(cwd)))
+
+        monkeypatch.setattr(asyncio, "create_subprocess_exec", start)
+
+    return install
+
+
+def test_a_command_uses_the_resume_form_when_a_session_is_known(tmp_path):
+    command = Command(
+        "claude",
+        "-p {prompt} --session-id {session}",
+        "-p {prompt} --resume {session}",
+    )
+
+    assert command.argv("hello", "new-id", tmp_path, resume=False) == [
+        "claude",
+        "-p",
+        "hello",
+        "--session-id",
+        "new-id",
+    ]
+    assert command.argv("hello", "abc", tmp_path) == ["claude", "-p", "hello", "--resume", "abc"]
+
+
+def test_the_json_answer_and_session_id_are_read():
+    stdout = "\n".join(
+        json.dumps(event)
+        for event in (
+            {"session_id": "s-1", "result": ""},
+            {"type": "item.completed", "item": {"text": "done"}},
+        )
+    )
+
+    assert _events(stdout) == ("done", "s-1")
+
+
+def test_both_plugins_carry_a_name_and_a_logo():
+    assert CodexAgent.name == "codex" and CodexAgent.avatar.startswith("data:image/svg+xml;base64,")
+    assert ClaudeCodeAgent.name == "claude" and ClaudeCodeAgent.avatar.startswith("data:image/svg+xml;base64,")
+
+
+def test_a_bad_timeout_is_refused_before_a_command_starts(monkeypatch):
+    monkeypatch.setenv("ZETTCODE_CODE_AGENTS_TIMEOUT", "nine")
+    with pytest.raises(RuntimeError, match="number of seconds"):
+        _timeout()
+
+    monkeypatch.setenv("ZETTCODE_CODE_AGENTS_TIMEOUT", "0")
+    with pytest.raises(RuntimeError, match="positive"):
+        _timeout()
+
+    monkeypatch.delenv("ZETTCODE_CODE_AGENTS_TIMEOUT")
+    assert _timeout() > 0
+
+
+@pytest.mark.skipif(
+    os.name == "nt", reason="the stand-in is a script with a shebang, which Windows will not run directly"
+)
+async def test_a_real_child_process_turn_saves_the_session_and_returns_its_text(tmp_path, monkeypatch):
+    script = tmp_path / "fake"
+    script.write_text(
+        "#!/usr/bin/env python3\nimport json, sys\nprint(json.dumps({'session_id': 's-1', 'result': sys.argv[1]}))\n",
+        encoding="utf-8",
+    )
+    script.chmod(0o755)
+    monkeypatch.setenv("ZETTCODE_CODE_AGENTS_DIR", str(tmp_path / "state"))
+
+    agent = CliAgent("agent-1", "Fake", Command(str(script), "{prompt}", "resume {session} {prompt}"))
+
+    assert await agent._run("hello") == "hello"
+    assert json.loads((tmp_path / "state" / "agent-1.json").read_text()) == {"session": "s-1"}
+
+
+async def test_a_cli_turn_saves_the_session_and_returns_its_text(tmp_path, monkeypatch, cli):
+    cli(lambda argv, cwd: json.dumps({"session_id": "s-1", "result": argv[1]}))
+    monkeypatch.setenv("ZETTCODE_CODE_AGENTS_DIR", str(tmp_path / "state"))
+
+    agent = CliAgent("agent-1", "Fake", Command("fake", "{prompt}", "resume {session} {prompt}"))
+
+    assert await agent._run("hello") == "hello"
+    assert json.loads((tmp_path / "state" / "agent-1.json").read_text()) == {"session": "s-1"}
+
+
+# -- the plugin's own settings ---------------------------------------------------------------------------------------
+
+
+@pytest.fixture
+def settings_file(tmp_path, monkeypatch):
+    """Point the plugin at a settings file and a state folder of its own, and return a function that writes the file."""
+    path = tmp_path / "config.json"
+    monkeypatch.setenv("ZETTCODE_CODE_AGENTS_CONFIG", str(path))
+    monkeypatch.setenv("ZETTCODE_CODE_AGENTS_DIR", str(tmp_path / "state"))
+    monkeypatch.setenv("ZETTCODE_CODE_AGENTS_CWD", str(tmp_path))
+    for name in ("BIN", "ARGS", "RESUME_ARGS"):
+        monkeypatch.delenv(f"ZETTCODE_CODEX_{name}", raising=False)
+        monkeypatch.delenv(f"ZETTCODE_CLAUDE_{name}", raising=False)
+    monkeypatch.delenv("ZETTCODE_CODE_AGENTS_TIMEOUT", raising=False)
+
+    def write(content) -> None:
+        path.write_text(content if isinstance(content, str) else json.dumps(content), encoding="utf-8")
+
+    return write
+
+
+def test_with_no_settings_an_agent_runs_in_the_gateways_folder_and_is_fully_trusted(tmp_path, settings_file):
+    settings = resolve(CODEX)
+
+    assert DEFAULT_PERMISSION == "full" and settings.permission == "full"
+    assert settings.cwd == tmp_path.resolve()
+    assert settings.timeout == 900.0
+    assert (settings.binary, settings.args) == ("codex", CODEX.args)
+
+
+def test_a_tools_own_section_beats_the_top_level_which_beats_the_environment(tmp_path, settings_file, monkeypatch):
+    (tmp_path / "top").mkdir()
+    (tmp_path / "api").mkdir()
+    monkeypatch.setenv("ZETTCODE_CLAUDE_BIN", "from-the-environment")
+    settings_file(
+        {
+            "cwd": str(tmp_path / "top"),
+            "permission": "read",
+            "timeout": 30,
+            "codex": {"cwd": str(tmp_path / "api"), "permission": "workspace", "bin": "/opt/codex"},
+        }
+    )
+
+    codex, claude = resolve(CODEX), resolve(CLAUDE)
+
+    assert (codex.cwd, codex.permission, codex.timeout, codex.binary) == (
+        (tmp_path / "api").resolve(),
+        "workspace",
+        30.0,
+        "/opt/codex",
+    )
+    # Claude has no section: it takes the shared values, and its own command from the environment.
+    assert (claude.cwd, claude.permission, claude.timeout) == ((tmp_path / "top").resolve(), "read", 30.0)
+    assert claude.binary == "from-the-environment"
+
+
+@pytest.mark.parametrize(
+    ("content", "needle"),
+    [
+        ("{not json", "is not valid JSON"),
+        ("[1, 2]", "must hold one JSON object"),
+        ({"permission": "root"}, '"permission"'),
+        ({"permission": 3}, '"permission" in'),
+        ({"cwd": "/no/such/folder/anywhere"}, "does not exist"),
+        ({"cwd": ""}, '"cwd" in'),
+        ({"timeout": 0}, '"timeout"'),
+        ({"timeout": True}, '"timeout"'),
+        ({"timeout": "soon"}, '"timeout"'),
+        ({"codex": "yes"}, '"codex" in'),
+        ({"codex": {"bin": ""}}, '"bin" in'),
+        # {permission} is several arguments, so it cannot be part of one (--sandbox={permission} cannot work).
+        ({"codex": {"args": "exec --sandbox={permission} {prompt}"}}, "word of its own"),
+        ({"codex": {"resume_args": "exec resume {session} x{permission} {prompt}"}}, '"resume_args"'),
+        ({"codex": {"args": "exec {prmpt}"}}, r"names \{prmpt\}"),
+        ({"codex": {"args": "exec 'unclosed {prompt}"}}, "not a command line"),
+        ({"codex": {"args": "exec {"}}, "cannot be filled in"),
+    ],
+)
+def test_a_setting_that_cannot_be_used_is_refused_with_the_file_and_the_key(settings_file, content, needle):
+    settings_file(content)
+
+    with pytest.raises(ConfigError, match=needle) as caught:
+        resolve(CODEX)
+
+    assert "config.json" in str(caught.value)
+
+
+def test_a_missing_or_empty_settings_file_is_no_settings(settings_file, tmp_path):
+    assert resolve(CODEX).permission == "full"
+    settings_file("  \n")
+    assert resolve(CODEX).permission == "full"
+
+
+# -- what each trust level asks of each CLI ---------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize(
+    ("tool", "permission", "resumed", "expected"),
+    [
+        (CODEX, "full", False, ["--dangerously-bypass-approvals-and-sandbox"]),
+        (CODEX, "workspace", False, ["--sandbox", "workspace-write"]),
+        (CODEX, "read", False, ["--sandbox", "read-only"]),
+        # `codex exec resume` has no --sandbox: the same choice goes in as a configuration override.
+        (CODEX, "full", True, ["--dangerously-bypass-approvals-and-sandbox"]),
+        (CODEX, "workspace", True, ["-c", 'sandbox_mode="workspace-write"']),
+        (CODEX, "read", True, ["-c", 'sandbox_mode="read-only"']),
+        (CLAUDE, "full", False, ["--permission-mode", "bypassPermissions"]),
+        (CLAUDE, "workspace", True, ["--permission-mode", "acceptEdits"]),
+        (CLAUDE, "read", False, ["--permission-mode", "plan"]),
+    ],
+)
+async def test_each_trust_level_becomes_the_arguments_of_its_cli(
+    tmp_path, settings_file, monkeypatch, cli, tool, permission, resumed, expected
+):
+    cli(lambda argv, cwd: json.dumps({"session_id": "s-1", "result": json.dumps(argv[1:])}))
+    settings_file({"permission": permission, tool.name: {"bin": "fake"}})
+    if resumed:
+        (tmp_path / "state").mkdir()
+        (tmp_path / "state" / "a.json").write_text(json.dumps({"session": "s-0"}), encoding="utf-8")
+
+    argv = json.loads(await CliAgent("a", "A", tool)._run("do it"))
+
+    # The flags are inside the command, before the prompt (Codex) or before -p (Claude), never glued to it.
+    for flag in expected:
+        assert flag in argv
+    assert argv.index(expected[0]) < argv.index("do it")
+    assert ("resume" in argv) is (resumed and tool is CODEX)
+
+
+async def test_an_edit_of_the_settings_applies_to_the_next_message_with_no_restart(tmp_path, settings_file, cli):
+    cli(lambda argv, cwd: json.dumps({"session_id": "s-1", "result": json.dumps({"argv": argv[1:], "cwd": str(cwd)})}))
+    first, second = tmp_path / "first", tmp_path / "second"
+    first.mkdir()
+    second.mkdir()
+    agent = CliAgent("agent-1", "Codex", dataclasses.replace(CODEX, binary="fake"))
+
+    settings_file({"cwd": str(first), "permission": "read"})
+    one = json.loads(await agent._run("hello"))
+    settings_file({"cwd": str(second), "permission": "workspace"})
+    two = json.loads(await agent._run("again"))
+
+    assert one["cwd"] == str(first.resolve()) and "read-only" in one["argv"]
+    # The same running agent, the next message: the new folder, and the new level in the form a resumed turn takes.
+    assert two["cwd"] == str(second.resolve()) and 'sandbox_mode="workspace-write"' in two["argv"]
+    assert "resume" in two["argv"]
+
+
+async def test_a_broken_settings_file_fails_the_turn_with_a_sentence_and_the_agent_goes_on(
+    tmp_path, settings_file, cli
+):
+    agent = CliAgent("agent-1", "Codex", CODEX)
+    settings_file("{oops")
+
+    with pytest.raises(ConfigError, match="not valid JSON"):
+        await agent._run("hello")
+
+    # Mended, the very next turn runs; nothing about the agent had to be rebuilt.
+    cli(lambda argv, cwd: '{"result": "ok"}')
+    settings_file({"codex": {"bin": "fake"}})
+    assert await agent._run("hello") == "ok"
+
+
+def test_a_command_template_without_the_permission_word_is_run_exactly_as_written(tmp_path):
+    own = Command("codex", "exec {prompt}", "exec resume {session} {prompt}")
+
+    assert own.argv("hi", "", tmp_path, permission=("--sandbox", "read-only")) == ["codex", "exec", "hi"]
+    shaped = Command("codex", "exec {permission} {prompt}", "x")
+    assert shaped.argv("hi", "", tmp_path, permission=("--a", "b")) == ["codex", "exec", "--a", "b", "hi"]
+    assert shaped.argv("hi", "", tmp_path) == ["codex", "exec", "hi"], "no flags: the word leaves nothing behind"