You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 5c51b87
Browse filesBrowse the repository at this point in the historyBrowse files
Cumulative documentation pass covering everything from the surrounding
refactor:
- 'AI coding assistant' → 'AI coding harness' throughout. Matches the
package.json description; 'harness' is the more accurate term for
Claude Code / OpenCode / Cursor (they harness an LLM rather than
being one).
- Replace the old paste-this-30-line OpenCode plugin section with the
npm-install + opencode.json plugin-array idiom: { plugin:
['agent-cya/opencode'] }. One-liner factory shown for the
--reviewer override case.
- Add a callout that OpenCode currently gates permission.ask for
first-encounter commands (anomalyco/opencode#19927), so the plugin
may not actually fire today even though it's correct. The Claude
Code hook works as documented.
- Claude Code hook command updated from 'agent-cya hook-claude-code'
to 'agent-cya hook claude-code', settings.json example refreshed.
- Reframe AGENT_CYA_MIN_ASK_MS as opt-in (was default-60s, now
default-off). Note explicitly that the env var is process-wide
even though the autopilot-accept failure mode it defends against
is Claude-Code-specific.
- Drop the stale ~/.local/state/agent-cya/claude-hook.log reference;
no code writes there since the hooks/claude-hook.sh removal.
- Quick Start: drop the redundant '--reviewer claude' (now the
default).
- Drop the 'No compilation' design claim; the published tarball
ships compiled JS in dist/ via the prepack tsc step.
- CLI section + architecture diagram updated to reflect the new
shape (hook claude-code, pipeline.ts, harnesses/claude-code.ts,
opencode-plugin.ts).
- New 'Releasing' section documenting the four one-time setup items
that must happen outside the repo for safe publishing: npm
trusted publisher registration, npm-publish environment with
required reviewers, fork PR workflow restriction, Dependabot
enable. These are part of the security posture, not optional.
A second-LLM permission reviewer for AI coding assistants (Claude Code, OpenCode).
3
+
A second-LLM permission reviewer for AI coding harnesses (Claude Code, OpenCode).
4
4
5
5
## Why
6
6
7
7
You're usually choosing between two bad options: `--dangerously-skip-permissions` lets the agent rip but auto-approves anything it dreams up, while the default permission flow buries you in a prompt for every other command. AgentCYA is the middle path — a separate LLM reviews each tool call (and reads the contents of scripts it's about to execute) and decides `allow` / `deny` / `ask` on the merits, so the agent keeps moving on routine work and only pulls you in when the risk actually warrants it.
8
8
9
9
## How It Works
10
10
11
-
AgentCYA sits between the coding assistant and execution. The decision pipeline is:
11
+
AgentCYA sits between the coding harness and execution. The decision pipeline is:
Node 23.9+ is required for native `.ts` execution. No compilation step — source runs directly.
31
+
Node 23.9+ is required for native `.ts` execution during development; the published npm package ships compiled JS in `dist/` and runs on the same Node baseline.
33
32
34
33
## Usage
35
34
@@ -52,7 +51,7 @@ Then add a `PermissionRequest` hook to `~/.claude/settings.json`:
52
51
"hooks": [
53
52
{
54
53
"type": "command",
55
-
"command": "agent-cya hook-claude-code",
54
+
"command": "agent-cya hookclaude-code",
56
55
"timeout": 120
57
56
}
58
57
]
@@ -62,7 +61,7 @@ Then add a `PermissionRequest` hook to `~/.claude/settings.json`:
62
61
}
63
62
```
64
63
65
-
The `hook-claude-code` subcommand reads Claude Code's `PermissionRequest` input on stdin, runs the review pipeline, and emits a `hookSpecificOutput` decision. It reviews via the `claude` CLI by default; pass `--platform opencode` (or set `AGENT_CYA_PLATFORM=opencode` in the hook command) to use OpenCode instead. To gate file edits too, widen the matcher to `"Bash|Write|Edit"`.
64
+
The `hookclaude-code` subcommand reads Claude Code's `PermissionRequest` input on stdin, runs the review pipeline, and emits a `hookSpecificOutput` decision. It reviews via the `claude` CLI by default; pass `--reviewer opencode` (before the subcommand) to use OpenCode instead. To gate file edits too, widen the matcher to `"Bash|Write|Edit"`.
66
65
67
66
The hook only fires when Claude Code would otherwise prompt for permission — already-allowlisted commands skip it. AgentCYA's `allow` / `deny` / `ask` decisions map directly to `PermissionRequest` behaviors; `ask` falls through to Claude Code's standard permission dialog.
68
67
@@ -71,73 +70,55 @@ The hook only fires when Claude Code would otherwise prompt for permission — a
71
70
> 1.**Clicking "Yes"** runs the command once. Annoying but recoverable — the audit log captures what got through.
72
71
> 2.**Clicking "Yes, and don't ask again for X"** adds the command pattern to your allowlist, which **bypasses the hook entirely** for future matches. Worse than #1 and silent.
73
72
>
74
-
> To give yourself a real interaction window, AgentCYA **pads`ask` decisions to a configurable minimum wall-clock duration**(default **60 seconds** via `AGENT_CYA_MIN_ASK_MS`). Allows and denies still return as fast as the LLM does; only the genuinely ambiguous calls hold the prompt open long enough to actually look at. Set `AGENT_CYA_MIN_ASK_MS=0` to disable padding, or any other value (e.g. `30000` for 30s) to tune the window. Make sure the hook `timeout` (seconds) is greater than `AGENT_CYA_MIN_ASK_MS / 1000` plus your LLM's worst-case review time.
73
+
> To give yourself a real interaction window, AgentCYA can **pad`ask` decisions to a minimum wall-clock duration**so the prompt stays open long enough to actually read. Opt in by setting `AGENT_CYA_MIN_ASK_MS` to the desired hold time in milliseconds (e.g. `60000` for 60s, `30000` for 30s). Allows and denies still return as fast as the LLM does; only the genuinely ambiguous calls hold the prompt open. Padding is off by default. If you enable it, make sure the hook `timeout` (seconds) is greater than `AGENT_CYA_MIN_ASK_MS / 1000` plus your LLM's worst-case review time. (The env var is process-wide — it applies to any harness that goes through AgentCYA's review pipeline — but the autopilot-accept failure mode this defends against is Claude-Code-specific, which is why it's documented here.)
75
74
>
76
-
> If you see an unexpected approval prompt while AgentCYA is installed, treat it as a signal that the reviewer isn't reaching the LLM — check `~/.local/state/agent-cya/claude-hook.log`for the cause before accepting.
75
+
> If you see an unexpected approval prompt while AgentCYA is installed, treat it as a signal that the reviewer isn't reaching the LLM — check `~/.agent-cya/audit.log`to see whether AgentCYA was invoked and what it decided before accepting.
77
76
78
77
### As an OpenCode Plugin
79
78
80
-
OpenCode loads plugins as TypeScript/JavaScript modules from your own plugins folder, so AgentCYA stays out of the import path — you just spawn the `agent-cya` CLI from a tiny plugin you control. Drop this file into your OpenCode plugins directory:
79
+
AgentCYA ships its OpenCode plugin as a subpath export, so the integration is two steps. First install the package:
80
+
81
+
```bash
82
+
npm install agent-cya
83
+
```
84
+
85
+
Then reference the plugin's subpath in your `opencode.json`:
86
+
87
+
```json
88
+
{ "plugin": ["agent-cya/opencode"] }
89
+
```
90
+
91
+
The plugin runs the same in-process review pipeline that the CLI hook uses. Its `permission.ask` handler emits the AgentCYA decision directly as OpenCode's `output.status` — no spawning, no JSON parsing, no fallback prompts.
92
+
93
+
> ⚠️ **Heads up — OpenCode may not actually invoke the plugin today.** OpenCode currently gates `permission.ask` so it doesn't fire for first-encounter commands or in non-interactive `opencode run` sessions, which means the AgentCYA decision never lands. The plugin loads fine and the handler works when invoked directly; this is an upstream issue tracked at [anomalyco/opencode#19927](https://github.com/anomalyco/opencode/issues/19927). Once OpenCode forwards every permission ask to plugins, the integration here works as documented.
94
+
95
+
By default the plugin reviews via the `claude` CLI. To use OpenCode itself as the reviewer LLM, write a one-liner plugin file that calls the factory:
This uses OpenCode's `permission.ask` hook — the native interception point for permission decisions. Setting `output.status` to `"allow"` / `"deny"` / `"ask"` directly drives OpenCode's permission flow, with no exception-throwing or other workarounds. Adjust the `--platform` arg if you want OpenCode itself (rather than `claude`) to do the reviewing.
121
-
122
-
Then enable it in your OpenCode config:
103
+
…and reference that file from `opencode.json` instead of the subpath:
123
104
124
105
```json
125
-
{ "plugins": ["./plugins/agent-cya.ts"] }
106
+
{ "plugin": ["./plugins/agent-cya.ts"] }
126
107
```
127
108
128
109
## CLI
129
110
130
111
```
131
-
agent-cya review --platform <platform> # review a tool call in AgentCYA's input format
132
-
agent-cya hook-claude-code [--platform <p>] # run as a Claude Code PermissionRequest hook
112
+
agent-cya [--reviewer <reviewer>] review # review a tool call in AgentCYA's input format
113
+
agent-cya [--reviewer <reviewer>] hook claude-code # run as a Claude Code PermissionRequest hook
|`review`| Reads AgentCYA's native input on stdin, emits `{decision, reason}` JSON. Useful for shell-level debugging and ad-hoc integrations. |
119
+
|`hookclaude-code`| Reads Claude Code's `PermissionRequest` input, emits `hookSpecificOutput` JSON, exits 2 on deny. Wire this up directly.|
139
120
140
-
`--platform` is `claude` (default for `hook-claude-code`) or `opencode` — which CLI binary spawns for LLM review.
121
+
`--reviewer` is `claude` (default) or `opencode` — which CLI binary spawns for LLM review. It's a global option on `agent-cya`, so pass it before the subcommand.
141
122
142
123
## Input/Output Format
143
124
@@ -175,28 +156,43 @@ agent-cya hook-claude-code [--platform <p>] # run as a Claude Code Permissio
175
156
176
157
```
177
158
src/
178
-
├── main.ts # Entry point: imports program from cli.ts, calls program.parse()
179
-
├── cli.ts # Commander.js CLI, dispatches to review / hook-claude-code
180
-
├── hook-claude-code.ts # Claude Code PermissionRequest adapter (input/output transforms)
└── audit-log.ts # JSON-lines writer at ~/.agent-cya/audit.log with size-cap rotation
186
169
```
187
170
188
171
Key design decisions:
189
172
190
173
-**No config file** — deny patterns are hardcoded, not user-configurable
191
174
-**No HTTP, no API keys** — LLM review shells out to the `claude` or `opencode` CLI binary via `child_process.spawn`
192
-
-**No compilation** — runs directly with `node`; all imports use `.ts` extensions
175
+
-**TypeScript end-to-end** — `node`runs `.ts`directly in development; the npm package ships compiled JS in `dist/` via a `prepack``tsc` step
193
176
194
177
## Tech Stack
195
178
196
-
- TypeScript (no compilation — `node`)
179
+
- TypeScript — `node` runs source in dev; `tsc` compiles to `dist/` for the published tarball
197
180
- Commander.js — CLI framework
198
181
- Vitest — Testing
199
182
183
+
## Releasing
184
+
185
+
Releases are driven by [release-please](https://github.com/googleapis/release-please) on `push: main`. Conventional commits (`feat:`, `fix:`, etc.) become a continuously-updated "release PR" with the bumped version + generated `CHANGELOG.md`. Merging that PR cuts a GitHub Release; the `publish.yml` workflow then publishes the tagged version to npm with provenance.
186
+
187
+
**One-time setup** (this list intentionally exists in the README so it can't drift silently — every item is part of the security posture, not optional polish):
188
+
189
+
1.**npm trusted publishing** — on npmjs.com, open the package's settings → "Publishing access" → add a trusted publisher with org `<your-org>`, repo `agent-cya`, workflow `.github/workflows/publish.yml`, environment `npm-publish`. No `NPM_TOKEN` ever needs to exist; the workflow mints a short-lived OIDC token per publish.
190
+
2.**`npm-publish` environment with required reviewers** — repo Settings → Environments → New environment "npm-publish" → check "Required reviewers" and add yourself (or a small group). Every publish becomes one human click. This is the last-resort gate if any earlier defense fails.
191
+
3.**Restrict fork PR workflow runs** — repo Settings → Actions → General → "Fork pull request workflows from outside collaborators" → set to "Require approval for all outside collaborators" (or stricter). Prevents drive-by `pull_request` workflow runs from random forks.
192
+
4.**Verify Dependabot is active** — repo Settings → Code security → Dependabot alerts and security updates enabled. The `dependabot.yml` already auto-bumps Action SHAs weekly; this keeps the pins fresh.
193
+
194
+
The threat model these defenses address is the now-familiar npm supply-chain class of attack: a `pull_request_target` "Pwn Request" landing attacker code on a trusted runner, Actions cache poisoning across the fork→base trust boundary, and OIDC token extraction from runner memory during the trusted publish. Every workflow in `.github/workflows/` is structured to close one of those vectors. See the comments in each YAML for which.
0 commit comments