Binding AI agents with physics, not politeness — AOS v0.1 as a minimal spec

Key Findings:

• Hard Blocking: sed -i and Oracle zone writes are physically prevented; the tool call never reaches the shell.
• Feedback Loop: Violation stderr flows back to the LLM context, forcing the agent to attempt alternative paths rather than silently failing or hallucinating compliance.
• Clean Debugging: Separating evaluation from generation removes narrative pollution, making post-mortems diffable and reliable.

Core Solution

AOS v0.1 defines minimal, implementation-agnostic boundaries enforced at the host layer. The architecture inspects every file write and shell invocation before execution.

1. Three Zones for Paths (§3.2)

Classify all paths to enforce structural roles:

• Oracle: Read-only for the agent. Contains specs, test expectations, evaluation oracles, and policy files. Prevents metric manipulation.
• Permitted: May rewrite freely. Includes implementation code, generated artifacts, and caches.
• Prohibited: Must not touch. Includes system directories and paths outside the workspace home.

2. Physical Enforcement Pipeline (§4.1)

The enforcement mechanism intercepts tool calls via runtime hooks (e.g., Claude Code PreToolUse):

LLM emits Write/Bash
    ↓
PreToolUse hook receives JSON on stdin
    ↓
Host inspects the payload against Zones/Patterns
    ↓ violation → exit 2 (Tool call blocked)
    ↓ OK       → exit 0 (Allow execution)
Tool runs (or not)

Implementation Example:

# Minimal example: pretooluse_iron_cage.py (Python 3)
import json
import os
import sys
from pathlib import Path

ORACLE_SEGMENTS = ("00_Management", "evals")  # read-only segments (example repo layout)

def is_oracle_path(path: str) -> bool:
    real = Path(path).resolve()
    parts = set(p.name for p in [real, *real.parents])
    return any(seg in parts for seg in ORACLE_SEGMENTS)

def main() -> int:
    payload = json.load(sys.stdin)
    tool_name = payload.get("tool_name", "")
    tool_input = payload.get("tool_input", {})

    if tool_name in ("Write", "Edit"):
        target = tool_input.get("file_path") or tool_input.get("filePath", "")
        if target and is_oracle_path(target):
            print(f"[iron_cage] Oracle zone write denied: {target}", file=sys.stderr)
            return 2  # Claude Code will not execute this call

    if tool_name == "Bash":
        cmd = tool_input.get("command", "")
        if "sed -i" in cmd or "truncate " in cmd:
            print(f"[iron_cage] Forbidden in-place edit pattern: {cmd}", file=sys.stderr)
            return 2

    return 0  # allow

if __name__ == "__main__":
    sys.exit(main())

Configuration: Register the hook in ~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "python3 /abs/path/pretooluse_iron_cage.py"
          }
        ]
      }
    ]
  }
}

3. Structural Role Separation (§4.3)

Never allow the generating agent to grade its own work. Run evaluation in a separate process with no shared session context.

Generation Agent  ─→  Artifact (code, doc)
                              │
                              ▼
                Evaluation Agent (no shared context)
                              │
                              ▼
                       PASS / FAIL

4. Physical Evidence (§4.4)

Discard chat narratives as evidence. Validate results via:

• Test Pass: Runner exit code and logs.
• File Created: ls or equivalent on disk.
• Catalog Updated: File hash verification.
• Rule: If it does not land on disk, it did not happen.

Pitfall Guide

1. Oracle Contamination: Allowing agents to modify test expectations or specs leads to "metric hacking" where tests pass but quality degrades. Best Practice: Enforce Oracle zones via hooks; specs must be physically read-only to the agent.
2. Self-Grading Bias: Using the same session for generation and evaluation results in biased reporting. Agents may re-label failures or hallucinate success. Best Practice: Strict role separation; evaluation must run in an isolated process with no shared context.
3. Trusting LLM Narratives: Relying on chat messages ("done", "PASS") causes false positives. Best Practice: Validate only physical evidence: exit codes, disk state, and file hashes.
4. Prohibited Zone Leakage: Agents accessing system directories or paths outside the workspace can cause side effects or security issues. Best Practice: Define Prohibited zones and block writes/reads to system dirs and external paths.
5. Hook Bypass via Regex Fragility: Overly complex or loose regex patterns in hooks may block valid commands or allow violations. Best Practice: Use precise pattern matching; provide stderr feedback on block so the agent can recover; maintain hooks via Issues/PRs.
6. Context Pollution in Eval: Even with separate processes, leaking generation artifacts or prompts into the eval context can bias results. Best Practice: Ensure the evaluation agent starts with a clean slate; pass only the artifact, not the generation history.

Deliverables

• 📘 Blueprint: AOS v0.1 Specification — Normative text for Three Zones, Physical Enforcement, Role Separation, and Physical Evidence.
• ✅ Checklist:
  • Define path zones (Oracle/Permitted/Prohibited) for the repository.
  • Deploy pretooluse_iron_cage.py hook script.
  • Configure PreToolUse hooks in agent settings (exit 2 on violation).
  • Isolate evaluation agent in a separate process with no shared context.
  • Update validation logic to check physical evidence (exit codes, disk state) instead of chat messages.
• 📄 Configuration Templates:
  • pretooluse_iron_cage.py: Python hook script for zone and pattern enforcement.
  • settings.json: Agent hook registration template.