Skip to content

Commit 5c51b87

Browse files
committed
docs: refresh README — opencode caveat, harness terminology, releasing section
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.
1 parent ead6d45 commit 5c51b87

1 file changed

Lines changed: 61 additions & 65 deletions

File tree

‎README.md‎

Lines changed: 61 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
11
# AgentCYA
22

3-
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).
44

55
## Why
66

77
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.
88

99
## How It Works
1010

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:
1212

1313
```
1414
stdin JSON → Hard deny? → File enrichment (Bash) → LLM review → stdout JSON + audit log
@@ -25,11 +25,10 @@ stdin JSON → Hard deny? → File enrichment (Bash) → LLM review → stdout J
2525
npm install
2626

2727
# Manual review:
28-
echo '{"toolType":"Bash","command":"ls"}' | \
29-
node src/main.ts review --platform claude
28+
echo '{"toolType":"Bash","command":"ls"}' | node src/main.ts review
3029
```
3130

32-
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.
3332

3433
## Usage
3534

@@ -52,7 +51,7 @@ Then add a `PermissionRequest` hook to `~/.claude/settings.json`:
5251
"hooks": [
5352
{
5453
"type": "command",
55-
"command": "agent-cya hook-claude-code",
54+
"command": "agent-cya hook claude-code",
5655
"timeout": 120
5756
}
5857
]
@@ -62,7 +61,7 @@ Then add a `PermissionRequest` hook to `~/.claude/settings.json`:
6261
}
6362
```
6463

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 `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 `--reviewer opencode` (before the subcommand) to use OpenCode instead. To gate file edits too, widen the matcher to `"Bash|Write|Edit"`.
6665

6766
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.
6867

@@ -71,73 +70,55 @@ The hook only fires when Claude Code would otherwise prompt for permission — a
7170
> 1. **Clicking "Yes"** runs the command once. Annoying but recoverable — the audit log captures what got through.
7271
> 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.
7372
>
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.)
7574
>
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.
7776
7877
### As an OpenCode Plugin
7978

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:
8196

8297
```typescript
8398
// ~/.config/opencode/plugins/agent-cya.ts
84-
import { spawn } from "node:child_process";
85-
86-
type Decision = { decision: "allow" | "deny" | "ask"; reason: string };
87-
88-
const runAgentCya = (input: object): Promise<Decision> =>
89-
new Promise((resolve) => {
90-
const child = spawn("agent-cya", ["review", "--platform", "claude"], {
91-
stdio: ["pipe", "pipe", "inherit"],
92-
});
93-
let out = "";
94-
child.stdout.on("data", (c) => (out += c.toString()));
95-
child.on("close", () => {
96-
try {
97-
resolve(JSON.parse(out.trim()));
98-
} catch {
99-
resolve({ decision: "ask", reason: "agent-cya returned no JSON" });
100-
}
101-
});
102-
child.stdin.end(JSON.stringify(input));
103-
});
104-
105-
export const AgentCyaGuard = async () => ({
106-
"permission.ask": async (
107-
input: { type?: string; pattern?: string },
108-
output: { status: "ask" | "deny" | "allow" },
109-
) => {
110-
const verdict = await runAgentCya({
111-
toolType: input.type ?? "Bash",
112-
command: input.pattern ?? "",
113-
fileContent: null,
114-
});
115-
output.status = verdict.decision;
116-
},
117-
});
99+
import { createAgentCyaPlugin } from "agent-cya/opencode";
100+
export default createAgentCyaPlugin({ reviewer: "opencode" });
118101
```
119102

120-
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:
123104

124105
```json
125-
{ "plugins": ["./plugins/agent-cya.ts"] }
106+
{ "plugin": ["./plugins/agent-cya.ts"] }
126107
```
127108

128109
## CLI
129110

130111
```
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
133114
```
134115

135-
| Subcommand | Purpose |
136-
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
137-
| `review` | Reads AgentCYA's native input on stdin, emits `{decision, reason}` JSON. Use this from your own integrations (OpenCode etc.). |
138-
| `hook-claude-code` | Reads Claude Code's `PermissionRequest` input, emits `hookSpecificOutput` JSON, exits 2 on deny. Wire this up directly. |
116+
| Subcommand | Purpose |
117+
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
118+
| `review` | Reads AgentCYA's native input on stdin, emits `{decision, reason}` JSON. Useful for shell-level debugging and ad-hoc integrations. |
119+
| `hook claude-code` | Reads Claude Code's `PermissionRequest` input, emits `hookSpecificOutput` JSON, exits 2 on deny. Wire this up directly. |
139120

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.
141122

142123
## Input/Output Format
143124

@@ -175,28 +156,43 @@ agent-cya hook-claude-code [--platform <p>] # run as a Claude Code Permissio
175156

176157
```
177158
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)
181-
├── rules.ts # Hardcoded deny regex patterns, evaluateHardDeny()
182-
├── file-enrich.ts # For Bash commands that run a script, reads file contents from disk
183-
├── prompt.ts # buildSystemPrompt() + buildUserPrompt() with XML sections
184-
├── llm.ts # Spawns claude/opencode CLI binary, 90s timeout, retry, JSON extractor
185-
└── audit-log.ts # JSON-lines writer at ~/.agent-cya/audit.log with size-cap rotation
159+
├── main.ts # Entry point: imports program from cli.ts, calls program.parse()
160+
├── cli.ts # Commander.js CLI, dispatches to review / hook claude-code
161+
├── pipeline.ts # evaluate(): hard-deny → enrich → LLM review, shared by all harnesses
162+
├── harnesses/claude-code.ts # Claude Code PermissionRequest adapter (input/output transforms)
163+
├── opencode-plugin.ts # OpenCode plugin subpath export: createAgentCyaPlugin() factory
164+
├── rules.ts # Hardcoded deny regex patterns, evaluateHardDeny()
165+
├── file-enrich.ts # For Bash commands that run a script, reads file contents from disk
166+
├── prompt.ts # buildSystemPrompt() + buildUserPrompt() with XML sections
167+
├── llm.ts # Spawns claude/opencode CLI binary, 90s timeout, retry, JSON extractor
168+
└── audit-log.ts # JSON-lines writer at ~/.agent-cya/audit.log with size-cap rotation
186169
```
187170

188171
Key design decisions:
189172

190173
- **No config file** — deny patterns are hardcoded, not user-configurable
191174
- **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
193176

194177
## Tech Stack
195178

196-
- TypeScript (no compilation — `node`)
179+
- TypeScript — `node` runs source in dev; `tsc` compiles to `dist/` for the published tarball
197180
- Commander.js — CLI framework
198181
- Vitest — Testing
199182

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.
195+
200196
## License
201197

202198
ISC

0 commit comments

Comments
 (0)