shield-harness 1.0.0

package/.claude/hooks/sh-postcompact.js

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+// sh-postcompact.js — Post-compaction state restoration & verification
+// Spec: DETAILED_DESIGN.md §5.8
+// Event: PostCompact
+// Matcher: auto
+// Target response time: < 200ms
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const {
+  readHookInput,
+  allow,
+  sha256,
+  readSession,
+  writeSession,
+  appendEvidence,
+  SH_DIR,
+} = require("./lib/sh-utils");
+
+const HOOK_NAME = "sh-postcompact";
+const BACKUP_DIR = path.join(SH_DIR, "compact-backup");
+const CLAUDE_MD = "CLAUDE.md";
+
+// ---------------------------------------------------------------------------
+// Restore Logic
+// ---------------------------------------------------------------------------
+
+/**
+ * Restore session state from compact-backup.
+ * Merges backup into current session (backup values take precedence for key fields).
+ * @returns {Object} restored session
+ */
+function restoreSessionState() {
+  const backupFile = path.join(BACKUP_DIR, "session.json");
+  const currentSession = readSession();
+
+  if (!fs.existsSync(backupFile)) {
+    return currentSession;
+  }
+
+  try {
+    const backup = JSON.parse(fs.readFileSync(backupFile, "utf8"));
+    // Merge: preserve backup's critical fields
+    return {
+      ...currentSession,
+      ...backup,
+      // Always update these from current state
+      last_compact: new Date().toISOString(),
+    };
+  } catch {
+    return currentSession;
+  }
+}
+
+/**
+ * Verify CLAUDE.md integrity after compaction.
+ * @param {Object} session - Session with baseline hash
+ * @returns {{ valid: boolean, message: string }}
+ */
+function verifyCLAUDEMD(session) {
+  if (!fs.existsSync(CLAUDE_MD)) {
+    return { valid: false, message: "CLAUDE.md not found" };
+  }
+
+  const currentHash = sha256(fs.readFileSync(CLAUDE_MD, "utf8"));
+
+  // If we don't have a baseline, just record it
+  if (!session.claude_md_hash) {
+    return {
+      valid: true,
+      message: `CLAUDE.md hash recorded: ${currentHash.slice(0, 12)}...`,
+    };
+  }
+
+  if (currentHash !== session.claude_md_hash) {
+    return {
+      valid: false,
+      message: `WARNING: CLAUDE.md has been modified since session start! Expected: ${session.claude_md_hash.slice(0, 12)}..., Got: ${currentHash.slice(0, 12)}...`,
+    };
+  }
+
+  return { valid: true, message: "CLAUDE.md integrity verified" };
+}
+
+/**
+ * Build restoration context for systemMessage injection.
+ * @param {Object} session
+ * @param {{ valid: boolean, message: string }} integrityCheck
+ * @returns {string}
+ */
+function buildRestorationContext(session, integrityCheck) {
+  const parts = [];
+
+  parts.push("=== Shield Harness Post-Compaction Restore ===");
+
+  // Integrity check result
+  if (!integrityCheck.valid) {
+    parts.push(`⚠ ${integrityCheck.message}`);
+  } else {
+    parts.push(`✓ ${integrityCheck.message}`);
+  }
+
+  // Session state
+  if (session.session_start) {
+    parts.push(`Session started: ${session.session_start}`);
+  }
+  if (session.token_budget) {
+    parts.push(
+      `Token budget: ${session.token_budget.used || 0}/${session.token_budget.session_limit || "?"}`,
+    );
+  }
+
+  // Key reminders
+  parts.push("");
+  parts.push("Key files to re-read if needed:");
+  parts.push("  - CLAUDE.md (project instructions)");
+  parts.push("  - .claude/rules/ (security & coding rules)");
+  parts.push("  - tasks/backlog.yaml (task SoT)");
+  parts.push("  - docs/DETAILED_DESIGN.md (hook specifications)");
+  parts.push("==========================================");
+
+  return parts.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+try {
+  const input = readHookInput();
+
+  // Restore session state from backup
+  const session = restoreSessionState();
+
+  // Verify CLAUDE.md integrity
+  const integrityCheck = verifyCLAUDEMD(session);
+
+  // Update and save session
+  writeSession(session);
+
+  // Record evidence
+  try {
+    appendEvidence({
+      hook: HOOK_NAME,
+      event: "PostCompact",
+      decision: "allow",
+      integrity_valid: integrityCheck.valid,
+      integrity_message: integrityCheck.message,
+      session_id: input.sessionId,
+    });
+  } catch {
+    // Evidence failure is non-blocking
+  }
+
+  // Inject restoration context
+  const context = buildRestorationContext(session, integrityCheck);
+  allow(context);
+} catch (_err) {
+  // Operational hook — fail-open
+  allow();
+}
+
+// ---------------------------------------------------------------------------
+// Exports (for testing)
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  restoreSessionState,
+  verifyCLAUDEMD,
+  buildRestorationContext,
+  BACKUP_DIR,
+};

