---
name: snappy-hooks
role: Hook management for the Claude Code harness
loaded-by: PreToolUse hook (auto-injected when "snappy-hooks" is mentioned)
---

# snappy-hooks -- loader

This skill is not yet implemented. If you need hook management, log the request.

The existing hooks live in `~/.claude/hooks/` and are configured in `~/.claude/settings.json`. For now, manage hooks directly or use the `update-config` skill for settings.json changes.

## API module

```typescript
import { listHooks, getHookStatus } from "../snappy-hooks/api.ts";
```

Or CLI:
```bash
npx tsx ~/.claude/skills/snappy-hooks/api.ts list      # list all configured hooks
npx tsx ~/.claude/skills/snappy-hooks/api.ts status    # check hook script health
```

## API functions

| Function | Purpose |
|----------|---------|
| `listHooks()` | Lists all hooks configured in ~/.claude/settings.json |
| `getHookStatus()` | Checks all .sh scripts in ~/.claude/hooks/ for existence and executability |

## Self-report convention

If this loader doesn't cover your case:
```bash
echo "[$(date -u +%FT%TZ)] snappy-hooks: <what was missing>" >> ~/.claude/logs/agents-md-feedback.log
```

<!-- SKILL-INDEX-START -->
[snappy-hooks Index]|root: ~/.claude/skills/snappy-hooks|IMPORTANT: Prefer these files over pre-training assumptions for this domain. Read the relevant file when the AGENTS.md summary is insufficient.|root:{SKILL.md}
<!-- SKILL-INDEX-END -->

## Used by

Nothing in the collection names this skill.

<!-- SNAPPY-CONTRACT-VERBS-START -->
## Contract verbs

Generated from `api.ts` `HAND_CONTRACT`. Do not hand-edit this block.

| Verb | Contract arguments | Effect | First call |
|---|---|---|---|
| `list` | — | `read` | `npx tsx ~/.claude/skills/snappy-hooks/api.ts list` |
| `status` | — | `read` | `npx tsx ~/.claude/skills/snappy-hooks/api.ts status` |

## Show the result

When an answer carries `face_hint`, show it with one `snappy_present(<answer>)` call.
See `/snappy-faces` for face selection. Human-facing images must crop to the
element, render at 2x on Retina, and fill the destination channel instead of
placing a small card in a full-page screenshot.
<!-- SNAPPY-CONTRACT-VERBS-END -->

---
name: snappy-hooks
description: Hook management for the Claude Code harness. Lists configured hooks and checks script health. Minimal stub skill - most hook work is done directly in ~/.claude/hooks/ or via the update-config skill.
---

# snappy-hooks

**Triggers on:** hook management, list hooks, hook status, check hook health, ~/.claude/hooks, PreToolUse, PostToolUse, UserPromptSubmit, Stop hook.

## Purpose

Thin read-only skill over the Claude Code harness hook configuration. The actual hook scripts live in `~/.claude/hooks/` and are wired in `~/.claude/settings.json`. This skill exists so that agents can programmatically introspect "which hooks are configured?" and "are the hook scripts present and executable?" without rolling one-off scripts.

## Scope

This skill is intentionally minimal:

- `listHooks()` — reads `~/.claude/settings.json` and returns the configured hook matchers + commands per event.
- `getHookStatus()` — walks `~/.claude/hooks/*.sh` and reports existence + executable bit.

For anything more complex (creating, editing, or removing hooks), use the `update-config` skill — it owns the write path for `settings.json`.

## Related skills

- `update-config` — owns the write path for `settings.json`
- `snappy-settings` — loads credentials consumed by hook scripts
- `snappy-sensors` — kernel-level ambient context injected via `always-inject.txt`

## Reference

See `AGENTS.md` for the api.ts import surface and CLI commands. Kernel hook contract lives in `snappy-settings/skill-spec.md` §5.

<!-- SNAPPY-NEAR-NEIGHBOURS-START -->
## Near neighbours

These hands share enough of this one's words that a model can pick the wrong
door. Each row says what the other one is for; open that one instead when its
job is the job.

