@hasna/hooks 0.4.1 → 0.6.0

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/mention-context/README.md

@@ -0,0 +1,109 @@
+# mention-context
+
+A `UserPromptSubmit` hook. When a prompt mentions `hasna/<repo>` or `hasnaxyz/<repo>`,
+it injects a short context block for that repository — local checkout HEAD, installed
+version, worktrees, npm version, GitHub default branch and open PRs.
+
+This is the first Python hook in this repository. Everything else under `hooks/` is
+TypeScript. The language is not a preference: this hook runs on **every prompt
+submission** under a sub-second budget, and starting a Python interpreter that exits
+immediately when no token matches is measurably cheaper here than the alternative that
+was available when it was written. A TypeScript port is a reasonable future change; it
+is a rewrite, not a move, and it is out of scope for the defect this directory was
+created to fix.
+
+## Layout
+
+```
+src/hasna-mention-context.py   the hook
+src/hasna-mention-warm.py      the out-of-band cache warmer — see "The two files are a pair"
+src/hook.test.ts               bun-test wrapper — runs the Python suite under `bun test`
+src/test_run_capture.py        the Python regression suite
+```
+
+## Running the tests
+
+```bash
+bun test hooks/mention-context          # via the wrapper, as CI runs it
+python3 hooks/mention-context/src/test_run_capture.py -v   # directly
+```
+
+The wrapper exists so the Python suite runs under the repository's existing `bun test`
+step with no CI workflow change. It **fails** rather than skips when `python3` is
+absent: a skip is indistinguishable from a pass in the summary line, and a regression
+test that can silently not run is not a regression test.
+
+## The two files are a pair, and each resolves the other by directory
+
+`hasna-mention-context.py` and `hasna-mention-warm.py` must be installed **into the same
+directory**. Neither takes a configured path for the other; each derives the other's
+location from its own `__file__`. The coupling runs in both directions and the two
+failures look nothing alike.
+
+**Warmer missing, hook present — silent.** The hook computes
+`WARM_BIN = <its own dir>/hasna-mention-warm.py` and guards the call with
+`os.path.isfile`, so `request_warm()` simply returns. Nothing raises, nothing is logged,
+and the prompt block still renders. What stops is the cold-cache self-heal: the hook
+hands every degraded or GitHub-less token to the warmer precisely so the *next* prompt
+is clean, and that hand-off never happens. A repository mentioned for the first time is
+degraded once and then stays degraded on every later prompt, instead of being clean
+thereafter. It does not recover on its own, because the hook's own live GitHub probe
+cannot close the gap — by the measurement recorded in the hook's header, `gh api graphql`
+takes 1.02–1.18 s against a whole-hook deadline of 0.900 s, so the probe is killed before
+it can write the cache. The warmer is the only thing that reliably fills it.
+
+**Hook missing, warmer present — loud.** The warmer computes
+`HOOK_PATH = <its own dir>/hasna-mention-context.py` and imports it at *module scope*
+(`H = load_hook()`), with no guard, to keep one definition of the cache paths, the entry
+shapes and the sanitizer. An absent hook is an immediate `FileNotFoundError` and the
+warmer does not start at all.
+
+Because the warmer imports the hook, the hook's `CACHE_DIR`, cache entry shape and
+sanitizer are a **contract with a second program in this directory**, not private
+details. Changing them means changing both files together.
+
+Note that the scheduled warming path does not depend on co-location: the cron entry
+invokes the warmer by absolute path. Co-location is what the hook's self-heal path needs.
+
+## Installation
+
+This directory is the source. The hook is installed by copying
+`src/hasna-mention-context.py` to the path registered in the agent's settings
+(`~/.hasna/hooks/bin/hasna-mention-context.py` on the current fleet) and is registered
+there by absolute path under `UserPromptSubmit`.
+
+Copy `src/hasna-mention-warm.py` to that **same directory** in the same step, and
+schedule it. On the current fleet it runs from cron at minutes 1, 11, 21, 31, 41 and 51
+under `flock`, and it holds its own lock, so overlapping runs are harmless. Installing
+the hook alone is a supported thing to do — the hook works without the warmer — but it
+costs the self-heal described above, silently, so it should be a decision rather than an
+oversight.
+
+Installation is deliberately **not** performed by merging this directory. The hook
+renders into every agent's prompt on every firing, so landing the source and updating
+the live path are two separately verified steps.
+
+## The defect this directory was created to fix
+
+`run_capture` derived its temp-file path from its `tag` argument alone, and
+`probe_local_head` passed a constant `tag="gitlog"`. Repository probes run concurrently
+against one shared temp directory, so every mentioned repository's `git log` wrote to
+and read back the same `gitlog.out`, and the reader got whatever the last writer left.
+
+The emitted value was always a **real sha from a real repository — just the wrong
+one**, which is why it read as correct. Four consecutive firings, each a different wrong
+pairing:
+
+```
+17:44   loops=82a3acf (right)   accounts=27cffd7 (right)   logs=absent
+17:48   loops=27cffd7 (WRONG)   logs=82a3acf (WRONG)          <- clean swap
+18:11   loops=27cffd7 (WRONG)   logs=146a70e (right)
+18:17   loops=82a3acf (right)   logs=82a3acf (WRONG)          <- duplicate sha
+```
+
+The race needs two or three mentions in one prompt. `MAX_TOKENS = 3`, so a single-repo
+mention produces one probe, no concurrency, and always the correct answer.
+
+The fix is in `run_capture`, which owns path construction, rather than at the call site:
+threading `org`/`word` into `probe_local_head` would have matched its siblings but left
+the invariant unenforced, so a fifth call site added later would inherit the bug.

package/hooks/mention-context/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "mention-context",
+  "version": "0.1.0",
+  "description": "UserPromptSubmit hook that injects repository context for @hasna/<repo> mentions",
+  "type": "module",
+  "main": "./src/hasna-mention-context.py",
+  "author": "Hasna",
+  "license": "Apache-2.0"
+}