package/.claude/hooks/sh-precompact.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+// sh-precompact.js — Pre-compaction state backup & context injection
+// Spec: DETAILED_DESIGN.md §5.8
+// Event: PreCompact
+// Matcher: auto
+// Target response time: < 200ms
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const {
+  readHookInput,
+  allow,
+  readSession,
+  appendEvidence,
+  SESSION_FILE,
+  SH_DIR,
+} = require("./lib/sh-utils");
+
+const HOOK_NAME = "sh-precompact";
+const BACKUP_DIR = path.join(SH_DIR, "compact-backup");
+
+// ---------------------------------------------------------------------------
+// Backup Logic
+// ---------------------------------------------------------------------------
+
+/**
+ * Copy session.json to compact-backup directory.
+ */
+function backupSessionState() {
+  if (!fs.existsSync(BACKUP_DIR)) {
+    fs.mkdirSync(BACKUP_DIR, { recursive: true });
+  }
+
+  // Backup session.json
+  if (fs.existsSync(SESSION_FILE)) {
+    fs.copyFileSync(SESSION_FILE, path.join(BACKUP_DIR, "session.json"));
+  }
+}
+
+/**
+ * Build context output for injection into compacted conversation.
+ * @param {Object} session - Current session state
+ * @returns {string}
+ */
+function buildContextOutput(session) {
+  const parts = [];
+
+  parts.push("=== Shield Harness Pre-Compaction Snapshot ===");
+
+  // Session state
+  if (session.session_start) {
+    parts.push(`Session started: ${session.session_start}`);
+  }
+  if (session.token_budget) {
+    parts.push(
+      `Token budget used: ${session.token_budget.used || 0}/${session.token_budget.session_limit || "?"}`,
+    );
+  }
+
+  // Key project files reminder
+  parts.push("");
+  parts.push("Key files:");
+  parts.push("  - CLAUDE.md (project instructions)");
+  parts.push("  - .claude/rules/ (security & coding rules)");
+  parts.push("  - tasks/backlog.yaml (task SoT — read-only)");
+  parts.push("  - docs/DETAILED_DESIGN.md (hook specifications)");
+
+  parts.push("=========================================");
+
+  return parts.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+try {
+  const input = readHookInput();
+  const session = readSession();
+
+  // Backup state before compaction
+  backupSessionState();
+
+  // Record evidence
+  try {
+    appendEvidence({
+      hook: HOOK_NAME,
+      event: "PreCompact",
+      decision: "allow",
+      backup_created: true,
+      session_id: input.sessionId,
+    });
+  } catch {
+    // Evidence failure is non-blocking
+  }
+
+  // Inject context
+  const context = buildContextOutput(session);
+  allow(context);
+} catch (_err) {
+  // Operational hook — fail-open
+  allow();
+}
+
+// ---------------------------------------------------------------------------
+// Exports (for testing)
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  backupSessionState,
+  buildContextOutput,
+  BACKUP_DIR,
+};

