cross-ai 0.1.0__tar.gz

cross_ai-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+cross.log
+data/
+__pycache__/
+*.pyc
+*.egg-info/
+.venv/
+dist/
+build/
+.env
+.tmp/
+.coverage
+evals/results/

cross_ai-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cross Attention Labs
+
+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.

cross_ai-0.1.0/PKG-INFO

@@ -0,0 +1,235 @@
+Metadata-Version: 2.4
+Name: cross-ai
+Version: 0.1.0
+Summary: Agent monitoring proxy and session manager — PTY wrapping, network interception, Slack relay, and gating
+Project-URL: Homepage, https://github.com/rfdearborn/cross
+Project-URL: Repository, https://github.com/rfdearborn/cross
+Project-URL: Issues, https://github.com/rfdearborn/cross/issues
+Author: Cross Attention Labs
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai,gating,monitoring,oversight,proxy,safety
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: pydantic-settings>=2.6.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: starlette>=0.52.0
+Requires-Dist: uvicorn[standard]>=0.41.0
+Requires-Dist: websockets>=13.0
+Provides-Extra: dev
+Requires-Dist: anyio[trio]>=4.0; extra == 'dev'
+Requires-Dist: mitmproxy>=12.0.0; extra == 'dev'
+Requires-Dist: pytest-anyio>=0.0.0; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: slack
+Requires-Dist: aiohttp>=3.9.0; extra == 'slack'
+Requires-Dist: slack-sdk>=3.0.0; extra == 'slack'
+Description-Content-Type: text/markdown
+
+# cross
+
+**Configurable Runtime Oversight and Safety Standard**
+
+cross makes AI agents more trustworthy *and* more capable with lightweight gating and monitoring.
+
+> **Not sure you need this?** Ask your agent to explain why you do.
+
+## Why cross
+
+Your agents are overeager. They're so locked in on finishing your task that they'll `rm -rf` an errant directory or push your credentials public without a second thought.
+
+cross watches from the outside, like a copilot keeping situational awareness while the pilot flies the plane, to guard against this. It pairs agents with spotters which, with separate context and fresh eyes, check actions and monitor sessions.
+
+cross expands the capability-safety frontier: with a babysitter watching, you can give agents more rope. You can stop pre-screening tool calls without feeling a pit in your stomach. More throughput, fewer surprises.
+
+## Quick Start
+
+```bash
+pip install cross-ai               # or: pip install cross-ai[slack] for Slack integration
+cross setup                        # interactive setup wizard (starts daemon automatically on macOS)
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/rfdearborn/cross && cd cross
+pip install -e ".[dev]"
+```
+
+Then point your agent's API traffic through cross. For Claude Code, add a shell wrapper:
+
+```bash
+# In your .zshrc / .bashrc
+claude() { cross wrap -- claude "$@"; }
+```
+
+`cross wrap` does two things: wraps the agent in a PTY for I/O control, and routes API traffic through the local proxy (`ANTHROPIC_BASE_URL=http://localhost:2767`) for structured monitoring and gating.
+
+## How It Works
+
+cross evaluates every tool call through a 3-layer pipeline:
+
+```
+Tool call arrives
+       |
+       v
+ +-----------+     no match     +----------+
+ |  Denylist  | --------------> |  ALLOW   |
+ |   Gate     |                 +----------+
+ +-----------+
+       | match
+       v
+ +-----------+     false pos    +----------+
+ |  LLM Gate  | --------------> |  ALLOW   |
+ |  (review)  |                 +----------+
+ +-----------+
+       | confirmed
+       v
+  BLOCK / ESCALATE
+  (feedback to agent / human review)
+
+       --- meanwhile, in the background ---
+
+ +-----------+
+ | Sentinel  |  periodic review of all activity
+ +-----------+
+```
+
+**Layer 1: Denylist gate** -- Fast deterministic pattern matching against YAML rules. Sub-millisecond, zero cost. Catches destructive commands (`rm -rf /`), credential exfiltration, reverse shells, system path writes, and more. Intentionally broad -- it's a triage filter, not a final judge.
+
+**Layer 2: LLM gate** -- Only invoked when the denylist flags a call. Reviews the tool call with full context (user intent, recent tool history, why it was flagged) and renders a verdict: ALLOW (false positive), BLOCK (confirmed dangerous), or ESCALATE (needs human review). This is why the denylist can be aggressive without generating noise -- the LLM catches false positives.
+
+**Layer 3: Sentinel** -- Async periodic reviewer that watches the full event stream over time. Detects patterns that per-call evaluation misses: tool calls that don't match user intent, suspicious sequences (read credentials then network call), escalating privilege patterns, and agents working around restrictions. Reports to the dashboard and Slack.
+
+Blocked tool calls are suppressed from the API response stream. The proxy automatically retries with the block reason injected, so the agent self-corrects without user intervention. For critical threats (credential exfiltration, reverse shells), the session is halted entirely until a human intervenes.
+
+## Supported Agents
+
+- **Claude Code** -- validated, full PTY + proxy + tool-level gating
+- **OpenClaw** -- validated, PTY + tool-level gating via `beforeToolCall` hook. `cross wrap -- openclaw` automatically injects a Node.js hook that gates every tool call through the cross daemon
+- **Any CLI agent** -- `cross wrap -- <agent-command>` provides PTY wrapping and API proxy for any CLI agent
+- **Any agent using Anthropic APIs** -- set `ANTHROPIC_BASE_URL=http://localhost:2767`
+
+## Dashboard
+
+cross ships with a built-in web dashboard at `http://localhost:2767`. No dependencies, no setup -- it's always active when the daemon is running.
+
+The dashboard shows:
+- **Pending approvals** -- escalated tool calls waiting for human review, with Approve/Deny buttons
+- **Live event feed** -- real-time stream of tool calls, gate decisions, and sentinel reviews
+
+You can also manage pending escalations from the CLI:
+
+```bash
+cross pending                          # list pending escalations
+cross pending approve <tool_use_id>    # approve
+cross pending deny <tool_use_id>       # deny
+```
+
+## Configuration
+
+### LLM Providers
+
+cross uses LLMs for the gate reviewer and sentinel. The default is `claude` (`cli/claude`), which uses your existing Claude Code subscription -- no API key needed. You can also use any other supported provider:
+
+| Provider | Model format | API key env var | Notes |
+|----------|-------------|-----------------|-------|
+| Claude Code | `cli/claude` (or just `claude`) | (none needed) | Default. Uses your Claude subscription via `claude -p` |
+| Google Gemini | `google/gemini-3-flash-preview` | `GOOGLE_API_KEY` | Free tier available |
+| Anthropic | `anthropic/claude-haiku-4-5` | `ANTHROPIC_API_KEY` | |
+| OpenAI | `openai/gpt-4o` | `OPENAI_API_KEY` | |
+| Ollama | `ollama/llama3` | (none needed) | Local models |
+
+Configure via environment variables (all prefixed `CROSS_`):
+
+```bash
+# LLM gate (default uses Claude Code, no key needed)
+CROSS_LLM_GATE_MODEL=cli/claude
+
+# Or use an API provider
+CROSS_LLM_GATE_MODEL=google/gemini-3-flash-preview
+CROSS_LLM_GATE_API_KEY=...          # or set GOOGLE_API_KEY
+
+# Sentinel
+CROSS_LLM_SENTINEL_MODEL=cli/claude
+CROSS_LLM_SENTINEL_INTERVAL_SECONDS=60
+```
+
+Or use `cross setup` for guided interactive configuration.
+
+### Denylist Rules
+
+Default rules ship with cross and cover destructive commands, credential exfiltration, reverse shells, and system path writes. Customize with YAML files in `~/.cross/rules.d/`:
+
+```yaml
+# ~/.cross/rules.d/my-rules.yaml
+rules:
+  - name: no-docker-push
+    tools: [Bash]
+    field: command
+    action: block
+    description: Prevent pushing Docker images
+    patterns:
+      - 'docker\s+push\b'
+
+# Disable a default rule by name
+disable:
+  - destructive-rm
+```
+
+Rules support `patterns` (regex, case-insensitive) and `contains` (substring matching), and can target specific tools and input fields.
+
+### All Settings
+
+Settings can be set via environment variables (`CROSS_` prefix) or `.env` files. cross loads `~/.cross/local.env` (personal overrides, survives `cross setup`), then `~/.cross/.env` (generated by setup), then `.env` in the working directory:
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `listen_port` | 2767 | Proxy listen port |
+| `gating_enabled` | true | Enable the denylist gate |
+| `llm_gate_enabled` | true | Enable LLM review of flagged calls |
+| `llm_gate_shadow` | false | Shadow mode: LLM decides but human makes the final call |
+| `llm_gate_threshold` | escalate | Min denylist action to trigger LLM review |
+| `llm_sentinel_enabled` | true | Enable periodic LLM sentinel reviews |
+| `llm_sentinel_interval_seconds` | 60 | Seconds between sentinel review cycles |
+| `gate_approval_timeout` | 300 | Seconds to wait for human approval on escalation |
+| `rules_dir` | ~/.cross/rules.d | Custom rules directory |
+
+## Architecture
+
+cross uses two complementary interception layers:
+
+**PTY wrapper** (`cross wrap`) -- Wraps any CLI agent in a pseudo-terminal for full I/O control. Enables bidirectional messaging relay (Slack/dashboard to agent), terminal-to-phone handoff, and session management. Agent-agnostic.
+
+**Network proxy** -- Intercepts API traffic via `ANTHROPIC_BASE_URL` redirect. Parses streaming SSE responses, buffers tool_use blocks for gate evaluation, and suppresses blocked calls from the response stream. Provides structured monitoring with zero agent modification.
+
+Both layers are coordinated by the daemon (`cross daemon`), which runs the proxy, gate chain, sentinel, dashboard, and optional Slack plugin as a single process.
+
+## Notification Channels
+
+- **Web dashboard** (default) -- zero dependencies, always active at `/cross/dashboard`
+- **Slack** (optional) -- gate decisions, sentinel reviews, and interactive approval buttons. Configure with `CROSS_SLACK_BOT_TOKEN` and `CROSS_SLACK_APP_TOKEN`. Install the `slack` extra: `pip install cross-ai[slack]`.
+
+## Development
+
+```bash
+git clone https://github.com/rfdearborn/cross
+cd cross
+pip install -e ".[dev,slack]"
+python -m pytest tests/
+```
+
+Ruff for linting (`ruff check`).
+
+## License
+
+MIT

