Skip to content

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

10.6 KB
Raw Blame
/**
 * Hook-system configuration: the `hooks` key's schema, severity resolution, and
 * the two reporters for config that is no longer read.
 *
 * Validation lives here rather than in profile-config.ts on purpose — that
 * module is deliberately Zod-free because `loadConfig` runs on many lightweight
 * startup paths. Same rule as custom endpoints: validate at the point of
 * consumption, warn and fall back rather than throwing, so a malformed `hooks`
 * block can never stop claudish from starting.
 *
 * `hooks` is read from the GLOBAL config only (`~/.claudish/config.json`, or the
 * `--config` / `CLAUDISH_CONFIG` override, which replaces both scopes). A
 * project `.claudish.json` is repo-controlled, and executing code it names would
 * need a trust model claudish does not have.
 */

import { existsSync, readFileSync } from "node:fs";
import { dirname } from "node:path";
import { z } from "zod";
import { getConfigFileOverride } from "../config-override.js";
import { logStderr } from "../logger.js";
import { activeConfigFile, getLocalConfigPath } from "../profile-config.js";
import type { Severity } from "./public.js";

const SeveritySchema = z.enum(["off", "warn", "fix"]);

/** Default and bounds of the host cap on consecutive hook-caused turns. */
export const INJECTION_MAX_CONSECUTIVE_DEFAULT = 3;

export const HooksConfigSchema = z.object({
  /** Loaded in order. Absolute, "~/…", or relative to the CONFIG FILE's directory. */
  modules: z.array(z.string().min(1)).optional(),
  /** "[modelGlob:]hookIdGlob" → severity. */
  severity: z.record(z.string(), SeveritySchema).optional(),
  injection: z
    .object({
      maxConsecutive: z.number().int().min(1).max(20).optional(),
    })
    .optional(),
  observer: z
    .object({
      enabled: z.boolean().optional(),
      // "enforce" is deliberately NOT accepted. The observer is advisory and
      // fire-and-forget; a user who asks for enforcement must be told it does
      // not exist, not left believing their calls are being gated.
      mode: z.enum(["off", "suggest"]).optional(),
      model: z.string().optional(),
      timeoutMs: z.number().int().positive().optional(),
      watchTools: z.array(z.string()).optional(),
    })
    .optional(),
  /** Behaviour-telemetry upload consent. Default off. Local journaling is always on. */
  telemetry: z.object({ enabled: z.boolean().optional() }).optional(),
});

export type HooksConfig = z.infer<typeof HooksConfigSchema>;

/** Where warnings go. A parameter so tests can capture them without touching stderr. */
export type WarnSink = (line: string) => void;

/** `logStderr` prefixes `[claudish] ` itself. */
const defaultWarn: WarnSink = (line) => logStderr(line);

/**
 * Parse a raw `hooks` value. Invalid input warns once per Zod issue and degrades
 * to `{}`: built-in hooks run at their default severity and no user module
 * loads. claudish always starts.
 */
export function parseHooksConfig(raw: unknown, warn: WarnSink = defaultWarn): HooksConfig {
  if (raw === undefined || raw === null) return {};
  const result = HooksConfigSchema.safeParse(raw);
  if (!result.success) {
    for (const issue of result.error.issues) {
      const where = issue.path.length > 0 ? `${issue.path.join(".")}: ` : "";
      warn(`hooks config: ${where}${issue.message}`);
    }
    return {};
  }
  return result.data;
}

/** The host cap on consecutive hook-caused turns for this config. */
export function maxConsecutiveInjections(config: HooksConfig): number {
  return config.injection?.maxConsecutive ?? INJECTION_MAX_CONSECUTIVE_DEFAULT;
}

/**
 * The directory relative module paths resolve against: the ACTIVE config file's
 * directory, never `process.cwd()` — in a pane child the cwd is the MCP
 * server's.
 */
export function hooksConfigDir(): string {
  return dirname(activeConfigFile());
}

/* ───────────── severity ───────────── */

/**
 * Resolve the effective severity for a hook id.
 *
 * Ported verbatim from the behavior layer (`behavior/config.ts`), with the map
 * now read from `hooks.severity`. Precedence: model-scoped keys beat unscoped
 * ones; within a tier an exact id beats a glob and a longer glob beats a
 * shorter one; otherwise the hook's own default.
 *
 *   { "plan-mode/*": "off", "plan-mode/plan-file-path": "fix" }
 */
export function resolveSeverity(
  hookId: string,
  defaultSeverity: Severity,
  severityMap: Record<string, Severity> | undefined,
  modelId?: string
): Severity {
  const rules = severityMap;
  if (!rules) return defaultSeverity;

  // Model-scoped keys beat unscoped ones. Nothing transfers between models — a
  // rule proven on one is a hypothesis on the next — so a user must be able to
  // arm a rule for the model that needs it without arming it for every model:
  //
  //   { "plan-mode/*": "warn", "gpt-5.6-*:plan-mode/plan-file-path": "fix" }
  //
  // Pass 1 considers only `model:rule` keys, pass 2 only unscoped keys.
  if (modelId) {
    const scoped = bestMatch(rules, hookId, modelId);
    if (scoped) return scoped;
  }
  return bestMatch(rules, hookId, undefined) ?? defaultSeverity;
}

/**
 * Best matching severity within one scope tier.
 *
 * Specificity wins: an exact match beats a glob, and a longer glob beats a
 * shorter one, so `{"plan-mode/*":"off","plan-mode/plan-file-path":"fix"}`
 * re-enables the single rule.
 */
