@hasna/hooks 0.6.8 → 0.7.2

package/hooks/hook-spiral-detector/README.md

@@ -0,0 +1,23 @@
+# hook-spiral-detector
+
+A PostToolUse hook that interrupts Claude Code after five consecutive Bash calls produce the same command, non-zero exit status, and first line of stderr.
+
+## Installation
+
+```bash
+hooks install spiral-detector
+```
+
+## Behavior
+
+- Hashes the command and error signature; command text and stderr are not persisted
+- Keeps streaks separate by session
+- Resets the streak after a success, a different failure, or a non-Bash tool call
+- Returns `{ "continue": false }` on the fifth identical failure, stopping the agent loop
+- Fails open if input or state cannot be read or written
+
+The threshold is deliberately five: it permits a small number of legitimate retries while interrupting a repeated repair loop early.
+
+## Event
+
+- **PostToolUse** (all tools, so non-Bash calls can reset the streak)

package/hooks/hook-spiral-detector/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "hook-spiral-detector",
+  "version": "0.1.0",
+  "description": "Interrupts Claude Code sessions after repeated identical command failures",
+  "type": "module",
+  "main": "./src/hook.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "author": "Hasna",
+  "license": "Apache-2.0"
+}

package/hooks/hook-spiral-detector/src/hook.test.ts

@@ -0,0 +1,72 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const homes: string[] = [];
+const hookPath = join(import.meta.dir, "hook.ts");
+
+async function invoke(home: string, input: object): Promise<Record<string, unknown>> {
+  const proc = Bun.spawn(["bun", "run", hookPath], {
+    stdin: new Response(JSON.stringify(input)),
+    stdout: "pipe",
+    stderr: "pipe",
+    env: { ...process.env, HOME: home },
+  });
+  const [stdout, exitCode] = await Promise.all([new Response(proc.stdout).text(), proc.exited]);
+  expect(exitCode).toBe(0);
+  return JSON.parse(stdout);
+}
+
+function input(session: string, command = "bun test", exitCode = 1): object {
+  return {
+    session_id: session,
+    tool_name: "Bash",
+    tool_input: { command },
+    tool_response: { exit_code: exitCode, stderr: "tests failed\nmore details" },
+  };
+}
+
+afterEach(() => {
+  for (const home of homes.splice(0)) rmSync(home, { recursive: true, force: true });
+});
+
+describe("spiral detector", () => {
+  test("interrupts on the fifth identical red signature", async () => {
+    const home = mkdtempSync(join(tmpdir(), "spiral-detector-"));
+    homes.push(home);
+    for (let attempt = 1; attempt < 5; attempt++) {
+      expect(await invoke(home, input("session-1"))).toEqual({ continue: true });
+    }
+    expect(await invoke(home, input("session-1"))).toMatchObject({
+      continue: false,
+      stopReason: expect.stringContaining("after 5 identical command failures"),
+    });
+  });
+
+  test("successes and changed failures reset the streak", async () => {
+    const home = mkdtempSync(join(tmpdir(), "spiral-detector-"));
+    homes.push(home);
+    for (let attempt = 0; attempt < 4; attempt++) await invoke(home, input("session-2"));
+    expect(await invoke(home, input("session-2", "bun test", 0))).toEqual({ continue: true });
+    for (let attempt = 0; attempt < 4; attempt++) await invoke(home, input("session-2"));
+    expect(await invoke(home, input("session-2", "bun run typecheck"))).toEqual({ continue: true });
+    for (let attempt = 1; attempt < 5; attempt++) {
+      expect(await invoke(home, input("session-2"))).toEqual({ continue: true });
+    }
+    expect(await invoke(home, input("session-2"))).toMatchObject({ continue: false });
+  });
+
+  test("supports the repository's legacy tool_output field", async () => {
+    const home = mkdtempSync(join(tmpdir(), "spiral-detector-"));
+    homes.push(home);
+    const legacy = {
+      session_id: "session-3",
+      tool_name: "Bash",
+      tool_input: { command: "npm test" },
+      tool_output: { exitCode: "2", stderr: "same error" },
+    };
+    for (let attempt = 1; attempt < 5; attempt++) await invoke(home, legacy);
+    expect(await invoke(home, legacy)).toMatchObject({ continue: false });
+  });
+});

package/hooks/hook-spiral-detector/src/hook.ts

