Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ node scripts/check-links.js 'https://example.com/' ['<url>'…] # each o
Things that catch contributors out:

- A rendered report can be corrected by copying its archive JSON back to `kosh-reports/data/qa-report-<type>.json`, editing the text and running `run-qa-report.sh` again. It counts as a correction when its seal holds and an archived JSON has the same seal; a refused report is sealed too but never archived, so a retry still merges. The merge restores `url`, `pages[]`, `inventory[]` and `linkChecks[]` from that copy, whatever the edit did to them, and the seal keeps the timestamp and `heldTo`. It leaves the session's capture, one held for a retry and the link record for their own runs. Functional's findings are still numbered, so an ID can change between copies, and their `fixAt` checked. If a browser that isn't in the run's capture has loaded the site since, it's refused, since that's how a new run reusing an old report looks: finish the later run first, or save the copy under another name, which skips the merge. So does editing the archive copy in place, and nothing restores its measurements. Earlier copies move aside under the run's timestamp, then `-2` and so on, and every copy gets the capture its hash covers, even under a new website name.
- `hooks/guard-capture.js` refuses edits to `capture*.jsonl` files and the link checker's `links*.jsonl` record in `kosh-reports/data/`, and anything naming this session's capture or record, since the merge seals both into a report as kosh's own. For commands that can reach a `kosh-reports/` kosh has run in (one holding a capture: anywhere in the session's project, or a run folder or a path in its `kosh-reports/` named by absolute path), it also refuses `*.jsonl` globs and any `rm` or `mv` of `kosh-reports/`, `kosh-reports/data`, the archive, or a glob of their contents, so clearing them is done by hand.
- `hooks/guard-capture.js` refuses edits to `capture*.jsonl` files and the link checker's `links*.jsonl` record in `kosh-reports/data/`, and anything naming this session's capture or record, since the merge seals both into a report as kosh's own. For commands that can reach a `kosh-reports/` kosh has run in (one holding a capture: anywhere in the session's project, or a run folder or a path in its `kosh-reports/` named by absolute path), it also refuses `*.jsonl` globs and any `rm` or `mv` of `kosh-reports/`, `kosh-reports/data`, the archive, or a glob of their contents, so clearing them is done by hand. Plugin hooks run on every Bash and edit call in every project, so `hooks/guard-capture.sh` starts Node only when the call's `command` or `file_path`, the only fields the guard reads, names `capture`, `links`, `jsonl` or `kosh-reports`, a word every rule needs; a rule that matches without one would be skipped, and the tests run every case through it. Without `node` on PATH it refuses such a call, since a guard that can't run shouldn't pass it.
- The merge keeps only the visits from the last browser that loaded the report's host, since a performance run starts with `browser_close`. A skill that closes the browser mid-run drops what it measured before.
- `kosh-reports/` is the project's, not kosh's: `$CLAUDE_PROJECT_DIR/kosh-reports`, which Claude Code sets for the capture and the hooks. Bash commands don't get it, so the scripts use the nearest `kosh-reports/data` at or above the cwd, looking no higher than the git root, else `kosh-reports/` in the cwd. The name is kosh's own so a project's `reports/` never gets client data mixed in. If `kosh-reports/.gitignore` is missing, the capture adds one (`*`) when it creates `data/`, and so does every successful render, even when Playwright made the folder first, since reports hold client URLs and console text. Schemas, skills and `plugin.json` still resolve from kosh's own folder. `KOSH_REPORTS_DIR` moves where the scripts and the capture look (the tests use it), not where the skills write.

