SocketDev
diff --git a/‎.claude/hooks/fleet/_shared/README.md‎
Lines changed: 47 additions & 0 deletions b/‎.claude/hooks/fleet/_shared/README.md‎
Lines changed: 47 additions & 0 deletions
diff --git a/‎.claude/hooks/fleet/_shared/acorn/README.md‎
Lines changed: 65 additions & 0 deletions b/‎.claude/hooks/fleet/_shared/acorn/README.md‎
Lines changed: 65 additions & 0 deletions
@@ -0,0 +1,47 @@
+# `.claude/hooks/_shared/`
+
+Helper modules shared across multiple hooks under `.claude/hooks/`. **Not a deployable hook** — has no `index.mts` entry point and no Claude Code hook lifecycle wiring.
+
+## What lives here
+
+- **`shell-command.mts`** — Tokenizes a Bash command string with `shell-quote` into discrete `Command`s (`binary`, `args`, leading env `assignments`, plus `viaVariable` / `viaEval` indirection flags). Exposes `parseCommands`, `findInvocation`, `commandsFor`, `invocationHasFlag`, and `hasOpaqueInvocation`. Used by every structure-sensitive Bash guard (`codex-no-write-guard`, `release-workflow-guard`, `no-empty-commit-guard`, the git-detection guards, …) so a forbidden invocation is matched on the actual parsed command — `$(…)` / `$VAR` / `eval` indirection is seen rather than evaded, and a quoted mention inside an `echo` or `-m` body can't false-trigger.
+
+- **`hook-env.mts`** — `isHookDisabled(slug)` and `hookLog(slug, ...lines)`. Standardizes the `SOCKET_<UPPER_SLUG>_DISABLED` env-var convention every hook supports plus the `[<slug>] <line>` stderr prefix shape. Use these in new hooks so every hook gets a uniform kill switch + output format for free.
+
+- **`markers.mts`** — Shared sentinel constants for bypass phrases the user can type to override a hook (`Allow <name> bypass`, etc.).
+
+- **`payload.mts`** — `ToolCallPayload` and `ToolInput` types for the PreToolUse JSON payload, plus `readCommand` / `readFilePath` / `readWriteContent` narrowing helpers. **Use this instead of re-declaring `tool_input` types per-hook** — the fleet had 7 hand-rolled variants before this module landed.
+
+- **`stop-reminder.mts`** — `runStopReminder(config)` scaffold for Stop hooks that are pure pattern-sweep over the last assistant turn. Reduces a typical pattern-only hook from 100-200 LOC to ~50. Pass `patterns: [{label, regex, why}, ...]` and `closingHint`; the scaffold handles stdin parse, transcript walk, code-fence strip, per-hit snippet extraction, and stderr emit.
+
+- **`token-patterns.mts`** — Canonical catalog of secret-bearing env-var key names (Socket, LLM providers, GitHub, Linear, Notion, AWS, Stripe, …). Used by `token-guard` (Bash) and `no-token-in-dotenv-guard` (Edit/Write) for the same shape detection.
+
+- **`transcript.mts`** — `readStdin()` for hook payloads, plus `readLastAssistantText()` and `readLastAssistantToolUses()` for walking the Claude Code session transcript JSONL. Tolerates the harness's 3 historical schema variants in one place so a schema bump is a one-file fix.
+
+- **`wheelhouse-root.mts`** — Walks up from `cwd` to find the local `socket-wheelhouse` checkout (used by hooks that need wheelhouse-relative paths, e.g. `new-hook-claude-md-guard`, `drift-check-reminder`).
+
+## When to reach for what (new hook quick-reference)
+
+- Writing a **Stop hook** that just emits a reminder when patterns match? → `import { runStopReminder } from '../_shared/stop-reminder.mts'`. See `comment-tone-reminder` or `excuse-detector` for the shape.
+
+- Writing a **PreToolUse hook** that inspects a tool call's input? → `import { ToolCallPayload, readCommand, readFilePath } from '../_shared/payload.mts'`. Saves you the `typeof === 'string'` guard.
+
+- Detecting whether a Bash command really invokes some binary/subcommand (and want `$(…)` / `$VAR` / quoted-mention false positives handled)? → `import { commandsFor, findInvocation } from '../_shared/shell-command.mts'`.
+
+- Want a kill switch for your hook? → `import { isHookDisabled, hookLog } from '../_shared/hook-env.mts'`. The hook is enabled by default and `SOCKET_<UPPER_SLUG>_DISABLED=1` opts out — same shape across the fleet.
+
+- Need to scan secret-bearing env-var names? → `import { ALL_TOKEN_KEY_PATTERNS } from '../_shared/token-patterns.mts'`.
+
+## Adding to `_shared/`
+
+A module belongs in `_shared/` when:
+
+1. Two or more hooks under `.claude/hooks/*/index.mts` need the same parsing / matching / IO logic.
+2. The logic is self-contained — no Claude Code hook lifecycle (`process.stdin`, exit codes, blocking semantics).
+3. Test coverage lives in `_shared/test/` alongside the helper.
+
+If only one hook uses it, keep it inline in that hook's directory. If three or more hooks need it across `.claude/hooks/` AND `.git-hooks/`, escalate it to `_helpers.mts` (the cross-boundary shared module) instead.
+
+## Not a hook
+
+The `audit-claude` script and the sync-scaffolding `every-hook-has-test` check skip `_shared/` because it carries no `index.mts`. Future contributors who add an `index.mts` here are mis-using the directory — the file should live in a sibling `<hook-name>/` directory instead.
@@ -0,0 +1,65 @@
+# acorn — shared wasm parser for fleet hooks
+
+Vendored from
+[`@ultrathink/acorn-monorepo`](https://github.com/SocketDev/ultrathink/tree/main/packages/acorn)'s
+Rust → WebAssembly prod build (path:
+`packages/acorn/lang/rust/build/prod/darwin-arm64/wasm/out/Final/`).
+Pending `@ultrathink/acorn` ship to the npm registry, fleet hooks
+that need AST-aware analysis `import` from here.
+
+## Provenance
+
+The three vendored files come straight from the ultrathink prod build:
+
+- `acorn.wasm` — compiled Rust acorn parser, ~3.3 MB.
+- `acorn-bindgen.cjs` — wasm-bindgen JS glue.
+- `acorn-sync.mts` — sync ESM loader (no top-level await,
+  `WebAssembly.Instance` constructed at module import).
+
+The artifact is rebuilt in ultrathink with `pnpm run
+build:wasm:node:release` from `packages/acorn/lang/rust`.
+
+## Refreshing
+
+Hooks importing this directory don't need to do anything special —
+the cascade keeps the files byte-identical with the ultrathink
+canonical source. To pull a newer build:
+
+```bash
+# Inside socket-wheelhouse (the canonical source for fleet template):
+node scripts/refresh-vendored-acorn.mts
+```
+
+The script reads from
+`$ULTRATHINK_ROOT/packages/acorn/lang/rust/build/prod/darwin-arm64/wasm/out/Final/`,
+copies the three files into this directory, and updates this README's
+"Last refreshed" line.
+
+Last refreshed: 2026-05-20 (ultrathink build dated 2026-05-20).
+
+## Public surface
+
+`template/.claude/hooks/fleet/_shared/acorn/index.mts` is the canonical
+import path for fleet hooks. It re-exports a narrow `tryParse` /
+`walkSimple` / `findBareCallsTo` surface — see the module's JSDoc for
+the parse-failure tolerance + visitor patterns hook authors rely on.
+
+Don't import `acorn-sync.mts` directly from hooks; the `index.mts`
+wrapper provides the failure-handling + visitor adapters every hook
+needs.
+
+## Why vendor instead of `import 'acorn'`
+
+- **No JS parser in the npm dep graph.** Hooks fire on every Edit/Write.
+  A 3-5 MB JS bundle in `node_modules` adds startup latency and Socket-
+  score risk on every fleet repo.
+- **AST parity with the lint plugin.** Both surfaces (oxlint via plugin
+  - hook via this loader) use the same acorn semantics — the rules can
+    share visitor logic without divergence between commit-time and
+    edit-time.
+- **wasm sandbox.** The parser runs in WebAssembly with no filesystem
+  / network access — even a malicious source file under analysis can't
+  reach the host.
+
+Retire this directory once `@ultrathink/acorn` ships and the wheelhouse
+catalog can pin it.