@@ -0,0 +1,93 @@
+#!/usr/bin/env bun
+
+/** Interrupt a session after five consecutive identical Bash failures. */
+
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+interface HookInput {
+  session_id?: string;
+  tool_name?: string;
+  tool_input?: Record<string, unknown>;
+  tool_response?: unknown;
+  tool_output?: unknown;
+}
+
+interface State {
+  signature: string;
+  count: number;
+}
+
+const THRESHOLD = 5;
+const STATE_DIR = join(homedir(), ".hasna", "hooks", "state", "spiral-detector");
+
+function hash(value: string): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function statePath(sessionId: string): string {
+  return join(STATE_DIR, `${hash(sessionId)}.json`);
+}
+
+function readState(path: string): State {
+  try {
+    const state = JSON.parse(readFileSync(path, "utf8")) as State;
+    if (typeof state.signature === "string" && Number.isInteger(state.count) && state.count > 0) return state;
+  } catch {}
+  return { signature: "", count: 0 };
+}
+
+function clearState(path: string): void {
+  try {
+    if (existsSync(path)) unlinkSync(path);
+  } catch {}
+}
+
+function redSignature(input: HookInput): string | null {
+  if (input.tool_name !== "Bash" || typeof input.tool_input?.command !== "string") return null;
+  const output = input.tool_response ?? input.tool_output;
+  if (!output || typeof output !== "object") return null;
+  const record = output as Record<string, unknown>;
+  const rawCode = record.exit_code ?? record.exitCode ?? record.code;
+  const exitCode = typeof rawCode === "string" ? Number(rawCode) : rawCode;
+  if (typeof exitCode !== "number" || !Number.isFinite(exitCode) || exitCode === 0) return null;
+  const stderr = typeof record.stderr === "string" ? record.stderr : "";
+  const firstLine = stderr.split(/\r?\n/, 1)[0] ?? "";
+  return hash(`${hash(input.tool_input.command)}\0${exitCode}\0${firstLine}`);
+}
+
+export function processInput(input: HookInput): { continue: boolean; stopReason?: string } {
+  if (!input.session_id) return { continue: true };
+  const path = statePath(input.session_id);
+  const signature = redSignature(input);
+  if (!signature) {
+    clearState(path);
+    return { continue: true };
+  }
+
+  const previous = readState(path);
+  const count = previous.signature === signature ? previous.count + 1 : 1;
+  try {
+    mkdirSync(STATE_DIR, { recursive: true });
+    writeFileSync(path, JSON.stringify({ signature, count }));
+  } catch {
+    return { continue: true };
+  }
+
+  return count >= THRESHOLD
+    ? { continue: false, stopReason: `Spiral detector interrupted the session after ${count} identical command failures. Change the command or underlying state before resuming.` }
+    : { continue: true };
+}
+
+export function run(): void {
+  try {
+    const input = JSON.parse(readFileSync(0, "utf8")) as HookInput;
+    console.log(JSON.stringify(processInput(input)));
+  } catch {
+    console.log(JSON.stringify({ continue: true }));
+  }
+}
+
+if (import.meta.main) run();

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

@@ -35,9 +35,10 @@ it sits under `repos/`; parenthesized command groups
 
 ## 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()` —
+Allowed orgs default to `hasna,hasnaxyz,hasna-products` and are overridable
+with the `WORKSPACE_REPOS_GUARD_ORGS` env var (comma-separated). Private
+workspace orgs must be added per-install via that var; they are never part
+of the public default. The home directory is resolved with `os.homedir()` —
 never hardcoded.
 
 ## Failure mode

package/hooks/hook-workspace-repos-guard/src/hook.test.ts