Expand Down
12 changes: 12 additions & 0 deletions hooks/guard-capture.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
#!/bin/sh
# Plugin hooks run on every Bash and edit call in every project, so Node starts only when a rule in guard-capture.js could match.
input=$(cat)
# The guard reads only command and file_path, so the transcript path (always .jsonl), the cwd and an edit's text never count. A key quoted inside a JSON string is escaped, so only real keys match.
printf '%s' "$input" \
| grep -oE '"(file_path|command)"[[:space:]]*:[[:space:]]*"([^"\\]|\\.)*"' \
| grep -qiE 'capture|links|jsonl|kosh-reports' || exit 0

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The pre-filter greps the whole tool_input, so an Edit/Write/MultiEdit whose content, old_string or new_string contains links, capture or jsonl gets through to Node. guard-capture.js never reads those fields: for edit tools it only tests args.file_path (hooks/guard-capture.js:60). For the users this PR targets (no node on the hook's PATH), that call now hits exit 2. So in any project, even with kosh unused, Claude can't write a README, HTML template or JS file that mentions "links" or "capture". Before this PR the same call went through with a non-blocking error; now it's a hard block. Match only the fields the guard reads, e.g. grep -oE '"(file_path|command)"[[:space:]]*:[[:space:]]*"([^"\\]|\\.)*"' | grep -qiE 'capture|links|jsonl|kosh-reports' || exit 0. That is safe for the same reason the existing sed is: a key quoted inside a JSON string is always escaped.

🤖 Fix prompt for AI agents
Verify each finding against the current code and only fix it if
needed.

In `hooks/guard-capture.sh`:
- Line 7: The pre-filter pipes all of `tool_input` into
  `grep -qiE 'capture|links|jsonl|kosh-reports'`. That includes Write
  `content` and Edit/MultiEdit `old_string`/`new_string`, but
  `blocked()` in hooks/guard-capture.js only tests `args.file_path`
  for edit tools and `args.command` for Bash. When node is missing,
  any edit whose text mentions "links" or "capture" therefore reaches
  the `exit 2` branch and is refused in every project, a regression
  from the old non-blocking error. Narrow the check to the
  `file_path` and `command` values, for example by first extracting
  them with `grep -oE '"(file_path|command)"[[:space:]]*:[[:space:]]*"([^"\\]|\\.)*"'`,
  then applying the keyword grep. Keep the transcript_path/cwd
  stripping, the `command -v node` fail-closed branch and the final
  `node "$(dirname "$0")/guard-capture.js"` call unchanged. Add a test
  to tests/guard-capture.test.js's no-node test showing that an Edit
  whose new_string contains "links" exits 0.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in d5443ab

if ! command -v node >/dev/null 2>&1; then
echo "Blocked: kosh's capture guard needs node on PATH to check this call." >&2
exit 2
fi
printf '%s' "$input" | node "$(dirname "$0")/guard-capture.js"
2 changes: 1 addition & 1 deletion hooks/hooks.json
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
"hooks": [
{
"type": "command",
"command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/guard-capture.js\""
"command": "sh \"${CLAUDE_PLUGIN_ROOT}/hooks/guard-capture.sh\""
}
]
},
Expand Down
44 changes: 39 additions & 5 deletions tests/guard-capture.test.js
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ const { spawnSync } = require('child_process');

const ROOT = path.join(__dirname, '..');
const HOOK = path.join(ROOT, 'hooks/guard-capture.js');
const WRAPPER = path.join(ROOT, 'hooks/guard-capture.sh');

// KOSH and SPACED are folders kosh has run in, FRESH a clone no run has used yet, ELSEWHERE an unrelated project,
// OTHER one whose kosh-reports/data holds a log that only looks like a capture, NESTED a project inside KOSH.
Expand Down Expand Up @@ -36,14 +37,14 @@ const SESSION = '0b3f6c2e-5d1a';
const RECASED = path.join(path.dirname(KOSH), path.basename(KOSH).toUpperCase());
const caseInsensitiveDisk = fs.existsSync(RECASED);

// `reports: null` runs the guard as installed, with KOSH_REPORTS_DIR unset; `project` is the root Claude Code gives hooks.
// Every case goes through the shell pre-filter, so a block it skipped fails here. `reports: null` runs the guard as installed, with KOSH_REPORTS_DIR unset; `project` is the root Claude Code gives hooks.
const guard = (input, { reports = KOSH, project, cwd = ROOT } = {}) => {
const env = { ...process.env, KOSH_REPORTS_DIR: reports && path.join(reports, 'kosh-reports'), CLAUDE_PROJECT_DIR: project };
if (!reports) delete env.KOSH_REPORTS_DIR;
if (!project) delete env.CLAUDE_PROJECT_DIR;
return spawnSync('node', [HOOK], { input: typeof input === 'string' ? input : JSON.stringify(input), encoding: 'utf8', cwd, env });
return spawnSync('sh', [WRAPPER], { input: typeof input === 'string' ? input : JSON.stringify(input), encoding: 'utf8', cwd, env });
};
const call = (tool_name, tool_input, cwd = KOSH) => ({ hook_event_name: 'PreToolUse', cwd, tool_name, tool_input });
const call = (tool_name, tool_input, cwd = KOSH) => ({ hook_event_name: 'PreToolUse', transcript_path: '/Users/x/.claude/projects/p/s.jsonl', cwd, tool_name, tool_input });

