@proflandrigan/shards 1.1.0

package/tools/gate-hook/__tests__/auto-verify.test.js

@@ -0,0 +1,343 @@
+// End-to-end tests for auto-verify mode.
+//
+// These tests pipe synthetic stdin payloads to gate-hook.js and assert on
+// stdout (the hook response) and on .shards/auto/state.json (the persisted
+// state). They run in an isolated tmp directory per test so concurrent
+// runs don't collide.
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { spawnSync } from 'child_process';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..', '..');
+const HOOK = path.join(REPO_ROOT, 'tools', 'gate-hook.js');
+
+// ─── Test infrastructure ──────────────────────────────────────────────────────
+
+let tmp;
+
+beforeEach(() => {
+  tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'shards-auto-test-'));
+});
+
+afterEach(() => {
+  if (tmp) {
+    fs.rmSync(tmp, { recursive: true, force: true });
+    tmp = null;
+  }
+});
+
+// Write a fake transcript file with one assistant message containing `text`.
+// Mirrors the JSONL shape Claude Code writes:
+//   {type: "assistant", message: {role: "assistant", content: [...]}}
+function writeTranscript(text, shape = 'real') {
+  const file = path.join(tmp, 'transcript.jsonl');
+  let entry;
+  if (shape === 'real') {
+    entry = {
+      type: 'assistant',
+      message: { role: 'assistant', content: [{ type: 'text', text }] },
+    };
+  } else {
+    // legacy — kept for symmetry; transcript.js still accepts this shape
+    entry = { role: 'assistant', content: [{ type: 'text', text }] };
+  }
+  fs.writeFileSync(file, JSON.stringify(entry) + '\n');
+  return file;
+}
+
+function runHook(event, payload, env = {}) {
+  const result = spawnSync('node', [HOOK, event], {
+    cwd: tmp,
+    input: JSON.stringify(payload),
+    encoding: 'utf8',
+    env: { ...process.env, ...env },
+  });
+  let parsed = null;
+  if (result.stdout && result.stdout.trim()) {
+    try { parsed = JSON.parse(result.stdout.trim()); } catch { /* not JSON */ }
+  }
+  return { stdout: result.stdout, stderr: result.stderr, status: result.status, parsed };
+}
+
+function readAutoState() {
+  const file = path.join(tmp, '.shards', 'auto', 'state.json');
+  if (!fs.existsSync(file)) return { open: false };
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+function readGateState() {
+  const file = path.join(tmp, '.shards', 'gates', 'state.json');
+  if (!fs.existsSync(file)) return { open: false };
+  const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+  // v2 per-session shape: reduce to a flat { open, ... } by surfacing any open
+  // session slot (legacy single-slot files just pass through).
+  if (raw && raw.sessions && typeof raw.sessions === 'object') {
+    const open = Object.values(raw.sessions).find(g => g && g.open);
+    return open ? { open: true, ...open, history: raw.history || [] }
+                : { open: false, history: raw.history || [] };
+  }
+  return raw;
+}
+
+// ─── Tests ────────────────────────────────────────────────────────────────────
+
+describe('auto-verify', () => {
+  it('::AUTO-VERIFY:: marker opens state', () => {
+    const transcript = writeTranscript(
+      '::AUTO-VERIFY:: agent=data-modeller phase=6 tool_budget=5 ttl_minutes=2'
+    );
+    runHook('stop', { transcript_path: transcript, session_id: 's1' });
+    const s = readAutoState();
+    expect(s.open).toBe(true);
+    expect(s.agent).toBe('data-modeller');
+    expect(s.phase).toBe('6');
+    expect(s.tool_budget_remaining).toBe(5);
+    expect(s.tool_budget_initial).toBe(5);
+  });
+
+  it('::ENDAUTO:: marker closes state', () => {
+    // Open
+    const t1 = writeTranscript('::AUTO-VERIFY:: agent=ml-engineer phase=3 tool_budget=10');
+    runHook('stop', { transcript_path: t1, session_id: 's1' });
+    expect(readAutoState().open).toBe(true);
+    // Close
+    const t2 = writeTranscript('Done with verification.\n\n::ENDAUTO::');
+    runHook('stop', { transcript_path: t2, session_id: 's1' });
+    expect(readAutoState().open).toBe(false);
+  });
+
+  it('PreToolUse auto-approves dbt show when block open', () => {
+    const t = writeTranscript('::AUTO-VERIFY:: agent=data-modeller phase=6 tool_budget=5');
+    runHook('stop', { transcript_path: t, session_id: 's1' });
+    const r = runHook('pre-tool-use', {
+      tool_name: 'Bash',
+      tool_input: { command: 'dbt show --select my_model' },
+    });
+    expect(r.parsed && r.parsed.hookSpecificOutput).toBeTruthy();
+    expect(r.parsed.hookSpecificOutput.permissionDecision).toBe('allow');
+    const s = readAutoState();
+    expect(s.tool_budget_remaining).toBe(4);
+  });
+
+  it('PreToolUse passes through non-allowlisted tool', () => {
+    const t = writeTranscript('::AUTO-VERIFY:: agent=data-modeller phase=6');
+    runHook('stop', { transcript_path: t, session_id: 's1' });
+    // A Write tool call should NOT be auto-approved.
+    const r = runHook('pre-tool-use', {
+      tool_name: 'Write',
+      tool_input: { file_path: '/x.sql' },
+    });
+    expect(r.parsed).toBeNull();
+    // Budget should not have decremented.
+    const s = readAutoState();
+    expect(s.tool_budget_remaining).toBe(20);
+  });
+
+  it('PreToolUse rejects dbt build (writes never auto-approved)', () => {
+    const t = writeTranscript('::AUTO-VERIFY:: agent=ae phase=7');
+    runHook('stop', { transcript_path: t, session_id: 's1' });
+    const r = runHook('pre-tool-use', {
+      tool_name: 'Bash',
+      tool_input: { command: 'dbt build --select my_model' },
+    });
+    expect(r.parsed).toBeNull();
+  });
+
+  it('PreToolUse rejects dbt run', () => {
+    const t = writeTranscript('::AUTO-VERIFY:: agent=ae phase=7');
+    runHook('stop', { transcript_path: t, session_id: 's1' });
+    const r = runHook('pre-tool-use', {
+      tool_name: 'Bash',
+      tool_input: { command: 'dbt run --select my_model' },
+    });
+    expect(r.parsed).toBeNull();
+  });
+
+  it('PreToolUse approves SELECT-only psql -c', () => {
+    const t = writeTranscript('::AUTO-VERIFY:: agent=da phase=3');
+    runHook('stop', { transcript_path: t, session_id: 's1' });
+    const r = runHook('pre-tool-use', {
+      tool_name: 'Bash',
+      tool_input: { command: 'psql -c "SELECT count(*) FROM events"' },
+    });
+    expect(r.parsed && r.parsed.hookSpecificOutput).toBeTruthy();
+    expect(r.parsed.hookSpecificOutput.permissionDecision).toBe('allow');
+  });
+
+  it('PreToolUse rejects INSERT via psql', () => {
+    const t = writeTranscript('::AUTO-VERIFY:: agent=da phase=3');
+    runHook('stop', { transcript_path: t, session_id: 's1' });
+    const r = runHook('pre-tool-use', {
+      tool_name: 'Bash',
+      tool_input: { command: 'psql -c "INSERT INTO events VALUES (1)"' },
+    });
+    expect(r.parsed).toBeNull();
+  });
+
+  it('Gate open suspends auto-verify (gates win)', () => {
+    // Open both auto-verify and gate
+    const t1 = writeTranscript('::AUTO-VERIFY:: agent=ae phase=7 tool_budget=5');
+    runHook('stop', { transcript_path: t1, session_id: 's1' });
+    const t2 = writeTranscript(
+      '::GATE:: id=test-gate phase=7 kind=phase agent=ae\nbody\n::ENDGATE::'
+    );
+    runHook('stop', { transcript_path: t2, session_id: 's1' });
+    expect(readGateState().open).toBe(true);
+    expect(readAutoState().open).toBe(true);
+
+    // Tool call should be BLOCKED by gate (not auto-approved). The hook
+    // returns the canonical PreToolUse contract — hookSpecificOutput.permission
+    // Decision: 'deny' — not the legacy `decision: 'block'` form.
+    const r = runHook('pre-tool-use', {
+      tool_name: 'Bash',
+      tool_input: { command: 'dbt show --select my_model' },
+      // Same session that opened the gate — under the v2 per-session model the
+      // gate only blocks its own session, so the session_id must match.
+      session_id: 's1',
+    });
+    expect(r.parsed && r.parsed.hookSpecificOutput).toBeTruthy();
+    expect(r.parsed.hookSpecificOutput.permissionDecision).toBe('deny');
+    expect(r.parsed.hookSpecificOutput.permissionDecisionReason).toMatch(/GATE-BLOCK/);
+  });
+
+  it('Tool budget exhaustion closes block', () => {
+    const t = writeTranscript('::AUTO-VERIFY:: agent=da phase=3 tool_budget=2');
+    runHook('stop', { transcript_path: t, session_id: 's1' });
+    // Use 2 approvals
+    for (let i = 0; i < 2; i++) {
+      runHook('pre-tool-use', {
+        tool_name: 'Bash', tool_input: { command: 'dbt show' },
+      });
+    }
+    // Third call: budget is 0 → isExpired returns true → block closes, falls through
+    const r = runHook('pre-tool-use', {
+      tool_name: 'Bash', tool_input: { command: 'dbt show' },
+    });
+    expect(r.parsed).toBeNull();
+    expect(readAutoState().open).toBe(false);
+  });
+
+  it('SHARDS_AUTO_VERIFY=0 disables the branch', () => {
+    // Open without env disabled
+    const t = writeTranscript('::AUTO-VERIFY:: agent=da phase=3');
+    runHook('stop', { transcript_path: t, session_id: 's1' }, { SHARDS_AUTO_VERIFY: '0' });
+    // State should NOT have been written
+    expect(readAutoState().open).toBe(false);
+  });
+
+  it('User halt prompt closes auto-verify', () => {
+    const t = writeTranscript('::AUTO-VERIFY:: agent=da phase=3');
+    runHook('stop', { transcript_path: t, session_id: 's1' });
+    expect(readAutoState().open).toBe(true);
+    runHook('user-prompt-submit', { prompt: 'stop, hold on a moment' });
+    expect(readAutoState().open).toBe(false);
+  });
+
+  it('Compound bash command is rejected (no auto-approve on rm via &&)', () => {
+    const t = writeTranscript('::AUTO-VERIFY:: agent=da phase=3');
+    runHook('stop', { transcript_path: t, session_id: 's1' });
+    const r = runHook('pre-tool-use', {
+      tool_name: 'Bash',
+      tool_input: { command: 'dbt show && rm -rf /tmp/foo' },
+    });
+    expect(r.parsed).toBeNull();
+  });
+
+  it('Read tool always auto-approves when block open', () => {
+    const t = writeTranscript('::AUTO-VERIFY:: agent=da phase=3');
+    runHook('stop', { transcript_path: t, session_id: 's1' });
+    const r = runHook('pre-tool-use', {
+      tool_name: 'Read',
+      tool_input: { file_path: '/x' },
+    });
+    expect(r.parsed && r.parsed.hookSpecificOutput.permissionDecision).toBe('allow');
+  });
+
+  it('Write tool blocked even with auto-verify open', () => {
+    const t = writeTranscript('::AUTO-VERIFY:: agent=da phase=3');
+    runHook('stop', { transcript_path: t, session_id: 's1' });
+    const r = runHook('pre-tool-use', {
+      tool_name: 'Write',
+      tool_input: { file_path: '/x' },
+    });
+    expect(r.parsed).toBeNull();
+  });
+
+  it('Auto-verify clamps tool_budget to AUTO_MAX_TOOL_BUDGET', () => {
+    const t = writeTranscript('::AUTO-VERIFY:: agent=da phase=3 tool_budget=999');
+    runHook('stop', { transcript_path: t, session_id: 's1' });
+    const s = readAutoState();
+    expect(s.tool_budget_initial).toBe(50);
+  });
+
+  it('reads real Claude Code transcript shape ({type, message: {role, content}})', () => {
+    // This is the canonical regression test — the actual transcript shape Claude
+    // Code writes. transcript.js previously only matched the legacy {role, content}
+    // shape, which silently broke gate + auto-verify enforcement.
+    const transcript = writeTranscript(
+      '::AUTO-VERIFY:: agent=data-modeller phase=6 tool_budget=5',
+      'real'
+    );
+    runHook('stop', { transcript_path: transcript, session_id: 's1' });
+    const s = readAutoState();
+    expect(s.open).toBe(true);
+    expect(s.tool_budget_remaining).toBe(5);
+  });
+
+  it('reads legacy transcript shape for backward compat', () => {
+    const transcript = writeTranscript(
+      '::AUTO-VERIFY:: agent=data-modeller phase=6 tool_budget=5',
+      'legacy'
+    );
+    runHook('stop', { transcript_path: transcript, session_id: 's1' });
+    const s = readAutoState();
+    expect(s.open).toBe(true);
+  });
+
+  it('open+close in same message: end state is closed', () => {
+    const transcript = writeTranscript(
+      '::AUTO-VERIFY:: agent=da phase=3 tool_budget=5\nverification done\n::ENDAUTO::'
+    );
+    runHook('stop', { transcript_path: transcript, session_id: 's1' });
+    const s = readAutoState();
+    expect(s.open).toBe(false);
+    expect(Array.isArray(s.history) && s.history.length >= 1).toBe(true);
+  });
+
+  it('close+open in same message: end state is open (re-opened)', () => {
+    // First open a block in turn 1
+    const t1 = writeTranscript('::AUTO-VERIFY:: agent=da phase=3 tool_budget=5');
+    runHook('stop', { transcript_path: t1, session_id: 's1' });
+    expect(readAutoState().open).toBe(true);
+    // Turn 2 closes the previous and opens a new one
+    const t2 = writeTranscript(
+      '::ENDAUTO::\n\n::AUTO-VERIFY:: agent=da phase=3 tool_budget=10'
+    );
+    runHook('stop', { transcript_path: t2, session_id: 's1' });
+    const s = readAutoState();
+    expect(s.open).toBe(true);
+    expect(s.tool_budget_initial).toBe(10);
+  });
+
+  it('audit log written to .shards/auto/history.jsonl', () => {
+    const t = writeTranscript('::AUTO-VERIFY:: agent=da phase=3');
+    runHook('stop', { transcript_path: t, session_id: 's1' });
+    runHook('pre-tool-use', {
+      tool_name: 'Bash',
+      tool_input: { command: 'dbt show --select x' },
+    });
+    const log = path.join(tmp, '.shards', 'auto', 'history.jsonl');
+    expect(fs.existsSync(log)).toBe(true);
+    const lines = fs.readFileSync(log, 'utf8').trim().split('\n');
+    const events = lines.map(l => JSON.parse(l));
+    expect(events.some(e => e.event === 'opened')).toBe(true);
+    expect(events.some(e => e.event === 'auto-approved' && e.tool === 'Bash')).toBe(true);
+  });
+});

package/tools/gate-hook/auto-allowlist.js

@@ -0,0 +1,179 @@
+// Hardcoded read-only allowlist for auto-verify mode.
+//
+// Returns true ONLY for tool calls that are confirmed safe verification
+// operations. Everything else falls through to the normal permission prompt.
+//
+// This list is intentionally NOT user-configurable. Users can extend the
+// session-wide allowlist via .claude/settings.json permissions.allow[]
+// (which Claude Code already honors before the hook fires). Auto-verify
+// is for the *additional* operations agents do during bulk verification
+// stretches that would otherwise spam prompts.
+'use strict';
+
+const sqlGuard = require('./sql-guard.js');
+
+// Tools that are always read-only.
+const READ_ONLY_TOOLS = new Set([
+  'Read', 'Glob', 'Grep', 'WebSearch',
+]);
+
+// Bash command prefixes that are read-only verification operations.
+// Matched as: command.trim() === prefix || command.startsWith(prefix + ' ')
+// Use the most specific prefix (e.g. "dbt show" not just "dbt") so that
+// destructive subcommands like "dbt run" or "dbt build" are NOT matched.
+const READ_ONLY_BASH_PREFIXES = [
+  // dbt — read-only subcommands only
+  'dbt show',
+  'dbt ls',
+  'dbt list',
+  'dbt parse',
+  'dbt compile',
+  'dbt deps',
+  'dbt debug',
+  'dbt source freshness',
+
+  // BigQuery CLI — metadata reads
+  'bq show',
+  'bq ls',
+  'bq head',
+
+  // git — already in the readonly preset, but listed here too as a
+  // belt-and-braces guarantee for users who edited their settings.json.
+  // Only read-only subcommand forms: bare `git branch`/`git tag`/`git remote`
+  // also match -d/-D/-m/-M, add/remove/set-url, and positional-arg creation.
+  'git status',
+  'git log',
+  'git diff',
+  'git show',
+  'git rev-parse',
+  'git stash list',
+  'git branch --list',
+  'git branch -a',
+  'git branch -r',
+  'git branch -v',
+  'git branch -vv',
+  'git branch --remotes',
+  'git branch --merged',
+  'git branch --no-merged',
+  'git branch --show-current',
+  'git branch --contains',
+  'git tag --list',
+  'git tag -l',
+  'git remote -v',
+  'git remote show',
+  'git remote get-url',
+
+  // python/pip metadata
+  'pip list',
+  'pip show',
+  'pip freeze',
+
+  // node/npm metadata
+  'npm ls',
+  'npm list',
+  'npm outdated',
+  'npm view',
+
+  // generic file inspection
+  'ls', 'cat', 'head', 'tail', 'wc', 'file', 'stat',
+];
+
+// Bash patterns that indicate destructive intent. Even if a more permissive
+// prefix matches above, these veto the auto-approval. Belt-and-braces.
+const DESTRUCTIVE_MARKERS = [
+  /\brm\b/, /\bmv\b/, /\bcp\s+-/, // basic destructive
+  />\s*[^|]/,                       // shell redirect to file
+  />>\s*/,                          // append redirect
+  /\bsudo\b/,
+  /\bcurl\b/, /\bwget\b/,           // network fetches that may exfiltrate
+  /\|\s*sh\b/, /\|\s*bash\b/,       // pipe-to-shell
+  /\$\([^)]/,                       // command substitution — bail (could hide anything)
+  /`[^`]/,                          // backtick command substitution
+  // find — -delete and -exec/-execdir/-ok/-okdir run arbitrary (often
+  // destructive) work with no `rm`/`;` present to trip the other markers;
+  // -fprint/-fprint0/-fprintf/-fls write output to a file (path-controlled
+  // write). `-ok` must not match `-okdir` (its exec-per-file prompt sibling),
+  // and `-fprint` must not match `-fprintf`, so each is listed separately;
+  // `-printf`/`-ls`/`-print0` (stdout-only forms) stay read-only.
+  /\s-delete\b/,
+  /\s-exec\b/,
+  /\s-execdir\b/,
+  /\s-ok\b/,
+  /\s-okdir\b/,
+  /\s-fprint(?:0)?\b/,
+  /\s-fprintf\b/,
+  /\s-fls\b/,
+  // git branch — the `-v`/`-vv` listing forms silently become CREATES when a
+  // bare branch name follows (`git branch -v feature` creates `feature`).
+  // Listing with `-v`/`-vv` never takes a positional, so any non-option token
+  // right after them is a create intent.
+  /\bgit\s+branch\s+-v+\s+[^\s-]/,
+  // git diff/show/log — --output=FILE / --output FILE / -o FILE silently
+  // writes a patch file. `--output-indicator-*` (a read-only diff styling
+  // flag) must not match.
+  /--output(?=\s|=)/,
+  /\bgit\s+(?:diff|show|log)\b[^\n]*\s-o(?=\s*\S)/,
+];
+
+// Compound separator detection — a single allow shouldn't authorize
+// `safe-cmd && rm -rf /`. If we see compound separators, bail.
+// Covers `&&`, `||`, `;`, `|`, a lone backgrounding `&` (`cat x & rm ...`),
+// and a literal newline (a command separator in bash when the model emits a
+// multi-line tool call). `&&`/`||` are matched by their own alternatives so
+// lone `&`/`|` (e.g. inside `$((..))` arithmetic) can't double-match.
+const COMPOUND_SEPARATORS = /(\&\&|\|\||[;&\n]|\|(?!\|))/;
+
+function isAutoApprovable(toolName, toolInput) {
+  if (!toolName) return false;
+
+  // Always-safe tools
+  if (READ_ONLY_TOOLS.has(toolName)) return true;
+
+  if (toolName !== 'Bash') return false;
+  if (!toolInput || typeof toolInput.command !== 'string') return false;
+
+  const cmd = toolInput.command.trim();
+  if (!cmd) return false;
+
+  // Reject compound commands outright. A user-facing rule should match each
+  // subcommand independently; we don't try to split-and-recheck because that
+  // gets risky. Agents doing verification should run one statement at a time.
+  if (COMPOUND_SEPARATORS.test(cmd)) {
+    // Special case: SQL guard already handles `;`-separated SELECT statements
+    // inside a quoted argument. The compound check fires on bare shell `;`.
+    // SQL invocations have the `;` *inside* a quoted SQL string, so the bare
+    // shell-level check would match. We give SQL guard first crack:
+    if (sqlGuard.isReadOnlyCliInvocation(cmd)) return true;
+    return false;
+  }
+
+  // Destructive markers veto.
+  for (const re of DESTRUCTIVE_MARKERS) {
+    if (re.test(cmd)) {
+      // Same SQL-guard exception: a SELECT may legitimately reference a column
+      // called `rm` or contain `>`. But destructive markers in non-SQL Bash
+      // commands are hard veto.
+      if (sqlGuard.isReadOnlyCliInvocation(cmd)) return true;
+      return false;
+    }
+  }
+
+  // Prefix match against the read-only list.
+  for (const prefix of READ_ONLY_BASH_PREFIXES) {
+    if (cmd === prefix) return true;
+    if (cmd.startsWith(prefix + ' ')) return true;
+  }
+
+  // bq query --dry_run is a metadata-only call.
+  if (/^bq\s+query\b/.test(cmd) && /--dry_run\b/.test(cmd)) {
+    // Dry-run still doesn't write. Allow.
+    return true;
+  }
+
+  // SELECT-only warehouse-CLI SQL.
+  if (sqlGuard.isReadOnlyCliInvocation(cmd)) return true;
+
+  return false;
+}
+
+module.exports = { isAutoApprovable, READ_ONLY_BASH_PREFIXES, READ_ONLY_TOOLS };

