bound-codex-tokens 0.1.0__tar.gz

bound_codex_tokens-0.1.0/PKG-INFO

@@ -0,0 +1,5 @@
+Metadata-Version: 2.4
+Name: bound-codex-tokens
+Version: 0.1.0
+Summary: Local token and v2 delegation guard for interactive Codex sessions
+Requires-Python: >=3.11

bound_codex_tokens-0.1.0/README.md

@@ -0,0 +1,101 @@
+# bound-codex-tokens
+
+Local, terminal-first protection for long-running Codex workflows. It lets
+Codex keep working overnight, while placing a finite boundary around one
+workflow and its delegated work.
+
+## The three controls
+
+1. **Bounded rollovers.** `--total` bounds all TUI segments together, and
+   `--compactions` is the finite number of automatic fresh-TUI resumes. By
+   default, the total is divided across the permitted segments. `--segment`
+   optionally chooses a smaller per-segment cap. At a segment cap, the wrapper
+   writes a small handoff and starts a fresh normal Codex TUI. At the total cap,
+   or after the allowed rollovers, it writes one final handoff and stops.
+2. **Configurable handoffs.** The handoff uses Luna by default, but its model,
+   reasoning effort, and prompt are independent of the interactive TUI. The
+   prompt is a top-level option so the continuation format is predictable.
+3. **Guarded v2 delegation.** `--no-fork` turns on
+   `--enable multi_agent_v2` and adds a temporary per-launch hook. It requires
+   `fork_turns: none`, blocks Sol by default, can allow a finite number of Sol
+   children, and can restrict children to an explicit model list.
+
+This is intentionally a safety wrapper, not a substitute for Codex: the TUI
+stays attached, so a long-running workflow can still make progress while the
+wrapper bounds its lifecycle.
+
+## Install
+
+```bash
+uv tool install bound-codex-tokens
+bound-codex-tokens --help
+```
+
+From a checkout, use `uv tool install .`.
+
+## Examples
+
+Run the normal TUI with a 10M workflow cap and two automatic rollovers (`K`,
+`M`, and `B` are accepted). This permits three segments of about 3.34M each:
+
+```bash
+bound-codex-tokens --total 10M --compactions 2 -- --yolo -m gpt-5.6-terra
+```
+
+`--yolo` is passed straight through to Codex and gives it broad authority to
+act without asking. Use it only in a workspace and environment you are willing
+to let the unattended TUI change.
+
+Customize the bounded handoff (also called a compaction here) independently:
+
+```bash
+bound-codex-tokens --total 10M --compactions 2 \
+  --compaction-model gpt-5.6-terra --compaction-effort high \
+  --compaction-prompt-file ./my-handoff-prompt.md \
+  -- --yolo
+```
+
+The default prompt is the versioned
+[`compaction.md`](bound_codex_tokens_assets/compaction.md) shipped with the
+release; the current upstream copy is also available at
+`https://raw.githubusercontent.com/garylvov/bound-codex-tokens/main/bound_codex_tokens_assets/compaction.md`.
+Use `--compaction-prompt-file` to pin a project-specific prompt. The wrapper
+does not use a copied native Codex compaction prompt: native compaction output
+is opaque, so this tool supplies only selected user/assistant messages plus a
+small manifest to the handoff model.
+
+Enable guarded multi-agent v2, permit only Terra or Luna children, and permit
+no Sol children:
+
+```bash
+bound-codex-tokens --total 10M --compactions 2 \
+  --no-fork --max-sol-subagents 0 \
+  --allowed-subagent-models gpt-5.6-terra gpt-5.6-luna \
+  -- --enable multi_agent_v2 --disable auto_review --yolo -m gpt-5.6-terra \
+  -c 'model_reasoning_effort="medium"'
+```
+
+`--no-fork` enables `multi_agent_v2` when it is absent and is
+idempotent when the normal Codex flag `--enable multi_agent_v2` is already
+present. `fork_turns: none` means a child starts without a copy of the parent
+conversation history. It prevents a large main context from being charged again
+to every delegated child. Use `--max-sol-subagents 2` to allow exactly two Sol
+children. Without a v2 policy, Sol is still denied by default; use
+`--allow-sol-subagents` only when that is intentional.
+
+`--disable auto_review` is passed to Codex and makes that choice explicit for
+these long-running sessions. It is separate from `--yolo`, which controls
+approval and sandbox bypass.
+
+The v2 hook also blocks nested `codex exec` calls, because their separate
+sessions would evade the wrapper's root-lineage accounting.
+
+## Notes
+
+* `--total` counts reported tokens from every supervised TUI segment, including
+  those before a rollover. The final handoff is a separate Luna/Terra call and
+  is not part of this total. This is a local guardrail, not a claim about final
+  provider billing categories.
+* The wrapper uses the regular Codex TUI, not a replacement client. It does not
+  change `~/.codex/config.toml`.
+* Run the no-cost checks with `bound-codex-tokens --self-test`.

