maestro-harness 0.1.0__tar.gz

maestro_harness-0.1.0/.gitignore

@@ -0,0 +1,46 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+
+# Virtual environments
+.venv/
+
+# Testing
+.pytest_cache/
+htmlcov/
+.coverage
+coverage.xml
+
+# Type checking
+.mypy_cache/
+.pyright/
+
+# Ruff
+.ruff_cache/
+
+# IDE
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# uv
+uv.lock
+
+# Project
+*.db
+*.sqlite3
+.maestro/
+src/api/
+
+# env
+.env

maestro_harness-0.1.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: maestro-harness
+Version: 0.1.0
+Summary: Agent Harness: policy-based guarded execution layer
+Requires-Python: >=3.12
+Requires-Dist: gitpython>=3.1.50
+Requires-Dist: pydantic>=2.10
+Requires-Dist: pyyaml>=6

maestro_harness-0.1.0/pyproject.toml

@@ -0,0 +1,17 @@
+[project]
+name = "maestro-harness"
+version = "0.1.0"
+description = "Agent Harness: policy-based guarded execution layer"
+requires-python = ">=3.12"
+dependencies = [
+    "gitpython>=3.1.50",
+    "pydantic>=2.10",
+    "pyyaml>=6",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/maestro_harness"]

maestro_harness-0.1.0/src/maestro_harness/acl.py

@@ -0,0 +1,39 @@
+"""Access Control List: filesystem and command permission checks."""
+
+from __future__ import annotations
+
+import fnmatch
+
+from .policy import AgentPolicy
+
+
+class AccessDecision:
+    __slots__ = ("allowed", "reason")
+
+    def __init__(self, allowed: bool, reason: str = "") -> None:
+        self.allowed = allowed
+        self.reason = reason
+
+
+def check_file_access(policy: AgentPolicy, path: str, mode: str = "write") -> AccessDecision:
+    # Deny takes precedence
+    for pattern in policy.filesystem.deny:
+        if fnmatch.fnmatch(path, pattern):
+            return AccessDecision(False, f"Path '{path}' denied by pattern '{pattern}'")
+    # Check allow list
+    for pattern in policy.filesystem.allow:
+        if fnmatch.fnmatch(path, pattern):
+            return AccessDecision(True)
+    return AccessDecision(False, f"Path '{path}' not in allow list")
+
+
+def check_command(policy: AgentPolicy, command: str) -> AccessDecision:
+    base = command.split()[0] if command.strip() else ""
+    # Deny takes precedence
+    for denied in policy.commands.deny:
+        if base == denied or command.startswith(denied + " "):
+            return AccessDecision(False, f"Command '{command}' denied by rule '{denied}'")
+    for allowed in policy.commands.allow:
+        if base == allowed or command.startswith(allowed + " "):
+            return AccessDecision(True)
+    return AccessDecision(False, f"Command '{command}' not in allow list")

maestro_harness-0.1.0/src/maestro_harness/budget.py

@@ -0,0 +1,59 @@
+"""Budget tracker: token, step, and time limits per agent."""
+
+from __future__ import annotations
+
+import time
+
+from .policy import BudgetConfig
+
+
+class BudgetExhaustedError(Exception):
+    pass
+
+
+class BudgetTracker:
+    def __init__(self, config: BudgetConfig) -> None:
+        self._config = config
+        self._tokens_used: int = 0
+        self._steps_used: int = 0
+        self._start_time: float | None = None
+
+    def start_timer(self) -> None:
+        self._start_time = time.monotonic()
+
+    def consume_tokens(self, count: int) -> None:
+        self._tokens_used += count
+        if self._tokens_used > self._config.max_tokens_per_task:
+            raise BudgetExhaustedError(
+                f"Token budget exhausted: {self._tokens_used}/{self._config.max_tokens_per_task}"
+            )
+
+    def consume_step(self) -> None:
+        self._steps_used += 1
+        if self._steps_used > self._config.max_steps_per_epoch:
+            raise BudgetExhaustedError(
+                f"Step budget exhausted: {self._steps_used}/{self._config.max_steps_per_epoch}"
+            )
+
+    def check_time(self) -> None:
+        if self._start_time is None:
+            return
+        elapsed = (time.monotonic() - self._start_time) / 60.0
+        if elapsed > self._config.max_wall_time_minutes:
+            raise BudgetExhaustedError(
+                f"Time budget exhausted: {elapsed:.1f}/{self._config.max_wall_time_minutes} min"
+            )
+
+    @property
+    def tokens_used(self) -> int:
+        return self._tokens_used
+
+    @property
+    def steps_used(self) -> int:
+        return self._steps_used
+
+    @property
+    def elapsed_minutes(self) -> float:
+        if self._start_time is None:
+            return 0.0
+        return (time.monotonic() - self._start_time) / 60.0

maestro_harness-0.1.0/src/maestro_harness/harness.py

@@ -0,0 +1,125 @@
+"""Harness: unified guard layer composing ACL, budget, validator, and sandbox."""
+
+from __future__ import annotations
+
+from .budget import BudgetTracker
+from .policy import AgentPolicy, BudgetConfig, HarnessPolicy, load_policy
+from .rollback import RollbackManager
+from .sandbox import LocalSandbox, SandboxResult
+from .validator import Action, ValidationResult, validate_action
+
+
+class Harness:
+    """Policy-aware action interceptor wrapping all guard layers."""
+
+    def __init__(self, policy_path: str, sandbox_root: str = ".") -> None:
+        self._policy = load_policy(policy_path)
+        self._sandbox = LocalSandbox(sandbox_root)
+        self._budgets: dict[str, BudgetTracker] = {}
+        self._rollback = RollbackManager(sandbox_root)
+
+    @classmethod
+    def from_policy(cls, policy: HarnessPolicy, sandbox_root: str = ".") -> Harness:
+        """Create a Harness directly from a HarnessPolicy object."""
+        instance = cls.__new__(cls)
+        instance._policy = policy
+        instance._sandbox = LocalSandbox(sandbox_root)
+        instance._budgets = {}
+        instance._rollback = RollbackManager(sandbox_root)
+        return instance
+
+    @property
+    def policy(self) -> HarnessPolicy:
+        return self._policy
+
+    def _get_budget(self, agent_id: str) -> BudgetTracker:
+        if agent_id not in self._budgets:
+            agent_policy = self._resolve_policy(agent_id)
+            config = agent_policy.budget if agent_policy else BudgetConfig()
+            self._budgets[agent_id] = BudgetTracker(config)
+            self._budgets[agent_id].start_timer()
+        return self._budgets[agent_id]
+
+    def _normalize_path(self, path: str) -> str:
+        """Make path relative to sandbox_root for ACL pattern matching."""
+        from pathlib import Path
+
+        p = Path(path).resolve()
+        root = Path(self._sandbox._root).resolve()
+        try:
+            rel = p.relative_to(root)
+            return str(rel)
+        except ValueError:
+            return path
+
+    def _resolve_policy(self, agent_id: str) -> AgentPolicy | None:
+        """Lookup agent policy with fallback to role prefix (e.g. backend-2 -> backend_agent)."""
+        if agent_id in self._policy.agents:
+            return self._policy.agents[agent_id]
+        import re
+        # Try exact match with _agent suffix (backend-test -> backend_agent)
+        role = re.sub(r'-[\w-]+$', '', agent_id)  # strip suffix like -0, -test
+        candidates = [role, role + '_agent', re.sub(r'_agent$', '', role)]
+        for c in candidates:
+            if c in self._policy.agents:
+                return self._policy.agents[c]
+        return None
+
+    def validate_action(self, agent_id: str, action: Action) -> ValidationResult:
+        agent_policy = self._resolve_policy(agent_id)
+        if agent_policy is None:
+            return ValidationResult(allowed=False, errors=[f"Unknown agent '{agent_id}'"])
+        # Normalize path for ACL matching
+        normalized = action.model_copy()
+        if normalized.target:
+            normalized.target = self._normalize_path(normalized.target)
+        return validate_action(agent_policy, normalized)
+
+    def execute_action(self, agent_id: str, action: Action) -> SandboxResult:
+        validation = self.validate_action(agent_id, action)
+        if not validation.allowed:
+            return SandboxResult(-1, "", f"Action blocked: {'; '.join(validation.errors)}")
+
+        budget = self._get_budget(agent_id)
+        budget.consume_step()
+        budget.check_time()
+
+        if action.command:
+            return self._sandbox.run_command(action.command)
+
+        if action.action_type in ("CODE_WRITE", "FILE_WRITE") and action.content:
+            self._sandbox.write_file(action.target, action.content)
+            return SandboxResult(0, f"Wrote {action.target}", "")
+
+        if action.action_type == "FILE_READ":
+            content = self._sandbox.read_file(action.target)
+            return SandboxResult(0, content, "")
+
+        return SandboxResult(0, "", "")
+
+    def check_budget(self, agent_id: str) -> dict[str, int | float]:
+        budget = self._get_budget(agent_id)
+        return {
+            "tokens_used": budget.tokens_used,
+            "steps_used": budget.steps_used,
+            "elapsed_minutes": round(budget.elapsed_minutes, 2),
+        }
+
+    def get_agent_policy(self, agent_id: str) -> AgentPolicy | None:
+        return self._resolve_policy(agent_id)
+
+    # ------------------------------------------------------------------
+    # Rollback API
+    # ------------------------------------------------------------------
+
+    def snapshot(self, tag: str = "maestro-rollback") -> str | None:
+        """Create a Git snapshot before an execution epoch."""
+        return self._rollback.snapshot(tag)
+
+    def rollback(self) -> bool:
+        """Reset the working tree to the last snapshot."""
+        return self._rollback.rollback()
+
+    def clear_snapshot(self) -> None:
+        """Remove the snapshot tag after a successful epoch."""
+        self._rollback.clear_snapshot()

maestro_harness-0.1.0/src/maestro_harness/policy.py

@@ -0,0 +1,46 @@
+"""Policy models and loader for the Agent Harness."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+from pydantic import BaseModel, Field
+
+
+class FilesystemRule(BaseModel):
+    allow: list[str] = Field(default_factory=list)
+    deny: list[str] = Field(default_factory=list)
+
+
+class CommandRule(BaseModel):
+    allow: list[str] = Field(default_factory=list)
+    deny: list[str] = Field(default_factory=list)
+
+
+class BudgetConfig(BaseModel):
+    max_tokens_per_task: int = 50000
+    max_steps_per_epoch: int = 30
+    max_wall_time_minutes: int = 10
+
+
+class HumanGateRule(BaseModel):
+    action_pattern: str
+    requires_approval: bool = True
+
+
+class AgentPolicy(BaseModel):
+    filesystem: FilesystemRule = Field(default_factory=FilesystemRule)
+    commands: CommandRule = Field(default_factory=CommandRule)
+    budget: BudgetConfig = Field(default_factory=BudgetConfig)
+    rollback: bool = True
+    human_gate: list[HumanGateRule] = Field(default_factory=list)
+
+
+class HarnessPolicy(BaseModel):
+    agents: dict[str, AgentPolicy] = Field(default_factory=dict)
+
+
+def load_policy(path: str) -> HarnessPolicy:
+    data = yaml.safe_load(Path(path).read_text())
+    return HarnessPolicy.model_validate(data)

maestro_harness-0.1.0/src/maestro_harness/rollback.py

@@ -0,0 +1,96 @@
+"""Git-based snapshot and rollback for the Agent Harness."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from git import InvalidGitRepositoryError, Repo
+
+logger = logging.getLogger(__name__)
+
+
+class RollbackManager:
+    """Manages Git snapshots before agent execution epochs.
+
+    Creates a temporary commit before an epoch starts; if validation fails,
+    the working tree is reset to that commit (soft rollback).
+    """
+
+    def __init__(self, repo_path: str = ".") -> None:
+        self._repo_path = Path(repo_path).resolve()
+        self._repo: Repo | None = None
+        self._snapshot_tag: str | None = None
+        self._original_branch: str | None = None
+        try:
+            self._repo = Repo(self._repo_path)
+        except InvalidGitRepositoryError:
+            logger.warning("No Git repository found at %s; rollback disabled", self._repo_path)
+
+    @property
+    def enabled(self) -> bool:
+        return self._repo is not None and not self._repo.bare
+
+    def snapshot(self, tag: str = "maestro-rollback") -> str | None:
+        """Create a snapshot commit and return its hexsha.
+
+        If the repo has uncommitted changes, they are stashed.
+        A lightweight tag is created for easy recovery.
+        """
+        if not self.enabled or self._repo is None:
+            return None
+
+        try:
+            # Stash any existing changes to keep the tree clean
+            if self._repo.is_dirty(untracked_files=True):
+                self._repo.git.stash("push", "-u", "-m", f"maestro-auto-stash-{tag}")
+
+            # Create a tag on HEAD for rollback
+            head = self._repo.head.commit
+            tag_name = f"{tag}-{head.hexsha[:8]}"
+
+            # Remove old tag if it exists
+            for existing in list(self._repo.tags):
+                if existing.name == tag_name:
+                    self._repo.delete_tag(existing)
+
+            self._repo.create_tag(tag_name, ref=head)
+            self._snapshot_tag = tag_name
+            logger.info("Rollback snapshot created: %s", tag_name)
+            return tag_name
+        except Exception as exc:
+            logger.warning("Failed to create snapshot: %s", exc)
+            return None
+
+    def rollback(self, tag: str | None = None) -> bool:
+        """Reset the working tree to the snapshot tag.
+
+        Returns True if rollback succeeded.
+        """
+        if not self.enabled or self._repo is None:
+            return False
+
+        target_tag = tag or self._snapshot_tag
+        if target_tag is None:
+            logger.warning("No snapshot tag available for rollback")
+            return False
+
+        try:
+            commit = self._repo.tags[target_tag].commit
+            self._repo.head.reset(commit, index=True, working_tree=True)
+            logger.info("Rolled back to %s", target_tag)
+            return True
+        except Exception as exc:
+            logger.warning("Rollback failed: %s", exc)
+            return False
+
+    def clear_snapshot(self) -> None:
+        """Remove the snapshot tag after a successful epoch."""
+        if self._repo is not None and self._snapshot_tag:
+            try:
+                for tag in list(self._repo.tags):
+                    if tag.name == self._snapshot_tag:
+                        self._repo.delete_tag(tag)
+            except Exception as exc:
+                logger.debug("Failed to delete snapshot tag: %s", exc)
+            self._snapshot_tag = None

maestro_harness-0.1.0/src/maestro_harness/sandbox.py

@@ -0,0 +1,58 @@
+"""Sandbox abstraction for isolated agent execution."""
+
+from __future__ import annotations
+
+import subprocess
+from typing import Protocol
+
+
+class SandboxResult:
+    __slots__ = ("exit_code", "stdout", "stderr")
+
+    def __init__(self, exit_code: int, stdout: str, stderr: str) -> None:
+        self.exit_code = exit_code
+        self.stdout = stdout
+        self.stderr = stderr
+
+
+class SandboxProvider(Protocol):
+    def run_command(
+        self, command: str, cwd: str | None = None, timeout: int = 60
+    ) -> SandboxResult: ...
+    def write_file(self, path: str, content: str) -> None: ...
+    def read_file(self, path: str) -> str: ...
+
+
+class LocalSandbox:
+    """Subprocess-based sandbox with directory restriction (Phase 1)."""
+
+    def __init__(self, allowed_root: str) -> None:
+        self._root = allowed_root
+
+    def run_command(self, command: str, cwd: str | None = None, timeout: int = 60) -> SandboxResult:
+        work_dir = cwd or self._root
+        try:
+            proc = subprocess.run(
+                command,
+                shell=True,
+                capture_output=True,
+                text=True,
+                cwd=work_dir,
+                timeout=timeout,
+            )
+            return SandboxResult(proc.returncode, proc.stdout, proc.stderr)
+        except subprocess.TimeoutExpired:
+            return SandboxResult(-1, "", f"Command timed out after {timeout}s")
+
+    def write_file(self, path: str, content: str) -> None:
+        from pathlib import Path
+
+        target = Path(self._root) / path
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(content)
+
+    def read_file(self, path: str) -> str:
+        from pathlib import Path
+
+        target = Path(self._root) / path
+        return target.read_text()

maestro_harness-0.1.0/src/maestro_harness/validator.py

@@ -0,0 +1,67 @@
+"""Action validator: pre-execution safety checks."""
+
+from __future__ import annotations
+
+import re
+
+from pydantic import BaseModel
+
+from .acl import check_command, check_file_access
+from .policy import AgentPolicy
+
+
+class Action(BaseModel):
+    agent_id: str
+    action_type: str = ""
+    target: str = ""
+    content: str = ""
+    command: str = ""
+
+
+class ValidationResult(BaseModel):
+    allowed: bool = True
+    errors: list[str] = []
+
+
+DANGEROUS_PATTERNS = [
+    re.compile(r"\beval\s*\("),
+    re.compile(r"\bos\.system\s*\("),
+    re.compile(r"\bsubprocess\.call\s*\(.*shell\s*=\s*True"),
+    re.compile(r"\brm\s+-rf\s+/"),
+    re.compile(r"\bos\.remove\s*\(\s*[\"']/?"),
+]
+
+MAX_DELETE_LINES = 50
+
+
+def validate_action(policy: AgentPolicy, action: Action) -> ValidationResult:
+    errors: list[str] = []
+
+    # File access check
+    if action.target and action.action_type in (
+        "CODE_WRITE", "FILE_WRITE", "FILE_DELETE", "FILE_READ"
+    ):
+        decision = check_file_access(policy, action.target)
+        if not decision.allowed:
+            errors.append(decision.reason)
+
+    # Command check
+    if action.command:
+        decision = check_command(policy, action.command)
+        if not decision.allowed:
+            errors.append(decision.reason)
+
+    # Dangerous pattern check
+    for pattern in DANGEROUS_PATTERNS:
+        if pattern.search(action.content):
+            errors.append(f"Dangerous pattern detected: {pattern.pattern}")
+
+    # Large deletion check
+    if action.action_type == "FILE_DELETE" and action.content:
+        deleted_lines = action.content.count("\n") + 1
+        if deleted_lines > MAX_DELETE_LINES:
+            errors.append(
+                f"Deletion of {deleted_lines} lines exceeds threshold of {MAX_DELETE_LINES}"
+            )
+
+    return ValidationResult(allowed=len(errors) == 0, errors=errors)

maestro_harness-0.1.0/tests/conftest.py

@@ -0,0 +1,55 @@
+"""Shared fixtures for maestro-harness tests."""
+
+from pathlib import Path
+
+import pytest
+
+from maestro_harness.policy import (
+    AgentPolicy,
+    BudgetConfig,
+    CommandRule,
+    FilesystemRule,
+    HarnessPolicy,
+)
+
+
+@pytest.fixture
+def sample_policy() -> HarnessPolicy:
+    return HarnessPolicy(
+        agents={
+            "backend_agent": AgentPolicy(
+                filesystem=FilesystemRule(
+                    allow=["src/api/**", "tests/api/**"],
+                    deny=["src/ui/**", "*.env"],
+                ),
+                commands=CommandRule(
+                    allow=["python", "pytest", "pip"],
+                    deny=["rm -rf", "curl", "wget"],
+                ),
+                budget=BudgetConfig(
+                    max_tokens_per_task=100,
+                    max_steps_per_epoch=5,
+                    max_wall_time_minutes=1,
+                ),
+            ),
+            "frontend_agent": AgentPolicy(
+                filesystem=FilesystemRule(
+                    allow=["src/ui/**", "public/**"],
+                    deny=["src/api/**"],
+                ),
+                commands=CommandRule(
+                    allow=["npm", "npx", "jest"],
+                    deny=["curl", "sudo"],
+                ),
+            ),
+        }
+    )
+
+
+@pytest.fixture
+def policy_file(tmp_path: Path, sample_policy: HarnessPolicy) -> str:
+    import yaml
+
+    path = tmp_path / "harness_policy.yaml"
+    path.write_text(yaml.dump(sample_policy.model_dump(), default_flow_style=False))
+    return str(path)

maestro_harness-0.1.0/tests/test_harness.py

@@ -0,0 +1,254 @@
+"""Tests for maestro-harness: policy, ACL, budget, validator, harness."""
+
+from pathlib import Path
+
+import pytest
+
+from maestro_harness.acl import check_command, check_file_access
+from maestro_harness.budget import BudgetExhaustedError, BudgetTracker
+from maestro_harness.harness import Harness
+from maestro_harness.policy import BudgetConfig, HarnessPolicy, load_policy
+from maestro_harness.validator import Action, validate_action
+
+
+class TestPolicyLoader:
+    def test_load_from_file(self, policy_file: str) -> None:
+        policy = load_policy(policy_file)
+        assert "backend_agent" in policy.agents
+        assert "frontend_agent" in policy.agents
+
+    def test_backend_filesystem_rules(self, policy_file: str) -> None:
+        policy = load_policy(policy_file)
+        be = policy.agents["backend_agent"]
+        assert "src/api/**" in be.filesystem.allow
+        assert "src/ui/**" in be.filesystem.deny
+
+
+class TestACL:
+    def test_allow_matching_path(self, sample_policy: HarnessPolicy) -> None:
+        be = sample_policy.agents["backend_agent"]
+        result = check_file_access(be, "src/api/auth.py")
+        assert result.allowed
+
+    def test_deny_takes_precedence(self, sample_policy: HarnessPolicy) -> None:
+        be = sample_policy.agents["backend_agent"]
+        result = check_file_access(be, "src/ui/app.tsx")
+        assert not result.allowed
+        assert "denied" in result.reason
+
+    def test_no_match_denied(self, sample_policy: HarnessPolicy) -> None:
+        be = sample_policy.agents["backend_agent"]
+        result = check_file_access(be, "random/file.txt")
+        assert not result.allowed
+
+    def test_env_denied(self, sample_policy: HarnessPolicy) -> None:
+        be = sample_policy.agents["backend_agent"]
+        result = check_file_access(be, ".env")
+        assert not result.allowed
+
+    def test_command_allowed(self, sample_policy: HarnessPolicy) -> None:
+        be = sample_policy.agents["backend_agent"]
+        result = check_command(be, "python main.py")
+        assert result.allowed
+
+    def test_command_denied(self, sample_policy: HarnessPolicy) -> None:
+        be = sample_policy.agents["backend_agent"]
+        result = check_command(be, "rm -rf /")
+        assert not result.allowed
+
+    def test_command_not_in_list(self, sample_policy: HarnessPolicy) -> None:
+        be = sample_policy.agents["backend_agent"]
+        result = check_command(be, "docker build .")
+        assert not result.allowed
+
+
+class TestBudget:
+    def test_consume_tokens(self) -> None:
+        tracker = BudgetTracker(BudgetConfig(max_tokens_per_task=100))
+        tracker.consume_tokens(50)
+        assert tracker.tokens_used == 50
+
+    def test_token_exhaustion(self) -> None:
+        tracker = BudgetTracker(BudgetConfig(max_tokens_per_task=10))
+        with pytest.raises(BudgetExhaustedError, match="Token"):
+            tracker.consume_tokens(20)
+
+    def test_step_exhaustion(self) -> None:
+        tracker = BudgetTracker(BudgetConfig(max_steps_per_epoch=2))
+        tracker.consume_step()
+        tracker.consume_step()
+        with pytest.raises(BudgetExhaustedError, match="Step"):
+            tracker.consume_step()
+
+    def test_elapsed_tracking(self) -> None:
+        tracker = BudgetTracker(BudgetConfig())
+        tracker.start_timer()
+        assert tracker.elapsed_minutes >= 0
+
+
+class TestValidator:
+    def test_valid_write(self, sample_policy: HarnessPolicy) -> None:
+        be = sample_policy.agents["backend_agent"]
+        action = Action(
+            agent_id="backend_agent",
+            action_type="CODE_WRITE",
+            target="src/api/auth.py",
+            content="def login(): pass",
+        )
+        result = validate_action(be, action)
+        assert result.allowed
+
+    def test_invalid_path(self, sample_policy: HarnessPolicy) -> None:
+        be = sample_policy.agents["backend_agent"]
+        action = Action(
+            agent_id="backend_agent",
+            action_type="CODE_WRITE",
+            target="src/ui/app.tsx",
+        )
+        result = validate_action(be, action)
+        assert not result.allowed
+
+    def test_dangerous_eval(self, sample_policy: HarnessPolicy) -> None:
+        be = sample_policy.agents["backend_agent"]
+        action = Action(
+            agent_id="backend_agent",
+            action_type="CODE_WRITE",
+            target="src/api/evil.py",
+            content="result = eval(user_input)",
+        )
+        result = validate_action(be, action)
+        assert not result.allowed
+        assert any("Dangerous" in e for e in result.errors)
+
+    def test_dangerous_os_system(self, sample_policy: HarnessPolicy) -> None:
+        be = sample_policy.agents["backend_agent"]
+        action = Action(
+            agent_id="backend_agent",
+            action_type="CODE_WRITE",
+            target="src/api/cmd.py",
+            content="os.system('rm -rf /')",
+        )
+        result = validate_action(be, action)
+        assert not result.allowed
+
+    def test_dangerous_command(self, sample_policy: HarnessPolicy) -> None:
+        be = sample_policy.agents["backend_agent"]
+        action = Action(
+            agent_id="backend_agent",
+            action_type="CODE_WRITE",
+            target="src/api/x.py",
+            content="pass",
+            command="rm -rf /tmp/anything",
+        )
+        result = validate_action(be, action)
+        assert not result.allowed
+
+
+class TestHarness:
+    def test_validate_known_agent(self, policy_file: str) -> None:
+        harness = Harness(policy_file)
+        action = Action(
+            agent_id="backend_agent",
+            action_type="CODE_WRITE",
+            target="src/api/auth.py",
+        )
+        result = harness.validate_action("backend_agent", action)
+        assert result.allowed
+
+    def test_validate_unknown_agent(self, policy_file: str) -> None:
+        harness = Harness(policy_file)
+        action = Action(agent_id="unknown", action_type="CODE_WRITE", target="f.py")
+        result = harness.validate_action("unknown", action)
+        assert not result.allowed
+        assert "Unknown" in result.errors[0]
+
+    def test_execute_blocked(self, policy_file: str) -> None:
+        harness = Harness(policy_file)
+        action = Action(
+            agent_id="backend_agent",
+            action_type="CODE_WRITE",
+            target="src/ui/app.tsx",
+        )
+        result = harness.execute_action("backend_agent", action)
+        assert result.exit_code == -1
+        assert "blocked" in result.stderr
+
+    def test_budget_tracking(self, policy_file: str) -> None:
+        harness = Harness(policy_file)
+        action = Action(
+            agent_id="backend_agent",
+            action_type="CODE_WRITE",
+            target="src/api/auth.py",
+            content="pass",
+        )
+        harness.execute_action("backend_agent", action)
+        status = harness.check_budget("backend_agent")
+        assert status["steps_used"] == 1
+
+    def test_file_read_allowed(self, policy_file: str, tmp_path: Path) -> None:
+        harness = Harness(policy_file, sandbox_root=str(tmp_path))
+        test_file = tmp_path / "src" / "api" / "auth.py"
+        test_file.parent.mkdir(parents=True, exist_ok=True)
+        test_file.write_text("def login(): pass")
+        action = Action(
+            agent_id="backend_agent",
+            action_type="FILE_READ",
+            target=str(test_file),
+        )
+        result = harness.execute_action("backend_agent", action)
+        assert result.exit_code == 0
+        assert "def login(): pass" in result.stdout
+
+    def test_file_read_blocked_by_acl(self, policy_file: str) -> None:
+        harness = Harness(policy_file)
+        action = Action(
+            agent_id="backend_agent",
+            action_type="FILE_READ",
+            target="src/ui/app.tsx",
+        )
+        result = harness.execute_action("backend_agent", action)
+        assert result.exit_code == -1
+        assert "blocked" in result.stderr
+
+    def test_file_write_and_read_roundtrip(self, policy_file: str, tmp_path: Path) -> None:
+        harness = Harness(policy_file, sandbox_root=str(tmp_path))
+        target = str(tmp_path / "src" / "api" / "new.py")
+        write_action = Action(
+            agent_id="backend_agent",
+            action_type="FILE_WRITE",
+            target=target,
+            content="x = 42",
+        )
+        harness.execute_action("backend_agent", write_action)
+        read_action = Action(
+            agent_id="backend_agent",
+            action_type="FILE_READ",
+            target=target,
+        )
+        result = harness.execute_action("backend_agent", read_action)
+        assert result.exit_code == 0
+        assert "x = 42" in result.stdout
+
+    def test_shell_exec_allowed(self, policy_file: str, tmp_path: Path) -> None:
+        harness = Harness(policy_file, sandbox_root=str(tmp_path))
+        action = Action(
+            agent_id="backend_agent",
+            action_type="SHELL_EXEC",
+            target="",
+            command="python -c 'print(hello)'",
+        )
+        result = harness.execute_action("backend_agent", action)
+        assert result.exit_code != 0  # NameError, but command was allowed to run
+        assert "hello" in result.stderr or "NameError" in result.stderr
+
+    def test_shell_exec_blocked(self, policy_file: str) -> None:
+        harness = Harness(policy_file)
+        action = Action(
+            agent_id="backend_agent",
+            action_type="SHELL_EXEC",
+            target="",
+            command="curl https://evil.com",
+        )
+        result = harness.execute_action("backend_agent", action)
+        assert result.exit_code == -1
+        assert "blocked" in result.stderr