package/tools/gate-hook/auto-state.js

@@ -0,0 +1,68 @@
+// Auto-verify state read/write for .shards/auto/state.json
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const AUTO_DIR = path.join(process.cwd(), '.shards', 'auto');
+const STATE = path.join(AUTO_DIR, 'state.json');
+
+function ensureDir() {
+  fs.mkdirSync(AUTO_DIR, { recursive: true });
+}
+
+function read() {
+  try {
+    return JSON.parse(fs.readFileSync(STATE, 'utf8'));
+  } catch {
+    return { open: false, history: [] };
+  }
+}
+
+// Atomic write via tmp + rename. See state.js for rationale. Concurrent UI
+// polls and hook invocations would otherwise observe partial JSON during a
+// bare writeFileSync and silently fall back to { open: false }.
+function write(s) {
+  ensureDir();
+  const tmp = `${STATE}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}.tmp`;
+  try {
+    fs.writeFileSync(tmp, JSON.stringify(s, null, 2));
+    fs.renameSync(tmp, STATE);
+  } catch (err) {
+    try { fs.unlinkSync(tmp); } catch {}
+    throw err;
+  }
+}
+
+// Returns true if the auto-verify block has expired (ttl elapsed or budget
+// exhausted). Caller is responsible for closing the state when this returns
+// true.
+function isExpired(s) {
+  if (!s || !s.open) return false;
+  if (typeof s.tool_budget_remaining === 'number' && s.tool_budget_remaining <= 0) {
+    return true;
+  }
+  if (s.expires_at) {
+    return new Date(s.expires_at).getTime() <= Date.now();
+  }
+  return false;
+}
+
+function close(s, reason) {
+  const closed_at = new Date().toISOString();
+  const historyEntry = {
+    id: s.id,
+    agent: s.agent,
+    phase: s.phase,
+    opened_at: s.opened_at,
+    closed_at,
+    closed_reason: reason,
+    approvals_used: (s.tool_budget_initial || 0) - (s.tool_budget_remaining || 0),
+  };
+  return {
+    open: false,
+    history: [...(s.history || []), historyEntry],
+  };
+}
+
+module.exports = { read, write, isExpired, close, STATE, AUTO_DIR };