bound_codex_tokens-0.1.0/bound_codex_tokens.egg-info/PKG-INFO

@@ -0,0 +1,5 @@
+Metadata-Version: 2.4
+Name: bound-codex-tokens
+Version: 0.1.0
+Summary: Local token and v2 delegation guard for interactive Codex sessions
+Requires-Python: >=3.11

bound_codex_tokens-0.1.0/bound_codex_tokens.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+bound_codex_tokens.py
+pyproject.toml
+bound_codex_tokens.egg-info/PKG-INFO
+bound_codex_tokens.egg-info/SOURCES.txt
+bound_codex_tokens.egg-info/dependency_links.txt
+bound_codex_tokens.egg-info/entry_points.txt
+bound_codex_tokens.egg-info/top_level.txt
+bound_codex_tokens_assets/__init__.py
+bound_codex_tokens_assets/compaction.md
+bound_codex_tokens_hooks/__init__.py
+bound_codex_tokens_hooks/v2_spawn_policy.py

bound_codex_tokens-0.1.0/bound_codex_tokens.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

bound_codex_tokens-0.1.0/bound_codex_tokens.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+bound-codex-tokens = bound_codex_tokens:main

bound_codex_tokens-0.1.0/bound_codex_tokens.egg-info/top_level.txt

@@ -0,0 +1,3 @@
+bound_codex_tokens
+bound_codex_tokens_assets
+bound_codex_tokens_hooks

bound_codex_tokens-0.1.0/bound_codex_tokens.py