cross_ai-0.1.0/README.md

@@ -0,0 +1,198 @@
+# cross
+
+**Configurable Runtime Oversight and Safety Standard**
+
+cross makes AI agents more trustworthy *and* more capable with lightweight gating and monitoring.
+
+> **Not sure you need this?** Ask your agent to explain why you do.
+
+## Why cross
+
+Your agents are overeager. They're so locked in on finishing your task that they'll `rm -rf` an errant directory or push your credentials public without a second thought.
+
+cross watches from the outside, like a copilot keeping situational awareness while the pilot flies the plane, to guard against this. It pairs agents with spotters which, with separate context and fresh eyes, check actions and monitor sessions.
+
+cross expands the capability-safety frontier: with a babysitter watching, you can give agents more rope. You can stop pre-screening tool calls without feeling a pit in your stomach. More throughput, fewer surprises.
+
+## Quick Start
+
+```bash
+pip install cross-ai               # or: pip install cross-ai[slack] for Slack integration
+cross setup                        # interactive setup wizard (starts daemon automatically on macOS)
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/rfdearborn/cross && cd cross
+pip install -e ".[dev]"
+```
+
+Then point your agent's API traffic through cross. For Claude Code, add a shell wrapper:
+
+```bash
+# In your .zshrc / .bashrc
+claude() { cross wrap -- claude "$@"; }
+```
+
+`cross wrap` does two things: wraps the agent in a PTY for I/O control, and routes API traffic through the local proxy (`ANTHROPIC_BASE_URL=http://localhost:2767`) for structured monitoring and gating.
+
+## How It Works
+
+cross evaluates every tool call through a 3-layer pipeline:
+
+```
+Tool call arrives
+       |
+       v
+ +-----------+     no match     +----------+
+ |  Denylist  | --------------> |  ALLOW   |
+ |   Gate     |                 +----------+
+ +-----------+
+       | match
+       v
+ +-----------+     false pos    +----------+
+ |  LLM Gate  | --------------> |  ALLOW   |
+ |  (review)  |                 +----------+
+ +-----------+
+       | confirmed
+       v
+  BLOCK / ESCALATE
+  (feedback to agent / human review)
+
+       --- meanwhile, in the background ---
+
+ +-----------+
+ | Sentinel  |  periodic review of all activity
+ +-----------+
+```
+
+**Layer 1: Denylist gate** -- Fast deterministic pattern matching against YAML rules. Sub-millisecond, zero cost. Catches destructive commands (`rm -rf /`), credential exfiltration, reverse shells, system path writes, and more. Intentionally broad -- it's a triage filter, not a final judge.
+
+**Layer 2: LLM gate** -- Only invoked when the denylist flags a call. Reviews the tool call with full context (user intent, recent tool history, why it was flagged) and renders a verdict: ALLOW (false positive), BLOCK (confirmed dangerous), or ESCALATE (needs human review). This is why the denylist can be aggressive without generating noise -- the LLM catches false positives.
+
+**Layer 3: Sentinel** -- Async periodic reviewer that watches the full event stream over time. Detects patterns that per-call evaluation misses: tool calls that don't match user intent, suspicious sequences (read credentials then network call), escalating privilege patterns, and agents working around restrictions. Reports to the dashboard and Slack.
+
+Blocked tool calls are suppressed from the API response stream. The proxy automatically retries with the block reason injected, so the agent self-corrects without user intervention. For critical threats (credential exfiltration, reverse shells), the session is halted entirely until a human intervenes.
+
+## Supported Agents
+
+- **Claude Code** -- validated, full PTY + proxy + tool-level gating
+- **OpenClaw** -- validated, PTY + tool-level gating via `beforeToolCall` hook. `cross wrap -- openclaw` automatically injects a Node.js hook that gates every tool call through the cross daemon
+- **Any CLI agent** -- `cross wrap -- <agent-command>` provides PTY wrapping and API proxy for any CLI agent
+- **Any agent using Anthropic APIs** -- set `ANTHROPIC_BASE_URL=http://localhost:2767`
+
+## Dashboard
+
+cross ships with a built-in web dashboard at `http://localhost:2767`. No dependencies, no setup -- it's always active when the daemon is running.
+
+The dashboard shows:
+- **Pending approvals** -- escalated tool calls waiting for human review, with Approve/Deny buttons
+- **Live event feed** -- real-time stream of tool calls, gate decisions, and sentinel reviews
+
+You can also manage pending escalations from the CLI:
+
+```bash
+cross pending                          # list pending escalations
+cross pending approve <tool_use_id>    # approve
+cross pending deny <tool_use_id>       # deny
+```
+
+## Configuration
+
+### LLM Providers
+
+cross uses LLMs for the gate reviewer and sentinel. The default is `claude` (`cli/claude`), which uses your existing Claude Code subscription -- no API key needed. You can also use any other supported provider:
+
+| Provider | Model format | API key env var | Notes |
+|----------|-------------|-----------------|-------|
+| Claude Code | `cli/claude` (or just `claude`) | (none needed) | Default. Uses your Claude subscription via `claude -p` |
+| Google Gemini | `google/gemini-3-flash-preview` | `GOOGLE_API_KEY` | Free tier available |
+| Anthropic | `anthropic/claude-haiku-4-5` | `ANTHROPIC_API_KEY` | |
+| OpenAI | `openai/gpt-4o` | `OPENAI_API_KEY` | |
+| Ollama | `ollama/llama3` | (none needed) | Local models |
+
+Configure via environment variables (all prefixed `CROSS_`):
+
+```bash
+# LLM gate (default uses Claude Code, no key needed)
+CROSS_LLM_GATE_MODEL=cli/claude
+
+# Or use an API provider
+CROSS_LLM_GATE_MODEL=google/gemini-3-flash-preview
+CROSS_LLM_GATE_API_KEY=...          # or set GOOGLE_API_KEY
+
+# Sentinel
+CROSS_LLM_SENTINEL_MODEL=cli/claude
+CROSS_LLM_SENTINEL_INTERVAL_SECONDS=60
+```
+
+Or use `cross setup` for guided interactive configuration.
+
+### Denylist Rules
+
+Default rules ship with cross and cover destructive commands, credential exfiltration, reverse shells, and system path writes. Customize with YAML files in `~/.cross/rules.d/`:
+
+```yaml
+# ~/.cross/rules.d/my-rules.yaml
+rules:
+  - name: no-docker-push
+    tools: [Bash]
+    field: command
+    action: block
+    description: Prevent pushing Docker images
+    patterns:
+      - 'docker\s+push\b'
+
+# Disable a default rule by name
+disable:
+  - destructive-rm
+```
+
+Rules support `patterns` (regex, case-insensitive) and `contains` (substring matching), and can target specific tools and input fields.
+
+### All Settings
+
+Settings can be set via environment variables (`CROSS_` prefix) or `.env` files. cross loads `~/.cross/local.env` (personal overrides, survives `cross setup`), then `~/.cross/.env` (generated by setup), then `.env` in the working directory:
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `listen_port` | 2767 | Proxy listen port |
+| `gating_enabled` | true | Enable the denylist gate |
+| `llm_gate_enabled` | true | Enable LLM review of flagged calls |
+| `llm_gate_shadow` | false | Shadow mode: LLM decides but human makes the final call |
+| `llm_gate_threshold` | escalate | Min denylist action to trigger LLM review |
+| `llm_sentinel_enabled` | true | Enable periodic LLM sentinel reviews |
+| `llm_sentinel_interval_seconds` | 60 | Seconds between sentinel review cycles |
+| `gate_approval_timeout` | 300 | Seconds to wait for human approval on escalation |
+| `rules_dir` | ~/.cross/rules.d | Custom rules directory |
+
+## Architecture
+
+cross uses two complementary interception layers:
+
+**PTY wrapper** (`cross wrap`) -- Wraps any CLI agent in a pseudo-terminal for full I/O control. Enables bidirectional messaging relay (Slack/dashboard to agent), terminal-to-phone handoff, and session management. Agent-agnostic.
+
+**Network proxy** -- Intercepts API traffic via `ANTHROPIC_BASE_URL` redirect. Parses streaming SSE responses, buffers tool_use blocks for gate evaluation, and suppresses blocked calls from the response stream. Provides structured monitoring with zero agent modification.
+
+Both layers are coordinated by the daemon (`cross daemon`), which runs the proxy, gate chain, sentinel, dashboard, and optional Slack plugin as a single process.
+
+## Notification Channels
+
+- **Web dashboard** (default) -- zero dependencies, always active at `/cross/dashboard`
+- **Slack** (optional) -- gate decisions, sentinel reviews, and interactive approval buttons. Configure with `CROSS_SLACK_BOT_TOKEN` and `CROSS_SLACK_APP_TOKEN`. Install the `slack` extra: `pip install cross-ai[slack]`.
+
+## Development
+
+```bash
+git clone https://github.com/rfdearborn/cross
+cd cross
+pip install -e ".[dev,slack]"
+python -m pytest tests/
+```
+
+Ruff for linting (`ruff check`).
+
+## License
+
+MIT

