shield-harness 1.0.0

package/.claude/hooks/sh-output-control.js

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+// sh-output-control.js — Output truncation + token budget tracking
+// Spec: DETAILED_DESIGN.md §4.2
+// Hook event: PostToolUse
+// Matcher: "" (all tools)
+// Target response time: < 20ms
+"use strict";
+
+const {
+  readHookInput,
+  allow,
+  allowWithResult,
+  readSession,
+  writeSession,
+} = require("./lib/sh-utils");
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const HOOK_NAME = "sh-output-control";
+
+// Truncation limits per tool (bytes)
+const TRUNCATION_LIMITS = {
+  Bash: { max: 20 * 1024, head: 10 * 1024, tail: 5 * 1024 },
+  Task: { max: 6 * 1024, head: 3 * 1024, tail: 2 * 1024 },
+  _default: { max: 50 * 1024, head: 25 * 1024, tail: 10 * 1024 },
+};
+
+// Token budget thresholds
+const BUDGET_WARNING_RATIO = 0.8;
+const BUDGET_LIMIT_RATIO = 1.0;
+
+// Rough token estimation: ~4 chars per token
+const CHARS_PER_TOKEN = 4;
+
+// ---------------------------------------------------------------------------
+// Helper Functions
+// ---------------------------------------------------------------------------
+
+/**
+ * Get truncation limits for a given tool.
+ * @param {string} toolName
+ * @returns {{ max: number, head: number, tail: number }}
+ */
+function getLimits(toolName) {
+  return TRUNCATION_LIMITS[toolName] || TRUNCATION_LIMITS._default;
+}
+
+/**
+ * Truncate output if it exceeds the limit.
+ * @param {string} output
+ * @param {string} toolName
+ * @returns {{ text: string, truncated: boolean }}
+ */
+function truncateOutput(output, toolName) {
+  if (!output) return { text: output, truncated: false };
+
+  const limits = getLimits(toolName);
+  if (output.length <= limits.max) {
+    return { text: output, truncated: false };
+  }
+
+  const head = output.slice(0, limits.head);
+  const tail = output.slice(-limits.tail);
+  const omitted = output.length - limits.head - limits.tail;
+  const notice = `\n\n--- [sh-output-control] ${omitted} bytes omitted (${output.length} total → ${limits.head + limits.tail} retained) ---\n\n`;
+
+  return {
+    text: head + notice + tail,
+    truncated: true,
+  };
+}
+
+/**
+ * Estimate token count from character length.
+ * @param {number} charCount
+ * @returns {number}
+ */
+function estimateTokens(charCount) {
+  return Math.ceil(charCount / CHARS_PER_TOKEN);
+}
+
+/**
+ * Track token budget and return warning context if thresholds are crossed.
+ * @param {number} outputSize - Size of tool output in characters
+ * @returns {string|null} Warning context or null
+ */
+function trackTokenBudget(outputSize) {
+  try {
+    const session = readSession();
+    const tokenBudget = session.token_budget;
+    if (!tokenBudget || !tokenBudget.session_limit) return null; // No budget configured
+
+    const budgetLimit = tokenBudget.session_limit;
+    const currentUsage = tokenBudget.used || 0;
+    const newTokens = estimateTokens(outputSize);
+    const updatedUsage = currentUsage + newTokens;
+
+    // Update session — write to token_budget.used (single source of truth)
+    writeSession({
+      ...session,
+      token_budget: {
+        ...tokenBudget,
+        used: updatedUsage,
+      },
+    });
+
+    const ratio = updatedUsage / budgetLimit;
+
+    if (ratio >= BUDGET_LIMIT_RATIO) {
+      return `[${HOOK_NAME}] トークン予算を超過しました（${updatedUsage}/${budgetLimit} tokens）。ユーザー確認が必要です。`;
+    }
+    if (ratio >= BUDGET_WARNING_RATIO) {
+      return `[${HOOK_NAME}] トークン予算の 80% に到達しました（${updatedUsage}/${budgetLimit} tokens）。`;
+    }
+
+    return null;
+  } catch {
+    // Budget tracking failure is non-blocking
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+try {
+  const input = readHookInput();
+  const { toolName, toolResult } = input;
+
+  const resultStr =
+    typeof toolResult === "string" ? toolResult : JSON.stringify(toolResult);
+
+  // Truncate if necessary
+  const { text, truncated } = truncateOutput(resultStr, toolName);
+
+  // Track token budget
+  const budgetWarning = trackTokenBudget(resultStr ? resultStr.length : 0);
+
+  // Build context messages
+  const context = [];
+  if (truncated) {
+    context.push(
+      `[${HOOK_NAME}] ${toolName} の出力を切り詰めました（制限超過）。`,
+    );
+  }
+  if (budgetWarning) {
+    context.push(budgetWarning);
+  }
+
+  // Output result
+  if (truncated) {
+    // Must use allowWithResult to replace the tool output
+    if (context.length > 0) {
+      // allowWithResult doesn't support additionalContext, so prepend warnings to the result
+      const contextHeader = context.join("\n") + "\n\n";
+      allowWithResult(contextHeader + text);
+    } else {
+      allowWithResult(text);
+    }
+  } else if (context.length > 0) {
+    allow(context.join("\n"));
+  } else {
+    allow();
+  }
+} catch (_err) {
+  // Operational hook — on error, pass through the original output.
+  allow();
+}
+
+// ---------------------------------------------------------------------------
+// Exports (for testing)
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  TRUNCATION_LIMITS,
+  truncateOutput,
+  estimateTokens,
+  getLimits,
+  trackTokenBudget,
+};

package/.claude/hooks/sh-permission-learn.js

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+// sh-permission-learn.js — Permission learning guard
+// Spec: DETAILED_DESIGN.md §5.7
+// Event: PermissionRequest
+// Target response time: < 20ms
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const {
+  readHookInput,
+  allow,
+  deny,
+  appendEvidence,
+} = require("./lib/sh-utils");
+
+const HOOK_NAME = "sh-permission-learn";
+const SETTINGS_FILE = path.join(".claude", "settings.json");
+const SETTINGS_LOCAL_FILE = path.join(".claude", "settings.local.json");
+const MAX_LEARNED_RULES = 100;
+
+// Overly broad patterns that should never be learned
+const LEARNING_BLACKLIST = [
+  /^Bash\(\*\)$/, // Too broad — allows all Bash commands
+  /^Edit\(\*\)$/, // Too broad — allows editing any file
+  /^Write\(\*\)$/, // Too broad — allows writing any file
+  /^Bash\(curl\s/, // Network access
+  /^Bash\(wget\s/, // Network access
+  /^Edit\(\.claude\//, // Self-modification
+  /^Write\(\.claude\//, // Self-modification
+];
+
+// ---------------------------------------------------------------------------
+// Checks
+// ---------------------------------------------------------------------------
+
+/**
+ * Load deny rules from settings.json.
+ * @returns {string[]}
+ */
+function loadDenyRules() {
+  try {
+    if (!fs.existsSync(SETTINGS_FILE)) return [];
+    const settings = JSON.parse(fs.readFileSync(SETTINGS_FILE, "utf8"));
+    return (settings.permissions && settings.permissions.deny) || [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Load current learned allow rules count from settings.local.json.
+ * @returns {number}
+ */
+function getLearnedRuleCount() {
+  try {
+    if (!fs.existsSync(SETTINGS_LOCAL_FILE)) return 0;
+    const local = JSON.parse(fs.readFileSync(SETTINGS_LOCAL_FILE, "utf8"));
+    return ((local.permissions && local.permissions.allow) || []).length;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Check if a permission pattern conflicts with any deny rule.
+ * A conflict exists when the requested permission would match something denied.
+ * @param {string} permissionPattern - e.g., "Bash(rm -rf *)"
+ * @param {string[]} denyRules
+ * @returns {string|null} - Conflicting deny rule, or null
+ */
+function checkDenyConflict(permissionPattern, denyRules) {
+  // Simple substring/overlap check
+  // Extract tool name from pattern
+  const toolMatch = permissionPattern.match(/^(\w+)\((.+)\)$/);
+  if (!toolMatch) return null;
+
+  const [, tool, pattern] = toolMatch;
+
+  for (const denyRule of denyRules) {
+    const denyMatch = denyRule.match(/^(\w+)\((.+)\)$/);
+    if (!denyMatch) continue;
+
+    const [, denyTool, denyPattern] = denyMatch;
+
+    // Same tool type
+    if (tool !== denyTool) continue;
+
+    // Check if the requested pattern would overlap with deny
+    // If the requested pattern contains the denied path/command, it conflicts
+    if (
+      pattern.includes(denyPattern.replace(/\*/g, "")) ||
+      denyPattern.includes(pattern.replace(/\*/g, ""))
+    ) {
+      return denyRule;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Check if a permission pattern is in the blacklist.
+ * @param {string} permissionPattern
+ * @returns {boolean}
+ */
+function isBlacklisted(permissionPattern) {
+  return LEARNING_BLACKLIST.some((re) => re.test(permissionPattern));
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+try {
+  const input = readHookInput();
+  // Permission pattern from the request
+  const permissionPattern =
+    input.toolInput.permission || input.toolInput.tool_pattern || "";
+
+  if (!permissionPattern) {
+    allow();
+  }
+
+  // Check 1: deny rule conflict
+  const denyRules = loadDenyRules();
+  const conflict = checkDenyConflict(permissionPattern, denyRules);
+  if (conflict) {
+    try {
+      appendEvidence({
+        hook: HOOK_NAME,
+        event: "PermissionRequest",
+        decision: "deny",
+        reason: "deny_rule_conflict",
+        pattern: permissionPattern,
+        conflicting_rule: conflict,
+        session_id: input.sessionId,
+      });
+    } catch {
+      // Non-blocking
+    }
+
+    deny(
+      `[${HOOK_NAME}] deny ルールは学習で上書きできません。衝突ルール: ${conflict}`,
+    );
+  }
+
+  // Check 2: blacklist
+  if (isBlacklisted(permissionPattern)) {
+    try {
+      appendEvidence({
+        hook: HOOK_NAME,
+        event: "PermissionRequest",
+        decision: "deny",
+        reason: "blacklisted_pattern",
+        pattern: permissionPattern,
+        session_id: input.sessionId,
+      });
+    } catch {
+      // Non-blocking
+    }
+
+    deny(`[${HOOK_NAME}] パターンが広すぎます: ${permissionPattern}`);
+  }
+
+  // Check 3: learning limit
+  const currentCount = getLearnedRuleCount();
+  if (currentCount >= MAX_LEARNED_RULES) {
+    try {
+      appendEvidence({
+        hook: HOOK_NAME,
+        event: "PermissionRequest",
+        decision: "deny",
+        reason: "learning_limit_exceeded",
+        pattern: permissionPattern,
+        current_count: currentCount,
+        session_id: input.sessionId,
+      });
+    } catch {
+      // Non-blocking
+    }
+
+    deny(
+      `[${HOOK_NAME}] 学習上限に到達しました (${currentCount}/${MAX_LEARNED_RULES})`,
+    );
+  }
+
+  // All checks passed — allow
+  try {
+    appendEvidence({
+      hook: HOOK_NAME,
+      event: "PermissionRequest",
+      decision: "allow",
+      pattern: permissionPattern,
+      session_id: input.sessionId,
+    });
+  } catch {
+    // Non-blocking
+  }
+
+  allow();
+} catch (err) {
+  // SECURITY hook — fail-close
+  process.stdout.write(
+    JSON.stringify({
+      reason: `[${HOOK_NAME}] Hook error (fail-close): ${err.message}`,
+    }),
+  );
+  process.exit(2);
+}
+
+// ---------------------------------------------------------------------------
+// Exports (for testing)
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  LEARNING_BLACKLIST,
+  MAX_LEARNED_RULES,
+  loadDenyRules,
+  getLearnedRuleCount,
+  checkDenyConflict,
+  isBlacklisted,
+};

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

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+// sh-permission.js — 4-category tool governance (Tier 2)
+// Spec: DETAILED_DESIGN.md §3.1
+// Hook event: PreToolUse
+// Matcher: Bash|Edit|Write|Read|WebFetch|MCP
+// Target response time: < 50ms
+"use strict";
+
+const { readHookInput, allow, deny } = require("./lib/sh-utils");
+
+// ---------------------------------------------------------------------------
+// Category Constants
+// ---------------------------------------------------------------------------
+
+const CATEGORY = {
+  READONLY: 1,
+  AGENT_SPAWN: 2,
+  EXECUTION: 3,
+  WRITE: 4,
+};
+
+// ---------------------------------------------------------------------------
+// READONLY_PATTERNS (Category 1 — auto-approve for Bash commands)
+// Spec: §3.1 READONLY_PATTERNS
+// ---------------------------------------------------------------------------
+
+const READONLY_PATTERNS = [
+  /^git\s+(status|diff|log|branch|show|blame|stash\s+list)\b/,
+  /^(ls|dir|pwd|whoami|date|uname|cat|head|tail|wc|find|which|type|file)\b/,
+  /^npm\s+(test|run|list|outdated|audit)\b/,
+  /^(node|bun|python|python3)\s+--version\b/,
+  /^(grep|rg|ag|awk)\s/,
+  /^sed\s+[^-]/, // sed without flags (read-only pipe usage only)
+];
+
+// ---------------------------------------------------------------------------
+// WRITE_PATTERNS (Category 4 — write operation detection for Bash commands)
+// Spec: §3.1 WRITE_PATTERNS
+// ---------------------------------------------------------------------------
+
+const WRITE_PATTERNS = [
+  /^(rm|del|rmdir|mkdir|mv|cp|chmod|chown)\b/,
+  /^git\s+(push|commit|merge|rebase|reset|checkout|clean)\b/,
+  /^npm\s+(install|publish|uninstall|update|link)\b/,
+  /^pip3?\s+install\b/,
+];
+
+// ---------------------------------------------------------------------------
+// Classification Logic
+// ---------------------------------------------------------------------------
+
+/**
+ * Classify a tool invocation into one of 4 categories.
+ *
+ * @param {string} toolName - Claude Code tool name
+ * @param {Object} toolInput - Tool input parameters
+ * @returns {{ category: number, label: string }}
+ */
+function classify(toolName, toolInput) {
+  // --- Category 1: Read-only tools (always auto-approve) ---
+  if (
+    toolName === "Read" ||
+    toolName === "Grep" ||
+    toolName === "Glob" ||
+    toolName === "WebSearch"
+  ) {
+    return { category: CATEGORY.READONLY, label: "read-only tool" };
+  }
+
+  // --- Category 2: Agent spawn (delegate to SubagentStart hook) ---
+  if (toolName === "Task" || toolName === "Agent") {
+    return { category: CATEGORY.AGENT_SPAWN, label: "agent spawn" };
+  }
+
+  // --- Bash command classification (Categories 1, 3, or 4) ---
+  if (toolName === "Bash") {
+    const command = (toolInput.command || "").trim();
+
+    // Check read-only patterns first (Category 1)
+    for (const pattern of READONLY_PATTERNS) {
+      if (pattern.test(command)) {
+        return { category: CATEGORY.READONLY, label: "read-only command" };
+      }
+    }
+
+    // Check write patterns (Category 4)
+    for (const pattern of WRITE_PATTERNS) {
+      if (pattern.test(command)) {
+        return { category: CATEGORY.WRITE, label: "write command" };
+      }
+    }
+
+    // Neither read-only nor write: Execution (Category 3)
+    return { category: CATEGORY.EXECUTION, label: "execution command" };
+  }
+
+  // --- Category 4: Write tools ---
+  if (toolName === "Edit" || toolName === "Write") {
+    return { category: CATEGORY.WRITE, label: "file write" };
+  }
+
+  // --- Category 3: WebFetch ---
+  if (toolName === "WebFetch") {
+    return { category: CATEGORY.EXECUTION, label: "web fetch" };
+  }
+
+  // --- Category 3: MCP tools ---
+  // Any tool not matched above is treated as MCP / unknown execution
+  return { category: CATEGORY.EXECUTION, label: "MCP tool" };
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+try {
+  const input = readHookInput();
+  const toolName = input.toolName;
+  const toolInput = input.toolInput;
+
+  const { category, label } = classify(toolName, toolInput);
+
+  switch (category) {
+    case CATEGORY.READONLY:
+      // Category 1: auto-approve, no context needed
+      allow();
+      break;
+
+    case CATEGORY.AGENT_SPAWN:
+      // Category 2: allow here, SubagentStart hook handles governance
+      allow();
+      break;
+
+    case CATEGORY.EXECUTION:
+      // Category 3: allow with context for awareness
+      allow(`[sh-permission] Category 3 (execution): ${label}`);
+      break;
+
+    case CATEGORY.WRITE:
+      // Category 4: allow (protected path checks are gate.sh's responsibility)
+      allow();
+      break;
+
+    default:
+      // Unknown category — fail-close
+      deny("Unknown category in sh-permission");
+      break;
+  }
+} catch (err) {
+  // fail-close: any uncaught error = deny
+  process.stdout.write(
+    JSON.stringify({
+      reason: `Hook error (sh-permission): ${err.message}`,
+    }),
+  );
+  process.exit(2);
+}