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

:

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.