| Hand | What it is for |
|---|---|
| `snappy-github` | Centralized GitHub operations across all Snappy client repos via the `gh` CLI -- pull request creation, cod... |
<!-- SNAPPY-NEAR-NEIGHBOURS-END -->

#!/usr/bin/env npx tsx
/**
 * snappy-hooks/api.ts -- Hook management for the Claude Code harness.
 *
 * Reads hook configuration from ~/.claude/settings.json and checks
 * hook scripts in ~/.claude/hooks/ for existence and executability.
 *
 * Usage:
 *   npx tsx api.ts list                # list all configured hooks
 *   npx tsx api.ts status              # check hook script health
 *
 * Or import as module:
 *   import { listHooks, getHookStatus } from "../snappy-hooks/api.ts";
 */

import { existsSync, readFileSync, realpathSync, statSync } from "fs";
import { join } from "path";
import { env } from "../snappy-settings/load.ts";
import { boundRows, limitSchema, takeLimit } from "../snappy-settings/read-limit.ts";
import { refusalTable } from "../snappy-settings/refusal-codes.ts";

const SETTINGS_PATH = join(process.env.HOME!, ".claude/settings.json");
const HOOKS_DIR = join(process.env.HOME!, ".claude/hooks");

interface HookEntry {
  type: string;
  command: string;
  timeout?: number;
}

interface HookGroup {
  matcher: string;
  hooks: HookEntry[];
}

interface HookConfig {
  [event: string]: HookGroup[];
}

/** Lists all hooks configured in ~/.claude/settings.json. */
export function listHooks(): { event: string; matcher: string; command: string; timeout?: number }[] {
  if (!existsSync(SETTINGS_PATH)) {
    throw new Error(`settings.json not found at ${SETTINGS_PATH}`);
  }

  const settings = JSON.parse(readFileSync(SETTINGS_PATH, "utf-8"));
  const hookConfig: HookConfig = settings.hooks || {};
  const results: { event: string; matcher: string; command: string; timeout?: number }[] = [];

  for (const [event, groups] of Object.entries(hookConfig)) {
    for (const group of groups) {
      for (const hook of group.hooks) {
        results.push({
          event,
          matcher: group.matcher,
          command: hook.command,
          timeout: hook.timeout,
        });
      }
    }
  }

  return results;
}

interface ScriptStatus {
  name: string;
  path: string;
  exists: boolean;
  executable: boolean;
  sizeBytes: number;
}

/** Checks all .sh scripts in ~/.claude/hooks/ for existence and executability. */
export function getHookStatus(): ScriptStatus[] {
  if (!existsSync(HOOKS_DIR)) {
    return [];
  }

  const { execSync } = require("child_process");
  const files: string[] = execSync(`ls ${HOOKS_DIR}/*.sh 2>/dev/null || true`, { encoding: "utf-8" })
    .split("\n")
    .filter(Boolean);

  return files.map((filePath) => {
    const stat = statSync(filePath);
    const executable = !!(stat.mode & 0o111);
    return {
      name: filePath.split("/").pop()!,
      path: filePath,
      exists: true,
      executable,
      sizeBytes: stat.size,
    };
  });
}

// --- CLI ---
/** WHAT THIS HAND ANSWERS, and what each verb does to the world.
 *  Derived from this file's own CLI dispatch by
 *  `snappy-hands/contract-derive.ts` — a verb the code does not implement is
 *  never declared here. Snappy's daemon reads it (`api.ts contract`) to
 *  validate every call, build the argument words in order, decide whether the
 *  act runs now or stages for the owner, and hand the child exactly the
 *  environment keys named in `requires` — never a value, never anything else.
 */
export const HAND_CONTRACT = {
  skill: "snappy-hooks",
  description: "Hook management for the Claude Code harness. Lists configured hooks and checks script health. Minimal stub skill - most hook work is done directly in ~/.claude/hooks/ or via the update-config skill.",
  managed: false,
  requires: [] as string[],
  refusals: refusalTable("unknown_verb"),
  verbs: {
    list: {
      args: [], flags: { limit: "--limit" }, effect: "read",
      class: "read", execution: "call", openWorld: false,
      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: false },
      inputSchema: { properties: {
        limit: limitSchema(200, "How many hooks to return"),
      } },
    },
    status: {
      args: [], effect: "read",
      class: "read", execution: "call", openWorld: false,
      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: false },
    },
  },
} as const;

