opencode-action-guard

Minimal external action guard for opencode.

The prototype runs opencode run --format json, parses tool-use events, and checks whether opencode reads a user-modified target file before editing it.

Requirements

• Python 3
• opencode CLI available on PATH
• A configured opencode provider/model

Files

• guard.py: CLI wrapper and action checker.
• guard_config.json: project configuration.
• opencode_target.md: sample watched target file.
• improved_plan.md: project design notes.

Quick Start

Initialize state and establish a baseline:

python3 guard.py init
python3 guard.py scan

Start interactive prompt mode:

python3 guard.py repl

In another terminal or editor, modify opencode_target.md. On the next prompt, the guard will inspect opencode's JSON action stream. If opencode edits the changed target file before reading it, the guard reports an ACTION GUARD ERROR.

Commands

python3 guard.py init
python3 guard.py scan
python3 guard.py status
python3 guard.py repl
python3 guard.py run "Say hello"
python3 guard.py reset-session

Configuration

guard_config.json controls the watched files and model:

{
  "project_dir": ".",
  "watched_files": [
    "opencode_target.md"
  ],
  "model": "deepseek/deepseek-chat",
  "instruct_required_reads": false,
  "opencode_command": "opencode"
}

Set instruct_required_reads to true if you want the wrapper to explicitly tell opencode to read changed files. Leave it false to test whether the guard catches violations without prompting the model.

Session Behavior

The guard persists the opencode sessionID in .action_guard/session.json and continues that session by default, so opencode can see previous prompts in repl or repeated run calls.

Use this to clear session memory:

python3 guard.py reset-session

Runtime Data

Runtime state is written under .action_guard/:

• file_state.json: watched-file baseline hashes.
• session.json: current opencode session id.
• traces/: JSON traces for each run.

This directory is ignored by git.