Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

feat(hooks): show the catalog selection in `claudish hooks list`

Jack Rudenko9432c41b846a
diff --git a/ai-docs/architecture/hooks.md b/ai-docs/architecture/hooks.md
index d7aaa3e2..8ffe8b4e 100644
--- a/ai-docs/architecture/hooks.md
+++ b/ai-docs/architecture/hooks.md
@@ -412,9 +412,11 @@ control, plus the in-place edit and the `warn` replacement built from the view.
**The Gemini built-in** (`gemini/thought-signature`, `order: "pre"`) is selected from catalog data
when the handler has a catalog connection: a Gemini-API wire, or a model whose catalog vendor is
-`google` behind a gateway, whatever its (possibly opaque) id. This is `BuiltinHook.selectByUpstream`
-over the internal `UpstreamFacts` that `ComposedHandler` passes in the applicability scope; they never
-reach a hook context. Without a connection (custom endpoints, dynamic subscriptions) its `models`
+`google` behind a gateway, whatever its (possibly opaque) id. This is `BuiltinHook.selectByUpstream`,
+an `UpstreamSelector` (wire APIs and vendors, data rather than a predicate, so `claudish hooks list`
+prints it as `catalogSelection` and in the text scope line) matched against the internal
+`UpstreamFacts` that `ComposedHandler` passes in the applicability scope; they never reach a hook
+context. Without a connection (custom endpoints, dynamic subscriptions) its `models`
globs decide: names containing `gemini` or `google/`. It keeps a cache keyed `"<provider>\0<modelId>"`, which reproduces the old per-handler
scope. The old middleware's `afterResponse` had no production caller and was deleted, not migrated.
`statsNames()` reports the `statsName` of the built-in raw hooks active for a model, so the OTLP
diff --git a/docs/advanced/hooks.md b/docs/advanced/hooks.md
index 8be2cd66..0f964947 100644
--- a/docs/advanced/hooks.md
+++ b/docs/advanced/hooks.md
@@ -791,7 +791,7 @@ and requests from team judges, are not held at all.
| Command | What it does | Exit |
|---|---|---|
-| `claudish hooks list [--json]` | Every hook, built-in and yours, in effective order, with its source, events, default and resolved severity, routes, models, order and `UNSAFE` flag. Then the modules that failed to load, and whether a `behavior` block is still in the config. | 0 |
+| `claudish hooks list [--json]` | Every hook, built-in and yours, in effective order, with its source, events, default and resolved severity, routes, models, order and `UNSAFE` flag. A built-in selected from the model catalog (`gemini/thought-signature`) also shows that selection, the wire API and vendor that pick it when the route has a catalog connection (`catalogSelection` in `--json`); its `models` globs apply only without one. Then the modules that failed to load, and whether a `behavior` block is still in the config. | 0 |
| `claudish hooks check <file> [--json]` | Loads one module on its own and validates it. | 0 valid, 1 invalid |
| `claudish hooks init [dir]` | Writes `example-hook.ts` and `claudish-hooks.d.ts` into `dir` (default `~/.claudish/hooks`). Refuses to overwrite either file. | 0, or 1 if a file exists |
| `claudish hooks corpus [--write] [--json]` | Replays recorded Claude Code transcripts offline and counts plan-mode divergences per model. | 0 |
diff --git a/packages/cli/src/hooks-command.followup.test.ts b/packages/cli/src/hooks-command.followup.test.ts
new file mode 100644
index 00000000..932065cd
--- /dev/null
+++ b/packages/cli/src/hooks-command.followup.test.ts
@@ -0,0 +1,81 @@
+/**
+ * F4.1: `claudish hooks list` describes the selection that actually applies to
+ * `gemini/thought-signature`.
+ *
+ * Contract (spec F4.1 and the selection rule pinned in hooks/raw.test.ts): with a catalog
+ * connection the built-in is selected by the connection's wire (`gemini`) or vendor
+ * (`google`); without one, by the model-name globs (`*gemini*`, `*google/*`). The listing
+ * must say both, because either can be what applies on a given route.
+ *
+ * Blind to the exact wording and JSON key names: the assertions look for the facts
+ * (the words wire and vendor, the values gemini and google, and the name globs), not a layout.
+ */
+
+import { afterAll, describe, expect, it } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const ENTRY = join(import.meta.dir, "index.ts");
+const root = mkdtempSync(join(tmpdir(), "claudish-hooks-list-followup-"));
+afterAll(() => rmSync(root, { recursive: true, force: true }));
+
+function list(extra: string[] = []) {
+ const configPath = join(root, "config.json");
+ writeFileSync(configPath, JSON.stringify({}));
+ const proc = Bun.spawnSync(["bun", "--no-env-file", ENTRY, "hooks", "list", ...extra], {
+ cwd: join(import.meta.dir, ".."),
+ env: {
+ PATH: process.env.PATH ?? "",
+ HOME: join(root, "home"),
+ CLAUDISH_CONFIG: configPath,
+ CLAUDISH_DISABLE_KEYCHAIN: "1",
+ CLAUDISH_DISABLE_OP: "1",
+ NO_COLOR: "1",
+ },
+ });
+ return { code: proc.exitCode, stdout: proc.stdout.toString(), stderr: proc.stderr.toString() };
+}
+
+/** The text of the gemini/thought-signature entry, up to the next hook id. */
+function geminiSection(text: string): string {
+ const start = text.indexOf("gemini/thought-signature");
+ expect(start).toBeGreaterThanOrEqual(0);
+ const rest = text.slice(start + "gemini/thought-signature".length);
+ const next = rest.search(/plan-mode\/plan-file-path|session-context\/|observer\/divergence/);
+ return next === -1 ? rest : rest.slice(0, next);
+}
+
+describe("F4.1 hooks list describes the gemini built-in's real selection", () => {
+ it("F4.1-a text listing names the catalog selection (wire gemini, vendor google) and the name globs", () => {
+ const r = list();
+ expect(r.code).toBe(0);
+ const section = geminiSection(r.stdout);
+ expect(section).toMatch(/wire/i);
+ expect(section).toMatch(/vendor/i);
+ expect(section).toContain("gemini");
+ expect(section).toContain("google");
+ expect(section).toContain("*gemini*");
+ expect(section).toContain("*google/*");
+ });
+
+ it("F4.1-b --json: the entry still carries the name globs and also exposes wire and vendor", () => {
+ const r = list(["--json"]);
+ expect(r.code).toBe(0);
+ const out = JSON.parse(r.stdout);
+ const entry = out.hooks.find((h: { id: string }) => h.id === "gemini/thought-signature");
+ expect(entry).toBeDefined();
+ expect(entry.models).toEqual(expect.arrayContaining(["*gemini*", "*google/*"]));
+ const serialized = JSON.stringify(entry);
+ expect(serialized).toMatch(/wire/i);
+ expect(serialized).toMatch(/vendor/i);
+ expect(serialized).toContain("google");
+ });
+
+ it("F4.1-c a hook selected by name only (plan-mode) is not described with wire or vendor", () => {
+ const r = list(["--json"]);
+ const out = JSON.parse(r.stdout);
+ const entry = out.hooks.find((h: { id: string }) => h.id === "plan-mode/plan-file-path");
+ expect(JSON.stringify(entry)).not.toMatch(/vendor/i);
+ });
+});
diff --git a/packages/cli/src/hooks-command.test.ts b/packages/cli/src/hooks-command.test.ts
index 127b4a36..c35ee490 100644
--- a/packages/cli/src/hooks-command.test.ts
+++ b/packages/cli/src/hooks-command.test.ts
@@ -84,6 +84,7 @@ describe("claudish hooks list --json", () => {
severity: "fix",
routes: "all",
models: ["*gemini*", "*google/*"],
+ catalogSelection: { wireApis: ["gemini"], vendors: ["google"] },
order: "pre",
unsafe: true,
});
diff --git a/packages/cli/src/hooks-command.ts b/packages/cli/src/hooks-command.ts
index df739775..e7265bf4 100644
--- a/packages/cli/src/hooks-command.ts
+++ b/packages/cli/src/hooks-command.ts
@@ -47,7 +47,11 @@ function severityColor(sev: string): string {
return dim(sev);
}
-/** A hook as `list --json` and `check --json` print it (§4.9). */
+/**
+ * A hook as `list --json` and `check --json` print it (§4.9). A built-in selected from catalog
+ * data also carries `catalogSelection`: on a route with a catalog connection the wire APIs and
+ * vendors there decide, and `models` only on a route without one.
+ */
function hookRow(hook: RegisteredHook, severity: string) {
return {
id: hook.id,
@@ -57,11 +61,28 @@ function hookRow(hook: RegisteredHook, severity: string) {
severity,
routes: hook.routes,
models: [...hook.models],
+ ...(hook.selectByUpstream && {
+ catalogSelection: {
+ wireApis: [...hook.selectByUpstream.wireApis],
+ vendors: [...hook.selectByUpstream.vendors],
+ },
+ }),
order: hook.order,
unsafe: hook.unsafe,
};
}
+/** The scope line's selection: catalog facts first when the hook has them, then the name globs. */
+function selectionOf(r: ReturnType<typeof hookRow>): string | null {
+ const globs = r.models.join(", ");
+ if (!r.catalogSelection) return r.models.join(",") !== "*" ? `models ${globs}` : null;
+ const facts = [
+ ...r.catalogSelection.wireApis.map((w) => `wire ${w}`),
+ ...r.catalogSelection.vendors.map((v) => `vendor ${v}`),
+ ].join(" or ");
+ return `catalog ${facts}; without a catalog connection, models ${globs}`;
+}
+
/* ───────────── list ───────────── */
async function list(json: boolean): Promise<number> {
@@ -107,7 +128,7 @@ async function list(json: boolean): Promise<number> {
`${r.source}`,
`events ${r.events.join(", ")}`,
`routes ${r.routes}`,
- r.models.join(",") !== "*" ? `models ${r.models.join(", ")}` : null,
+ selectionOf(r),
r.order !== "normal" ? `order ${r.order}` : null,
].filter(Boolean);
console.log(` ${dim(scope.join(" · "))}\n`);
diff --git a/packages/cli/src/hooks/builtins/gemini-thought-signature.ts b/packages/cli/src/hooks/builtins/gemini-thought-signature.ts
index 505e7a4e..8940e1d7 100644
--- a/packages/cli/src/hooks/builtins/gemini-thought-signature.ts
+++ b/packages/cli/src/hooks/builtins/gemini-thought-signature.ts
@@ -88,7 +88,7 @@ export function createGeminiThoughtSignatureHook(): BuiltinHook {
"Sends Gemini's reasoning_details back with the assistant tool calls they were produced for",
order: "pre",
models: ["*gemini*", "*google/*"],
- selectByUpstream: (upstream) => upstream.wireApi === "gemini" || upstream.vendor === "google",
+ selectByUpstream: { wireApis: ["gemini"], vendors: ["google"] },
routes: "all",
defaultSeverity: "fix",
statsName: GEMINI_THOUGHT_SIGNATURE_STATS_NAME,
diff --git a/packages/cli/src/hooks/registry.ts b/packages/cli/src/hooks/registry.ts
index 4dac4c45..4b203e83 100644
--- a/packages/cli/src/hooks/registry.ts
+++ b/packages/cli/src/hooks/registry.ts
@@ -67,6 +67,23 @@ export interface UpstreamFacts {
vendor: string | null;
}
+/**
+ * Catalog facts that select a built-in on a route with a catalog connection: the route's wire API
+ * is one of `wireApis`, or its vendor is one of `vendors`. Data, not a predicate, so
+ * `claudish hooks list` can print the selection that actually applies.
+ */
+export interface UpstreamSelector {
+ wireApis: ReadonlyArray<string>;
+ vendors: ReadonlyArray<string>;
+}
+
+export function upstreamSelected(selector: UpstreamSelector, upstream: UpstreamFacts): boolean {
+ return (
+ (upstream.wireApi !== null && selector.wireApis.includes(upstream.wireApi)) ||
+ (upstream.vendor !== null && selector.vendors.includes(upstream.vendor))
+ );
+}
+
/** A built-in hook. Its id carries no `hook:` prefix. */
export type BuiltinHook = HookDefinition & {
/** Name reported in stats `middleware_names` while this raw built-in is active. */
@@ -77,7 +94,7 @@ export type BuiltinHook = HookDefinition & {
* an opaque gateway id, is then not asked again. Without a connection the
* `models` globs decide, as for every hook.
*/
- selectByUpstream?: (upstream: UpstreamFacts) => boolean;
+ selectByUpstream?: UpstreamSelector;
};
/** A user hook as the loader produced it. */
@@ -109,7 +126,7 @@ export interface RegisteredHook {
events: ReadonlyArray<HookEventName>;
statsName?: string;
/** Built-ins only: see `BuiltinHook.selectByUpstream`. */
- selectByUpstream?: (upstream: UpstreamFacts) => boolean;
+ selectByUpstream?: UpstreamSelector;
}
/** A hook selected for one event, with its resolved severity. */
@@ -151,7 +168,7 @@ function register(
source: RegisteredHook["source"],
module?: string,
statsName?: string,
- selectByUpstream?: (upstream: UpstreamFacts) => boolean
+ selectByUpstream?: UpstreamSelector
): RegisteredHook {
const hook: RegisteredHook = {
id,
@@ -245,6 +262,6 @@ export class HookRegistry {
function routeMatches(hook: RegisteredHook, route: RouteInfo, upstream?: UpstreamFacts): boolean {
if (hook.routes === "native" && !route.native) return false;
if (hook.routes === "foreign" && route.native) return false;
- if (upstream && hook.selectByUpstream) return hook.selectByUpstream(upstream);
+ if (upstream && hook.selectByUpstream) return upstreamSelected(hook.selectByUpstream, upstream);
return hook.models.some((glob) => globMatches(glob, route.modelId));
}