claws-code 0.8.0

package/scripts/gen-client-types.mjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+// gen-client-types.mjs — Generate schemas/client-types.d.ts from SCHEMA_BY_NAME.
+// Usage: node scripts/gen-client-types.mjs  (from repo root)
+
+import { execSync } from 'child_process';
+import { writeFileSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { createRequire } from 'module';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname  = dirname(__filename);
+const repoRoot   = join(__dirname, '..');
+const extRoot    = join(repoRoot, 'extension');
+const bundlePath = join(extRoot, 'dist', 'event-schemas.bundle.cjs');
+
+mkdirSync(join(extRoot, 'dist'), { recursive: true });
+
+const esbuildBin = join(extRoot, 'node_modules', '.bin', 'esbuild');
+const srcPath    = join(extRoot, 'src', 'event-schemas.ts');
+execSync(
+  `"${esbuildBin}" "${srcPath}" --bundle --format=cjs --platform=node --outfile="${bundlePath}"`,
+  { stdio: 'pipe' },
+);
+
+const require = createRequire(__filename);
+const mod = require(bundlePath);
+const SCHEMA_BY_NAME = mod.SCHEMA_BY_NAME ?? {};
+
+function zodToTs(schema, depth = 0) {
+  const def = schema._def;
+  const t = def.typeName ?? 'unknown';
+  const pad = '  '.repeat(depth);
+
+  switch (t) {
+    case 'ZodObject': {
+      const shape = schema.shape;
+      const fields = Object.entries(shape).map(([k, v]) => {
+        const isOpt = v._def.typeName === 'ZodOptional';
+        const inner = isOpt ? v._def.innerType : v;
+        return `${pad}  ${k}${isOpt ? '?' : ''}: ${zodToTs(inner, depth + 1)};`;
+      }).join('\n');
+      return `{\n${fields}\n${pad}}`;
+    }
+    case 'ZodString':   return 'string';
+    case 'ZodNumber':   return 'number';
+    case 'ZodBoolean':  return 'boolean';
+    case 'ZodUnknown':  return 'unknown';
+    case 'ZodNull':     return 'null';
+    case 'ZodLiteral':  return JSON.stringify(def.value);
+    case 'ZodEnum':     return def.values.map(v => JSON.stringify(v)).join(' | ');
+    case 'ZodArray':    return `Array<${zodToTs(def.type, depth)}>`;
+    case 'ZodRecord':   return `Record<string, ${zodToTs(def.valueType, depth)}>`;
+    case 'ZodNullable': return `${zodToTs(def.innerType, depth)} | null`;
+    case 'ZodOptional': return zodToTs(def.innerType, depth);
+    case 'ZodUnion':    return def.options.map(o => zodToTs(o, depth)).join(' | ');
+    default:            return 'unknown';
+  }
+}
+
+function toPascal(kebab) {
+  return kebab
+    .replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase())
+    .replace(/^[a-z]/, c => c.toUpperCase());
+}
+
+const lines = [
+  '// @generated — do not edit. Run: node scripts/gen-client-types.mjs',
+  '// Source: extension/src/event-schemas.ts — SCHEMA_BY_NAME',
+  '',
+];
+
+for (const [name, schema] of Object.entries(SCHEMA_BY_NAME)) {
+  const iface = toPascal(name);
+  lines.push(`export interface ${iface} ${zodToTs(schema)}`);
+  lines.push('');
+}
+
+const outPath = join(repoRoot, 'schemas', 'client-types.d.ts');
+writeFileSync(outPath, lines.join('\n'), 'utf8');
+console.log(`[gen-client-types] wrote schemas/client-types.d.ts (${Object.keys(SCHEMA_BY_NAME).length} types)`);

package/scripts/git-hooks/pre-commit

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# Claws pre-commit hook — enforces CHANGELOG.md is updated for code changes.
+# Installed by scripts/install.sh into .git/hooks/pre-commit.
+
+staged=$(git diff --cached --name-only 2>/dev/null)
+
+# Only care about commits that touch code files
+code_files=$(echo "$staged" | grep -E '\.(ts|js|mjs|sh)$' | grep -v '\.d\.ts$' || true)
+
+if [ -z "$code_files" ]; then
+  exit 0
+fi
+
+# CHANGELOG.md must also be staged
+if echo "$staged" | grep -q "^CHANGELOG\.md$"; then
+  exit 0
+fi
+
+echo ""
+echo "  pre-commit: CHANGELOG.md not staged"
+echo ""
+echo "  Code files in this commit:"
+echo "$code_files" | sed 's/^/    /'
+echo ""
+echo "  Update CHANGELOG.md with what changed, then:"
+echo "    git add CHANGELOG.md && git commit"
+echo ""
+echo "  To bypass (chores, docs-only, WIP):"
+echo "    git commit --no-verify"
+echo ""
+exit 1

