Getting Started

1. Clone the repo

git clone https://github.com/zjgulai/Agent_hook.git ~/project/Agent_hook
cd ~/project/Agent_hook
python3 -m pip install --user pyyaml tomli tomli_w

2. Install a hook to opencode

./bin/agent-hook install protect-sensitive-files --client opencode

# Output:
[
  {
    "client": "opencode",
    "name": "protect-sensitive-files",
    "plugin": "/Users/you/.config/opencode/plugins/agent-hook-protect-sensitive-files.js",
    "backup": null
  }
]

3. Verify real blocking

# Direct hook call (what opencode runtime does internally)
echo '{"tool":"Write","parameters":{"filePath":"/proj/.env"}}' \
    | python3 registry/protect-sensitive-files/source/hook.py

# Output: exit code 2 + JSON reason
{
  "block": true,
  "reason": "protect-sensitive-files: blocked write to '/proj/.env'
             — matches exact name '.env'.
             Override via AGENT_HOOK_ALLOW_SENSITIVE=path1:path2 if intentional."
}

4. Install to all 4 clients

for h in protect-sensitive-files guard-bash post-edit-format \
         session-context-injector final-verify; do
  ./bin/agent-hook install "$h" --client all
done

codex is unsupported for hooks (skipped automatically). cursor gets a degraded Rule for the few that have a degradation template. kimi gets a config.toml entry. opencode gets the full JS plugin.

5. Run doctor

./bin/agent-hook doctor

# Output sections:
== schema ==
  ok final-verify v0.1.0
  ok guard-bash v0.1.0
  ...
== source files (executable, no 3rd-party imports) ==
  ok    final-verify              exec=True  bad-imports=none
  ...
== required binaries ==
  ok    guard-bash                -> python3
  ...
== client install status ==
  opencode: 5 managed by agent-hook (...)
  codex   : 0 managed by agent-hook (none)
  cursor  : 3 managed by agent-hook (...)
  kimi    : 5 managed by agent-hook (...)

6. List install state

./bin/agent-hook list

# Tabular: name | priority | events | opencode | codex | cursor | kimi
final-verify              P0  Stop              managed   n/a   absent   managed
guard-bash                P0  PreToolUse        managed   n/a   managed  managed
post-edit-format          P0  PostToolUse       managed   n/a   absent   managed
protect-sensitive-files   P0  PreToolUse        managed   n/a   managed  managed
session-context-injector  P0  SessionStart      managed   n/a   managed  managed