Skip to content

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

4.1 KB
Raw Blame
/**
 * Built-in hook `observer/divergence`: the local advisory observer.
 *
 * A small LOCAL model (hooks/observer/client.ts) is asked whether a tool call
 * the model just made violates one of claudish's conformance rules. It sees a
 * digest — tool names, harness facts, the call's argument keys and path-like
 * values — never conversation text. Its verdict lands in the divergence log
 * (`~/.claudish/behavior-divergences.jsonl`), the input for rules that do not
 * exist yet.
 *
 * An observe-mode `toolCall` hook: it never holds the stream and can only warn,
 * so turning the observer on no longer suppresses incremental delivery of
 * `Write` content, as the behavior layer's buffering did. The consultation is
 * fire-and-forget: the handler returns at once, and the observer keeps its own
 * timeout (`hooks.observer.timeoutMs`), so a slow local model never counts as a
 * hook timeout.
 *
 * Off unless `hooks.observer.enabled` is true and the mode is not `off`.
 * `enforce` is rejected by the config schema: the observer is advisory.
 */

import { log } from "../../logger.js";
import type { HooksConfig } from "../config.js";
import { observe } from "../observer/client.js";
import { buildDigest } from "../observer/digest.js";
import { recordLiveDivergence } from "../observer/live-log.js";
import type { ToolCallAction, ToolCallContext } from "../public.js";
import type { BuiltinHook } from "../registry.js";

export const OBSERVER_HOOK_ID = "observer/divergence";

/** Watched when `hooks.observer.watchTools` is not set (unchanged from the behavior layer). */
export const DEFAULT_WATCH_TOOLS: ReadonlyArray<string> = [
  "Write",
  "Edit",
  "NotebookEdit",
  "ExitPlanMode",
];

/** True when the config turns the observer on. */
export function observerEnabled(config: Pick<HooksConfig, "observer">): boolean {
  return config.observer?.enabled === true && (config.observer.mode ?? "suggest") !== "off";
}

/** Ask the observer about one delivered call. Advisory only: never throws, never awaited by the seam. */
async function consult(
  config: Pick<HooksConfig, "observer">,
  ruleVocabulary: ReadonlyArray<string>,
  ctx: ToolCallContext
): Promise<void> {
  try {
    const digest = buildDigest({
      model: ctx.route.modelId,
      toolNames: ctx.request.tools.map((t) => t.name),
      harness: { ...ctx.harness },
      ruleVocabulary: [...ruleVocabulary],
      call: { name: ctx.tool.name, args: { ...ctx.tool.args } },
    });
    const verdict = await observe(digest, config);
    if (!verdict?.ruleId) return;
    log(
      `[hooks:observer] flagged ${ctx.tool.name} as ${verdict.ruleId} ` +
        `(confidence ${verdict.confidence})${verdict.note ? `: ${verdict.note}` : ""}`
    );
    await recordLiveDivergence({
      source: "observer",
      ts: new Date().toISOString(),
      model: ctx.route.modelId,
      toolName: ctx.tool.name,
      ruleId: verdict.ruleId,
      confidence: verdict.confidence,
      note: verdict.note,
      paths: digest.proposedCall?.paths,
    });
  } catch (err) {
    log(`[hooks:observer] consult failed: ${err}`);
  }
}

/**
 * The observer built-in for one config. `ruleVocabulary` is the rule ids the
 * observer may name (every other built-in's id); anything else it returns is a
 * hallucination and is discarded.
 */
export function createObserverHook(
  config: Pick<HooksConfig, "observer">,
  ruleVocabulary: ReadonlyArray<string>
): BuiltinHook {
  return {
    apiVersion: 1,
    id: OBSERVER_HOOK_ID,
    description:
      "Ask a small local model whether a delivered tool call breaks a conformance rule; " +
      "log its verdict. Advisory, off by default (hooks.observer).",
    defaultSeverity: "fix",
    // The measured divergences are foreign models'; native Claude honours
    // Claude Code's conventions itself.
    routes: "foreign",
    on: {
      toolCall: {
        tools: config.observer?.watchTools ?? DEFAULT_WATCH_TOOLS,
        observe: true,
        armed: () => observerEnabled(config),
        handle(ctx: ToolCallContext): ToolCallAction[] {
          void consult(config, ruleVocabulary, ctx);
          return [];
        },
      },
    },
  };
}