function bestMatch(
  rules: Record<string, Severity>,
  ruleId: string,
  modelId: string | undefined
): Severity | null {
  let best: { score: number; severity: Severity } | null = null;

  for (const [key, severity] of Object.entries(rules)) {
    const { model: keyModel, rule: keyRule } = parseRuleKey(key);
    if (!scopeMatches(keyModel, modelId)) continue;
    if (!globMatches(keyRule, ruleId)) continue;
    const score = specificity(keyRule);
    if (!best || score > best.score) best = { score, severity };
  }

  return best ? best.severity : null;
}

/**
 * Split a config key into its optional model scope and its rule pattern.
 *
 * A `:` only introduces a model scope when it precedes the rule namespace. Rule
 * ids themselves never contain one, but HOOK ids look like `hook:file/rule` —
 * an unanchored split would silently mis-read every hook rule as model-scoped.
 */
function parseRuleKey(key: string): { model?: string; rule: string } {
  const sep = key.indexOf(":");
  if (sep <= 0 || key.startsWith("hook:")) return { rule: key };
  return { model: key.slice(0, sep), rule: key.slice(sep + 1) };
}

/** Scoped keys match only in the scoped pass, unscoped keys only in the unscoped pass. */
function scopeMatches(keyModel: string | undefined, modelId: string | undefined): boolean {
  if (modelId === undefined) return keyModel === undefined;
  return keyModel !== undefined && globMatches(keyModel, modelId);
}

/** Exact beats glob; among globs, more literal characters wins. */
function specificity(pattern: string): number {
  return pattern.includes("*") ? pattern.replace(/\*/g, "").length : Number.MAX_SAFE_INTEGER;
}

/** `*` matches any run of characters, including `/`. Anchored at both ends. */
export function globMatches(pattern: string, value: string): boolean {
  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
  return new RegExp(`^${escaped}$`).test(value);
}

/* ───────────── reporters ───────────── */

/** Pre-hook-system `behavior` keys and what replaced each. */
const BEHAVIOR_MOVES: ReadonlyArray<readonly [string, string]> = [
  ["rules", "behavior.rules → hooks.severity"],
  [
    "hooks",
    "behavior.hooks → hooks.modules (modules must be rewritten to the claudish/hooks contract, apiVersion: 1)",
  ],
  ["observer", "behavior.observer → hooks.observer"],
  [
    "telemetry",
    "behavior.telemetry → hooks.telemetry (consent is NOT carried over: set hooks.telemetry.enabled yourself)",
  ],
  ["preset", "behavior.preset → removed"],
];

let behaviorReported = false;

/**
 * Report a `behavior` block in the global config, once per process.
 *
 * Reported, never migrated: old modules cannot be ported mechanically, so an
 * automatic rewrite would point `hooks.modules` at files that fail the shape
 * check, and copying telemetry consent silently would launder it.
 *
 * @returns true when it printed.
 */
export function reportBehaviorBlock(behavior: unknown, warn: WarnSink = defaultWarn): boolean {
  if (behaviorReported || behavior === undefined || behavior === null) return false;
  behaviorReported = true;
  const keys =
    typeof behavior === "object" && !Array.isArray(behavior)
      ? Object.keys(behavior as Record<string, unknown>)
      : [];
  warn('the "behavior" config block is no longer read. Move it to "hooks":');
  const relevant = BEHAVIOR_MOVES.filter(([key]) => keys.includes(key));
  for (const [, line] of relevant.length > 0 ? relevant : BEHAVIOR_MOVES) warn(`  ${line}`);
  return true;
}

let projectHooksReported = false;

/**
 * Report a `hooks` key in the project `.claudish.json`, once per process.
 *
 * With a `--config` / `CLAUDISH_CONFIG` override the project scope is suppressed
 * entirely, so there is nothing to report.
 *
 * @returns true when it printed.
 */
export function reportProjectHooks(
  projectConfigPath: string = getLocalConfigPath(),
  warn: WarnSink = defaultWarn
): boolean {
  if (projectHooksReported || getConfigFileOverride()) return false;
  try {
    if (!existsSync(projectConfigPath)) return false;
    const parsed = JSON.parse(readFileSync(projectConfigPath, "utf-8")) as unknown;
    if (!parsed || typeof parsed !== "object" || !("hooks" in parsed)) return false;
  } catch {
    // An unreadable or garbled project file is someone else's error to report.
    return false;
  }
  projectHooksReported = true;
  warn(`hooks in ${projectConfigPath} ignored: hooks are read from the global config only`);
  return true;
}

/**
 * Validate a global config's `hooks` block and run every config-load reporter: one
 * line per issue in an invalid `hooks` block (which then counts as `{}`), the
 * `behavior` migration lines, and the project-`hooks`-ignored line, the last two
 * once per process. The launcher's engine and `claudish hooks list` both read the
 * config through here, so they report the same things.
 */
export function readHooksConfig(
  raw: { hooks?: unknown; behavior?: unknown },
  warn: WarnSink = defaultWarn
): HooksConfig {
  const config = parseHooksConfig(raw.hooks, warn);
  reportBehaviorBlock(raw.behavior, warn);
  reportProjectHooks(undefined, warn);
  return config;
}

/** Test seam: let both reporters print again. */
export function resetConfigReportersForTests(): void {
  behaviorReported = false;
  projectHooksReported = false;
}