automaton/contracts/harness-integration.md

Harness Integration Contract

This document defines the integration contract between the automaton framework and any agent harness (opencode, aider, cursor, etc.).

Enforcement Layers

The framework provides three enforcement layers, from strongest to weakest:

1. Harness pre-edit hook (blocks edits before they happen) — primary enforcement
2. Git pre-commit hook (blocks commits without a task) — safety net
3. Prompt-based rules (ALLOWED/FORBIDDEN sections in phase prompts) — advisory only

Layer 1: Harness Pre-Edit Hook

Before allowing any file edit, a harness MUST call:

python ~/.automaton/scripts/status.py --can-edit --project {project} [--file {path}] [--json]

Exit Codes

Code	Meaning
0	ALLOWED — edits are permitted
1	DENIED — edits are not permitted
2	ERROR — invalid arguments or task not found

Modes

1. --can-edit --project {p} (no --task, no --file)

   • Checks if ANY task in the project is in implement or doc_review phase
   • Returns ALLOWED if at least one task is in an edit-allowed phase
   • Returns DENIED if no tasks allow edits

2. --can-edit --project {p} --file {path} (no --task)

   • Same as (1) but also verifies the file is within the project scope
   • Returns DENIED if the file is outside the project directory

3. --can-edit --project {p} --task {t} (no --file)

   • Checks if a specific task is in an edit-allowed phase
   • Returns DENIED if the task phase doesn't allow edits

4. --can-edit --project {p} --task {t} --file {path}

   • Same as (3) but also verifies file scope

JSON Output

Add --json to any --can-edit call to get a machine-readable JSON object on the last line of output:

python ~/.automaton/scripts/status.py --can-edit --project /my/project --json

Allowed response:

{"allowed": true, "reason": "edit_task", "primary_task": {"task": "my-feature", "phase": "implement"}, "all_edit_tasks": [...]}

Denied response:

{"allowed": false, "reason": "no_edit_tasks", "tasks": []}

Out of scope response:

{"allowed": false, "reason": "out_of_scope", "task": "my-feature", "phase": "implement", "file": "/outside/project/file.py"}

Layer 2: Git Pre-Commit Hook

A pre-commit hook blocks commits when no task is in an edit-allowed phase.

Installation

# Option 1: Copy directly
cp ~/.automaton/scripts/git-hooks/pre-commit .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

# Option 2: Symlink (preferred — auto-updates)
ln -s ~/.automaton/scripts/git-hooks/pre-commit .git/hooks/pre-commit

What it does

Checks status.py --can-edit --project {project}. If DENIED (exit code 1), the commit is blocked with instructions to create or transition a task.

Bypass

git commit --no-verify bypasses the hook. Use only when intentionally committing framework documentation or config changes that don't require a task.

Layer 3: Prompt-Based Rules

Each phase prompt includes ALLOWED/FORBIDDEN sections. These are advisory — they rely on the agent choosing to follow them. The harness pre-edit hook and pre-commit hook provide computational enforcement that these rules describe.

Harness-Specific Integration

opencode (pi)

opencode supports plugins with tool.execute.before hooks. A plugin is provided at ~/.automaton/plugins/automaton-guard/plugin.ts.

Installation:

Add to your project's opencode.json:

{
  "plugin": ["~/.automaton/plugins/automaton-guard"]
}

Or install globally via pi install.

The plugin intercepts edit and write tool calls, runs status.py --can-edit --project {dir} --file {path} --json, and blocks the edit if DENIED. The agent receives a message explaining why the edit was blocked and how to proceed.

aider

Aider supports pre-edit hooks via its command system. Before each editing session:

python ~/.automaton/scripts/status.py --can-edit --project /path/to/project

If DENIED, aider should not proceed.

Cursor / Copilot / Cline

These tools do not currently support pre-edit hooks. For these, the git pre-commit hook is the primary enforcement mechanism. Configure your project's .git/hooks/pre-commit as described above.

Generic (any harness)

Any tool that can execute shell commands before file edits should:

1. Before session start: --can-edit --project {p} — verify at least one task allows edits
2. Before each file edit: --can-edit --project {p} --file {path} --json — verify the specific file is in scope
3. On DENIED: block the edit and show the denial message to the user

Enforcement Coverage Matrix

Harness	Pre-edit hook	Pre-commit hook	Prompt rules
opencode (pi)	Plugin	Symlink	Yes
aider	Manual	Symlink	Yes
Cursor	—	Symlink	Yes
Copilot	—	Symlink	Yes
Cline	—	Symlink	Yes
Raw LLM API	—	Symlink	Yes

Pre-commit hooks work universally because git is universal. Pre-edit hooks require harness support.