package/.claude/hooks/sh-quiet-inject.js

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+// sh-quiet-inject.js — Auto-inject quiet flags to save tokens
+// Spec: DETAILED_DESIGN.md §3.5
+// Hook event: PreToolUse
+// Matcher: Bash
+// Target response time: < 10ms
+"use strict";
+
+const { readHookInput, allow, allowWithUpdate } = require("./lib/sh-utils");
+
+// ---------------------------------------------------------------------------
+// Quiet Injection Rules
+// ---------------------------------------------------------------------------
+
+/**
+ * Each rule: { pattern, flag, verboseCheck }
+ * - pattern: RegExp matching the command (e.g., /\bgit\s+clone\b/)
+ * - flag: The quiet flag to inject (e.g., "-q", "--silent")
+ * - verboseCheck: RegExp matching verbose flags that should prevent injection
+ */
+const QUIET_RULES = [
+  // Git commands: inject -q unless -v/--verbose present
+  {
+    pattern: /\bgit\s+clone\b/,
+    flag: "-q",
+    verboseCheck: /\s-v\b|\s--verbose\b/,
+  },
+  {
+    pattern: /\bgit\s+fetch\b/,
+    flag: "-q",
+    verboseCheck: /\s-v\b|\s--verbose\b/,
+  },
+  {
+    pattern: /\bgit\s+pull\b/,
+    flag: "-q",
+    verboseCheck: /\s-v\b|\s--verbose\b/,
+  },
+  {
+    pattern: /\bgit\s+push\b/,
+    flag: "-q",
+    verboseCheck: /\s-v\b|\s--verbose\b/,
+  },
+
+  // npm commands: inject --silent unless --verbose present
+  {
+    pattern: /\bnpm\s+install\b/,
+    flag: "--silent",
+    verboseCheck: /\s--verbose\b/,
+  },
+  {
+    pattern: /\bnpm\s+ci\b/,
+    flag: "--silent",
+    verboseCheck: /\s--verbose\b/,
+  },
+
+  // cargo build: inject -q unless --verbose/-v present
+  {
+    pattern: /\bcargo\s+build\b/,
+    flag: "-q",
+    verboseCheck: /\s--verbose\b|\s-v\b/,
+  },
+
+  // pip install: inject -q unless --verbose/-v present
+  {
+    pattern: /\bpip3?\s+install\b/,
+    flag: "-q",
+    verboseCheck: /\s--verbose\b|\s-v\b/,
+  },
+
+  // docker pull: inject -q unless --verbose/-v present
+  {
+    pattern: /\bdocker\s+pull\b/,
+    flag: "-q",
+    verboseCheck: /\s--verbose\b|\s-v\b/,
+  },
+];
+
+// ---------------------------------------------------------------------------
+// Injection Logic
+// ---------------------------------------------------------------------------
+
+/**
+ * Attempt to inject a quiet flag into a command string.
+ *
+ * Finds the matching subcommand (e.g., "git clone") and inserts the flag
+ * immediately after it.
+ *
+ * @param {string} command - The original command string.
+ * @returns {{ modified: boolean, command: string }}
+ */
+function injectQuietFlag(command) {
+  for (const rule of QUIET_RULES) {
+    const match = command.match(rule.pattern);
+    if (!match) continue;
+
+    // Skip if already has quiet flag injected
+    // Check for common quiet flags in the command
+    if (/\s-q\b|\s--quiet\b|\s--silent\b/.test(command)) continue;
+
+    // Skip if verbose flag is present
+    if (rule.verboseCheck.test(command)) continue;
+
+    // Insert flag right after the matched subcommand
+    const insertPos = match.index + match[0].length;
+    const modified =
+      command.slice(0, insertPos) + " " + rule.flag + command.slice(insertPos);
+
+    return { modified: true, command: modified };
+  }
+
+  return { modified: false, command };
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+try {
+  const input = readHookInput();
+  const command = (input.toolInput.command || "").trim();
+
+  // Empty command — nothing to inject
+  if (!command) {
+    allow();
+  }
+
+  const result = injectQuietFlag(command);
+
+  if (result.modified) {
+    allowWithUpdate({ command: result.command });
+  } else {
+    allow();
+  }
+} catch (_err) {
+  // Operational hook, not security — on error, just allow.
+  // Worst case: extra output tokens, not a security breach.
+  allow();
+}
+
+// ---------------------------------------------------------------------------
+// Exports (for testing)
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  QUIET_RULES,
+  injectQuietFlag,
+};