@@ -0,0 +1,398 @@
+#!/usr/bin/env python3
+"""A small, local session-budget supervisor for the interactive Codex TUI."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import shlex
+import signal
+import subprocess
+import sys
+import time
+from collections import defaultdict
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+def default_summary_prompt() -> str:
+    """Read the versioned prompt distributed with this release."""
+    from importlib.resources import files
+
+    return files("bound_codex_tokens_assets").joinpath("compaction.md").read_text(encoding="utf-8").strip()
+
+
+def token_limit(value: str) -> int:
+    match = re.fullmatch(r"([0-9][0-9_]*(?:\.[0-9]+)?)([KkMmBb]?)", value.strip())
+    if not match:
+        raise argparse.ArgumentTypeError("use an integer or 10K, 10M, 1B")
+    multiplier = {"": 1, "k": 1_000, "m": 1_000_000, "b": 1_000_000_000}[match.group(2).lower()]
+    result = int(float(match.group(1).replace("_", "")) * multiplier)
+    if result <= 0:
+        raise argparse.ArgumentTypeError("must be a positive token count")
+    return result
+
+
+def model_list(values: list[str]) -> list[str]:
+    """Normalize one CLI model list, accepting commas for shell convenience."""
+    return [model.strip() for value in values for model in value.split(",") if model.strip()]
+
+
+def default_sessions_dir() -> Path:
+    codex_home = Path(os.environ.get("CODEX_HOME", str(Path.home() / ".codex")))
+    return codex_home / "sessions"
+
+
+def discover_logs(directory: Path) -> set[Path]:
+    return set(directory.glob("*/*/*/*.jsonl")) if directory.exists() else set()
+
+
+def content_text(value: Any) -> str:
+    if isinstance(value, str):
+        return value
+    if isinstance(value, list):
+        return "\n".join(content_text(item.get("text", "")) if isinstance(item, dict) else "" for item in value)
+    return ""
+
+
+@dataclass
+class FileState:
+    offset: int = 0
+    session_id: str | None = None
+    parent_id: str | None = None
+    source: str | None = None
+    model: str | None = None
+    total_tokens: int = 0
+    last_cumulative: int | None = None
+    excerpts: list[str] = field(default_factory=list)
+
+
+class SessionWatch:
+    def __init__(self, sessions_dir: Path, baseline: set[Path], deny_sol: bool, require_none: bool):
+        self.sessions_dir = sessions_dir
+        self.baseline = baseline
+        self.states: dict[Path, FileState] = {}
+        self.root_id: str | None = None
+        self.related_ids: set[str] = set()
+        self.deny_sol = deny_sol
+        self.require_none = require_none
+        self.violation: str | None = None
+
+    def poll(self) -> None:
+        for path in discover_logs(self.sessions_dir) - self.baseline:
+            state = self.states.setdefault(path, FileState())
+            try:
+                with path.open("r", encoding="utf-8") as handle:
+                    handle.seek(state.offset)
+                    lines = handle.readlines()
+                    state.offset = handle.tell()
+            except (OSError, UnicodeDecodeError):
+                continue
+            for line in lines:
+                try:
+                    self._record(path, state, json.loads(line))
+                except json.JSONDecodeError:
+                    continue
+        self._refresh_lineage()
+
+    def _record(self, path: Path, state: FileState, record: dict[str, Any]) -> None:
+        payload = record.get("payload", {})
+        if record.get("type") == "session_meta":
+            state.session_id = payload.get("session_id") or payload.get("id")
+            state.parent_id = payload.get("parent_thread_id") or payload.get("forked_from_id")
+            state.source = str(payload.get("thread_source") or "")
+            state.model = str(payload.get("model") or payload.get("model_slug") or "")
+            if self.root_id is None and state.source == "user":
+                self.root_id = state.session_id
+            if self.deny_sol and state.source == "subagent" and "sol" in state.model.lower():
+                self.violation = f"Sol child recorded in {path.name}"
+
+        if record.get("type") == "event_msg" and payload.get("type") == "token_count":
+            usage = payload.get("info", {}).get("last_token_usage", {})
+            cumulative = payload.get("info", {}).get("total_token_usage", {}).get("total_tokens")
+            spent = usage.get("total_tokens")
+            if isinstance(cumulative, int) and cumulative != state.last_cumulative and isinstance(spent, int):
+                state.total_tokens += spent
+                state.last_cumulative = cumulative
+
+        if record.get("type") == "response_item" and payload.get("type") == "message":
+            role = payload.get("role")
+            text = content_text(payload.get("content"))
+            if role in {"user", "assistant"} and text:
+                state.excerpts.append(f"{role}: {text[:1800]}")
+
+        # v2 spawn requests are persisted as function calls in the root transcript.
+        if record.get("type") == "response_item" and payload.get("type") == "function_call":
+            if payload.get("name") != "spawn_agent":
+                return
+            try:
+                args = json.loads(payload.get("arguments", "{}"))
+            except (TypeError, json.JSONDecodeError):
+                return
+            if self.deny_sol and "sol" in str(args.get("model", "")).lower():
+                self.violation = "spawn_agent requested a Sol subagent"
+            if self.require_none and args.get("fork_turns") != "none":
+                self.violation = "spawn_agent did not explicitly request fork_turns: none"
+
+    def _refresh_lineage(self) -> None:
+        if not self.root_id:
+            return
+        related = {self.root_id}
+        changed = True
+        while changed:
+            changed = False
+            for state in self.states.values():
+                if state.session_id and state.parent_id in related and state.session_id not in related:
+                    related.add(state.session_id)
+                    changed = True
+        self.related_ids = related
+
+    @property
+    def tokens(self) -> int:
+        return sum(state.total_tokens for state in self.states.values() if state.session_id in self.related_ids)
+
+    def related_paths(self) -> list[Path]:
+        return [path for path, state in self.states.items() if state.session_id in self.related_ids]
+
+
+def terminate(process: subprocess.Popen[bytes], grace: float = 8.0) -> None:
+    if process.poll() is not None:
+        return
+    try:
+        os.killpg(process.pid, signal.SIGTERM)
+    except ProcessLookupError:
+        return
+    deadline = time.monotonic() + grace
+    while process.poll() is None and time.monotonic() < deadline:
+        time.sleep(0.2)
+    if process.poll() is None:
+        os.killpg(process.pid, signal.SIGKILL)
+
+
+def write_bundle(output_dir: Path, watch: SessionWatch, reason: str, tokens: int) -> Path:
+    stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+    bundle = output_dir / f"handoff-{stamp}"
+    bundle.mkdir(parents=True, exist_ok=False)
+    excerpts: list[str] = []
+    for path in watch.related_paths():
+        excerpts.extend(watch.states[path].excerpts[-30:])
+    excerpts = excerpts[-100:]
+    source = bundle / "selected-transcript.md"
+    source.write_text(
+        "# Bounded transcript selection\n\n"
+        f"Reason: {reason}\n\nReported lineage tokens: {tokens:,}\n\n"
+        "Only user/assistant messages are included; raw tool output and full history are excluded.\n\n"
+        + "\n\n".join(excerpts),
+        encoding="utf-8",
+    )
+    (bundle / "manifest.json").write_text(json.dumps({
+        "reason": reason, "reported_tokens": tokens,
+        "root_session_id": watch.root_id,
+        "session_logs": [str(path) for path in watch.related_paths()],
+    }, indent=2) + "\n", encoding="utf-8")
+    return bundle
+
+
+def run_summary(bundle: Path, model: str, effort: str, summary_prompt: str, cwd: Path) -> Path:
+    handoff = bundle / "HANDOFF.md"
+    prompt = (
+        f"Read only {bundle / 'selected-transcript.md'} and {bundle / 'manifest.json'}. "
+        f"{summary_prompt} Write the result to the output file. "
+        "Do not read any session JSONL files."
+    )
+    command = ["codex", "exec", "--skip-git-repo-check", "-C", str(cwd), "-s", "read-only",
+               "-m", model, "-c", f"model_reasoning_effort={json.dumps(effort)}", "-o", str(handoff), prompt]
+    print(f"[bound] generating bounded handoff with {model} ({effort})...", flush=True)
+    subprocess.run(command, check=True)
+    return handoff
+
+
+def without_initial_prompt(arguments: list[str]) -> list[str]:
+    """Keep common Codex flags; drop positional prompt for the fresh handoff TUI."""
+    takes_value = {"-c", "--config", "-i", "--image", "-m", "--model", "-p", "--profile", "-s", "--sandbox", "-C", "--cd", "--add-dir", "-a", "--ask-for-approval", "--enable", "--disable"}
+    result: list[str] = []
+    index = 0
+    while index < len(arguments):
+        item = arguments[index]
+        if item in takes_value:
+            result.append(item)
+            if index + 1 < len(arguments):
+                result.append(arguments[index + 1])
+            index += 2
+        elif item.startswith("-"):
+            result.append(item)
+            index += 1
+        else:
+            break
+    return result
+
+
+def v2_already_enabled(arguments: list[str]) -> bool:
+    """Recognize the normal CLI spelling so the v2 flag is never duplicated."""
+    return any(
+        item == "--enable=multi_agent_v2"
+        or item == "features.multi_agent_v2=true"
+        or (item == "--enable" and index + 1 < len(arguments) and arguments[index + 1] == "multi_agent_v2")
+        for index, item in enumerate(arguments)
+    )
+
+
+def v2_policy_config_args(max_sol_subagents: int, allowed_models: list[str], state_file: Path,
+                          already_enabled: bool) -> list[str]:
+    """Return a process-local PreToolUse hook config, without touching config.toml."""
+    from bound_codex_tokens_hooks import v2_spawn_policy
+
+    command_args = [
+        sys.executable, str(Path(v2_spawn_policy.__file__).resolve()),
+        "--max-sol-subagents", str(max_sol_subagents), "--state-file", str(state_file),
+    ]
+    for model in allowed_models:
+        command_args.extend(["--allowed-model", model])
+    command = shlex.join(command_args)
+    # TOML inline tables use `=` rather than JSON's `:`. Build it explicitly so
+    # the hook command remains safely quoted even when its path contains spaces.
+    value = ('[{ matcher = ".*", hooks = '
+             '[{ type = "command", command = ' + json.dumps(command) +
+             ', timeout = 5, statusMessage = "checking protected Codex policy" }] }]')
+    enable_args = [] if already_enabled else ["--enable", "multi_agent_v2"]
+    return [*enable_args, "-c", f"hooks.PreToolUse={value}"]
+
+
+def self_test() -> int:
+    assert token_limit("500") == 500
+    assert token_limit("10M") == 10_000_000
+    assert without_initial_prompt(["--yolo", "-m", "gpt-5.6-luna", "hello"]) == ["--yolo", "-m", "gpt-5.6-luna"]
+    assert v2_already_enabled(["--enable", "multi_agent_v2"])
+    assert v2_already_enabled(["--enable=multi_agent_v2"])
+    assert not v2_already_enabled(["--enable", "multi_agent"])
+    print("self-test passed: limits, flag preservation, and idempotent v2 activation")
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--total", "--session", dest="total", type=token_limit, default=10_000_000,
+                        help="reported-token cap across all TUI segments; e.g. 10M")
+    parser.add_argument("--segment", type=token_limit,
+                        help="optional reported-token cap before a handoff and fresh TUI")
+    parser.add_argument("--compactions", type=int, default=2, help="maximum automatic fresh-TUI resumes")
+    parser.add_argument("--sessions-dir", type=Path, default=default_sessions_dir())
+    parser.add_argument("--output-dir", type=Path, default=Path.cwd() / ".bound-codex-tokens")
+    parser.add_argument("--summary-model", "--compaction-model", dest="summary_model", default="gpt-5.6-luna",
+                        help="model used for the bounded handoff")
+    parser.add_argument("--summary-effort", "--compaction-effort", dest="summary_effort", default="medium",
+                        help="reasoning effort used for the bounded handoff")
+    parser.add_argument("--summary-prompt", "--compaction-prompt", dest="summary_prompt",
+                        help="top-level instructions for the bounded handoff")
+    parser.add_argument("--summary-prompt-file", "--compaction-prompt-file", dest="summary_prompt_file", type=Path,
+                        help="Markdown/text file containing handoff instructions")
+    parser.add_argument("--poll-seconds", type=float, default=2.0)
+    parser.add_argument("--deny-sol-subagents", action="store_true", default=True,
+                        help="stop when a Sol subagent is requested (default)")
+    parser.add_argument("--allow-sol-subagents", action="store_false", dest="deny_sol_subagents",
+                        help="permit Sol subagents outside the v2 policy hook")
+    parser.add_argument("--require-fork-none", action="store_true")
+    parser.add_argument("--no-fork", "--v2-spawn-policy", dest="v2_spawn_policy", action="store_true",
+                        help="enable v2 and require fork_turns: none for subagents")
+    parser.add_argument("--max-sol-subagents", type=int, default=0, help="Sol subagent allowance under v2 policy")
+    parser.add_argument("--allowed-subagent-models", nargs="+", default=[], metavar="MODEL",
+                        help="space- or comma-separated allowed v2 subagent models")
+    parser.add_argument("--allowed-subagent-model", action="append", dest="allowed_subagent_model_legacy", default=[],
+                        help=argparse.SUPPRESS)
+    parser.add_argument("--self-test", action="store_true")
+    parser.add_argument("codex_args", nargs=argparse.REMAINDER, help="pass Codex TUI flags after --")
+    args = parser.parse_args()
+    if args.self_test:
+        return self_test()
+    if args.compactions < 0:
+        parser.error("--compactions must be zero or greater")
+    if args.max_sol_subagents < 0:
+        parser.error("--max-sol-subagents must be zero or greater")
+    if args.summary_prompt and args.summary_prompt_file:
+        parser.error("use only one of --compaction-prompt and --compaction-prompt-file")
+    if args.summary_prompt_file:
+        try:
+            summary_prompt = args.summary_prompt_file.read_text(encoding="utf-8").strip()
+        except OSError as exc:
+            parser.error(f"could not read compaction prompt file: {exc}")
+    else:
+        summary_prompt = args.summary_prompt or default_summary_prompt()
+    if not summary_prompt:
+        parser.error("compaction prompt must not be empty")
+    codex_args = args.codex_args[1:] if args.codex_args[:1] == ["--"] else args.codex_args
+    if not args.sessions_dir.exists():
+        parser.error(f"sessions directory not found: {args.sessions_dir}")
+
+    # A compaction count is a count of fresh-TUI resumes, so it permits one
+    # more TUI segment than its value. Split the total by default so the total
+    # budget remains useful rather than silently becoming an unreachable cap.
+    segment_limit = args.segment or (args.total + args.compactions) // (args.compactions + 1)
+
+    rollovers = 0
+    workflow_tokens = 0
+    first_launch = True
+    cwd = Path.cwd()
+    state_file = args.output_dir / f"v2-spawn-policy-{os.getpid()}.json"
+    allowed_models = model_list(args.allowed_subagent_models) + args.allowed_subagent_model_legacy
+    policy_args = (
+        v2_policy_config_args(
+            args.max_sol_subagents, allowed_models, state_file, v2_already_enabled(codex_args)
+        )
+        if args.v2_spawn_policy else []
+    )
+    while True:
+        baseline = discover_logs(args.sessions_dir)
+        launch_args = (codex_args if first_launch else without_initial_prompt(codex_args) + [
+            f"Read the protected handoff at {handoff}; continue from it. Do not use native resume."
+        ]) + policy_args
+        print(
+            f"[bound] starting TUI segment {rollovers + 1}; "
+            f"segment cap {segment_limit:,}, total cap {args.total:,} reported tokens",
+            flush=True,
+        )
+        process = subprocess.Popen(["codex", *launch_args], start_new_session=True)
+        watch = SessionWatch(args.sessions_dir, baseline, args.deny_sol_subagents, args.require_fork_none)
+        reason: str | None = None
+        while process.poll() is None:
+            time.sleep(args.poll_seconds)
+            watch.poll()
+            if watch.violation:
+                reason = f"policy violation: {watch.violation}"
+            elif watch.root_id and workflow_tokens + watch.tokens >= args.total:
+                reason = (
+                    f"workflow total cap reached: {workflow_tokens + watch.tokens:,} "
+                    f">= {args.total:,}"
+                )
+            elif watch.root_id and watch.tokens >= segment_limit:
+                reason = f"segment cap reached: {watch.tokens:,} >= {segment_limit:,}"
+            if reason:
+                print(f"[bound] {reason}; stopping TUI", flush=True)
+                terminate(process)
+                break
+        if reason is None:
+            return process.wait()
+        workflow_tokens += watch.tokens
+        bundle = write_bundle(args.output_dir, watch, reason, watch.tokens)
+        try:
+            handoff = run_summary(bundle, args.summary_model, args.summary_effort, summary_prompt, cwd)
+        except subprocess.CalledProcessError as exc:
+            print(f"[bound] handoff failed ({exc.returncode}); bundle retained at {bundle}", file=sys.stderr)
+            return exc.returncode
+        if "workflow total cap reached" in reason or rollovers >= args.compactions:
+            print(
+                f"[bound] automatic resume limit reached; final handoff: {handoff}\n"
+                "[bound] No new TUI was started. Resume manually from this handoff when ready.",
+                flush=True,
+            )
+            return 75
+        print(f"[bound] handoff written to {handoff}; reopening TUI", flush=True)
+        rollovers += 1
+        first_launch = False
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

bound_codex_tokens-0.1.0/bound_codex_tokens_assets/__init__.py

@@ -0,0 +1 @@
+"""Versioned assets distributed with bound-codex-tokens."""

bound_codex_tokens-0.1.0/bound_codex_tokens_assets/compaction.md

@@ -0,0 +1,3 @@
+Create a concise continuation handoff. Preserve completed actions, current
+state, important assumptions, relevant tool outcomes, unresolved blockers, and
+the next concrete step.

bound_codex_tokens-0.1.0/bound_codex_tokens_hooks/__init__.py

@@ -0,0 +1 @@
+"""Bundled Codex hook assets for bound-codex-tokens."""

bound_codex_tokens-0.1.0/bound_codex_tokens_hooks/v2_spawn_policy.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+"""PreToolUse policy for Codex v2 `spawn_agent` calls."""
+
+from __future__ import annotations
+
+import argparse
+import fcntl
+import json
+from pathlib import Path
+import re
+import sys
+from typing import Any
+
+
+def deny(reason: str, max_sol: int) -> dict[str, Any]:
+    message = (
+        f"bound-codex-tokens blocked this operation: {reason}. "
+        "For multi_agent_v2, use fork_turns: none and a permitted subagent model "
+        f"(Sol allowance: {max_sol})."
+    )
+    return {
+        "decision": "block",
+        "reason": message,
+        "systemMessage": message,
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "additionalContext": message,
+        },
+    }
+
+
+def sol_slot(state_file: Path, session_id: str, maximum: int) -> tuple[bool, int]:
+    """Atomically reserve one Sol slot for this root session."""
+    state_file.parent.mkdir(parents=True, exist_ok=True)
+    with state_file.open("a+", encoding="utf-8") as handle:
+        fcntl.flock(handle.fileno(), fcntl.LOCK_EX)
+        handle.seek(0)
+        try:
+            state = json.load(handle)
+        except json.JSONDecodeError:
+            state = {}
+        count = int(state.get(session_id, 0))
+        if count >= maximum:
+            return False, count
+        state[session_id] = count + 1
+        handle.seek(0)
+        handle.truncate()
+        json.dump(state, handle)
+        handle.flush()
+        return True, count + 1
+
+
+def nested_codex_exec(tool_input: Any) -> bool:
+    """Detect a Codex CLI exec command in a tool payload without shell parsing."""
+    if isinstance(tool_input, dict):
+        return any(nested_codex_exec(value) for key, value in tool_input.items()
+                   if key in {"cmd", "command", "shell_command"})
+    if not isinstance(tool_input, str):
+        return False
+    return bool(re.search(r"\bcodex\s+(?:exec|e)\b", tool_input, re.IGNORECASE))
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(add_help=False)
+    parser.add_argument("--max-sol-subagents", type=int, default=0)
+    parser.add_argument("--allowed-model", action="append", default=[])
+    parser.add_argument("--state-file", type=Path, required=True)
+    args = parser.parse_args()
+    if args.max_sol_subagents < 0:
+        return 2
+    try:
+        event = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        return 0
+    if event.get("hook_event_name") != "PreToolUse":
+        print("{}")
+        return 0
+    tool_input = event.get("tool_input") or {}
+    if nested_codex_exec(tool_input):
+        print(json.dumps(deny("nested `codex exec` sessions are disabled because they bypass lineage accounting", args.max_sol_subagents)))
+        return 0
+    if event.get("tool_name") != "spawn_agent":
+        print("{}")
+        return 0
+    if tool_input.get("fork_turns") != "none":
+        print(json.dumps(deny("fork_turns must be explicitly set to none", args.max_sol_subagents)))
+        return 0
+    model = str(tool_input.get("model") or "").lower()
+    allowed_models = {item.lower() for item in args.allowed_model}
+    if allowed_models and model not in allowed_models:
+        print(json.dumps(deny("subagent model is not in the allowed-model list", args.max_sol_subagents)))
+        return 0
+    if "sol" in model:
+        allowed, used = sol_slot(args.state_file, str(event.get("session_id")), args.max_sol_subagents)
+        if not allowed:
+            print(json.dumps(deny(f"Sol-subagent allowance exhausted ({used}/{args.max_sol_subagents})", args.max_sol_subagents)))
+            return 0
+        message = f"bound-codex-tokens: Sol subagent {used}/{args.max_sol_subagents} allowed."
+        print(json.dumps({"hookSpecificOutput": {"hookEventName": "PreToolUse", "additionalContext": message}}))
+        return 0
+    print("{}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

bound_codex_tokens-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "bound-codex-tokens"
+version = "0.1.0"
+description = "Local token and v2 delegation guard for interactive Codex sessions"
+requires-python = ">=3.11"
+dependencies = []
+
+[project.scripts]
+bound-codex-tokens = "bound_codex_tokens:main"
+
+[tool.setuptools]
+py-modules = ["bound_codex_tokens"]
+packages = ["bound_codex_tokens_assets", "bound_codex_tokens_hooks"]
+
+[tool.setuptools.package-data]
+bound_codex_tokens_assets = ["*.md"]

bound_codex_tokens-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+