for (const [name, input, options] of [
['writing a capture', call('Write', { file_path: path.join(KOSH, 'kosh-reports/data/capture-0b3f6c2e-5d1a.jsonl'), content: '{}' })],
Expand Down Expand Up @@ -154,9 +155,42 @@ for (const [name, input, options] of [

test('the plugin runs the guard before every write and shell command', () => {
const entries = require(path.join(ROOT, 'hooks/hooks.json')).hooks.PreToolUse;
const guarded = entries.filter((entry) => entry.hooks.some((hook) => hook.command.includes('hooks/guard-capture.js')));
assert.ok(fs.existsSync(HOOK));
const guarded = entries.filter((entry) => entry.hooks.some((hook) => hook.command.includes('hooks/guard-capture.sh')));
assert.ok(fs.existsSync(HOOK) && fs.existsSync(WRAPPER));
for (const tool of ['Write', 'Edit', 'MultiEdit', 'Bash']) {
assert.ok(guarded.some((entry) => new RegExp(`^(?:${entry.matcher})$`).test(tool)), `${tool} is not guarded`);
}
});

// A PATH with the tools the pre-filter needs and no node.
const withoutNode = () => {
const bin = fs.mkdtempSync(path.join(os.tmpdir(), 'kosh-guard-bin-'));
for (const tool of ['cat', 'grep', 'sed', 'dirname']) {
fs.symlinkSync(spawnSync('sh', ['-c', `command -v ${tool}`], { encoding: 'utf8' }).stdout.trim(), path.join(bin, tool));
}
return bin;
};

test('without node, the guard blocks a call a rule could match and allows any other', (t) => {
const bin = withoutNode();
t.after(() => fs.rmSync(bin, { recursive: true, force: true }));
const run = (input) => spawnSync('/bin/sh', [WRAPPER], { input: JSON.stringify(input), encoding: 'utf8', cwd: KOSH, env: { PATH: bin } });
const blocked = run(call('Bash', { command: 'rm kosh-reports/data/capture-abc.jsonl' }));
assert.strictEqual(blocked.status, 2, blocked.stderr);
assert.match(blocked.stderr, /needs node/);
const allowed = run(call('Bash', { command: 'git status' }));
assert.strictEqual(allowed.status, 0, allowed.stderr);
// Claude Code's input always has a .jsonl transcript path, and a project folder can be named anything.
const real = run({ ...call('Bash', { command: 'git status' }, path.join(OTHER, 'kosh-reports/data/capture-links')), session_id: SESSION, transcript_path: `/Users/x/.claude/projects/p/${SESSION}.jsonl` });
assert.strictEqual(real.status, 0, real.stderr);
const spaced = spawnSync('/bin/sh', [WRAPPER], { input: JSON.stringify({ transcript_path: '/p/s.jsonl', cwd: '/capture', tool_name: 'Bash', tool_input: { command: 'ls' } }, null, 1), encoding: 'utf8', cwd: KOSH, env: { PATH: bin } });
assert.strictEqual(spaced.status, 0, spaced.stderr);
// The guard never reads an edit's text, so text that mentions captures doesn't need node.
for (const input of [
call('Edit', { file_path: 'README.md', old_string: 'a', new_string: 'see the links and kosh-reports/data/capture-abc.jsonl' }),
call('Write', { file_path: 'docs/notes.md', content: '"command": "rm capture.jsonl"' }),
]) {
const text = run(input);
assert.strictEqual(text.status, 0, text.stderr);
}
});
Loading