cross_ai-0.1.0/cross/__init__.py

@@ -0,0 +1,3 @@
+"""cross — Configurable Runtime Oversight and Safety Standard."""
+
+__version__ = "0.1.0"

cross_ai-0.1.0/cross/__main__.py

@@ -0,0 +1,4 @@
+from cross.cli import main
+
+if __name__ == "__main__":
+    main()

cross_ai-0.1.0/cross/ansi.py

@@ -0,0 +1,40 @@
+"""ANSI escape code stripping and terminal output cleaning."""
+
+from __future__ import annotations
+
+import re
+
+# Matches ANSI escape sequences comprehensively
+_ANSI_RE = re.compile(
+    r"\x1b"  # ESC character
+    r"(?:"
+    r"\[[0-9;?]*[A-Za-z]"  # CSI sequences: ESC [ params letter
+    r"|\][^\x07\x1b]*(?:\x07|\x1b\\)"  # OSC sequences
+    r"|[()][AB012]"  # Character set selection
+    r"|[=>]"  # Keypad modes
+    r"|."  # Other single-char escapes
+    r")"
+)
+
+# Leftover partial CSI params (e.g. "38;2;248;242m" without the ESC[)
+# Require 2+ semicolon-separated numbers to avoid false positives on normal text
+_PARTIAL_CSI_RE = re.compile(r"\d+(?:;\d+)+[mGKHJABCDfsu]")
+
+# Control characters to strip (except newline, tab, carriage return)
+_CTRL_RE = re.compile(r"[\x00-\x08\x0b-\x0c\x0e-\x1a\x1c-\x1f\x7f]")
+
+# Box drawing and decorative characters that clutter output
+_DECORATION_RE = re.compile(r"[╌─━┌┐└┘├┤┬┴┼╭╮╯╰│║═]+")
+
+
+def strip_ansi(data: bytes) -> str:
+    """Strip ANSI escape codes, control characters, and decoration from terminal output."""
+    text = data.decode("utf-8", errors="replace")
+    text = _ANSI_RE.sub("", text)
+    text = _PARTIAL_CSI_RE.sub("", text)
+    text = _CTRL_RE.sub("", text)
+    text = _DECORATION_RE.sub("", text)
+    # Collapse multiple spaces/blank lines
+    text = re.sub(r"[ \t]+", " ", text)
+    text = re.sub(r"\n{3,}", "\n\n", text)
+    return text