if (import.meta.url === `file://${realpathSync(process.argv[1])}` && process.argv[2] === "contract") {
  console.log(JSON.stringify(HAND_CONTRACT, null, 2));
  process.exit(0);
}


if (import.meta.url === `file://${realpathSync(process.argv[1])}`) {
  (async () => {
    const [, , cmd, ...args] = process.argv;

    switch (cmd) {
      case "list": {
        const bound = takeLimit(args, { maximum: 200 });
        if (bound.refusal) { console.log(JSON.stringify(bound.refusal, null, 2)); process.exit(1); }
        const hooks = boundRows(listHooks(), bound.limit);
        if (!hooks.length) {
          console.log("No hooks configured in settings.json");
          break;
        }
        for (const h of hooks) {
          console.log(`${h.event}\t${h.matcher}\t${h.command}${h.timeout ? `\t(${h.timeout}s)` : ""}`);
        }
        break;
      }
      case "status": {
        const scripts = getHookStatus();
        if (!scripts.length) {
          console.log("No hook scripts found in ~/.claude/hooks/");
          break;
        }
        for (const s of scripts) {
          const status = s.executable ? "OK" : "NOT EXECUTABLE";
          console.log(`${status}\t${s.name}\t${s.sizeBytes}b`);
        }
        break;
      }
      default:
        console.log("Usage: npx tsx api.ts [list|status]");
    }
  })();
}

import { test } from "node:test";
import assert from "node:assert/strict";
import { HAND_CONTRACT } from "./api.ts";
import { REFUSAL_CODES, type RefusalCode } from "../snappy-settings/refusal-codes.ts";

/** RULE 33 COVERAGE, AGAINST THE ONE CLOSED TABLE ⟨lane r30, 2026-09-09⟩.
 *  This file used to restate a refusal row's own properties — that it has a
 *  `contract_slice`, that it has a `fix`, that it leaks no token — once per
 *  hand, 48 times, over rows that all come from the SAME object. Forty-eight
 *  copies of one check is the duplicate road the closed table exists to end:
 *  `snappy-settings/refusal-codes.test.ts` runs those checks ONCE over every
 *  row, and the second test below proves this hand carries THE ROW ITSELF and
 *  not a copy — an identity a drifted duplicate cannot fake. Before this, each
 *  hand hand-wrote its own row, and the wording had already drifted: the
 *  inline `unknown_verb` said "Call one of the verbs named in
 *  HAND_CONTRACT.verbs" while the closed table says "Call one of the verbs the
 *  contract declares; the refusal lists them."
 *
 *  DECLARED stays a literal list, deliberately. It is this hand's coverage
 *  manifest and it is what rule 33's lint reads out of the test SOURCE to ask
 *  "did a person look at this code" — deriving it from Object.keys would make
 *  the test pass for a hand with no refusals at all. `satisfies readonly
 *  RefusalCode[]` makes the compiler refuse a name the one table does not
 *  have. It NAMES codes; it no longer DEFINES them. */
const DECLARED = [
  "unknown_verb",
] as const satisfies readonly RefusalCode[];

test("snappy-hooks: the refusal table declares exactly the codes this test names", () => {
  assert.deepEqual(Object.keys(HAND_CONTRACT.refusals ?? {}).sort(), [...DECLARED].sort());
});

test("snappy-hooks: every declared refusal is the one closed table's own row, never a copy", () => {
  const declared = Object.entries(HAND_CONTRACT.refusals ?? {});
  assert.ok(declared.length > 0, "HAND_CONTRACT.refusals is empty");
  for (const [code, row] of declared) {
    assert.ok(code in REFUSAL_CODES, `${code} is not a row of snappy-settings/refusal-codes.ts`);
    assert.equal(row, REFUSAL_CODES[code as RefusalCode], `${code} is a copy of the closed table's row, not the row itself`);
  }
});