package/tools/gate-hook/classify.js

@@ -0,0 +1,21 @@
+// Classify user prompts as confirm / deny / ambiguous
+'use strict';
+
+const CONFIRM_RE = /^\s*(y|yes|yep|yeah|yup|confirm(ed)?|proceed|go|go ahead|approved|lgtm|ship it|ok|okay|sounds good|looks good|continue|next|advance|move on)\b/i;
+const DENY_RE = /^\s*(n|no|nope|stop|hold|wait|change|revise|actually|not quite|let me)\b/i;
+
+// ::GATE-CONFIRM:: <id> — explicit confirm from advanced users
+const EXPLICIT_CONFIRM_RE = /^\s*::GATE-CONFIRM::\s+(\S+)/i;
+
+function classify(prompt) {
+  if (!prompt || !prompt.trim()) return 'ambiguous';
+
+  const m = EXPLICIT_CONFIRM_RE.exec(prompt);
+  if (m) return 'confirm';
+
+  if (CONFIRM_RE.test(prompt)) return 'confirm';
+  if (DENY_RE.test(prompt)) return 'deny';
+  return 'ambiguous';
+}
+
+module.exports = { classify };

package/tools/gate-hook/log.js

@@ -0,0 +1,57 @@
+// Append entries to violations.jsonl / gate-history.jsonl
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const GATE_DIR = path.join(process.cwd(), '.shards', 'gates');
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+// Atomic-append: open with O_APPEND and write the full JSON line in a single
+// syscall. POSIX guarantees that writes <= PIPE_BUF (typically 4096 bytes) to
+// a file opened with O_APPEND are atomic with respect to other O_APPEND
+// writers — concurrent gate-hook invocations cannot interleave bytes within a
+// single line. JSONL entries here are well under PIPE_BUF.
+//
+// We deliberately do NOT use fs.appendFileSync here because Node's
+// implementation can fall back to non-atomic open/write/close patterns under
+// some conditions. Doing the open + writeSync + close explicitly is a
+// belt-and-braces guarantee.
+function atomicAppendLine(file, line) {
+  let fd;
+  try {
+    fd = fs.openSync(file, 'a');
+    fs.writeSync(fd, line);
+  } finally {
+    if (typeof fd === 'number') {
+      try { fs.closeSync(fd); } catch {}
+    }
+  }
+}
+
+function appendViolation(entry) {
+  ensureDir(GATE_DIR);
+  const file = path.join(GATE_DIR, 'violations.jsonl');
+  const line = JSON.stringify({ ...entry, ts: new Date().toISOString() }) + '\n';
+  atomicAppendLine(file, line);
+}
+
+function appendHistory(entry) {
+  ensureDir(GATE_DIR);
+  const file = path.join(GATE_DIR, 'gates.jsonl');
+  const line = JSON.stringify({ ...entry, ts: new Date().toISOString() }) + '\n';
+  atomicAppendLine(file, line);
+}
+
+function appendAutoHistory(entry) {
+  const dir = path.join(process.cwd(), '.shards', 'auto');
+  ensureDir(dir);
+  const file = path.join(dir, 'history.jsonl');
+  const line = JSON.stringify({ ...entry, ts: new Date().toISOString() }) + '\n';
+  atomicAppendLine(file, line);
+}
+
+module.exports = { appendViolation, appendHistory, appendAutoHistory };