cross_ai-0.1.0/cross/chain.py

@@ -0,0 +1,147 @@
+"""Evaluator chain — runs gate evaluators and aggregates results.
+
+Two-stage evaluation:
+  Stage 1: Run all gates (denylist, etc.), max action wins.
+  Stage 2: If result >= threshold AND review gate exists, run LLM review.
+           Review verdict overrides stage 1 (catches false positives).
+           On ABSTAIN/error, stage 1 result stands.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import copy
+import logging
+import time
+
+from cross.config import settings
+from cross.evaluator import Action, EvaluationResponse, Gate, GateRequest
+
+logger = logging.getLogger("cross.chain")
+
+
+class GateChain:
+    """Runs gate evaluators against a tool call, with optional LLM review stage."""
+
+    def __init__(
+        self,
+        gates: list[Gate] | None = None,
+        review_gate: Gate | None = None,
+        review_threshold: Action = Action.BLOCK,
+    ):
+        self.gates: list[Gate] = gates or []
+        self.review_gate: Gate | None = review_gate
+        self.review_threshold: Action = review_threshold
+
+    def add(self, gate: Gate):
+        self.gates.append(gate)
+
+    async def evaluate(self, request: GateRequest) -> EvaluationResponse:
+        """Run all gates, optionally escalate to LLM review."""
+        # Stage 1: run all gates
+        stage1_result = await self._run_gates(request)
+
+        # Stage 2: LLM review if result >= threshold
+        if (
+            self.review_gate
+            and stage1_result.action.value >= self.review_threshold.value
+            and stage1_result.action != Action.ABSTAIN
+        ):
+            review_result = await self._run_review(request, stage1_result)
+            if review_result is not None:
+                return review_result
+            # ABSTAIN/error → stage 1 stands
+
+        return stage1_result
+
+    async def _run_gates(self, request: GateRequest) -> EvaluationResponse:
+        """Stage 1: run all gates, max action wins."""
+        if not self.gates:
+            return EvaluationResponse(action=Action.ALLOW, evaluator="chain:empty")
+
+        responses: list[EvaluationResponse] = []
+
+        for gate in self.gates:
+            start = time.monotonic()
+            try:
+                timeout_s = gate.timeout_ms / 1000.0
+                resp = await asyncio.wait_for(gate.evaluate(request), timeout=timeout_s)
+            except asyncio.TimeoutError:
+                elapsed_ms = (time.monotonic() - start) * 1000
+                logger.warning(
+                    f"Gate '{gate.name}' timed out after {elapsed_ms:.1f}ms "
+                    f"(limit: {gate.timeout_ms}ms), using on_error={gate.on_error.name}"
+                )
+                resp = EvaluationResponse(
+                    action=gate.on_error,
+                    reason=f"Gate timed out after {elapsed_ms:.1f}ms",
+                    evaluator=gate.name,
+                )
+            except Exception as e:
+                logger.exception(f"Gate '{gate.name}' raised: {e}")
+                resp = EvaluationResponse(
+                    action=gate.on_error,
+                    reason=f"Gate error: {e}",
+                    evaluator=gate.name,
+                )
+            elapsed_ms = (time.monotonic() - start) * 1000
+            resp.duration_ms = elapsed_ms
+
+            if not resp.evaluator:
+                resp.evaluator = gate.name
+
+            responses.append(resp)
+
+        # Max action wins
+        max_response = max(responses, key=lambda r: r.action.value)
+
+        # If everything abstained, treat as allow
+        if max_response.action == Action.ABSTAIN:
+            return EvaluationResponse(action=Action.ALLOW, evaluator="chain:all_abstained")
+
+        return max_response
+
+    async def _run_review(self, request: GateRequest, stage1_result: EvaluationResponse) -> EvaluationResponse | None:
+        """Stage 2: run LLM review gate. Returns None if review abstains/errors."""
+        assert self.review_gate is not None
+
+        # Copy request to avoid mutating the caller's object
+        request = copy.copy(request)
+        request.prior_result = stage1_result
+
+        start = time.monotonic()
+        try:
+            timeout_s = self.review_gate.timeout_ms / 1000.0
+            resp = await asyncio.wait_for(self.review_gate.evaluate(request), timeout=timeout_s)
+        except asyncio.TimeoutError:
+            elapsed_ms = (time.monotonic() - start) * 1000
+            logger.warning(f"Review gate timed out after {elapsed_ms:.1f}ms, keeping stage-1 result")
+            return None
+        except Exception as e:
+            logger.warning(f"Review gate error: {e}, keeping stage-1 result")
+            return None
+
+        elapsed_ms = (time.monotonic() - start) * 1000
+        resp.duration_ms = elapsed_ms
+
+        if resp.action == Action.ABSTAIN:
+            logger.info("Review gate abstained, keeping stage-1 result")
+            return None
+
+        # Shadow mode: LLM decides, but escalate to human with LLM's reasoning
+        if settings.llm_gate_shadow:
+            shadow_reason = f"[Shadow] LLM gate would {resp.action.name}: {resp.reason}"
+            logger.info(f"Shadow mode — escalating to human. {shadow_reason[:150]}")
+            return EvaluationResponse(
+                action=Action.ESCALATE,
+                reason=shadow_reason,
+                evaluator=f"{resp.evaluator}:shadow",
+                confidence=resp.confidence,
+                duration_ms=resp.duration_ms,
+                metadata={"shadow_verdict": resp.action.name, "shadow_reason": resp.reason},
+            )
+
+        logger.info(
+            f"Review gate overrides stage-1 ({stage1_result.action.name} → {resp.action.name}): {resp.reason[:100]}"
+        )
+        return resp