package/.claude/hooks/sh-session-end.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+// sh-session-end.js — Session cleanup & statistics
+// Spec: DETAILED_DESIGN.md §5.8
+// Event: SessionEnd
+// Target response time: < 200ms
+"use strict";
+
+const fs = require("fs");
+const {
+  readHookInput,
+  allow,
+  readSession,
+  writeSession,
+  appendEvidence,
+  EVIDENCE_FILE,
+} = require("./lib/sh-utils");
+
+const HOOK_NAME = "sh-session-end";
+
+// ---------------------------------------------------------------------------
+// Statistics computation
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute session statistics from evidence ledger.
+ * @param {string} sessionId
+ * @returns {{ toolCalls: number, denials: number, topTools: string[], duration: string }}
+ */
+function computeStats(sessionId) {
+  const stats = { toolCalls: 0, denials: 0, topTools: [], duration: "unknown" };
+
+  try {
+    if (!fs.existsSync(EVIDENCE_FILE)) return stats;
+
+    const lines = fs.readFileSync(EVIDENCE_FILE, "utf8").trim().split("\n");
+    const toolCounts = {};
+    let sessionStart = null;
+
+    for (const line of lines) {
+      if (!line) continue;
+      try {
+        const entry = JSON.parse(line);
+        // Only count entries from this session
+        if (entry.session_id && entry.session_id !== sessionId) continue;
+
+        if (entry.event === "SessionStart") {
+          sessionStart = entry.recorded_at;
+        }
+        if (entry.tool) {
+          stats.toolCalls++;
+          toolCounts[entry.tool] = (toolCounts[entry.tool] || 0) + 1;
+        }
+        if (entry.decision === "deny") {
+          stats.denials++;
+        }
+      } catch {
+        // Skip malformed lines
+      }
+    }
+
+    // Top 3 tools
+    stats.topTools = Object.entries(toolCounts)
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 3)
+      .map(([tool, count]) => `${tool}(${count})`);
+
+    // Duration
+    if (sessionStart) {
+      const startMs = new Date(sessionStart).getTime();
+      const endMs = Date.now();
+      const diffMin = Math.round((endMs - startMs) / 60000);
+      if (diffMin < 60) {
+        stats.duration = `${diffMin}m`;
+      } else {
+        const h = Math.floor(diffMin / 60);
+        const m = diffMin % 60;
+        stats.duration = `${h}h${m}m`;
+      }
+    }
+  } catch {
+    // Stats computation failure is non-critical
+  }
+
+  return stats;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+try {
+  const input = readHookInput();
+  const { sessionId } = input;
+
+  // Compute session stats
+  const stats = computeStats(sessionId);
+
+  // Record close marker in evidence ledger
+  try {
+    appendEvidence({
+      hook: HOOK_NAME,
+      event: "SessionEnd",
+      decision: "allow",
+      summary: {
+        tool_calls: stats.toolCalls,
+        denials: stats.denials,
+        top_tools: stats.topTools,
+        duration: stats.duration,
+      },
+      session_id: sessionId,
+    });
+  } catch {
+    // Evidence failure is non-blocking
+  }
+
+  // Reset session.json
+  const session = readSession();
+  session.retry_count = 0;
+  session.stop_hook_active = false;
+  session.session_end = new Date().toISOString();
+  writeSession(session);
+
+  // Output summary
+  const summary = [
+    `[${HOOK_NAME}] Session closed.`,
+    `  Tool calls: ${stats.toolCalls}, Denials: ${stats.denials}`,
+    `  Top tools: ${stats.topTools.join(", ") || "none"}`,
+    `  Duration: ${stats.duration}`,
+  ].join("\n");
+
+  allow(summary);
+} catch (_err) {
+  // Operational hook — fail-open
+  allow();
+}
+
+// ---------------------------------------------------------------------------
+// Exports (for testing)
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  computeStats,
+};