@hasna/hooks 0.5.0 → 0.6.1

package/hooks/hook-scanoutput/src/hook.ts

@@ -0,0 +1,319 @@
+#!/usr/bin/env bun
+
+/**
+ * Claude Code Hook: scanoutput
+ *
+ * PostToolUse hook that scans tool output for credential shapes and WARNS.
+ *
+ * THIS IS DETECTION, NOT PREVENTION, AND THE DISTINCTION IS THE WHOLE DESIGN.
+ *
+ * PostToolUse fires after the tool has run and after its result exists. Measured
+ * across the 48-hook catalog at @hasna/hooks 0.5.0: no output-rewriting field
+ * exists on any event — `continue`, `decision`, `hookSpecificOutput`,
+ * `additionalContext`, `suppressOutput` and `permissionDecision` are the whole
+ * surface, and `suppressOutput` hides THE HOOK'S OWN stdout rather than the
+ * tool's. So by the time this hook can see a credential, that credential is
+ * already in the transcript. This hook cannot and does not stop that.
+ *
+ * It is worth running anyway because today nothing notices at all: a credential
+ * emitted by a third-party tool into ordinary output is indistinguishable from
+ * ordinary output until a human happens to look. This converts a silent
+ * exposure into a recorded one with a named blast radius, which is what the
+ * incident duty needs and currently cannot get.
+ *
+ * Do not describe it as prevention anywhere — in docs, help text, commit
+ * messages or channel posts. A guard advertised as preventing a leak it only
+ * reports afterwards retires the worry without retiring the exposure, and that
+ * is worse than no guard.
+ *
+ * It never blocks. Every path answers `{ continue: true }`, including its own
+ * failures, following the fail-open idiom the catalog already uses.
+ */
+
+import { readFileSync } from "fs";
+
+/** The scanner surface this hook uses: `scanInputExposures` from @hasna/secrets. */
+export type ScanFn = (options: { text?: string; maxBytes?: number; timeoutMs?: number }) => {
+  schema: string;
+  version: number;
+  source: string;
+  root: string;
+  redacted: true;
+  limits: { findings: number; maxFileBytes?: number; timeoutMs?: number };
+  stats: {
+    filesScanned: number;
+    filesSkipped: number;
+    bytesScanned: number;
+    errors: string[];
+    skipped?: { path: string; reason: string; bytes?: number }[];
+  };
+  truncated: boolean;
+  truncatedReason?: string;
+  findings: {
+    id: string;
+    detector: string;
+    severity: string;
+    path: string;
+    line: number;
+    column: number;
+    /** Already redacted by the scanner — the value never appears here. */
+    preview: string;
+    evidencePath: string;
+  }[];
+};
+
+export interface HookInput {
+  session_id?: string;
+  cwd?: string;
+  hook_event_name?: string;
+  tool_name?: string;
+  tool_input?: Record<string, unknown>;
+  /**
+   * THE FIELD CLAUDE CODE ACTUALLY SENDS. Verified against the Claude Code
+   * 2.1.226 binary on 2026-08-10, in both its embedded documentation and its
+   * implementation:
+   *
+   *   "tool_input": { ... },
+   *   "tool_response": { "success": true }  // PostToolUse only
+   *
+   *   hook_event_name:"PostToolUse", tool_name:e, tool_input:r,
+   *   tool_response:n, tool_use_id:t, duration_ms:l
+   *
+   * Counted in the same binary: `tool_response` 21 occurrences,
+   * `tool_output` 2 — and both of those are the telemetry event name
+   * `tengu_dead_probe_hook_updated_mcp_tool_output`, neither adjacent to
+   * `PostToolUse`. Control: a deliberately absent string returns 0.
+   *
+   * Read this before "simplifying" the two fields below into one. Every other
+   * hook in this catalog reads `tool_output` only, so on Claude Code they
+   * receive `undefined` and silently observe nothing — which for a scanner
+   * means a clean verdict over an empty string. That is the vacuous-gate
+   * defect this hook exists to notice, and it nearly shipped inside it.
+   */
+  tool_response?: Record<string, unknown> | string;
+  /** Compatibility only: the pre-existing catalog convention, and some runtimes may use it. */
+  tool_output?: Record<string, unknown> | string;
+}
+
+export interface HookOutput {
+  continue: true;
+}
+
+export interface ScanOutcome {
+  /**
+   * `unscanned` exists so that "I looked at all of it and it was clean" and "I
+   * could not look" do not share an answer. A guard that reports those
+   * identically is the defect this hook was built to notice, committed inside
+   * the hook itself.
+   */
+  status: "clean" | "found" | "unscanned" | "empty" | "error";
+  findingCount: number;
+  detectors: string[];
+  previews: string[];
+  bytesScanned?: number;
+  reason?: string;
+  error?: string;
+}
+
+/** Ceiling on what we hand the scanner. Above it the outcome is `unscanned`, never `clean`. */
+export const MAX_SCAN_BYTES = 4_000_000;
+
+/**
+ * Wall-clock bound on the scan, well under the scanner's own 10s default.
+ *
+ * This sits on a tool call's critical path, and the Claude installer target
+ * writes no `timeout` into settings.json (only the Codewith target does), so
+ * the wiring supplies no outer bound. Measured cost is 1.4-7.3ms for 11 KB and
+ * 64-90ms for 2.2 MB, so 2s is generous by more than an order of magnitude and
+ * still bounds a pathological input. Exceeding it marks the scan truncated,
+ * which this hook reports as `unscanned` rather than clean.
+ */
+export const SCAN_TIMEOUT_MS = 2_000;
+
+const OUTPUT_FIELDS = ["stdout", "stderr", "output", "content", "text", "error", "result"] as const;
+
+/**
+ * Pull the text out of a tool result, whether it arrived as a string or a record.
+ *
+ * `tool_response` is what Claude Code sends (see HookInput above); `tool_output`
+ * is accepted as a fallback so this also works on any runtime using the older
+ * catalog convention. Reading only one of them is how a scanner ends up
+ * reporting a confident clean over an empty string.
+ */
+export function extractToolOutputText(input: HookInput): string {
+  const output = input.tool_response ?? input.tool_output;
+  if (output === undefined || output === null) return "";
+  if (typeof output === "string") return output;
+  if (typeof output !== "object") return String(output);
+
+  const parts: string[] = [];
+  for (const field of OUTPUT_FIELDS) {
+    const value = (output as Record<string, unknown>)[field];
+    if (typeof value === "string" && value.length > 0) parts.push(value);
+  }
+  // Nothing recognised but the record is non-empty: scan its serialised form rather
+  // than silently skipping an output shape this list does not know about.
+  if (parts.length === 0) {
+    try {
+      const serialised = JSON.stringify(output);
+      if (serialised && serialised !== "{}") return serialised;
+    } catch {
+      return "";
+    }
+    return "";
+  }
+  return parts.join("\n");
+}
+
+/**
+ * Scan the text and classify the result.
+ *
+ * `scan` is injected so the hook's own behaviour is testable without the
+ * scanner, and so a missing or broken @hasna/secrets degrades to `error` and a
+ * warning rather than taking the session down with it.
+ */
+export function analyzeToolOutput(text: string, scan: ScanFn): ScanOutcome {
+  if (!text || text.length === 0) {
+    return { status: "empty", findingCount: 0, detectors: [], previews: [] };
+  }
+
+  let result: ReturnType<ScanFn>;
+  try {
+    result = scan({ text, maxBytes: MAX_SCAN_BYTES, timeoutMs: SCAN_TIMEOUT_MS });
+  } catch (err) {
+    return {
+      status: "error",
+      findingCount: 0,
+      detectors: [],
+      previews: [],
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+
+  const findings = result?.findings ?? [];
+  if (findings.length > 0) {
+    return {
+      status: "found",
+      findingCount: findings.length,
+      detectors: [...new Set(findings.map((f) => f.detector))],
+      previews: findings.slice(0, 5).map((f) => `${f.evidencePath} ${f.detector}/${f.severity} ${f.preview}`),
+      bytesScanned: result.stats?.bytesScanned,
+    };
+  }
+
+  // No findings is only good news if the whole input was actually read.
+  const stats = result?.stats;
+  const skipped = stats?.skipped?.length ?? 0;
+  const errors = stats?.errors?.length ?? 0;
+  const bytes = stats?.bytesScanned ?? 0;
+  if (result?.truncated || skipped > 0 || errors > 0 || bytes <= 0) {
+    const reason =
+      result?.truncatedReason ??
+      stats?.skipped?.[0]?.reason ??
+      stats?.errors?.[0] ??
+      (bytes <= 0 ? "zero bytes scanned" : "incomplete scan");
+    return { status: "unscanned", findingCount: 0, detectors: [], previews: [], bytesScanned: bytes, reason };
+  }
+
+  return { status: "clean", findingCount: 0, detectors: [], previews: [], bytesScanned: bytes };
+}
+
+/** The stderr line(s) a human or agent actually reads. Empty string means stay silent. */
+export function formatWarning(outcome: ScanOutcome): string {
+  if (outcome.status === "clean" || outcome.status === "empty") return "";
+
+  if (outcome.status === "error") {
+    return `[scanoutput] could not scan this tool output: ${outcome.error ?? "unknown error"} — treat it as UNSCANNED, not clean.`;
+  }
+
+  if (outcome.status === "unscanned") {
+    return `[scanoutput] UNSCANNED tool output (${outcome.reason ?? "incomplete"}) — no finding here is not evidence of no credential.`;
+  }
+
+  const lines = [
+    `[scanoutput] ${outcome.findingCount} credential shape(s) in tool output ` +
+      `[${outcome.detectors.join(", ")}] — this output is ALREADY in the transcript; ` +
+      `this hook reports it and cannot remove it.`,
+    ...outcome.previews.map((p) => `  ${p}`),
+    `  Record it to the incidents channel by NAME and SCOPE only, never the value, then continue.`,
+  ];
+  return lines.join("\n");
+}
+
+export function buildHookOutput(_outcome: ScanOutcome): HookOutput {
+  // Unconditional. A guard that fails closed on its own bug gets uninstalled.
+  return { continue: true };
+}
+
+function readStdinJson(): HookInput | null {
+  try {
+    const raw = readFileSync(0, "utf-8").trim();
+    if (!raw) return null;
+    return JSON.parse(raw) as HookInput;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the real scanner. Imported lazily and in-process: a CLI spawn costs a
+ * fixed ~1.3-1.8s on this fleet regardless of payload, while the in-process call
+ * is ~25ms of import plus ~2ms for 11 KB and ~80ms for 2.2 MB (measured
+ * 2026-08-10, station01). The spawn is the dominant term and is avoidable.
+ */
+async function loadScanner(): Promise<ScanFn> {
+  const mod = (await import("@hasna/secrets/scanner")) as unknown as { scanInputExposures: ScanFn };
+  if (typeof mod?.scanInputExposures !== "function") {
+    throw new Error("@hasna/secrets/scanner does not export scanInputExposures");
+  }
+  return mod.scanInputExposures;
+}
+
+function respond(output: HookOutput): void {
+  console.log(JSON.stringify(output));
+}
+
+function warn(message: string): void {
+  if (message) console.error(message);
+}
+
+export async function run(): Promise<void> {
+  try {
+    const input = readStdinJson();
+    if (!input) {
+      respond({ continue: true });
+      return;
+    }
+
+    const text = extractToolOutputText(input);
+    if (!text) {
+      respond({ continue: true });
+      return;
+    }
+
+    let scan: ScanFn;
+    try {
+      scan = await loadScanner();
+    } catch (err) {
+      warn(
+        `[scanoutput] could not scan this tool output: ${
+          err instanceof Error ? err.message : String(err)
+        } — treat it as UNSCANNED, not clean.`,
+      );
+      respond({ continue: true });
+      return;
+    }
+
+    const outcome = analyzeToolOutput(text, scan);
+    warn(formatWarning(outcome));
+    respond(buildHookOutput(outcome));
+  } catch (err) {
+    // Nothing this hook does may end a session.
+    warn(`[scanoutput] hook failed: ${err instanceof Error ? err.message : String(err)}`);
+    respond({ continue: true });
+  }
+}
+
+if (import.meta.main) {
+  void run();
+}

package/hooks/hook-workspace-repos-guard/README.md

@@ -0,0 +1,63 @@
+# workspace-repos-guard
+
+Codewith-native hook installed as `hooks run workspace-repos-guard`.
+
+PreToolUse guard for the canonical workspace structure (knowledge
+`k_mssu9jdq_dgnnu2`): `$HOME/workspace` contains ONLY `repos/` + `scratch/` +
+`AGENTS.md`, and `repos/` contains ONLY GitHub-org folders. Checkouts at
+`$HOME/workspace/repos/<org>/<repo>/` are read/context only.
+
+## What it blocks
+
+- Any write to `$HOME/workspace/repos` itself (file tools and Bash).
+- Any write that would create a top-level entry directly under `repos/`
+  (depth 1 — a stray folder or file at the org level).
+- Any write whose second path segment is not an allowed GitHub org.
+- Any delete (`rm`, `rmdir`, `git clean`, `git rm`, `unlink`, `shred`,
+  `trash`, ...) anywhere under `$HOME/workspace/repos`, at any depth,
+  including deep inside org checkouts.
+
+## What it allows
+
+- Reads, always.
+- Writes deeper inside an allowed org folder
+  (`repos/<org>/<repo>/...`). Structure only: it deliberately does NOT
+  duplicate the `worktree-guard` hook, which owns edits-in-shared-checkouts
+  semantics.
+
+Home spellings (`~`, `$HOME`, `${HOME}`, quoted or not, including split-quote
+forms like `"$HOME"/workspace/repos`, which Bash treats identically to the
+unquoted spelling) are expanded before classification; `apply_patch` tools
+are inspected through their `Add File` / `Update File` / `Delete File`
+markers; Bash relative operands are resolved against the command's cwd when
+it sits under `repos/`; parenthesized command groups
+(`(cd ... && rm -rf ...)`) are unwrapped.
+
+## Configuration
+
+Allowed orgs default to `hasna,hasnaxyz,hasna-internal,hasna-products` and
+are overridable with the `WORKSPACE_REPOS_GUARD_ORGS` env var
+(comma-separated). The home directory is resolved with `os.homedir()` —
+never hardcoded.
+
+## Failure mode
+
+Fail-open: on any parse or evaluation error the hook responds `continue` so a
+guard defect can never wedge the agent.
+
+## Known limitation
+
+The guard is a best-effort **structural** guard, not an execution sandbox.
+Variable indirection cannot be caught by pre-expansion inspection: a command
+that builds its target dynamically (`R=...; rm -rf $R`, loops over computed
+paths, scripts downloaded and executed at runtime) is undetectable at hook
+time. The hook inspects literal spellings of the protected path (`~/...`,
+`$HOME/...`, `${HOME}/...`, split-quote forms such as `"$HOME"/...`, the
+resolved absolute home) and relative operands resolved from the command's
+cwd, so anything the shell would expand or indirect through a variable is
+outside its reach. Because it also fails open, it must never be relied on as
+the only protection layer.
+
+## License
+
+Apache-2.0

package/hooks/hook-workspace-repos-guard/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "workspace-repos-guard",
+  "version": "0.1.0",
+  "description": "Codewith-native Workspace Repos Guard hook for @hasna/hooks",
+  "type": "module",
+  "main": "./src/hook.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "author": "Hasna",
+  "license": "Apache-2.0"
+}