@@ -15,8 +15,8 @@ function isBlocked(result: { output: { decision?: string; reason?: string } }):
   return null;
 }describe("hook-workspace-repos-guard", () => {
   describe("resolveAllowedOrgs", () => {
-    test("defaults to the four canonical GitHub orgs", () => {
-      expect([...resolveAllowedOrgs({})].sort()).toEqual(["hasna", "hasna-internal", "hasna-products", "hasnaxyz"]);
+    test("defaults to the three public canonical GitHub orgs", () => {
+      expect([...resolveAllowedOrgs({})].sort()).toEqual(["hasna", "hasna-products", "hasnaxyz"]);
     });
 
     test("parses comma-separated env override, trimming whitespace and empties", () => {
@@ -31,9 +31,9 @@ function isBlocked(result: { output: { decision?: string; reason?: string } }):
       expect(isBlocked(result)).toBeNull();
     });
 
-    test("Edit inside hasna-internal org continues", () => {
-      const result = evaluate(preToolUse("Edit", { file_path: join(REPOS, "hasna-internal", "platform", "docs", "readme.md") }));
-      expect(result.output.continue).toBe(true);
+    test("Edit inside a non-default org is blocked", () => {
+      const result = evaluate(preToolUse("Edit", { file_path: join(REPOS, "notanorg", "platform", "docs", "readme.md") }));
+      expect(isBlocked(result)).not.toBeNull();
     });
 
     test("MultiEdit with relative file_path resolves against cwd and continues inside allowed org", () => {
@@ -65,7 +65,7 @@ function isBlocked(result: { output: { decision?: string; reason?: string } }):
         `echo note > ${join(REPOS, "hasna", "apps", "scratch.md")}`,
         `touch ${join(REPOS, "hasna", "apps", "apps", "foo", "x.txt")}`,
         `git clone https://github.com/hasna/foo.git ${join(REPOS, "hasna", "foo")}`,
-        `mkdir -p ${join(REPOS, "hasna-internal", "platform", "apps")}`,
+        `mkdir -p ${join(REPOS, "hasnaxyz", "iapp-probe", "docs")}`,
       ];
       for (const command of commands) {
         const result = evaluate(preToolUse("Bash", { command }));
@@ -77,7 +77,7 @@ function isBlocked(result: { output: { decision?: string; reason?: string } }):
       const commands = [
         `touch ~/workspace/repos/hasna/apps/foo.md`,
         `echo x > ~/workspace/repos/hasnaxyz/iapp-probe/notes.md`,
-        `mkdir -p "${HOME}/workspace/repos/hasna-internal/platform/apps"`,
+        `mkdir -p "${HOME}/workspace/repos/hasnaxyz/iapp-probe/notes"`,
         `touch "$HOME"/workspace/repos/hasna/apps/x.txt`,
         `echo x > "\${HOME}"/workspace/repos/hasnaxyz/iapp-probe/notes.md`,
       ];

package/hooks/hook-workspace-repos-guard/src/hook.ts

@@ -30,8 +30,10 @@
  * tools are inspected through their `*** Add File:` / `*** Update File:` /
  * `*** Delete File:` markers. Parenthesized command groups are unwrapped.
  *
- * Allowed orgs default to hasna,hasnaxyz,hasna-internal,hasna-products and are
- * overridable with the WORKSPACE_REPOS_GUARD_ORGS env var (comma-separated).
+ * Allowed orgs default to hasna,hasnaxyz,hasna-products and are overridable
+ * with the WORKSPACE_REPOS_GUARD_ORGS env var (comma-separated). Private
+ * workspace orgs must be added per-install via that var; they are never part
+ * of the public default.
  * Home is resolved with os.homedir(); never hardcoded. Fail-open on any parse
  * or evaluation error so a guard defect cannot wedge the agent.
  */
@@ -51,7 +53,7 @@ const FILE_WRITE_TOOLS = new Set(["Write", "Edit", "MultiEdit", "NotebookEdit"])
 
 const PATCH_TOOLS = new Set(["apply_patch", "ApplyPatch", "functions.apply_patch"]);
 
-const DEFAULT_ORGS = ["hasna", "hasnaxyz", "hasna-internal", "hasna-products"];
+const DEFAULT_ORGS = ["hasna", "hasnaxyz", "hasna-products"];
 
 const RULE = "workspace-repos-guard";
 

package/hooks/mention-context/src/hasna-mention-context.py

@@ -721,7 +721,7 @@ def render_section(t):
         if proj.get("path"):
             L.append(f"  {'':<11} path {sanitize(proj.get('path'), 120)}")
         if isinstance(dups, int) and dups > 1:
-            # Real hazard, not trivia: `open-todos` exists as FIVE project rows
+            # Real hazard, not trivia: `todos` exists as FIVE project rows
             # with task counters 3/50/58/101/150 across three machine_ids, and
             # the BUG rows are spread over all of them. An agent that files
             # against the wrong row files into a fossil nobody reads.
@@ -732,7 +732,7 @@ def render_section(t):
 
     # --- last 3 bugs -------------------------------------------------------
     # Merged across every matching project row, because BUG rows are genuinely
-    # spread across the duplicates: open-todos carries 58 across 5 rows. Scoping
+    # spread across the duplicates: todos carries 58 across 5 rows. Scoping
     # to the primary alone would hide real bugs. The scope is stated on the line
     # so the count is never read as belonging to the single project above.
     bugs = t.get("bugs") or []

package/hooks/mention-context/src/hasna-mention-warm.py

@@ -340,7 +340,7 @@ def candidate_names(org, word):
 def warm_slow(org, word, tmpdir, projects_cache):
     """Resolve the todos project for a repo and collect its last 3 BUG rows.
 
-    Duplicate project rows are the norm, not the exception: `open-todos` exists
+    Duplicate project rows are the norm, not the exception: `todos` exists
     FOUR times, with 3 / 101 / 58 / 150 task counters on three different
     machine_ids, and the BUG rows are spread across all four (2+7+14+34 = 57).
     Picking by name alone would silently return a 3-task fossil. So the primary

package/hooks/pre-bash/README.md

@@ -81,7 +81,7 @@ remote relative path cannot be resolved against the local working directory.
 
 ## Install for Codewith
 
-Prefer renderer-managed configuration through open-configs. @hasna/hooks can emit the TOML fragment:
+Prefer renderer-managed configuration through configs. @hasna/hooks can emit the TOML fragment:
 
 ```bash
 hooks install pre-bash --target codewith

package/hooks/prompt-guard/README.md

@@ -6,7 +6,7 @@ This hook is OSS-safe: optional Hasna CLIs are best-effort and missing CLIs fail
 
 ## Install for Codewith
 
-Prefer renderer-managed configuration through open-configs. @hasna/hooks can emit the TOML fragment:
+Prefer renderer-managed configuration through configs. @hasna/hooks can emit the TOML fragment:
 
 ```bash
 hooks install prompt-guard --target codewith

package/hooks/session-start/README.md

@@ -6,7 +6,7 @@ This hook is OSS-safe: optional Hasna CLIs are best-effort and missing CLIs fail
 
 ## Install for Codewith
 
-Prefer renderer-managed configuration through open-configs. @hasna/hooks can emit the TOML fragment:
+Prefer renderer-managed configuration through configs. @hasna/hooks can emit the TOML fragment:
 
 ```bash
 hooks install session-start --target codewith

package/hooks/stop-sync/README.md

@@ -6,7 +6,7 @@ This hook is OSS-safe: optional Hasna CLIs are best-effort and missing CLIs fail
 
 ## Install for Codewith
 
-Prefer renderer-managed configuration through open-configs. @hasna/hooks can emit the TOML fragment:
+Prefer renderer-managed configuration through configs. @hasna/hooks can emit the TOML fragment:
 
 ```bash
 hooks install stop-sync --target codewith

package/hooks/worktree-guard/README.md

@@ -61,7 +61,7 @@ from a guardrail by a cooperating agent, not a way to reach a shared checkout.
 
 ## Install for Codewith
 
-Prefer renderer-managed configuration through open-configs. @hasna/hooks can emit the TOML fragment:
+Prefer renderer-managed configuration through configs. @hasna/hooks can emit the TOML fragment:
 
 ```bash
 hooks install worktree-guard --target codewith

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/hooks",
-  "version": "0.6.8",
+  "version": "0.7.2",
   "description": "Open source hooks library for AI coding agents - Install safety, quality, and automation hooks with a single command",
   "type": "module",
   "bin": {
@@ -30,7 +30,9 @@
     "dashboard:dev": "cd dashboard && bun run dev",
     "dashboard:build": "cd dashboard && bun run build",
     "dashboard:preview": "cd dashboard && bun run preview",
-    "postinstall": "mkdir -p $HOME/.hasna/hooks/profiles 2>/dev/null || true"
+    "postinstall": "mkdir -p $HOME/.hasna/hooks/profiles 2>/dev/null || true",
+    "scan:artifact": "bun scripts/artifact-scan.ts",
+    "prepack": "bun run build && bun run scan:artifact"
   },
   "keywords": [
     "claude-code",
@@ -49,11 +51,12 @@
     "@types/pg": "^8.15.6",
     "@types/react": "^18.2.0",
     "typescript": "^5",
-    "bun-types": "1.3.14"
+    "bun-types": "1.3.14",
+    "@hasna/contracts": "0.13.3"
   },
   "dependencies": {
-    "@hasna/events": "^0.1.6",
-    "@hasna/secrets": "0.3.0",
+    "@hasna/events": "^0.1.16",
+    "@hasna/secrets": "0.3.4",
     "@modelcontextprotocol/sdk": "^1.26.0",
     "chalk": "^5.3.0",
     "commander": "^12.1.0",
@@ -64,7 +67,8 @@
     "ink-text-input": "^6.0.0",
     "pg": "^8.16.3",
     "react": "^18.2.0",
-    "zod": "3.25.76"
+    "zod": "3.25.76",
+    "@hasna/contracts": "0.13.3"
   },
   "engines": {
     "bun": ">=1.0.0"