package/scripts/hooks/lifecycle-state.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+// Shared module — read/write .claws/lifecycle-state.json
+'use strict';
+const fs   = require('fs');
+const path = require('path');
+
+const PHASES = [
+  'PLAN-REQUIRED',
+  'PLAN',
+  'SPAWN',
+  'DEPLOY',
+  'OBSERVE',
+  'RECOVER',
+  'HARVEST',
+  'CLEANUP',
+  'REFLECT',
+];
+
+function phaseIndex(phase) {
+  return PHASES.indexOf(phase);
+}
+
+function statePath(cwd) {
+  return path.join(cwd, '.claws', 'lifecycle-state.json');
+}
+
+function readState(cwd) {
+  const p = statePath(cwd);
+  if (!fs.existsSync(p)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeState(cwd, state) {
+  const p = statePath(cwd);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  // M-29: atomic write (tmp + renameSync) — mirrors extension/src/lifecycle-store.ts.
+  // Prevents partial lifecycle-state.json if the hook process is killed mid-write.
+  // F3: open+writeSync+fsyncSync+close before rename for durability on power-cut.
+  const content = JSON.stringify(state, null, 2) + '\n';
+  const tmp = p + '.claws-tmp.' + process.pid + '-' + (++writeState._nonce);
+  let _fd;
+  try {
+    _fd = fs.openSync(tmp, 'w', 0o644);
+    fs.writeSync(_fd, content);
+    fs.fsyncSync(_fd);
+    fs.closeSync(_fd);
+    _fd = null;
+    fs.renameSync(tmp, p);
+  } catch (err) {
+    if (_fd != null) { try { fs.closeSync(_fd); } catch { /* ignore */ } }
+    try { fs.unlinkSync(tmp); } catch { /* ignore */ }
+    throw err;
+  }
+}
+writeState._nonce = 0;
+
+module.exports = { readState, writeState, PHASES, phaseIndex };

package/scripts/hooks/package.json

@@ -0,0 +1,4 @@
+{
+  "type": "commonjs",
+  "private": true
+}

package/scripts/hooks/post-tool-use-claws.js

@@ -0,0 +1,292 @@
+#!/usr/bin/env node
+try { require('fs').appendFileSync('/tmp/claws-hook-trace.log', `${new Date().toISOString()} hook-fired pid=${process.pid} cwd=${process.cwd()} argv=${JSON.stringify(process.argv)}\n`); } catch {}
+// Claws PostToolUse hook — fail-closes the spawn → monitor race window.
+//
+// Fires after every MCP tool call. Only acts on spawn-class tools
+// (claws_create/worker/fleet/dispatch_subworker) where the call succeeded
+// and returned a terminal_id. Waits up to ~4s for lifecycle.monitors to
+// register the terminal (4s nominal so cleanup has ~1s before the 5s self-kill).
+// If missing, publishes wave.violation event + auto-closes the orphaned terminal.
+//
+// SAFETY CONTRACT (P5): never crash, never block, never exit non-zero.
+// Errors silently swallowed unless CLAWS_DEBUG=1.
+'use strict';
+
+// M-24: gate error handlers on CLAWS_DEBUG — when CLAWS_DEBUG=1, errors
+// propagate visibly for debugging instead of being silently swallowed.
+if (!process.env.CLAWS_DEBUG) {
+  process.on('uncaughtException', () => { try { process.exit(0); } catch {} });
+  process.on('unhandledRejection', () => { try { process.exit(0); } catch {} });
+}
+
+
+// M-13: 5-second self-kill safety timer — hook can never hang the parent process.
+setTimeout(() => { process.exit(0); }, 5000).unref();
+
+const SPAWN_CLASS = new Set([
+  'mcp__claws__claws_create',
+  'mcp__claws__claws_worker',
+  'mcp__claws__claws_fleet',
+  'mcp__claws__claws_dispatch_subworker',
+]);
+
+// Monitor wait window: 4000 ms (< 5 s self-kill) leaves ~1 s for violation
+// cleanup (publish + close) before the self-kill fires.
+const MONITOR_WAIT_MS = 4000;
+const MONITOR_POLL_MS = 500;
+
+let input = '';
+// M-13: single try block for both 'data' and 'end' — fail together or not at all.
+try {
+  process.stdin.on('data', d => { input += d; });
+  process.stdin.on('end', () => {
+    run(input).catch(() => { try { process.exit(0); } catch {} });
+  });
+} catch {
+  process.exit(0);
+}
+
+// Append a structured diagnostic line to /tmp/claws-hook-diag.log (never throws).
+function writeDiag(event, detail) {
+  try {
+    const line = `${new Date().toISOString()} hook-diag ${event} ${JSON.stringify(detail)}\n`;
+    require('fs').appendFileSync('/tmp/claws-hook-diag.log', line);
+  } catch {}
+}
+
+// BUG6-L1 (v0714, .local/plans/v0714/investigations/bug6-hook-nested-context.md):
+// Forward-compat normalizer. Handles all observed Claude Code tool_response shapes and
+// returns null for unknown/unparseable input so callers can log a diagnostic instead of
+// silently proceeding with a broken value.
+//
+// Shapes handled:
+//  1. Bare array:     [{type:'text', text:'<JSON>'}]          ← current Claude Code
+//  2. Wrapped object: {content:[{type:'text', text:'<JSON>'}]} ← older Claude Code
+//  3. Plain object:   {ok:true, terminal_id:..., ...}          ← already-unwrapped / tests
+//  4. null / undefined / primitive → null
+//  5. Unknown shape → null + diagnostic
+function unwrapMcpResponse(resp) {
+  if (resp == null || typeof resp !== 'object') {
+    writeDiag('unwrap-null-or-primitive', { type: typeof resp });
+    return null;
+  }
+
+  // Shape 3 — plain object already unwrapped
+  if (resp.ok !== undefined) return resp;
+
+  // Shape 1 — bare array of content blocks (current Claude Code)
+  if (Array.isArray(resp) && resp[0] && typeof resp[0].text === 'string') {
+    try { return JSON.parse(resp[0].text); }
+    catch (e) { writeDiag('unwrap-bare-array-parse-fail', { error: e.message, preview: resp[0].text.slice(0, 200) }); return null; }
+  }
+
+  // Shape 2 — wrapped object with content array (older Claude Code)
+  if (Array.isArray(resp.content) && resp.content[0] && typeof resp.content[0].text === 'string') {
+    try { return JSON.parse(resp.content[0].text); }
+    catch (e) { writeDiag('unwrap-wrapped-parse-fail', { error: e.message, preview: resp.content[0].text.slice(0, 200) }); return null; }
+  }
+
+  // Unknown shape — emit diagnostic so future format changes are observable
+  writeDiag('unwrap-unknown-shape', { keys: Object.keys(resp), isArray: Array.isArray(resp), preview: JSON.stringify(resp).slice(0, 300) });
+  return null;
+}
+
+async function run(raw) {
+  try { require('fs').appendFileSync(`/tmp/claws-hook-stdin-${process.pid}.json`, raw); } catch {}
+  try {
+    const fs   = require('fs');
+    const path = require('path');
+
+    let data = {};
+    try { data = JSON.parse(raw); } catch { process.exit(0); return; }
+
+    const toolName = data.tool_name || '';
+    if (!SPAWN_CLASS.has(toolName)) { process.exit(0); return; }
+
+    const resp = unwrapMcpResponse(data.tool_response);
+    if (!resp) { writeDiag('unwrap-failed', { tool: toolName }); process.exit(0); return; }
+    if (!resp.ok) { process.exit(0); return; }
+
+    const terminalIds = extractTerminalIds(resp);
+    if (terminalIds.length === 0) { process.exit(0); return; }
+
+    const cwd = data.cwd || process.cwd();
+    const socketPath = findSocket(cwd);
+    if (!socketPath) { process.exit(0); return; }
+
+    // Layer 1: spawn per-worker pgrep watchers (fire-and-forget, <1ms).
+    // Complements the lifecycle.snapshot check below — verifies an OS-level
+    // stream-events.js process is actually alive watching the corrId, not just
+    // that lifecycle.monitors[] was pre-populated by mcp_server at spawn time.
+    spawnWatchers(extractWorkerEntries(resp), socketPath);
+
+    for (const tid of terminalIds) {
+      await checkOne(socketPath, tid, toolName);
+    }
+    process.exit(0);
+  } catch {
+    process.exit(0);
+  }
+}
+
+// Returns [{terminalId, corrId}] for spawning per-worker pgrep watchers.
+function extractWorkerEntries(resp) {
+  if (Array.isArray(resp.workers)) {
+    return resp.workers
+      .filter(w => w && (w.terminal_id != null || w.id != null))
+      .map(w => ({
+        terminalId: w.terminal_id != null ? w.terminal_id : w.id,
+        corrId:     w.correlation_id || null,
+      }));
+  }
+  const tid = resp.terminal_id != null   ? resp.terminal_id
+    : Array.isArray(resp.terminal_ids) && resp.terminal_ids[0] != null ? resp.terminal_ids[0]
+    : resp.id != null ? resp.id
+    : null;
+  return [{ terminalId: tid, corrId: resp.correlation_id || null }];
+}
+
+function spawnWatchers(entries, socketPath) {
+  const { spawn } = require('child_process');
+  const path      = require('path');
+  const fs        = require('fs');
+  const watcherPath = path.join(__dirname, '..', 'monitor-arm-watch.js');
+  // Derive the project root from the socket path so the watcher's cwd is
+  // deterministic regardless of where the hook process was launched from.
+  const projectRoot = socketPath
+    ? path.dirname(path.dirname(socketPath))
+    : undefined;
+  for (const { terminalId, corrId } of entries) {
+    if (!corrId || terminalId == null) continue;
+    try {
+      const debugLog = `/tmp/claws-monitor-arm-watch-${corrId}.log`;
+      const fd = fs.openSync(debugLog, 'a');
+      spawn(process.execPath, [
+        watcherPath,
+        '--corr-id',  corrId,
+        '--term-id',  String(terminalId),
+        '--grace-ms', '10000',
+        '--socket',   socketPath,
+      ], {
+        detached: true,
+        stdio:    ['ignore', fd, fd],
+        cwd:      projectRoot,
+      }).unref();
+      try { fs.closeSync(fd); } catch {}
+    } catch { /* fire-and-forget — never throw */ }
+  }
+}
+
+function extractTerminalIds(resp) {
+  if (Array.isArray(resp.terminal_ids)) {
+    return resp.terminal_ids.filter(id => id != null);
+  }
+  if (resp.terminal_id != null) return [resp.terminal_id];
+  // claws_create returns { id, logPath? } — use id as fallback
+  if (resp.id != null) return [resp.id];
+  // claws_fleet: { workers: [{terminal_id, ...}] }
+  if (Array.isArray(resp.workers)) {
+    return resp.workers
+      .filter(w => w && (w.terminal_id != null || w.id != null))
+      .map(w => (w.terminal_id != null ? w.terminal_id : w.id));
+  }
+  return [];
+}
+
+async function checkOne(socketPath, terminalId, toolName) {
+  const registered = await waitForMonitor(socketPath, terminalId, MONITOR_WAIT_MS, MONITOR_POLL_MS);
+  if (registered) return;
+
+  try {
+    process.stderr.write(
+      `[claws] PostToolUse: monitor not registered for terminal ${terminalId} within 5s.` +
+      ` Auto-cancelling spawn (use Monitor + scripts/stream-events.js | grep pattern next time).\n`
+    );
+  } catch {}
+
+  try {
+    await sendCmd(socketPath, {
+      cmd: 'publish',
+      topic: 'wave.violation',
+      payload: { kind: 'monitor-missing', terminal_id: terminalId, tool_name: toolName, ts: new Date().toISOString() },
+    });
+  } catch {}
+
+  try {
+    await sendCmd(socketPath, { cmd: 'close', id: terminalId });
+  } catch {}
+}
+
+async function waitForMonitor(socketPath, terminalId, maxWaitMs, intervalMs) {
+  const deadline = Date.now() + maxWaitMs;
+  while (Date.now() < deadline) {
+    try {
+      const snap = await sendCmd(socketPath, { cmd: 'lifecycle.snapshot' });
+      if (monitorPresent(snap, terminalId)) return true;
+    } catch { /* socket error — retry */ }
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) break;
+    await sleep(Math.min(intervalMs, remaining));
+  }
+  return false;
+}
+
+function monitorPresent(snap, terminalId) {
+  if (!snap || !snap.ok) return false;
+  const state = snap.state || snap;
+  const monitors = state.monitors;
+  if (!monitors) return false;
+  if (Array.isArray(monitors)) {
+    return monitors.some(m => m && String(m.terminal_id) === String(terminalId));
+  }
+  return Object.prototype.hasOwnProperty.call(monitors, String(terminalId));
+}
+
+function sendCmd(socketPath, obj) {
+  return new Promise((resolve, reject) => {
+    const net = require('net');
+    const id  = Math.random().toString(36).slice(2);
+    const msg = JSON.stringify({ id, ...obj }) + '\n';
+    let buf  = '';
+    let done = false;
+    const sock = net.createConnection(socketPath);
+    const timer = setTimeout(() => {
+      if (!done) { done = true; try { sock.destroy(); } catch {} reject(new Error('timeout')); }
+    }, 2000);
+    sock.on('connect', () => {
+      try { sock.write(msg); } catch (e) {
+        if (!done) { done = true; clearTimeout(timer); reject(e); }
+      }
+    });
+    sock.on('data', chunk => {
+      buf += chunk;
+      const nl = buf.indexOf('\n');
+      if (nl !== -1 && !done) {
+        done = true;
+        clearTimeout(timer);
+        try { sock.destroy(); } catch {}
+        try { resolve(JSON.parse(buf.slice(0, nl))); } catch (e) { reject(e); }
+      }
+    });
+    sock.on('error', e => { if (!done) { done = true; clearTimeout(timer); reject(e); } });
+    sock.on('close', () => { if (!done) { done = true; clearTimeout(timer); reject(new Error('closed')); } });
+  });
+}
+
+function findSocket(startDir) {
+  const path = require('path');
+  const fs   = require('fs');
+  let dir = startDir;
+  for (let i = 0; i < 10; i++) {
+    const candidate = path.join(dir, '.claws', 'claws.sock');
+    try { if (fs.existsSync(candidate)) return candidate; } catch {}
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+function sleep(ms) {
+  return new Promise(r => setTimeout(r, ms));
+}

package/scripts/hooks/pre-bash-no-verify-block.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+// PreToolUse hook: blocks `git commit --no-verify` (and similar bypass flags)
+// per advisory-mechanism-audit Finding F32.
+//
+// Workers/orchestrators that try to skip pre-commit hooks get a hard
+// rejection with a clear error message.
+//
+// Hook input: Claude Code passes JSON via stdin: { tool: 'Bash', args: { command: '...' } }
+// Hook output: exit 0 = allow; exit 1 with stderr message = block.
+
+'use strict';
+
+if (!process.env.CLAWS_DEBUG) {
+  process.on('uncaughtException', () => { try { process.exit(0); } catch {} });
+  process.on('unhandledRejection', () => { try { process.exit(0); } catch {} });
+}
+
+const fs = require('fs');
+const LOG = '/tmp/claws-hook-no-verify.log';
+
+function log(msg) {
+  try {
+    fs.appendFileSync(LOG, `${new Date().toISOString()} ${msg}\n`);
+  } catch (_) {}
+}
+
+// Self-kill safety — hook can never hang the parent process.
+setTimeout(() => { log('hook self-kill 5s'); process.exit(0); }, 5000).unref();
+
+let input = '';
+process.stdin.on('data', (chunk) => { input += chunk; });
+process.stdin.on('end', () => {
+  let parsed;
+  try {
+    parsed = JSON.parse(input || '{}');
+  } catch (e) {
+    log(`malformed input: ${e.message}`);
+    process.exit(0);
+  }
+
+  const cmd = (parsed.tool_input && parsed.tool_input.command) ||
+              (parsed.args && parsed.args.command) || '';
+  if (typeof cmd !== 'string') process.exit(0);
+
+  // Match git commit/rebase/push with bypass flags.
+  // The -n short form regex uses a negative lookahead to avoid matching -name, -no, etc.
+  const blockedPatterns = [
+    /\bgit\s+commit\b[^|;&\n]*--no-verify\b/,
+    /\bgit\s+commit\b[^|;&\n]*\s-n(?![a-zA-Z0-9_-])/,
+    /\bgit\s+commit\b[^|;&\n]*--no-gpg-sign\b/,
+    /\bgit\s+rebase\b[^|;&\n]*--no-verify\b/,
+    /\bgit\s+push\b[^|;&\n]*--no-verify\b/,
+    /\bcommit\.gpgsign=false\b/,
+  ];
+
+  for (const re of blockedPatterns) {
+    if (re.test(cmd)) {
+      const reason =
+        '[claws-hook] BLOCKED: bypass flag detected in git command. ' +
+        'Pre-commit hooks exist for a reason (tests, lint, type checks). ' +
+        'Fix the underlying issue instead of bypassing. ' +
+        'If you genuinely need to bypass, ask the human user explicitly. ' +
+        `Pattern matched: ${re.source}`;
+      log(`BLOCKED: ${cmd.slice(0, 200)}`);
+      process.stderr.write(reason + '\n');
+      process.exit(1);
+    }
+  }
+
+  log(`ALLOWED: ${cmd.slice(0, 100)}`);
+  process.exit(0);
+});