Skip to content

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

feat(hooks)!: replace claudish behavior with claudish hooks

Jack Rudenko42bc36ccdf8d
diff --git a/packages/cli/src/behavior-command.ts b/packages/cli/src/behavior-command.ts
deleted file mode 100644
index 6aa19316..00000000
--- a/packages/cli/src/behavior-command.ts
+++ /dev/null
@@ -1,264 +0,0 @@
-/**
- * `claudish behavior` — inspect the Layer 4 behavior compatibility layer.
- *
- * Two actions, both read-only by default:
- *
- * claudish behavior rules what is active, and at what severity
- * claudish behavior corpus [--write] replay recorded transcripts for divergences
- *
- * `rules` exists because the layer is otherwise invisible: a user who edits
- * `behavior.rules` in config has no way to tell whether their glob matched, or
- * whether a rule is off because it is gated to foreign models. `corpus` exists
- * because the divergence data is what any NEW rule should be written from —
- * without a way to run it, "look at the evidence first" is not actionable advice.
- */
-
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import {
- BUILTIN_RULES,
- buildCorpus,
- outboxPath,
- parseBehaviorConfig,
- resolveSeverity,
-} from "./behavior/index.js";
-import { getConfigPath, loadConfig } from "./profile-config.js";
-import { cliAnsi } from "./theme/ansi.js";
-
-// Theme-aware color helpers. cliAnsi() is resolved inside each helper (i.e. at
-// render time), never at module load — theme detection runs at CLI startup,
-// after this module is imported.
-const green = (s: string) => {
- const a = cliAnsi();
- return `${a.GREEN}${s}${a.RESET}`;
-};
-const yellow = (s: string) => {
- const a = cliAnsi();
- return `${a.YELLOW}${s}${a.RESET}`;
-};
-const dim = (s: string) => {
- const a = cliAnsi();
- return `${a.DIM}${s}${a.RESET}`;
-};
-const bold = (s: string) => {
- const a = cliAnsi();
- return `${a.BOLD}${s}${a.RESET}`;
-};
-
-function severityColor(sev: string): string {
- if (sev === "fix") return green(sev);
- if (sev === "warn") return yellow(sev);
- return dim(sev);
-}
-
-function showRules(json: boolean): void {
- const config = parseBehaviorConfig(loadConfig().behavior);
- const rows = BUILTIN_RULES.map((rule) => ({
- id: rule.id,
- severity: resolveSeverity(rule.id, rule.defaultSeverity, config),
- defaultSeverity: rule.defaultSeverity,
- intercepts: rule.interceptsTools ?? [],
- description: rule.description,
- }));
-
- if (json) {
- console.log(JSON.stringify({ rules: rows, observer: config.observer ?? null }, null, 2));
- return;
- }
-
- console.log(bold("\nBehavior rules\n"));
- for (const r of rows) {
- const overridden =
- r.severity !== r.defaultSeverity ? dim(` (default ${r.defaultSeverity})`) : "";
- console.log(` ${severityColor(r.severity).padEnd(18)} ${r.id}${overridden}`);
- console.log(` ${dim(r.description)}`);
- if (r.intercepts.length > 0) {
- console.log(` ${dim(`repairs: ${r.intercepts.join(", ")}`)}`);
- }
- console.log();
- }
-
- // Rules only run for foreign models — say so, or an all-Claude user will
- // reasonably conclude the layer is broken when nothing ever fires.
- console.log(dim(" Rules are inactive for native Claude models by design.\n"));
-
- const obs = config.observer;
- const obsState = obs?.enabled ? (obs.mode ?? "suggest") : "off";
- console.log(` observer: ${obsState === "off" ? dim("off") : green(obsState)}`);
- if (obs?.model) console.log(` ${dim(`observer model: ${obs.model}`)}`);
- console.log();
-}
-
-/** Per-model breakdown — the actionable part: it says WHICH models need a rule. */
-function printByModel(records: { model?: string; outcome: string }[]): void {
- const byModel = new Map<string, { ok: number; degraded: number }>();
- for (const r of records) {
- const m = r.model ?? "unknown";
- const e = byModel.get(m) ?? { ok: 0, degraded: 0 };
- if (r.outcome === "degraded") e.degraded++;
- else e.ok++;
- byModel.set(m, e);
- }
- if (byModel.size === 0) return;
-
- console.log(bold(" by model (degraded / ok)\n"));
- const ranked = [...byModel.entries()].sort(
- (a, b) => b[1].degraded - a[1].degraded || b[1].ok - a[1].ok
- );
- for (const [model, v] of ranked) {
- const flag = v.degraded > 0 ? yellow(String(v.degraded)) : dim(String(v.degraded));
- console.log(` ${model.padEnd(26)} ${flag} / ${v.ok}`);
- }
- console.log();
-}
-
-function showCorpus(write: boolean, json: boolean): void {
- const result = buildCorpus({ write });
-
- if (json) {
- console.log(JSON.stringify(result, null, 2));
- return;
- }
-
- const degraded = result.records.filter((r) => r.outcome === "degraded");
- const ok = result.records.filter((r) => r.outcome === "ok");
- const catchable = degraded.filter((r) => r.observedPaths.length > 0);
-
- console.log(bold("\nBehavior divergence corpus\n"));
- console.log(` transcripts scanned : ${result.scanned}`);
- console.log(` plan-exit records : ${result.records.length}`);
- console.log(` ${green("plan found")} : ${ok.length}`);
- console.log(` ${yellow("degraded (no plan)")} : ${degraded.length}`);
- console.log(` of those, a rule would have fired on ${catchable.length}\n`);
-
- printByModel(result.records);
-
- if (result.outputPath) {
- console.log(dim(` appended to ${result.outputPath}\n`));
- } else if (write) {
- console.log(dim(" nothing to write (no records found)\n"));
- } else {
- console.log(dim(" pass --write to append these records to the divergence log\n"));
- }
-}
-
-/**
- * Flip `behavior.telemetry.enabled` in the global config, preserving every other
- * key byte-for-byte.
- *
- * Reads and writes the file directly rather than going through
- * `saveConfig(loadConfig())`: `loadConfig` merges through an ALLOW-LIST, so any
- * key it does not enumerate — a hand-added setting, a field from a newer
- * claudish — would be dropped on save. Toggling one boolean must not be able to
- * damage the rest of a user's config.
- */
-function setTelemetryEnabled(value: boolean): void {
- const path = getConfigPath();
- let cfg: Record<string, unknown> = {};
- try {
- if (existsSync(path)) {
- const parsed = JSON.parse(readFileSync(path, "utf-8")) as unknown;
- if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
- cfg = parsed as Record<string, unknown>;
- }
- }
- } catch {
- // Garbled file → start from empty rather than crash. Matches readRawConfig.
- }
-
- const behavior =
- cfg.behavior && typeof cfg.behavior === "object" && !Array.isArray(cfg.behavior)
- ? { ...(cfg.behavior as Record<string, unknown>) }
- : {};
- behavior.telemetry = { enabled: value };
- cfg.behavior = behavior;
-
- writeFileSync(path, `${JSON.stringify(cfg, null, 2)}\n`, "utf-8");
-}
-
-/**
- * Show — and change — the behaviour-telemetry opt-in.
- *
- * A consent flag reachable only by hand-editing config is not a consent flag, so
- * this is the surface that makes it one. It states the retention period and the
- * never-send list up front, because consent to something unstated is not consent.
- */
-function showTelemetry(action: "status" | "enable" | "disable", json: boolean): void {
- if (action !== "status") {
- // RAW read-modify-write, deliberately NOT saveConfig(loadConfig()).
- // `loadConfig` is an allow-list that copies known keys and silently drops
- // everything else, so saving what it returns would delete any key it does
- // not know about. Same reasoning as onepassword-config.ts's mutateConfig.
- setTelemetryEnabled(action === "enable");
- }
-
- const config = parseBehaviorConfig(loadConfig().behavior);
- const on = config.telemetry?.enabled === true;
-
- // Reported so "I turned it on and nothing happened" has an answer. Reports are
- // spooled at exit and delivered by a LATER run, so a non-zero count here is
- // normal rather than a symptom.
- let pending = 0;
- try {
- const path = outboxPath();
- if (existsSync(path)) {
- pending = readFileSync(path, "utf8").split("\n").filter(Boolean).length;
- }
- } catch {
- // Unreadable outbox is not worth failing a status command over.
- }
-
- if (json) {
- console.log(JSON.stringify({ enabled: on, pendingReports: pending }, null, 2));
- return;
- }
-
- console.log(bold("\nBehavior telemetry\n"));
- console.log(` status : ${on ? green("enabled") : dim("disabled")}`);
- console.log(` pending : ${pending} session report(s) awaiting delivery\n`);
-
- if (!on) {
- console.log(" Opting in shares which models violate Claude Code conventions,");
- console.log(" so rules can be written for models we cannot test ourselves.\n");
- console.log(dim(" Sent : model, provider, rule id, tool name, decision counts,"));
- console.log(dim(" a coarse context bucket, and categorical path relations"));
- console.log(dim(" Never : file paths, argument values, prompts, code, model output,"));
- console.log(dim(" credentials, or repo/branch/project names"));
- console.log(dim(" Session : identified by a salted hash, unlinkable across sessions"));
- console.log(dim(" Kept : 12 months, then non-identifying weekly aggregates only\n"));
- console.log(` Enable with ${bold("claudish behavior telemetry --enable")}\n`);
- return;
- }
-
- console.log(dim(" Local journalling is always on and unaffected by this setting.\n"));
- console.log(` Disable with ${bold("claudish behavior telemetry --disable")}\n`);
-}
-
-export async function behaviorCommand(argv: string[]): Promise<void> {
- const json = argv.includes("--json");
- const write = argv.includes("--write");
- const action = argv.find((a) => !a.startsWith("-")) ?? "rules";
-
- switch (action) {
- case "rules":
- showRules(json);
- return;
- case "corpus":
- showCorpus(write, json);
- return;
- case "telemetry":
- showTelemetry(
- argv.includes("--enable") ? "enable" : argv.includes("--disable") ? "disable" : "status",
- json
- );
- return;
- default:
- console.error(`Unknown action "${action}".
-
-Usage:
- claudish behavior rules [--json]
- claudish behavior corpus [--write] [--json]
- claudish behavior telemetry [--enable | --disable] [--json]
-`);
- process.exit(1);
- }
-}
diff --git a/packages/cli/src/behavior/config.test.ts b/packages/cli/src/behavior/config.test.ts
deleted file mode 100644
index 48c24782..00000000
--- a/packages/cli/src/behavior/config.test.ts
+++ /dev/null
@@ -1,183 +0,0 @@
-import { describe, expect, it } from "bun:test";
-import { parseBehaviorConfig, resolveSeverity } from "./config.js";
-
-describe("parseBehaviorConfig", () => {
- it("degrades invalid config to an empty object without throwing", () => {
- let parsed: ReturnType<typeof parseBehaviorConfig> | undefined;
-
- expect(() => {
- parsed = parseBehaviorConfig({
- rules: { "plan-mode/plan-file-path": "rewrite-everything" },
- observer: { timeoutMs: -1 },
- });
- }).not.toThrow();
- expect(parsed).toEqual({});
- });
-});
-
-describe("resolveSeverity", () => {
- it("prefers an exact rule id over a matching glob", () => {
- expect(
- resolveSeverity("plan-mode/plan-file-path", "warn", {
- rules: {
- "plan-mode/*": "off",
- "plan-mode/plan-file-path": "fix",
- },
- })
- ).toBe("fix");
- });
-
- it("uses the longest matching glob", () => {
- expect(
- resolveSeverity("plan-mode/plan-file-path", "warn", {
- rules: {
- "*": "off",
- "plan-*": "warn",
- "plan-mode/plan-*": "fix",
- },
- })
- ).toBe("fix");
- });
-
- it("allows a specific rule to be re-enabled inside a disabled namespace", () => {
- const config = {
- rules: {
- "plan-mode/*": "off" as const,
- "plan-mode/plan-file-path": "fix" as const,
- },
- };
-
- expect(resolveSeverity("plan-mode/other-rule", "warn", config)).toBe("off");
- expect(resolveSeverity("plan-mode/plan-file-path", "warn", config)).toBe("fix");
- });
-
- it("falls back to the rule's default severity when unconfigured", () => {
- expect(resolveSeverity("plan-mode/plan-file-path", "fix", {})).toBe("fix");
- expect(
- resolveSeverity("plan-mode/plan-file-path", "warn", {
- rules: { "other-namespace/*": "off" },
- })
- ).toBe("warn");
- });
-
- it("uses an unscoped key when no model-scoped key matches", () => {
- expect(
- resolveSeverity(
- "plan-mode/plan-file-path",
- "warn",
- {
- rules: {
- "plan-mode/plan-file-path": "fix",
- "other-model:plan-mode/plan-file-path": "off",
- },
- },
- "gpt-5.6-sol"
- )
- ).toBe("fix");
- });
-
- it("lets a matching model-scoped key beat an unscoped key", () => {
- expect(
- resolveSeverity(
- "plan-mode/plan-file-path",
- "warn",
- {
- rules: {
- "plan-mode/plan-file-path": "off",
- "gpt-5.6-sol:plan-mode/plan-file-path": "fix",
- },
- },
- "gpt-5.6-sol"
- )
- ).toBe("fix");
- });
-
- it("does not apply a model-scoped key to a different model", () => {
- expect(
- resolveSeverity(
- "plan-mode/plan-file-path",
- "warn",
- {
- rules: {
- "plan-mode/plan-file-path": "warn",
- "gpt-5.6-sol:plan-mode/plan-file-path": "fix",
- },
- },
- "gpt-5.6-codex"
- )
- ).toBe("warn");
- });
-
- it("matches model globs", () => {
- expect(
- resolveSeverity(
- "plan-mode/plan-file-path",
- "warn",
- { rules: { "gpt-5.6-*:plan-mode/plan-file-path": "fix" } },
- "gpt-5.6-sol"
- )
- ).toBe("fix");
- });
-
- it("prefers an exact rule id over a rule glob in both scope tiers", () => {
- const unscoped = {
- rules: {
- "plan-mode/*": "off" as const,
- "plan-mode/plan-file-path": "fix" as const,
- },
- };
- const scoped = {
- rules: {
- "gpt-5.6-*:plan-mode/*": "off" as const,
- "gpt-5.6-*:plan-mode/plan-file-path": "fix" as const,
- },
- };
-
- expect(resolveSeverity("plan-mode/plan-file-path", "warn", unscoped, "gpt-5.6-sol")).toBe(
- "fix"
- );
- expect(resolveSeverity("plan-mode/plan-file-path", "warn", scoped, "gpt-5.6-sol")).toBe("fix");
- });
-
- it("prefers the longer rule glob in both scope tiers", () => {
- const unscoped = {
- rules: {
- "plan-*": "off" as const,
- "plan-mode/plan-*": "fix" as const,
- },
- };
- const scoped = {
- rules: {
- "gpt-5.6-*:plan-*": "off" as const,
- "gpt-5.6-*:plan-mode/plan-*": "fix" as const,
- },
- };
-
- expect(resolveSeverity("plan-mode/plan-file-path", "warn", unscoped, "gpt-5.6-sol")).toBe(
- "fix"
- );
- expect(resolveSeverity("plan-mode/plan-file-path", "warn", scoped, "gpt-5.6-sol")).toBe("fix");
- });
-
- it("does not mis-parse a hook rule id as a model scope", () => {
- expect(
- resolveSeverity(
- "hook:my-file/my-rule",
- "warn",
- { rules: { "hook:my-file/my-rule": "fix" } },
- "gpt-5.6-sol"
- )
- ).toBe("fix");
- });
-
- it("uses unscoped-only behavior when modelId is omitted", () => {
- expect(
- resolveSeverity("plan-mode/plan-file-path", "off", {
- rules: {
- "plan-mode/plan-file-path": "warn",
- "gpt-5.6-sol:plan-mode/plan-file-path": "fix",
- },
- })
- ).toBe("warn");
- });
-});
diff --git a/packages/cli/src/behavior/config.ts b/packages/cli/src/behavior/config.ts
deleted file mode 100644
index cbff9751..00000000
--- a/packages/cli/src/behavior/config.ts
+++ /dev/null
@@ -1,141 +0,0 @@
-/**
- * Behavior-layer configuration: schema, loading, and severity resolution.
- *
- * 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 (see the note at the top of config-schema.ts). Same rule as
- * custom endpoints: validate at the point of consumption, warn and fall back
- * rather than throwing, so a malformed `behavior` block can never stop claudish
- * from starting.
- */
-
-import { z } from "zod";
-import { logStderr } from "../logger.js";
-import type { BehaviorConfig, Severity } from "./types.js";
-
-const SeveritySchema = z.enum(["off", "warn", "fix"]);
-
-export const BehaviorConfigSchema = z.object({
- preset: z.string().optional(),
- // Separate from `stats.enabled` on purpose — see the note on BehaviorConfig.
- telemetry: z.object({ enabled: z.boolean().optional() }).optional(),
- rules: z.record(z.string(), SeveritySchema).optional(),
- hooks: z.array(z.string()).optional(),
- observer: z
- .object({
- enabled: z.boolean().optional(),
- // "enforce" is deliberately NOT accepted — see the note on BehaviorConfig.
- // Rejecting it is better than accepting it and quietly behaving as
- // "suggest": a user who asks for enforcement should 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(),
-});
-
-/**
- * Parse a raw `behavior` config value. Invalid input warns once and degrades to
- * an empty config (every rule at its own default) rather than failing the run.
- */
-export function parseBehaviorConfig(raw: unknown): BehaviorConfig {
- if (raw === undefined || raw === null) return {};
- const result = BehaviorConfigSchema.safeParse(raw);
- if (!result.success) {
- logStderr(
- `[behavior] Ignoring invalid "behavior" config: ${result.error.issues
- .map((i) => `${i.path.join(".")}: ${i.message}`)
- .join("; ")}`
- );
- return {};
- }
- return result.data;
-}
-
-/**
- * Resolve the effective severity for a rule.
- *
- * Precedence: exact id → longest matching glob → the rule's own default. Longest
- * glob wins so a user can broadly disable a namespace and re-enable one member:
- *
- * { "plan-mode/*": "off", "plan-mode/plan-file-path": "fix" }
- */
-export function resolveSeverity(
- ruleId: string,
- defaultSeverity: Severity,
- config: BehaviorConfig,
- modelId?: string
-): Severity {
- const rules = config.rules;
- 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, ruleId, modelId);
- if (scoped) return scoped;
- }
- return bestMatch(rules, ruleId, 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. */
-function globMatches(pattern: string, value: string): boolean {
- const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*");
- return new RegExp(`^${escaped}$`).test(value);
-}
diff --git a/packages/cli/src/behavior/engine.test.ts b/packages/cli/src/behavior/engine.test.ts
deleted file mode 100644
index dc724b5e..00000000
--- a/packages/cli/src/behavior/engine.test.ts
+++ /dev/null
@@ -1,283 +0,0 @@
-import { describe, expect, it } from "bun:test";
-import { BehaviorEngine } from "./engine.js";
-import { planFilePathRule } from "./rules/plan-mode.js";
-import type { BehaviorRule } from "./types.js";
-
-function makeRule(overrides: Partial<BehaviorRule> & Pick<BehaviorRule, "id">): BehaviorRule {
- return {
- description: overrides.id,
- defaultSeverity: "fix",
- appliesTo: () => true,
- ...overrides,
- };
-}
-
-function startSession(engine: BehaviorEngine, isNativeAnthropic = false) {
- return engine.startSession({
- modelId: "gpt-5.6-codex",
- providerName: "openai-codex",
- isNativeAnthropic,
- });
-}
-
-function planRequest(path: string): any {
- return {
- system: `Plan mode is active. You should create your plan at ${path}`,
- messages: [],
- };
-}
-
-describe("BehaviorEngine rule isolation", () => {
- it("returns a no-op session for native Anthropic models", () => {
- const rule = makeRule({ id: "test/native-noop" });
- const session = startSession(new BehaviorEngine({}, [rule]), true);
-
- expect(session.isNoop).toBe(true);
- expect(session.interceptsTool("Write")).toBe(false);
- });
-
- it("isolates an appliesTo exception and still runs another rule", () => {
- const broken = makeRule({
- id: "test/broken-applies",
- appliesTo: () => {
- throw new Error("appliesTo exploded");
- },
- });
- const healthy = makeRule({
- id: "test/healthy-applies",
- onRequest: () => [{ type: "injectSystemNote", text: "healthy rule ran" }],
- });
- const session = startSession(new BehaviorEngine({}, [broken, healthy]));
- const request = { system: "base", messages: [] };
-
- expect(() => session.applyRequest(request, [], [], [])).not.toThrow();
- expect(request.system).toBe("base\n\nhealthy rule ran");
- });
-
- it("isolates an onRequest exception and still runs another rule", () => {
- const broken = makeRule({
- id: "test/broken-request",
- onRequest: () => {
- throw new Error("onRequest exploded");
- },
- });
- const healthy = makeRule({
- id: "test/healthy-request",
- onRequest: () => [{ type: "injectSystemNote", text: "healthy rule ran" }],
- });
- const session = startSession(new BehaviorEngine({}, [broken, healthy]));
- const request = { system: "base", messages: [] };
-
- expect(() => session.applyRequest(request, [], [], [])).not.toThrow();
- expect(request.system).toBe("base\n\nhealthy rule ran");
- });
-
- it("isolates an onToolCall exception and still applies another repair", () => {
- const broken = makeRule({
- id: "test/broken-tool-call",
- interceptsTools: ["Write"],
- onToolCall: () => {
- throw new Error("onToolCall exploded");
- },
- });
- const healthy = makeRule({
- id: "test/healthy-tool-call",
- interceptsTools: ["Write"],
- onToolCall: (ctx) => [
- {
- type: "repairToolArgs",
- args: { ...ctx.args, file_path: "/tmp/repaired.md" },
- reason: "test repair",
- },
- ],
- });
- const session = startSession(new BehaviorEngine({}, [broken, healthy]));
- session.applyRequest({ messages: [] }, [], [], []);
-
- const repaired = session.repairToolCall(
- "Write",
- JSON.stringify({ file_path: "/tmp/original.md", content: "plan" })
- );
-
- expect(repaired).not.toBeNull();
- expect(JSON.parse(repaired!)).toEqual({ file_path: "/tmp/repaired.md", content: "plan" });
- });
-});
-
-describe("BehaviorSession request actions", () => {
- it("warn severity leaves request data untouched while fix severity mutates it", () => {
- const rule = makeRule({
- id: "test/rewrite-description",
- onRequest: () => [
- { type: "rewriteToolDescription", tool: "ExitPlanMode", append: " [assigned path]" },
- ],
- });
-
- const warnClaudeTools = [{ name: "ExitPlanMode", description: "original" }];
- const warnTools = [
- { type: "function", function: { name: "ExitPlanMode", description: "converted" } },
- ];
- const warnSession = startSession(
- new BehaviorEngine({ rules: { "test/rewrite-description": "warn" } }, [rule])
- );
- warnSession.applyRequest({ messages: [] }, warnClaudeTools, warnTools, []);
-
- expect(warnClaudeTools[0].description).toBe("original");
- expect(warnTools[0].function.description).toBe("converted");
-
- const fixClaudeTools = [{ name: "ExitPlanMode", description: "original" }];
- const fixTools = [
- { type: "function", function: { name: "ExitPlanMode", description: "converted" } },
- ];
- const fixSession = startSession(new BehaviorEngine({}, [rule]));
- fixSession.applyRequest({ messages: [] }, fixClaudeTools, fixTools, []);
-
- expect(fixClaudeTools[0].description).toBe("original [assigned path]");
- expect(fixTools[0].function.description).toBe("converted [assigned path]");
- });
-
- it("rewrites both Claude-format and converted tool descriptions", () => {
- const rule = makeRule({
- id: "test/both-tool-formats",
- onRequest: () => [
- { type: "rewriteToolDescription", tool: "TargetTool", append: " appended" },
- ],
- });
- const claudeTools = [
- { name: "TargetTool", description: "claude" },
- { name: "OtherTool", description: "other" },
- ];
- const tools = [
- { type: "function", function: { name: "TargetTool", description: "converted" } },
- { type: "function", function: { name: "OtherTool", description: "other" } },
- ];
-
- startSession(new BehaviorEngine({}, [rule])).applyRequest(
- { messages: [] },
- claudeTools,
- tools,
- []
- );
-
- expect(claudeTools.map((tool) => tool.description)).toEqual(["claude appended", "other"]);
- expect(tools.map((tool) => tool.function.description)).toEqual(["converted appended", "other"]);
- });
-
- it("appends a system note to a string system prompt", () => {
- const rule = makeRule({
- id: "test/string-system-note",
- onRequest: () => [{ type: "injectSystemNote", text: "important note" }],
- });
- const request = { system: "existing system", messages: [] };
-
- startSession(new BehaviorEngine({}, [rule])).applyRequest(request, [], [], []);
-
- expect(request.system).toBe("existing system\n\nimportant note");
- });
-
- it("appends a text block to an array system prompt", () => {
- const rule = makeRule({
- id: "test/array-system-note",
- onRequest: () => [{ type: "injectSystemNote", text: "important note" }],
- });
- const request = {
- system: [{ type: "text", text: "existing system" }],
- messages: [],
- };
-
- startSession(new BehaviorEngine({}, [rule])).applyRequest(request, [], [], []);
-
- expect(request.system).toEqual([
- { type: "text", text: "existing system" },
- { type: "text", text: "important note" },
- ]);
- });
-
- it("creates a system prompt when none was present", () => {
- const rule = makeRule({
- id: "test/absent-system-note",
- onRequest: () => [{ type: "injectSystemNote", text: "important note" }],
- });
- const request: any = { messages: [] };
-
- startSession(new BehaviorEngine({}, [rule])).applyRequest(request, [], [], []);
-
- expect(request.system).toBe("important note");
- });
-});
-
-describe("BehaviorSession tool interception", () => {
- const armingRule = makeRule({
- id: "test/arming",
- interceptsTools: ["Write"],
- armed: (facts) => facts.planModeActive,
- });
-
- it("arms buffering only after request inspection, for an armed fix rule", () => {
- const beforeRequest = startSession(new BehaviorEngine({}, [armingRule]));
- expect(beforeRequest.interceptsTool("Write")).toBe(false);
-
- const outsidePlanMode = startSession(new BehaviorEngine({}, [armingRule]));
- outsidePlanMode.applyRequest({ system: "ordinary request", messages: [] }, [], [], []);
- expect(outsidePlanMode.interceptsTool("Write")).toBe(false);
-
- const armedFalse = makeRule({
- ...armingRule,
- id: "test/arming-false",
- armed: () => false,
- });
- const explicitlyUnarmed = startSession(new BehaviorEngine({}, [armedFalse]));
- explicitlyUnarmed.applyRequest(planRequest("/tmp/plans/assigned.md"), [], [], []);
- expect(explicitlyUnarmed.interceptsTool("Write")).toBe(false);
-
- const armedFix = startSession(new BehaviorEngine({}, [armingRule]));
- armedFix.applyRequest(planRequest("/tmp/plans/assigned.md"), [], [], []);
- expect(armedFix.interceptsTool("Write")).toBe(true);
-
- const warnOnly = startSession(
- new BehaviorEngine({ rules: { "test/arming": "warn" } }, [armingRule])
- );
- warnOnly.applyRequest(planRequest("/tmp/plans/assigned.md"), [], [], []);
- expect(warnOnly.interceptsTool("Write")).toBe(false);
- });
-
- it("keeps harness facts independent across concurrent sessions", () => {
- const engine = new BehaviorEngine({}, [planFilePathRule]);
- const first = startSession(engine);
- const second = startSession(engine);
- const firstPath = "/tmp/session-one-plans/assigned-one.md";
- const secondPath = "/tmp/session-two-plans/assigned-two.md";
-
- first.applyRequest(planRequest(firstPath), [], [], []);
- second.applyRequest(planRequest(secondPath), [], [], []);
-
- const firstRepair = first.repairToolCall(
- "Write",
- JSON.stringify({ file_path: "/tmp/session-one-plans/invented.md" })
- );
- const secondRepair = second.repairToolCall(
- "Write",
- JSON.stringify({ file_path: "/tmp/session-two-plans/invented.md" })
- );
-
- expect(first.harness.planFilePath).toBe(firstPath);
- expect(second.harness.planFilePath).toBe(secondPath);
- expect(JSON.parse(firstRepair!).file_path).toBe(firstPath);
- expect(JSON.parse(secondRepair!).file_path).toBe(secondPath);
- });
-
- it("returns null for malformed JSON and when no rule changes the arguments", () => {
- const passiveRule = makeRule({
- id: "test/passive-tool-call",
- interceptsTools: ["Write"],
- onToolCall: () => [],
- });
- const session = startSession(new BehaviorEngine({}, [passiveRule]));
- session.applyRequest({ messages: [] }, [], [], []);
-
- expect(session.repairToolCall("Write", "{not valid json")).toBeNull();
- expect(
- session.repairToolCall("Write", JSON.stringify({ file_path: "/tmp/file.md" }))
- ).toBeNull();
- });
-});
diff --git a/packages/cli/src/behavior/engine.ts b/packages/cli/src/behavior/engine.ts
deleted file mode 100644
index aa0c7b8c..00000000
--- a/packages/cli/src/behavior/engine.ts
+++ /dev/null
@@ -1,645 +0,0 @@
-/**
- * Behavior rule engine.
- *
- * Rules return actions; the engine applies them. Nothing else in the layer is
- * allowed to mutate the request, which is what makes severity levels meaningful
- * and every change traceable to a rule id.
- *
- * CONCURRENCY: ComposedHandler is cached per model and can serve overlapping
- * requests, so per-request state (detected harness facts, the active rule set)
- * lives on a BehaviorSession created by `startSession()` — never on the engine.
- * The stream-parser closure captures its own session, so two in-flight requests
- * cannot read each other's plan file path.
- */
-
-import { detectHarnessFacts, extractAvailableSkills, extractSessionId } from "../hooks/harness.js";
-import {
- type Decision,
- type Surface,
- classifyPath,
- isUploadDecision,
- isUploadSurface,
- recordDecision,
-} from "../hooks/journal.js";
-import {
- recordTelemetryDecision,
- recordTelemetryTurn,
- setTelemetryConsent,
-} from "../hooks/telemetry/aggregate.js";
-import { log } from "../logger.js";
-import { resolveSeverity } from "./config.js";
-import type {
- BehaviorConfig,
- BehaviorContext,
- BehaviorRule,
- HarnessFacts,
- ModelOutputContext,
- RuleAction,
- Severity,
-} from "./types.js";
-
-/**
- * Caps on per-turn observation. A long turn can emit megabytes; holding all of
- * it to run rules at the end is a bad trade for a diagnostic feature.
- */
-const MAX_OBSERVED_CHARS = 64 * 1024;
-const MAX_OBSERVED_TOOLS = 200;
-
-/** The slice of BehaviorEngine a session needs for cross-turn state. */
-interface CorrectionStore {
- queueCorrection(key: string, text: string): void;
- drainCorrections(key: string): string[];
-}
-
-interface ActiveRule {
- rule: BehaviorRule;
- severity: Severity;
-}
-
-/** Per-request state. Created by BehaviorEngine.startSession(). */
-export class BehaviorSession {
- private facts: HarnessFacts = { planModeActive: false };
- /**
- * Populated only once the request has been inspected. Empty until then, so a
- * request that never calls applyRequest buffers nothing.
- */
- private bufferedTools = new Set<string>();
-
- /** Accumulated assistant output for the current turn. */
- private textBuf = "";
- private reasoningBuf = "";
- private toolsCalled: string[] = [];
- /** Claude Code session id — stable across turns, the key for cross-turn state. */
- private sessionId?: string;
- /** System prompt text for this request (CLAUDE.md, user rules, skill listing). */
- private systemText = "";
-
- /** True when any active rule actually inspects model output. */
- private get watchesOutput(): boolean {
- return this.active.some((a) => typeof a.rule.onModelOutput === "function");
- }
-
- constructor(
- private readonly active: ActiveRule[],
- private readonly modelId: string,
- private readonly providerName: string,
- private readonly config: BehaviorConfig = {},
- /** Owns cross-turn state; a session is per-request and cannot hold it. */
- private readonly engine: CorrectionStore = { queueCorrection() {}, drainCorrections: () => [] }
- ) {}
-
- /** True when the observer should be consulted on this run. */
- private get observerOn(): boolean {
- return (
- this.config.observer?.enabled === true && (this.config.observer.mode ?? "suggest") !== "off"
- );
- }
-
- /**
- * Tools the observer watches when enabled.
- *
- * The observer exists to find divergences the RULES do not yet encode, so it
- * cannot be limited to tools a rule already intercepts — that would only ever
- * show it calls that are already handled. Buffering these costs incremental
- * delivery, which is why the observer is opt-in and off by default.
- */
- private observerWatchList(): string[] {
- return this.config.observer?.watchTools ?? ["Write", "Edit", "NotebookEdit", "ExitPlanMode"];
- }
-
- /**
- * Decide which tools need buffering, now that harness state is known.
- *
- * Two gates, both necessary. A rule at `warn` cannot apply a repair, so
- * buffering for it would be pure cost; and a rule that is not armed for this
- * request (e.g. a plan-mode rule outside plan mode) cannot fire at all. The
- * net effect is that ordinary sessions stream tool arguments incrementally
- * exactly as they did before this layer existed.
- */
- private armBuffering(): void {
- const armed = new Set<string>();
- for (const { rule, severity } of this.active) {
- if (severity !== "fix") continue;
- if (rule.armed && !rule.armed(this.facts)) continue;
- for (const t of rule.interceptsTools ?? []) armed.add(t);
- }
- // The observer needs to SEE calls to say anything about them, and the only
- // hook that carries a completed call is the repair seam.
- if (this.observerOn) {
- for (const t of this.observerWatchList()) armed.add(t);
- }
- this.bufferedTools = armed;
- }
-
- get harness(): HarnessFacts {
- return this.facts;
- }
-
- /** True when no rule is active — lets callers skip work entirely. */
- get isNoop(): boolean {
- return this.active.length === 0;
- }
-
- /**
- * Run request-time rules. Called from the middleware `beforeRequest` hook,
- * which the pipeline guarantees runs before `buildPayload`.
- */
- applyRequest(claudeRequest: any, claudeTools: any[], tools: any[], messages: any[]): void {
- if (this.active.length === 0) return;
-
- this.facts = detectHarnessFacts(claudeRequest);
- this.sessionId = extractSessionId(claudeRequest);
- this.systemText =
- typeof claudeRequest?.system === "string"
- ? claudeRequest.system
- : String(claudeRequest?.system ?? "");
- this.facts.sessionId = this.sessionId;
- this.facts.skills = extractAvailableSkills(this.systemText);
- this.armBuffering();
-
- // Apply anything an output rule queued at the end of a PREVIOUS turn of this
- // same Claude Code session. Keyed by the session id Claude Code sends, so
- // two concurrent conversations against the same model cannot cross over.
- if (this.sessionId) {
- for (const text of this.engine.drainCorrections(this.sessionId)) {
- this.applyAction(
- "behavior/pending-correction",
- "fix",
- { type: "injectSystemNote", text },
- {
- modelId: this.modelId,
- providerName: this.providerName,
- isNativeAnthropic: false,
- claudeRequest,
- claudeTools,
- tools,
- messages,
- systemText: this.systemText,
- harness: this.facts,
- }
- );
- }
- }
-
- const ctx: BehaviorContext = {
- modelId: this.modelId,
- providerName: this.providerName,
- isNativeAnthropic: false,
- claudeRequest,
- claudeTools,
- tools,
- messages,
- systemText: this.systemText,
- harness: this.facts,
- };
-
- for (const { rule, severity } of this.active) {
- if (!rule.onRequest) continue;
- let actions: RuleAction[] = [];
- try {
- actions = rule.onRequest(ctx) ?? [];
- } catch (err) {
- // A broken rule degrades to no-op. It must never fail the user's request.
- log(`[behavior] rule ${rule.id} onRequest threw: ${err}`);
- continue;
- }
- for (const action of actions) this.applyAction(rule.id, severity, action, ctx);
- }
- }
-
- /** Whether this tool's arguments must be buffered so a repair can land. */
- interceptsTool(toolName: string): boolean {
- return this.bufferedTools.has(toolName);
- }
-
- /**
- * Note that a turn finished on the wire, with the context size it ran at.
- *
- * Separate from `finishTurn()`, which runs output RULES and only fires when a
- * rule watches output. This runs on every turn, because a session where no
- * rule ever fired is the denominator every violation-rate question needs — a
- * rule that fires twice means nothing without knowing whether it saw 3 turns
- * or 300.
- *
- * Counts only; the token figure never leaves as anything finer than a bucket.
- */
- noteTurnComplete(inputTokens?: number): void {
- recordTelemetryTurn({
- sessionId: this.sessionId,
- model: this.modelId,
- provider: this.providerName,
- inputTokens,
- });
- }
-
- /**
- * Accumulate assistant output as it streams.
- *
- * Bounded: a long turn can emit megabytes, and holding all of it to run a
- * regex at the end is a poor trade. The cap keeps the head, because the
- * claims worth catching ("I've verified…", "tests pass") are overwhelmingly
- * stated up front rather than buried after 200KB of code.
- */
- observeText(text: string, kind: "text" | "reasoning" = "text"): void {
- if (!this.watchesOutput || !text) return;
- const buf = kind === "reasoning" ? this.reasoningBuf : this.textBuf;
- if (buf.length >= MAX_OBSERVED_CHARS) return;
- if (kind === "reasoning") this.reasoningBuf += text;
- else this.textBuf += text;
- }
-
- /** Record a tool call by name, so output rules can see what the turn actually did. */
- observeToolCall(toolName: string): void {
- if (!this.watchesOutput) return;
- if (this.toolsCalled.length < MAX_OBSERVED_TOOLS) this.toolsCalled.push(toolName);
- }
-
- /**
- * Run output rules. Called once the response stream has completed.
- *
- * The turn is already on the wire, so nothing here can change it — actions are
- * recorded, and `injectSystemNote` is held for the NEXT request instead.
- */
- finishTurn(): void {
- if (!this.watchesOutput) return;
- const ctx: ModelOutputContext = {
- modelId: this.modelId,
- providerName: this.providerName,
- text: this.textBuf,
- reasoning: this.reasoningBuf,
- toolsCalled: this.toolsCalled,
- harness: this.facts,
- };
-
- for (const { rule, severity } of this.active) {
- if (!rule.onModelOutput) continue;
- let actions: RuleAction[] = [];
- try {
- actions = rule.onModelOutput(ctx) ?? [];
- } catch (err) {
- log(`[behavior] rule ${rule.id} onModelOutput threw: ${err}`);
- continue;
- }
- for (const action of actions) {
- if (action.type === "warn") {
- log(`[behavior] ${rule.id} (output): ${action.message}`);
- this.journal("model_output", "warned", { ruleId: rule.id, note: action.message });
- continue;
- }
- if (action.type !== "injectSystemNote") continue;
- if (severity !== "fix") {
- this.journal("model_output", "warned", { ruleId: rule.id, note: "correction withheld" });
- continue;
- }
- // Carried into the next request rather than applied now — the response
- // this rule reacted to has already reached the client. Stored on the
- // engine under the Claude Code session id, because THIS session object
- // is destroyed when the request completes.
- if (this.sessionId) this.engine.queueCorrection(this.sessionId, action.text);
- this.journal("model_output", "matched", { ruleId: rule.id, note: "correction queued" });
- log(`[behavior] ${rule.id} queued a correction for the next request`);
- }
- }
-
- this.textBuf = "";
- this.reasoningBuf = "";
- this.toolsCalled = [];
- }
-
- /**
- * Offer a completed tool call to the rules.
- *
- * @returns replacement argument JSON, or null to leave the call untouched.
- */
- repairToolCall(toolName: string, rawArgs: string): string | null {
- if (!this.bufferedTools.has(toolName)) return null;
-
- let args: Record<string, any> = {};
- try {
- const parsed = JSON.parse(rawArgs || "{}");
- if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) args = parsed;
- } catch {
- // Malformed JSON is the recovery layer's problem, not ours. Leave it be.
- return null;
- }
-
- let changed = false;
- for (const { rule, severity } of this.active) {
- if (!rule.onToolCall) continue;
- if (!(rule.interceptsTools ?? []).includes(toolName)) continue;
-
- let actions: RuleAction[] = [];
- try {
- actions =
- rule.onToolCall({
- modelId: this.modelId,
- toolName,
- args,
- rawArgs,
- harness: this.facts,
- }) ?? [];
- } catch (err) {
- log(`[behavior] rule ${rule.id} onToolCall threw: ${err}`);
- continue;
- }
-
- for (const action of actions) {
- if (action.type === "warn") {
- log(`[behavior] ${rule.id} (warn): ${action.message}`);
- continue;
- }
- if (action.type !== "repairToolArgs") continue;
- if (severity !== "fix") {
- log(`[behavior] ${rule.id} (warn-only, not applied): ${action.reason}`);
- continue;
- }
- // Capture the path relation BEFORE overwriting args — afterwards the
- // observed value is gone and the classification cannot be reconstructed.
- this.journal("tool_call", "repaired", {
- ruleId: rule.id,
- toolName,
- argKeys: Object.keys(args),
- observedPath: typeof args.file_path === "string" ? args.file_path : undefined,
- expectedPath: this.facts.planFilePath,
- note: action.reason,
- });
- args = action.args;
- changed = true;
- // Deliberately log-file only, not stderr: claudish shares stdio with the
- // Claude Code TUI and stray stderr writes corrupt its rendering.
- log(`[behavior] ${rule.id} repaired ${toolName}: ${action.reason}`);
- }
- }
-
- // A call that reached a rule and was left alone is still a decision, and the
- // dream session needs the negatives as much as the positives — a rule that
- // never fires looks identical to a rule that is not needed without them.
- if (!changed) {
- this.journal("tool_call", "ignored", {
- toolName,
- argKeys: Object.keys(args),
- observedPath: typeof args.file_path === "string" ? args.file_path : undefined,
- expectedPath: this.facts.planFilePath,
- });
- }
-
- // Ask the observer about calls the deterministic rules did NOT change —
- // those are the candidates for rules that do not exist yet.
- //
- // Fire-and-forget by necessity: this method is called synchronously from the
- // stream parsers, which use its return value immediately. An advisory model
- // must never sit between the model and the client, so its verdict lands in
- // the divergence log rather than in this turn.
- if (this.observerOn && !changed) {
- void this.consultObserver(toolName, args);
- }
-
- return changed ? JSON.stringify(args) : null;
- }
-
- /**
- * Record one decision. Fire-and-forget — journalling must never sit between
- * the model and the client.
- */
- private journal(
- surface: Surface,
- decision: Decision,
- detail: {
- ruleId?: string;
- toolName?: string;
- argKeys?: string[];
- observedPath?: string;
- expectedPath?: string;
- note?: string;
- }
- ): void {
- const pathRelation = classifyPath(detail.observedPath, detail.expectedPath);
-
- // Same call site as the local journal, so the two can never disagree about
- // what happened. This one only counts — no paths, no values; see
- // telemetry/aggregate.ts. It is a no-op unless telemetry is opted in.
- if (isUploadSurface(surface) && isUploadDecision(decision))
- recordTelemetryDecision({
- sessionId: this.sessionId,
- model: this.modelId,
- provider: this.providerName,
- surface,
- decision,
- ruleId: detail.ruleId,
- toolName: detail.toolName,
- pathRelation,
- });
-
- void recordDecision({
- ts: new Date().toISOString(),
- model: this.modelId,
- provider: this.providerName,
- surface,
- decision,
- ruleId: detail.ruleId,
- toolName: detail.toolName,
- argKeys: detail.argKeys,
- pathRelation,
- // Full detail stays local; nothing uploads a journal line.
- local: {
- observedPath: detail.observedPath,
- expectedPath: detail.expectedPath,
- note: detail.note,
- },
- });
- }
-
- /** Advisory only. Never awaited, never throws into the request path. */
- private async consultObserver(toolName: string, args: Record<string, any>): Promise<void> {
- try {
- const { buildDigest } = await import("../hooks/observer/digest.js");
- const { observe } = await import("../hooks/observer/client.js");
- const { recordLiveDivergence } = await import("../hooks/observer/live-log.js");
-
- const digest = buildDigest({
- model: this.modelId,
- toolNames: [...this.bufferedTools],
- harness: this.facts,
- ruleVocabulary: this.active.map((a) => a.rule.id),
- call: { name: toolName, args },
- });
-
- const verdict = await observe(digest, this.config);
- if (!verdict?.ruleId) return; // nothing to report
-
- log(
- `[behavior:observer] flagged ${toolName} as ${verdict.ruleId} ` +
- `(confidence ${verdict.confidence})${verdict.note ? `: ${verdict.note}` : ""}`
- );
- await recordLiveDivergence({
- source: "observer",
- ts: new Date().toISOString(),
- model: this.modelId,
- toolName,
- ruleId: verdict.ruleId,
- confidence: verdict.confidence,
- note: verdict.note,
- paths: digest.proposedCall?.paths,
- });
- } catch (err) {
- log(`[behavior:observer] consult failed: ${err}`);
- }
- }
-
- private applyAction(
- ruleId: string,
- severity: Severity,
- action: RuleAction,
- ctx: BehaviorContext
- ): void {
- if (action.type === "warn") {
- log(`[behavior] ${ruleId} (warn): ${action.message}`);
- return;
- }
- if (severity !== "fix") {
- log(`[behavior] ${ruleId} (warn-only, not applied): ${action.type}`);
- return;
- }
-
- switch (action.type) {
- case "injectSystemNote": {
- const req = ctx.claudeRequest;
- if (typeof req.system === "string") {
- req.system = `${req.system}\n\n${action.text}`;
- } else if (Array.isArray(req.system)) {
- req.system.push({ type: "text", text: action.text });
- } else {
- req.system = action.text;
- }
- log(`[behavior] ${ruleId} injected system note (${action.text.length} chars)`);
- break;
- }
- case "rewriteToolDescription": {
- // Applied to BOTH representations. The converted array is what the
- // Chat Completions payload aliases and what Codex's buildPayload reads
- // when it rebuilds each tool; claudeTools is what any later
- // re-conversion would read. Updating one alone silently misses a path.
- let hits = 0;
- for (const t of ctx.claudeTools) {
- if (t?.name !== action.tool) continue;
- t.description = `${t.description ?? ""}${action.append}`;
- hits++;
- }
- for (const t of ctx.tools) {
- const fn = t?.function ?? t;
- if (fn?.name !== action.tool) continue;
- fn.description = `${fn.description ?? ""}${action.append}`;
- hits++;
- }
- log(`[behavior] ${ruleId} rewrote description of ${action.tool} (${hits} site(s))`);
- break;
- }
- case "repairToolArgs":
- // Only meaningful inside repairToolCall(); ignored at request time.
- log(`[behavior] ${ruleId} returned repairToolArgs from onRequest — ignored`);
- break;
- }
- }
-}
-
-/**
- * Corrections queued by one turn and applied to the next.
- *
- * These CANNOT live on the session: a session is per-request, so anything an
- * output rule queues at the end of turn N is destroyed before turn N+1 is built.
- * They also cannot live per-model, because two concurrent conversations against
- * the same model would leak corrections into each other.
- *
- * So they are keyed by a conversation fingerprint — see `conversationKey()`.
- * Bounded, because a long-running proxy would otherwise accumulate one entry per
- * conversation it has ever seen.
- */
-const MAX_TRACKED_CONVERSATIONS = 64;
-
-export class BehaviorEngine {
- private readonly corrections = new Map<string, string[]>();
-
- constructor(
- private readonly config: BehaviorConfig,
- private readonly rules: BehaviorRule[]
- ) {
- // The engine owns the parsed config, so consent is pushed to the collector
- // from here rather than re-read on the request path.
- const optedIn = config.telemetry?.enabled === true;
- setTelemetryConsent(optedIn);
-
- // Deliver anything a PREVIOUS session spooled at exit. Done here, in the
- // background of a live process, because shutdown is synchronous and cannot
- // await a POST. Never awaited, never allowed to throw.
- if (optedIn) {
- void import("../hooks/telemetry/upload.js")
- .then((m) => m.drainOutbox())
- .catch((err) => log(`[behavior:telemetry] drain unavailable: ${err}`));
- }
- }
-
- /** Queue a correction for the next request in this conversation. */
- queueCorrection(key: string, text: string): void {
- const list = this.corrections.get(key) ?? [];
- list.push(text);
- this.corrections.set(key, list);
- // Evict oldest — Map preserves insertion order.
- while (this.corrections.size > MAX_TRACKED_CONVERSATIONS) {
- const oldest = this.corrections.keys().next().value;
- if (oldest === undefined) break;
- this.corrections.delete(oldest);
- }
- }
-
- /** Drain corrections for a conversation. */
- drainCorrections(key: string): string[] {
- const list = this.corrections.get(key) ?? [];
- this.corrections.delete(key);
- return list;
- }
-
- /**
- * Build the per-request session.
- *
- * Rules are gated here, once, so the hot paths (`interceptsTool`, called per
- * tool call) are set lookups rather than repeated predicate evaluation.
- */
- startSession(params: {
- modelId: string;
- providerName: string;
- isNativeAnthropic: boolean;
- }): BehaviorSession {
- const active: ActiveRule[] = [];
-
- // Native Claude models already follow Claude Code's conventions — the whole
- // layer stays off for them so a no-op layer is genuinely a no-op.
- if (!params.isNativeAnthropic) {
- for (const rule of this.rules) {
- const severity = resolveSeverity(
- rule.id,
- rule.defaultSeverity,
- this.config,
- params.modelId
- );
- if (severity === "off") continue;
- let applies = false;
- try {
- applies = rule.appliesTo(params);
- } catch (err) {
- log(`[behavior] rule ${rule.id} appliesTo threw: ${err}`);
- continue;
- }
- if (applies) active.push({ rule, severity });
- }
- }
-
- if (active.length > 0) {
- log(
- `[behavior] ${active.length} rule(s) active for ${params.modelId}: ` +
- active.map((a) => `${a.rule.id}=${a.severity}`).join(", ")
- );
- }
-
- return new BehaviorSession(active, params.modelId, params.providerName, this.config, this);
- }
-}
diff --git a/packages/cli/src/behavior/hooks.test.ts b/packages/cli/src/behavior/hooks.test.ts
deleted file mode 100644
index 7491b263..00000000
--- a/packages/cli/src/behavior/hooks.test.ts
+++ /dev/null
@@ -1,127 +0,0 @@
-import { describe, expect, it } from "bun:test";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { loadHookRules } from "./hooks.js";
-
-async function inTempDir(run: (dir: string) => Promise<void>): Promise<void> {
- const dir = mkdtempSync(join(tmpdir(), "claudish-behavior-hooks-"));
- try {
- await run(dir);
- } finally {
- rmSync(dir, { recursive: true, force: true });
- }
-}
-
-function validHookSource(id: string, description: string, severity?: "off" | "warn" | "fix") {
- const severityLine = severity ? `defaultSeverity: "${severity}",` : "";
- return `
-export default {
- id: ${JSON.stringify(id)},
- description: ${JSON.stringify(description)},
- ${severityLine}
- appliesTo: () => true,
- onRequest: () => [],
-};
-`;
-}
-
-describe("loadHookRules", () => {
- it("returns an empty array for empty or undefined path lists", async () => {
- expect(await loadHookRules([])).toEqual([]);
- expect(await loadHookRules(undefined)).toEqual([]);
- });
-
- it("loads a valid hook and namespaces its id with the filename", async () => {
- await inTempDir(async (dir) => {
- const path = join(dir, "valid-hook.ts");
- writeFileSync(path, validHookSource("custom-rule", "valid rule", "fix"));
-
- const rules = await loadHookRules([path]);
-
- expect(rules).toHaveLength(1);
- expect(rules[0].id).toBe("hook:valid-hook/custom-rule");
- expect(rules[0].description).toBe("valid rule");
- expect(rules[0].defaultSeverity).toBe("fix");
- });
- });
-
- it("skips a module that exports no valid rule without throwing", async () => {
- await inTempDir(async (dir) => {
- const path = join(dir, "invalid-hook.ts");
- writeFileSync(path, "export const answer = 42;\n");
-
- let rules: Awaited<ReturnType<typeof loadHookRules>> | undefined;
- await expect(
- (async () => {
- rules = await loadHookRules([path]);
- })()
- ).resolves.toBeUndefined();
- expect(rules).toEqual([]);
- });
- });
-
- it("skips a nonexistent hook path without throwing", async () => {
- await inTempDir(async (dir) => {
- const missing = join(dir, "does-not-exist.ts");
-
- await expect(loadHookRules([missing])).resolves.toEqual([]);
- });
- });
-
- it("continues loading after one hook fails to import", async () => {
- await inTempDir(async (dir) => {
- const broken = join(dir, "broken.ts");
- const valid = join(dir, "healthy.ts");
- writeFileSync(broken, 'throw new Error("broken hook");\n');
- writeFileSync(valid, validHookSource("survivor", "healthy rule", "fix"));
-
- const rules = await loadHookRules([broken, valid]);
-
- expect(rules.map((rule) => rule.id)).toEqual(["hook:healthy/survivor"]);
- });
- });
-
- it("defaults an omitted severity to warn", async () => {
- await inTempDir(async (dir) => {
- const path = join(dir, "safe-default.ts");
- writeFileSync(path, validHookSource("no-severity", "safe default"));
-
- const rules = await loadHookRules([path]);
-
- expect(rules).toHaveLength(1);
- expect(rules[0].defaultSeverity).toBe("warn");
- });
- });
-
- it("keeps the first rule when namespaced ids are duplicated", async () => {
- await inTempDir(async (dir) => {
- const path = join(dir, "duplicates.ts");
- writeFileSync(
- path,
- `
-const first = {
- id: "same-id",
- description: "first",
- defaultSeverity: "fix",
- appliesTo: () => true,
-};
-const second = {
- id: "same-id",
- description: "second",
- defaultSeverity: "off",
- appliesTo: () => true,
-};
-export default [first, second];
-`
- );
-
- const rules = await loadHookRules([path]);
-
- expect(rules).toHaveLength(1);
- expect(rules[0].id).toBe("hook:duplicates/same-id");
- expect(rules[0].description).toBe("first");
- expect(rules[0].defaultSeverity).toBe("fix");
- });
- });
-});
diff --git a/packages/cli/src/behavior/hooks.ts b/packages/cli/src/behavior/hooks.ts
deleted file mode 100644
index 0c6587ed..00000000
--- a/packages/cli/src/behavior/hooks.ts
+++ /dev/null
@@ -1,121 +0,0 @@
-/**
- * User hook loading for the behavior layer.
- *
- * A hook is a plain module that exports one or more BehaviorRule objects. It
- * gets the same engine, the same action vocabulary, and the same per-rule
- * try/catch isolation as a built-in rule — the only difference is where it came
- * from and that its id is namespaced.
- *
- * Everything here is non-fatal by design. A hook that fails to import, exports
- * the wrong shape, or throws on load produces a warning and is skipped. This
- * matches the established posture for op:// sources and startup glob failures:
- * a broken optional extension must never stop claudish from starting, least of
- * all when the user is trying to start it in order to fix that extension.
- */
-
-import { isAbsolute, resolve } from "node:path";
-import { logStderr } from "../logger.js";
-import type { BehaviorRule } from "./types.js";
-
-/** Structural check — a hook module is untrusted input, not a typed import. */
-function isBehaviorRule(value: any): value is BehaviorRule {
- return (
- !!value &&
- typeof value === "object" &&
- typeof value.id === "string" &&
- value.id.length > 0 &&
- typeof value.appliesTo === "function" &&
- (value.onRequest === undefined || typeof value.onRequest === "function") &&
- (value.onToolCall === undefined || typeof value.onToolCall === "function")
- );
-}
-
-/** Accept `default`, `rules`, or any named export that structurally matches. */
-function collectRules(mod: any): BehaviorRule[] {
- const found: BehaviorRule[] = [];
- const consider = (v: any) => {
- if (Array.isArray(v)) v.forEach(consider);
- else if (isBehaviorRule(v)) found.push(v);
- };
- consider(mod?.default);
- consider(mod?.rules);
- for (const [key, value] of Object.entries(mod ?? {})) {
- if (key === "default" || key === "rules") continue;
- consider(value);
- }
- // Same rule object can be reachable via two exports; keep one of each.
- return [...new Set(found)];
-}
-
-function shortName(path: string): string {
- const base = path.split("/").pop() ?? path;
- return base.replace(/\.[cm]?[jt]s$/, "");
-}
-
-/**
- * Load rules from the configured hook paths.
- *
- * @param paths Hook module paths. Relative paths resolve against `cwd`.
- * @param cwd Base for relative resolution (the project directory).
- */
-export async function loadHookRules(
- paths: string[] | undefined,
- cwd: string = process.cwd()
-): Promise<BehaviorRule[]> {
- if (!paths?.length) return [];
-
- const loaded: BehaviorRule[] = [];
- const seen = new Set<string>();
-
- for (const raw of paths) {
- const abs = isAbsolute(raw) ? raw : resolve(cwd, raw);
- const rules = await importHook(abs, raw);
- for (const rule of rules) namespaceInto(rule, abs, seen, loaded);
- }
-
- if (loaded.length > 0) {
- logStderr(
- `[behavior] Loaded ${loaded.length} hook rule(s): ${loaded.map((r) => r.id).join(", ")}`
- );
- }
- return loaded;
-}
-
-/** Import one hook module. Any failure warns and yields no rules. */
-async function importHook(abs: string, raw: string): Promise<BehaviorRule[]> {
- let mod: any;
- try {
- mod = await import(abs);
- } catch (err) {
- logStderr(`[behavior] Skipping hook ${raw}: ${err instanceof Error ? err.message : err}`);
- return [];
- }
- const rules = collectRules(mod);
- if (rules.length === 0) {
- logStderr(`[behavior] Hook ${raw} exported no valid BehaviorRule — skipped`);
- }
- return rules;
-}
-
-function namespaceInto(
- rule: BehaviorRule,
- abs: string,
- seen: Set<string>,
- out: BehaviorRule[]
-): void {
- // Namespaced so a hook can never silently shadow a built-in rule id, and so
- // `behavior.rules` config can target hook rules unambiguously.
- const namespaced = `hook:${shortName(abs)}/${rule.id}`;
- if (seen.has(namespaced)) {
- logStderr(`[behavior] Duplicate hook rule ${namespaced} — keeping the first`);
- return;
- }
- seen.add(namespaced);
- out.push({
- ...rule,
- id: namespaced,
- // A hook author who omits severity gets "warn": user code that silently
- // rewrites tool calls on first install is a bad default. Opt in via config.
- defaultSeverity: rule.defaultSeverity ?? "warn",
- });
-}
diff --git a/packages/cli/src/behavior/index.ts b/packages/cli/src/behavior/index.ts
deleted file mode 100644
index a8c99a8b..00000000
--- a/packages/cli/src/behavior/index.ts
+++ /dev/null
@@ -1,89 +0,0 @@
-/**
- * Layer 4: Behavior Compatibility Layer.
- *
- * Public surface. See types.ts for why this layer exists.
- */
-
-import { loadConfig } from "../profile-config.js";
-import { parseBehaviorConfig } from "./config.js";
-import { BehaviorEngine } from "./engine.js";
-import { PLAN_MODE_RULES } from "./rules/plan-mode.js";
-import { SESSION_CONTEXT_RULES } from "./rules/session-context.js";
-import type { BehaviorRule } from "./types.js";
-
-export { BehaviorEngine, BehaviorSession } from "./engine.js";
-export { parseBehaviorConfig, resolveSeverity } from "./config.js";
-export { detectHarnessFacts } from "../hooks/harness.js";
-export { loadHookRules } from "./hooks.js";
-export { buildDigest } from "../hooks/observer/digest.js";
-export type { ObserverDigest } from "../hooks/observer/digest.js";
-export { observe, resetObserverModelCache } from "../hooks/observer/client.js";
-export type { ObserverVerdict } from "../hooks/observer/client.js";
-export { buildCorpus, replayTranscript } from "../hooks/observer/corpus.js";
-export type { CorpusResult, Divergence } from "../hooks/observer/corpus.js";
-export {
- TELEMETRY_SCHEMA_VERSION,
- contextFillPct,
- contextBucket,
- outboxPath,
- pendingReports,
- recordTelemetryDecision,
- recordTelemetryTurn,
- resetTelemetryState,
- setSessionContextWindow,
- setTelemetryConsent,
- spoolPendingSync,
-} from "../hooks/telemetry/aggregate.js";
-export type { ContextBucket, SessionReport } from "../hooks/telemetry/aggregate.js";
-export { drainOutbox, resetDrainState } from "../hooks/telemetry/upload.js";
-export type {
- BehaviorConfig,
- BehaviorContext,
- BehaviorRule,
- HarnessFacts,
- RuleAction,
- Severity,
- ToolCallContext,
-} from "./types.js";
-
-/** Rules shipped with claudish. User hooks are appended to these at load time. */
-export const BUILTIN_RULES: BehaviorRule[] = [...PLAN_MODE_RULES, ...SESSION_CONTEXT_RULES];
-
-/**
- * Build an engine from a raw config value (the `behavior` key of the merged
- * claudish config). Invalid config degrades to defaults rather than throwing —
- * a behavior layer that can stop claudish from starting is worse than no layer.
- */
-export function createBehaviorEngine(rawConfig: unknown, extraRules: BehaviorRule[] = []) {
- return new BehaviorEngine(parseBehaviorConfig(rawConfig), [...BUILTIN_RULES, ...extraRules]);
-}
-
-let sharedEngine: BehaviorEngine | null = null;
-let hookRules: BehaviorRule[] = [];
-
-/**
- * Process-wide engine. Memoized because the engine is stateless (all per-request
- * state lives on a BehaviorSession) and ComposedHandler is constructed once per
- * model — re-reading and re-validating the config for each one would be waste.
- */
-export function getBehaviorEngine(): BehaviorEngine {
- if (!sharedEngine) {
- sharedEngine = createBehaviorEngine(loadConfig().behavior, hookRules);
- }
- return sharedEngine;
-}
-
-/**
- * Register rules loaded from user hook modules. Must run before the first
- * `getBehaviorEngine()` call; the loader is invoked during startup.
- */
-export function registerHookRules(rules: BehaviorRule[]): void {
- hookRules = [...hookRules, ...rules];
- sharedEngine = null;
-}
-
-/** Test seam: drop the memoized engine so the next call re-reads config. */
-export function resetBehaviorEngine(): void {
- sharedEngine = null;
- hookRules = [];
-}
diff --git a/packages/cli/src/behavior/output-rules.test.ts b/packages/cli/src/behavior/output-rules.test.ts
deleted file mode 100644
index 1949fa8d..00000000
--- a/packages/cli/src/behavior/output-rules.test.ts
+++ /dev/null
@@ -1,221 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it, spyOn } from "bun:test";
-import * as journal from "../hooks/journal.js";
-import * as logger from "../logger.js";
-import type { BehaviorEngine } from "./engine.js";
-import { createBehaviorEngine } from "./index.js";
-import type { BehaviorRule, ModelOutputContext, Severity } from "./types.js";
-
-const SESSION_A = "ce7d9e68-f907-444f-9680-69ec3048ce9c";
-const SESSION_B = "62e11a50-15c1-4863-b880-0a518425db74";
-
-function makeRule(
- id: string,
- onModelOutput?: NonNullable<BehaviorRule["onModelOutput"]>,
- defaultSeverity: Severity = "fix"
-): BehaviorRule {
- return {
- id,
- description: id,
- defaultSeverity,
- appliesTo: () => true,
- onModelOutput,
- };
-}
-
-function requestFor(sessionId: string, system = "base system") {
- const userId = JSON.stringify({
- device_id: "abc123",
- account_uuid: "",
- session_id: sessionId,
- });
- return JSON.parse(
- `{"system":${JSON.stringify(system)},"messages":[],"metadata":{"user_id":${JSON.stringify(userId)}}}`
- );
-}
-
-function startSession(engine: BehaviorEngine) {
- return engine.startSession({
- modelId: "gpt-5.6-sol",
- providerName: "openai-codex",
- isNativeAnthropic: false,
- });
-}
-
-function applyRequest(engine: BehaviorEngine, request: ReturnType<typeof requestFor>) {
- const session = startSession(engine);
- session.applyRequest(request, [], [], []);
- return session;
-}
-
-let journalSpy: ReturnType<typeof spyOn>;
-
-beforeEach(() => {
- // Output decisions are journalled fire-and-forget. Keep this suite entirely
- // inside the test process instead of touching the user's real journal.
- journalSpy = spyOn(journal, "recordDecision").mockResolvedValue(undefined);
-});
-
-afterEach(() => {
- journalSpy.mockRestore();
-});
-
-describe("behavior output rules", () => {
- it("passes accumulated text, reasoning, and tool names in stream order", () => {
- let observed: ModelOutputContext | undefined;
- const rule = makeRule("test/output-context", (ctx) => {
- observed = ctx;
- return [];
- });
- const engine = createBehaviorEngine({}, [rule]);
- const session = applyRequest(engine, requestFor(SESSION_A));
-
- session.observeText("first ");
- session.observeText("thought one; ", "reasoning");
- session.observeToolCall("Write");
- session.observeText("second");
- session.observeText("thought two", "reasoning");
- session.observeToolCall("Edit");
- session.finishTurn();
-
- expect(observed?.text).toBe("first second");
- expect(observed?.reasoning).toBe("thought one; thought two");
- expect(observed?.toolsCalled).toEqual(["Write", "Edit"]);
- });
-
- it("logs a warn action without mutating the current or next request", () => {
- const logSpy = spyOn(logger, "log").mockImplementation(() => {});
- try {
- const rule = makeRule("test/output-warn", () => [
- { type: "warn", message: "model took a shortcut" },
- ]);
- const engine = createBehaviorEngine({}, [rule]);
- const current = requestFor(SESSION_A);
- const session = applyRequest(engine, current);
-
- session.observeText("unverified claim");
- session.finishTurn();
- const next = requestFor(SESSION_A);
- applyRequest(engine, next);
-
- expect(current.system).toBe("base system");
- expect(next.system).toBe("base system");
- expect(logSpy).toHaveBeenCalledWith(
- "[behavior] test/output-warn (output): model took a shortcut"
- );
- expect(journalSpy).toHaveBeenCalled();
- } finally {
- logSpy.mockRestore();
- }
- });
-
- it("injects an output correction on the next request for the same session", () => {
- const correction = "Run the verification before claiming completion.";
- const rule = makeRule("test/cross-turn-correction", () => [
- { type: "injectSystemNote", text: correction },
- ]);
- const engine = createBehaviorEngine({}, [rule]);
- const current = requestFor(SESSION_A, "turn one system");
- const session = applyRequest(engine, current);
-
- session.observeText("This should work.");
- session.finishTurn();
-
- expect(current.system).toBe("turn one system");
- const next = requestFor(SESSION_A, "turn two system");
- applyRequest(engine, next);
- expect(next.system).toBe(`turn two system\n\n${correction}`);
- });
-
- it("does not leak a correction to a different session id", () => {
- const correction = "Session A correction";
- const rule = makeRule("test/session-isolation", () => [
- { type: "injectSystemNote", text: correction },
- ]);
- const engine = createBehaviorEngine({}, [rule]);
- const session = applyRequest(engine, requestFor(SESSION_A));
- session.finishTurn();
-
- const other = requestFor(SESSION_B);
- applyRequest(engine, other);
-
- expect(other.system).toBe("base system");
- });
-
- it("drains a correction after applying it once", () => {
- const correction = "One-shot correction";
- const rule = makeRule("test/drained-correction", () => [
- { type: "injectSystemNote", text: correction },
- ]);
- const engine = createBehaviorEngine({}, [rule]);
- applyRequest(engine, requestFor(SESSION_A)).finishTurn();
-
- const next = requestFor(SESSION_A);
- applyRequest(engine, next);
- const later = requestFor(SESSION_A);
- applyRequest(engine, later);
-
- expect(next.system).toBe(`base system\n\n${correction}`);
- expect(later.system).toBe("base system");
- });
-
- it("does not queue an output correction at warn severity", () => {
- const rule = makeRule("test/warn-correction", () => [
- { type: "injectSystemNote", text: "withheld correction" },
- ]);
- const engine = createBehaviorEngine({ rules: { "test/warn-correction": "warn" } }, [rule]);
- applyRequest(engine, requestFor(SESSION_A)).finishTurn();
-
- const next = requestFor(SESSION_A);
- applyRequest(engine, next);
-
- expect(next.system).toBe("base system");
- });
-
- it("does no output accumulation work when no output rule is active", () => {
- // The built-in plan rule is active for this foreign model, but it has no
- // onModelOutput hook. That distinction is what should disable accumulation.
- const engine = createBehaviorEngine({}, []);
- const session = startSession(engine);
-
- expect(session.isNoop).toBe(false);
- expect(() => {
- session.observeText("x".repeat(2 * 1024 * 1024));
- session.finishTurn();
- }).not.toThrow();
- });
-
- it("isolates an output-rule exception and still runs later rules", () => {
- let healthyRuns = 0;
- const broken = makeRule("test/broken-output", () => {
- throw new Error("output rule exploded");
- });
- const healthy = makeRule("test/healthy-output", () => {
- healthyRuns++;
- return [];
- });
- const engine = createBehaviorEngine({}, [broken, healthy]);
- const request = requestFor(SESSION_A);
- const session = applyRequest(engine, request);
-
- expect(() => session.finishTurn()).not.toThrow();
- expect(healthyRuns).toBe(1);
- expect(request.system).toBe("base system");
- });
-
- it("bounds accumulated text at 64 KB even when the stream emits far more", () => {
- let observedLength = -1;
- const rule = makeRule("test/output-cap", (ctx) => {
- observedLength = ctx.text.length;
- return [];
- });
- const engine = createBehaviorEngine({}, [rule]);
- const session = applyRequest(engine, requestFor(SESSION_A));
- const chunk = "x".repeat(8 * 1024);
-
- expect(() => {
- for (let i = 0; i < 256; i++) session.observeText(chunk);
- session.finishTurn();
- }).not.toThrow();
- expect(observedLength).toBe(64 * 1024);
- });
-});
diff --git a/packages/cli/src/behavior/rules/plan-mode.test.ts b/packages/cli/src/behavior/rules/plan-mode.test.ts
deleted file mode 100644
index dcac7370..00000000
--- a/packages/cli/src/behavior/rules/plan-mode.test.ts
+++ /dev/null
@@ -1,111 +0,0 @@
-import { describe, expect, it } from "bun:test";
-import type { BehaviorContext, ToolCallContext } from "../types.js";
-import { planFilePathRule } from "./plan-mode.js";
-
-const assignedPath = "/workspace/.custom-plans/assigned-session.md";
-const planDir = "/workspace/.custom-plans";
-
-function requestContext(overrides: Partial<BehaviorContext> = {}): BehaviorContext {
- return {
- modelId: "gpt-5.6-codex",
- providerName: "openai-codex",
- isNativeAnthropic: false,
- claudeRequest: { messages: [] },
- claudeTools: [{ name: "ExitPlanMode", description: "Exit plan mode" }],
- tools: [],
- messages: [],
- systemText: "",
- harness: {
- planModeActive: true,
- planFilePath: assignedPath,
- planDir,
- },
- ...overrides,
- };
-}
-
-function toolCallContext(args: Record<string, unknown>): ToolCallContext {
- return {
- modelId: "gpt-5.6-codex",
- toolName: "Write",
- args,
- rawArgs: JSON.stringify(args),
- harness: {
- planModeActive: true,
- planFilePath: assignedPath,
- planDir,
- },
- };
-}
-
-describe("planFilePathRule.onRequest", () => {
- it("returns no actions when plan mode is inactive", () => {
- const ctx = requestContext({ harness: { planModeActive: false } });
-
- expect(planFilePathRule.onRequest!(ctx)).toEqual([]);
- });
-
- it("returns no actions when ExitPlanMode is not offered", () => {
- const ctx = requestContext({
- claudeTools: [{ name: "Write", description: "Write a file" }],
- tools: [{ type: "function", function: { name: "Edit", description: "Edit a file" } }],
- });
-
- expect(planFilePathRule.onRequest!(ctx)).toEqual([]);
- });
-
- it("appends the exact assigned path to the ExitPlanMode description", () => {
- const actions = planFilePathRule.onRequest!(requestContext());
-
- expect(actions).toHaveLength(1);
- expect(actions[0].type).toBe("rewriteToolDescription");
- if (actions[0].type !== "rewriteToolDescription") {
- throw new Error("expected rewriteToolDescription action");
- }
- expect(actions[0].tool).toBe("ExitPlanMode");
- expect(actions[0].append).toContain(
- `Your plan MUST be written to exactly this path:\n${assignedPath}`
- );
- });
-});
-
-describe("planFilePathRule.onToolCall", () => {
- it("redirects an invented filename inside the assigned plan directory", () => {
- const actions = planFilePathRule.onToolCall!(
- toolCallContext({ file_path: `${planDir}/invented-name.md`, content: "# Plan" })
- );
-
- expect(actions).toHaveLength(1);
- expect(actions[0].type).toBe("repairToolArgs");
- if (actions[0].type !== "repairToolArgs") {
- throw new Error("expected repairToolArgs action");
- }
- expect(actions[0].args).toEqual({ file_path: assignedPath, content: "# Plan" });
- });
-
- it("does not touch a normal project file outside the plan directory", () => {
- const actions = planFilePathRule.onToolCall!(
- toolCallContext({ file_path: "/workspace/src/implementation.ts", content: "source" })
- );
-
- expect(actions).toEqual([]);
- });
-
- it("does not touch the already-correct assigned path", () => {
- expect(
- planFilePathRule.onToolCall!(
- toolCallContext({ file_path: assignedPath, content: "# Correct plan" })
- )
- ).toEqual([]);
- });
-
- it("ignores missing and non-string file_path values", () => {
- expect(planFilePathRule.onToolCall!(toolCallContext({ content: "missing" }))).toEqual([]);
- expect(
- planFilePathRule.onToolCall!(toolCallContext({ file_path: 42, content: "number" }))
- ).toEqual([]);
- expect(
- planFilePathRule.onToolCall!(toolCallContext({ file_path: null, content: "null" }))
- ).toEqual([]);
- });
-});
diff --git a/packages/cli/src/behavior/rules/plan-mode.ts b/packages/cli/src/behavior/rules/plan-mode.ts
deleted file mode 100644
index b966497f..00000000
--- a/packages/cli/src/behavior/rules/plan-mode.ts
+++ /dev/null
@@ -1,108 +0,0 @@
-/**
- * Plan-mode conformance rules.
- *
- * Background (measured, not assumed). Claude Code 2.1.220's ExitPlanModeV2 takes
- * NO plan parameter — its advertised schema is `{allowedPrompts?}` and the tool
- * description says outright: "This tool does NOT take the plan content as a
- * parameter - it will read the plan from the file you wrote". CC's
- * `normalizeToolInput` injects `plan` from disk at the session's assigned path.
- *
- * So `ExitPlanMode({})` is CORRECT, and the real failure is upstream: the model
- * writes its plan somewhere else. gpt-5.6-sol produced a complete 12.9 KB plan
- * under a filename it invented; CC read the assigned path, found nothing, and
- * returned `plan: null`. That downgrades the approval dialog from the rich form
- * ("Here is Claude's plan" + `Yes, and bypass permissions` / `Yes, auto-accept
- * edits` / `Yes, manually approve edits`) to a bare "Exit plan mode?" yes/no —
- * and since the rich dialog is the only surface that offers permission
- * elevation on exit, the session always falls back to manual approval.
- *
- * Across 115 recorded ExitPlanMode calls the discriminator was exact: sessions
- * that wrote to the assigned path got the rich dialog 7/7, sessions that did not
- * got the degraded one 17/17. Native Claude models were 87/87 correct, so this
- * rule is scoped to foreign models only.
- */
-
-import type { BehaviorRule } from "../types.js";
-
-/** Tools that can create the plan file, and so can target the wrong path. */
-const WRITE_TOOLS = ["Write", "Edit", "NotebookEdit"];
-
-function directoryOf(filePath: string): string | undefined {
- const slash = filePath.lastIndexOf("/");
- return slash > 0 ? filePath.slice(0, slash) : undefined;
-}
-
-/**
- * Keeps the model's plan writes pointed at the plan file Claude Code actually
- * reads, and restates the path where the model is most likely to look for it.
- */
-export const planFilePathRule: BehaviorRule = {
- id: "plan-mode/plan-file-path",
- description:
- "Keep plan-mode writes on the plan file Claude Code assigned, and name that " +
- "path in the ExitPlanMode description.",
- defaultSeverity: "fix",
- interceptsTools: WRITE_TOOLS,
-
- // Native Claude models are already 87/87 on this; running the rule for them
- // would be pure risk with no upside.
- appliesTo: ({ isNativeAnthropic }) => !isNativeAnthropic,
-
- // Outside plan mode this rule cannot fire, so it must not cause Write/Edit
- // arguments to be buffered — that would suppress incremental streaming of
- // file contents on every ordinary request.
- armed: (facts) => facts.planModeActive === true,
-
- onRequest(ctx) {
- const { planModeActive, planFilePath } = ctx.harness;
- if (!planModeActive || !planFilePath) return [];
-
- // Only speak up if the tool is actually on offer this turn.
- const hasExitPlanMode =
- ctx.claudeTools.some((t: any) => t?.name === "ExitPlanMode") ||
- ctx.tools.some((t: any) => (t?.function ?? t)?.name === "ExitPlanMode");
- if (!hasExitPlanMode) return [];
-
- // The original reminder is a system message that, in the sessions that
- // failed, sat ~180K tokens behind the current turn. A tool description is
- // re-read at the moment the model decides to call the tool, which is exactly
- // when this fact needs to be in front of it.
- return [
- {
- type: "rewriteToolDescription",
- tool: "ExitPlanMode",
- append: `
-
-## Plan file for THIS session
-Your plan MUST be written to exactly this path:
-${planFilePath}
-Do not invent a different filename, and do not derive one from the task. Claude Code reads only that exact path; a plan written anywhere else is invisible to it and the approval will show "No plan found".`,
- },
- ];
- },
-
- onToolCall(ctx) {
- const { planFilePath, planDir } = ctx.harness;
- if (!planFilePath || !planDir) return [];
-
- const filePath = ctx.args.file_path;
- if (typeof filePath !== "string" || filePath === planFilePath) return [];
-
- // Only ever redirect writes that are ALREADY aimed at the plan directory.
- // A model writing source files, docs, or session artifacts elsewhere is
- // doing normal work and must not be touched.
- if (directoryOf(filePath) !== planDir) return [];
-
- return [
- {
- type: "repairToolArgs",
- args: { ...ctx.args, file_path: planFilePath },
- reason:
- `redirected ${ctx.toolName} from ${filePath} to the session's assigned ` +
- `plan file ${planFilePath}`,
- },
- ];
- },
-};
-
-export const PLAN_MODE_RULES: BehaviorRule[] = [planFilePathRule];
diff --git a/packages/cli/src/behavior/rules/session-context.test.ts b/packages/cli/src/behavior/rules/session-context.test.ts
deleted file mode 100644
index e7a09b3f..00000000
--- a/packages/cli/src/behavior/rules/session-context.test.ts
+++ /dev/null
@@ -1,80 +0,0 @@
-import { describe, expect, it } from "bun:test";
-import {
- SESSION_CONTEXT_RULES,
- hasInjectedSessionContext,
- noHarnessEchoRule,
-} from "./session-context.js";
-
-const MARKER = "SessionStart hook additional context";
-
-function requestContext(systemText = "", messages: unknown[] = [], isNativeAnthropic = false) {
- const context = {
- systemText,
- messages,
- modelId: "m",
- providerName: "p",
- isNativeAnthropic,
- };
-
- // biome-ignore lint/suspicious/noExplicitAny: This rule reads only the literal fields above.
- return context as any;
-}
-
-describe("hasInjectedSessionContext", () => {
- it("detects the marker in system text", () => {
- expect(hasInjectedSessionContext(MARKER, [])).toBe(true);
- });
-
- it("detects the marker in the first message's string content", () => {
- expect(hasInjectedSessionContext("", [{ content: MARKER }])).toBe(true);
- });
-
- it("detects the marker in a text content block in the first message", () => {
- const messages = [{ content: [{ type: "text", text: MARKER }] }];
-
- expect(hasInjectedSessionContext("", messages)).toBe(true);
- });
-
- it("returns false for ordinary and empty input", () => {
- expect(hasInjectedSessionContext("You are a helpful assistant.", [])).toBe(false);
- expect(hasInjectedSessionContext("", [])).toBe(false);
- });
-
- it("does not scan later messages", () => {
- // Only messages[0] is scanned so the model's own earlier echo cannot re-arm the rule.
- expect(
- hasInjectedSessionContext("", [
- { content: "An ordinary first message." },
- { content: MARKER },
- ])
- ).toBe(false);
- });
-
- it("matches upper- and lower-case marker variants", () => {
- expect(hasInjectedSessionContext("SESSIONSTART HOOK ADDITIONAL CONTEXT", [])).toBe(true);
- expect(hasInjectedSessionContext("sessionstart hook additional context", [])).toBe(true);
- });
-});
-
-describe("noHarnessEchoRule", () => {
- it("applies only to foreign models", () => {
- expect(noHarnessEchoRule.appliesTo(requestContext("", [], true))).toBe(false);
- expect(noHarnessEchoRule.appliesTo(requestContext("", [], false))).toBe(true);
- });
-
- it("injects exactly one system note when context is present", () => {
- const actions = noHarnessEchoRule.onRequest!(requestContext(MARKER));
-
- expect(actions).toEqual([{ type: "injectSystemNote", text: expect.any(String) }]);
- });
-
- it("returns no actions when context is absent", () => {
- expect(noHarnessEchoRule.onRequest!(requestContext("An ordinary system prompt."))).toEqual([]);
- });
-});
-
-describe("SESSION_CONTEXT_RULES", () => {
- it("contains noHarnessEchoRule", () => {
- expect(SESSION_CONTEXT_RULES).toContain(noHarnessEchoRule);
- });
-});
diff --git a/packages/cli/src/behavior/rules/session-context.ts b/packages/cli/src/behavior/rules/session-context.ts
deleted file mode 100644
index 2f4ffe7d..00000000
--- a/packages/cli/src/behavior/rules/session-context.ts
+++ /dev/null
@@ -1,111 +0,0 @@
-/**
- * Keep Claude Code's own session context OUT of the model's answer.
- *
- * Background (measured, not assumed). A `SessionStart` hook's stdout is NOT
- * written to `claude -p`'s stdout — probed 2026-08-18 against CC 2.1.233 with a
- * hook emitting a sentinel and a one-word prompt: stdout came back as exactly
- * `"banana\n"`, sentinel absent from both stdout and stderr. So hook output
- * reaches the model the only other way it can: as injected context the model
- * READS.
- *
- * Which means a foreign model can decide it is content to reproduce. In team
- * session team-20260815-115227, `response-01.md` (minimax-m3) and
- * `response-04.md` (kimi-k3) both OPEN with the host session's SessionStart
- * output — a "Coaching" block recommending `npx claudeup`, and an "Insight"
- * block — instead of the requested deliverable. The blind judges penalised both
- * in those words: "leaked harness boilerplate in deliverable", "irrelevant
- * coaching preamble violates the requested structure". Two of six models, and
- * it moved their scores.
- *
- * ## Why this is a behaviour rule and not a hermeticity fix
- *
- * The obvious fix — don't give children the host's hooks — has no lever:
- *
- * · Hooks MERGE across settings tiers. Probed 2026-08-18: a project-tier
- * `SessionStart` hook still fired with `--settings '{"hooks":{}}'` layered
- * above it, which is the highest (CLI-args) tier. A settings overlay cannot
- * clear an inherited hook.
- * · `--bare` does skip hooks, but also skips CLAUDE.md auto-discovery, plugin
- * sync and auto-memory, and defers the MCP connection past `system/init`
- * (see CLAUDE.md). Team children need their project context and MCP tools —
- * the grok run in that very session made 6 `mcp__…__search_pattern` calls.
- * · A clean `CLAUDE_CONFIG_DIR` loses the user's MCP servers and plugins for
- * the same reason.
- *
- * So the context is going to arrive. What claudish can change is what the model
- * DOES with it — which is exactly Layer 4's job.
- *
- * Following the layer's design rule ("put the fact where the decision is made"),
- * this states the convention in the system prompt, where the model decides how
- * to open its answer. It is deliberately NOT a post-hoc filter on the response:
- * there is no reliable way to tell "boilerplate the model echoed" from "the
- * user's own words quoted legitimately", and a wrong strip would delete real
- * content from a deliverable.
- */
-
-import type { BehaviorRule } from "../types.js";
-
-/**
- * How Claude Code labels hook-injected context. Taken from CC 2.1.233's own
- * wording; matched case-insensitively and loosely so a phrasing tweak degrades
- * to "rule stands down", never to a false positive on user prose.
- */
-const SESSION_CONTEXT_MARKERS = ["sessionstart hook additional context", "hook additional context"];
-
-/** Does this request actually carry injected session context? */
-export function hasInjectedSessionContext(systemText: string, messages: unknown[]): boolean {
- const haystacks: string[] = [systemText ?? ""];
-
- // CC may place the hook context in the first user turn rather than the system
- // prompt, so check both — but only the FIRST message, because scanning a long
- // conversation would match the model's own earlier echo and re-arm forever.
- const first = Array.isArray(messages) ? messages[0] : undefined;
- if (first && typeof first === "object") {
- const content = (first as { content?: unknown }).content;
- if (typeof content === "string") {
- haystacks.push(content);
- } else if (Array.isArray(content)) {
- for (const block of content) {
- const text = (block as { text?: unknown } | null)?.text;
- if (typeof text === "string") haystacks.push(text);
- }
- }
- }
-
- return haystacks.some((h) => {
- const lower = h.toLowerCase();
- return SESSION_CONTEXT_MARKERS.some((m) => lower.includes(m));
- });
-}
-
-const NOTE =
- "Operational context note. This session may include text injected by the harness " +
- "itself — SessionStart hook output, coaching or insight blocks, tooling banners, " +
- "status lines. That material is addressed to you, not to the user, and it is not " +
- "part of the task. Never reproduce, summarise, or quote it in your answer, and never " +
- "let it open your response. Begin your answer with the requested deliverable and " +
- "nothing before it.";
-
-/**
- * Tells a foreign model that harness-injected session context is operational,
- * not content to be repeated back.
- */
-export const noHarnessEchoRule: BehaviorRule = {
- id: "session-context/no-harness-echo",
- description:
- "Stop foreign models opening their answer with harness-injected session context " +
- "(SessionStart hook output, coaching/insight blocks).",
- defaultSeverity: "fix",
-
- // Native Claude treats this context as operational already; the measured
- // failures were foreign models only, and running it natively would be pure
- // risk against a harness that already behaves.
- appliesTo: ({ isNativeAnthropic }) => !isNativeAnthropic,
-
- onRequest(ctx) {
- if (!hasInjectedSessionContext(ctx.systemText, ctx.messages)) return [];
- return [{ type: "injectSystemNote", text: NOTE }];
- },
-};
-
-export const SESSION_CONTEXT_RULES: BehaviorRule[] = [noHarnessEchoRule];
diff --git a/packages/cli/src/behavior/types.ts b/packages/cli/src/behavior/types.ts
deleted file mode 100644
index e1c9c1b2..00000000
--- a/packages/cli/src/behavior/types.ts
+++ /dev/null
@@ -1,248 +0,0 @@
-/**
- * Layer 4: Behavior Compatibility Layer — core types.
- *
- * Layers 1-3 translate the wire format, the model dialect, and the transport.
- * This layer translates the thing none of those cover: the *behavioral
- * conventions* the agent harness expects. A foreign model can speak the OpenAI
- * wire format perfectly, use every tool correctly, and still break Claude Code
- * because it did not follow an unwritten protocol.
- *
- * The motivating case: CC 2.1.220's ExitPlanModeV2 takes no `plan` parameter —
- * it reads the plan from a file at a CC-assigned path. gpt-5.6-sol wrote a
- * complete plan to a filename it invented instead, so CC found nothing at the
- * assigned path, reported `plan: null`, and degraded the approval dialog to a
- * bare yes/no with no permission-elevation option.
- *
- * Rules never mutate the request themselves. They RETURN actions, and the engine
- * applies them. That keeps every change attributable to a rule id, loggable, and
- * testable without a live request.
- */
-
-/**
- * Linter semantics, deliberately: users already know what these mean.
- * off — rule does not run
- * warn — rule runs, actions are logged but NOT applied
- * fix — rule runs, actions are applied
- */
-export type Severity = "off" | "warn" | "fix";
-
-/**
- * Facts about the harness detected from the incoming request.
- *
- * Extracted once per request by `harness.ts` and shared with every rule, so the
- * fragile business of matching Claude Code's prompt strings lives in exactly one
- * place rather than being copy-pasted into each rule.
- */
-export interface HarnessFacts {
- /** True when the plan-mode system reminder is present in this request. */
- planModeActive: boolean;
- /**
- * The exact plan file path Claude Code assigned to this session.
- *
- * Never inferred from a default directory: CC exposes a `planDir` setting
- * ("Custom directory for plan files, relative to project root"), so assuming
- * ~/.claude/plans would silently break for anyone who set it. If the anchor
- * is absent this stays undefined and dependent rules stand down.
- */
- planFilePath?: string;
- /** Directory portion of `planFilePath`, for "is this write in the plan dir" tests. */
- planDir?: string;
- /** Claude Code session id — stable across turns of one session. */
- sessionId?: string;
- /**
- * Skills Claude Code offered this turn, in listing order.
- *
- * Empty means "no listing found", NOT "the user has no skills" — a rule must
- * not conclude anything from an empty list.
- */
- skills?: ReadonlyArray<AvailableSkill>;
-}
-
-/** A skill Claude Code offered the model. */
-export interface AvailableSkill {
- name: string;
- description: string;
-}
-
-/** Request-time context handed to `onRequest`. All mutable fields are live. */
-export interface BehaviorContext {
- modelId: string;
- providerName: string;
- /** Native Claude models already follow these conventions — rules default off. */
- isNativeAnthropic: boolean;
- /** Normalized Claude-format request. Owns `system`. Mutable. */
- claudeRequest: any;
- /** Claude-format tool definitions (`{name, description, input_schema}`). Mutable. */
- claudeTools: any[];
- /** Converted, target-format tools. Mutable — see the note in engine.applyAction. */
- tools: any[];
- /** Converted, target-format messages. Mutable. */
- messages: any[];
- /**
- * The system prompt as text.
- *
- * Carries CLAUDE.md, the user's project rules, and the skill listing — all of
- * which already arrive on every request. A rule reads this to decide that a
- * skill or a user rule applies, then INJECTS the relevant content rather than
- * instructing the model to go and fetch it.
- */
- systemText: string;
- harness: HarnessFacts;
-}
-
-/**
- * What the model said this turn, handed to `onModelOutput` once the stream ends.
- *
- * Deliberately NORMALIZED text rather than raw stream events: the four parsers
- * deliver four different shapes (a Chat Completions `delta`, a Responses API
- * event, an Anthropic frame, a Gemini part), and making every rule understand
- * all four would guarantee that rules silently work on some providers and not
- * others. Each parser knows its own shape; rules see prose.
- */
-export interface ModelOutputContext {
- modelId: string;
- providerName: string;
- /** Assistant text for the turn, concatenated in order. */
- text: string;
- /** Reasoning/thinking text, where the provider exposes it separately. */
- reasoning: string;
- /** Tool names called during this turn, in order. Lets a rule see "claimed
- * done but never called a test-running tool". */
- toolsCalled: string[];
- harness: HarnessFacts;
-}
-
-/** Tool-call context handed to `onToolCall`, after arguments are fully accumulated. */
-export interface ToolCallContext {
- modelId: string;
- toolName: string;
- /** Parsed arguments. If the model emitted invalid JSON this is `{}`. */
- args: Record<string, any>;
- /** Raw argument JSON exactly as the model produced it. */
- rawArgs: string;
- harness: HarnessFacts;
-}
-
-/**
- * The closed set of things a rule may ask for. Closed on purpose: an open
- * "run this callback" action would make rule effects unauditable, which defeats
- * the point of having severity levels at all.
- */
-export type RuleAction =
- | {
- /** Append a note to the system prompt. Used to restate a convention the
- * model has lost track of under context pressure. */
- type: "injectSystemNote";
- text: string;
- }
- | {
- /** Append to a tool's description. A tool description sits adjacent to the
- * call decision, so it survives context pressure that buries a reminder
- * hundreds of thousands of tokens back. */
- type: "rewriteToolDescription";
- tool: string;
- append: string;
- }
- | {
- /** Replace the arguments of the tool call currently being intercepted. */
- type: "repairToolArgs";
- args: Record<string, any>;
- /** Human-readable reason, logged when applied. */
- reason: string;
- }
- | {
- /** Record a divergence without changing anything. */
- type: "warn";
- message: string;
- };
-
-export interface BehaviorRule {
- /** Stable, namespaced id, e.g. "plan-mode/plan-file-path". Users key config off this. */
- id: string;
- description: string;
- defaultSeverity: Severity;
- /**
- * Tool names whose arguments this rule may rewrite.
- *
- * This drives SELECTIVE BUFFERING in the stream parsers. Repair is only
- * possible if a call's arguments are withheld until it completes, and
- * withholding costs incremental delivery — so it is opt-in per tool, and every
- * tool no rule names keeps streaming exactly as before.
- */
- interceptsTools?: string[];
- /**
- * Whether the rule is live for THIS request, given the detected harness state.
- * Defaults to true when omitted.
- *
- * This is what keeps `interceptsTools` honest. Model/provider gating
- * (`appliesTo`) happens before the request is inspected, so without this a
- * rule that intercepts `Write` would force buffering on every request for
- * every foreign model — turning off incremental delivery of file contents
- * even when the rule could not possibly fire. Arming on harness state means
- * a session outside plan mode buffers nothing and streams exactly as before.
- */
- armed?(facts: HarnessFacts): boolean;
- /** Model/provider gating, evaluated before any hook runs. */
- appliesTo(ctx: { modelId: string; providerName: string; isNativeAnthropic: boolean }): boolean;
- onRequest?(ctx: BehaviorContext): RuleAction[];
- onToolCall?(ctx: ToolCallContext): RuleAction[];
- /**
- * Runs once per turn, after the model's response has been fully streamed.
- *
- * This is where shortcut and rule-violation detection lives — those show up in
- * what the model SAYS ("this should work", "tests would pass") and in what it
- * did NOT do, not in any single tool call's arguments.
- *
- * The response has already reached the client by the time this runs, so it
- * cannot alter the current turn. Emit `warn` to record, or `injectSystemNote`
- * to correct on the NEXT request (see `pendingCorrections`).
- */
- onModelOutput?(ctx: ModelOutputContext): RuleAction[];
-}
-
-/** User-facing config, read from the `behavior` key of ~/.claudish/config.json. */
-export interface BehaviorConfig {
- preset?: string;
- /**
- * Uploading behaviour decisions to claudish's servers for aggregate analysis.
- *
- * Its own opt-in, deliberately NOT sharing the existing `stats.enabled`
- * consent: that was granted for usage statistics, and reusing it to ship
- * behavioural records would be consent laundering. Default off.
- *
- * Local journalling is unaffected by this and always on — it is the user's own
- * data on their own disk, like `logs/`.
- *
- * Only the allow-listed `UploadableEntry` projection is ever sent: model,
- * provider, surface, decision, rule id, tool name, argument KEY names, and a
- * categorical path relation. No paths, no argument values, no message text.
- */
- telemetry?: {
- enabled?: boolean;
- };
- /** Rule id (or glob, e.g. "plan-mode/*") → severity. */
- rules?: Record<string, Severity>;
- /** Paths to user modules exporting BehaviorRule(s). */
- hooks?: string[];
- observer?: {
- enabled?: boolean;
- /**
- * `suggest` logs what it sees to the divergence log.
- *
- * There is deliberately no `enforce`. The tool-call seam the observer hangs
- * off is synchronous — stream parsers consume its return value immediately —
- * so an async model cannot gate a call without putting a network round-trip
- * between the model and the client. Config validation REJECTS `enforce`
- * rather than accepting it and quietly behaving as `suggest`.
- */
- mode?: "off" | "suggest";
- /** Omit to auto-discover a local model. Never defaulted to a pinned id. */
- model?: string;
- timeoutMs?: number;
- /**
- * Tools whose calls the observer is shown. Buffering these costs incremental
- * delivery, which is why the observer is off by default.
- */
- watchTools?: string[];
- };
-}
diff --git a/packages/cli/src/hooks-command.test.ts b/packages/cli/src/hooks-command.test.ts
new file mode 100644
index 00000000..127b4a36
--- /dev/null
+++ b/packages/cli/src/hooks-command.test.ts
@@ -0,0 +1,215 @@
+/**
+ * `claudish hooks list|check|init|telemetry` (§4.9), spawned as the real CLI
+ * entry with a generated HOME and a `CLAUDISH_CONFIG` override, so the
+ * developer's config is never read or written.
+ */
+
+import { afterAll, describe, expect, it } from "bun:test";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const CLI_ROOT = join(import.meta.dir, "..");
+const ENTRY = join(import.meta.dir, "index.ts");
+const root = mkdtempSync(join(tmpdir(), "claudish-hooks-cli-"));
+afterAll(() => rmSync(root, { recursive: true, force: true }));
+
+let seq = 0;
+function sandbox(config: Record<string, unknown>) {
+ const dir = mkdtempSync(join(root, `s${++seq}-`));
+ const configPath = join(dir, "config.json");
+ writeFileSync(configPath, JSON.stringify(config));
+ return { dir, configPath };
+}
+
+function run(args: string[], configPath: string, cwd = CLI_ROOT) {
+ const proc = Bun.spawnSync(["bun", "--no-env-file", ENTRY, "hooks", ...args], {
+ cwd,
+ 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(),
+ };
+}
+
+function writeModule(dir: string, name: string, source: string): string {
+ const path = join(dir, name);
+ writeFileSync(path, source);
+ return path;
+}
+
+describe("claudish hooks list --json", () => {
+ it("prints every hook in effective order, then load errors and the behavior flag", () => {
+ const { dir, configPath } = sandbox({});
+ const good = writeModule(
+ dir,
+ "marker.ts",
+ `export default { apiVersion: 1, id: "add", on: { responseEnd: () => [] } };`
+ );
+ const bad = writeModule(dir, "broken.ts", `export default { apiVersion: 2, id: "x" };`);
+ writeFileSync(
+ configPath,
+ JSON.stringify({
+ hooks: { modules: [good, bad], severity: { "hook:marker/*": "warn" } },
+ behavior: { rules: {} },
+ })
+ );
+
+ const r = run(["list", "--json"], configPath);
+ expect(r.code).toBe(0);
+ const out = JSON.parse(r.stdout);
+ expect(out.apiVersion).toBe(1);
+ expect(out.configFile).toBe(configPath);
+ expect(out.hooks.map((h: any) => h.id)).toEqual([
+ "gemini/thought-signature",
+ "plan-mode/plan-file-path",
+ "session-context/no-harness-echo",
+ "observer/divergence",
+ "hook:marker/add",
+ ]);
+ expect(out.hooks[0]).toEqual({
+ id: "gemini/thought-signature",
+ source: "builtin",
+ events: ["raw.providerRequest", "raw.providerChunk", "raw.providerStreamEnd"],
+ defaultSeverity: "fix",
+ severity: "fix",
+ routes: "all",
+ models: ["*gemini*", "*google/*"],
+ order: "pre",
+ unsafe: true,
+ });
+ expect(out.hooks[1]).toMatchObject({
+ id: "plan-mode/plan-file-path",
+ events: ["request", "toolCall"],
+ routes: "foreign",
+ unsafe: false,
+ });
+ expect(out.hooks[4]).toMatchObject({
+ id: "hook:marker/add",
+ source: "user",
+ defaultSeverity: "fix",
+ severity: "warn",
+ });
+ expect(out.errors).toHaveLength(1);
+ expect(out.errors[0].module).toBe(bad);
+ expect(out.errors[0].reason).toContain("apiVersion 2 is not supported");
+ expect(out.behaviorConfigFound).toBe(true);
+ });
+});
+
+describe("claudish hooks check", () => {
+ it("exits 0 for a valid module", () => {
+ const { dir, configPath } = sandbox({});
+ const path = writeModule(
+ dir,
+ "ok.ts",
+ `export default { apiVersion: 1, id: "ok", on: { request: () => [] } };`
+ );
+ const r = run(["check", path, "--json"], configPath);
+ expect(r.code).toBe(0);
+ const out = JSON.parse(r.stdout);
+ expect(out.valid).toBe(true);
+ expect(out.hooks.map((h: any) => h.id)).toEqual(["hook:ok/ok"]);
+ });
+
+ it("X-3: exits 1 and names the rule for a declared async providerChunk", () => {
+ const { dir, configPath } = sandbox({});
+ const path = writeModule(
+ dir,
+ "twohooks.ts",
+ `export default [
+ { apiVersion: 1, id: "async-one", unsafe: true, raw: { async providerChunk() {} } },
+ { apiVersion: 1, id: "sync-one", unsafe: true, raw: { providerChunk() {} } },
+ ];`
+ );
+ const r = run(["check", path], configPath);
+ expect(r.code).toBe(1);
+ expect(r.stdout).toContain("raw.providerChunk must be synchronous");
+ });
+
+ it("exits 1 for a missing file argument", () => {
+ const { configPath } = sandbox({});
+ expect(run(["check"], configPath).code).toBe(1);
+ });
+});
+
+describe("claudish hooks init", () => {
+ it("writes the example and the ambient types, refuses to overwrite, and the example checks", () => {
+ const { dir, configPath } = sandbox({});
+ const target = join(dir, "hooks");
+ const first = run(["init", target], configPath);
+ expect(first.code).toBe(0);
+ expect(existsSync(join(target, "example-hook.ts"))).toBe(true);
+ const dts = readFileSync(join(target, "claudish-hooks.d.ts"), "utf8");
+ expect(dts).toContain('declare module "claudish/hooks"');
+ expect(dts).toContain("export const HOOK_API_VERSION = 1;");
+
+ const again = run(["init", target], configPath);
+ expect(again.code).toBe(1);
+ expect(again.stderr).toContain("already exists");
+
+ expect(run(["check", join(target, "example-hook.ts")], configPath).code).toBe(0);
+ });
+
+ it("the ambient declaration type-checks the example with nothing installed", () => {
+ const { dir, configPath } = sandbox({});
+ const target = join(dir, "typed");
+ expect(run(["init", target], configPath).code).toBe(0);
+ // A project of its own, with no ambient types at all: only the reference
+ // to claudish-hooks.d.ts can satisfy `import type … from "claudish/hooks"`.
+ writeFileSync(
+ join(target, "tsconfig.json"),
+ JSON.stringify({
+ compilerOptions: {
+ strict: true,
+ noEmit: true,
+ target: "ES2022",
+ module: "ESNext",
+ moduleResolution: "bundler",
+ types: [],
+ },
+ files: ["example-hook.ts"],
+ })
+ );
+ const tsc = join(CLI_ROOT, "node_modules", ".bin", "tsc");
+ const proc = Bun.spawnSync([tsc, "-p", join(target, "tsconfig.json")], { cwd: target });
+ expect(proc.stdout.toString() + proc.stderr.toString()).toBe("");
+ expect(proc.exitCode).toBe(0);
+ });
+});
+
+describe("claudish hooks telemetry", () => {
+ it("--enable writes hooks.telemetry.enabled into the active config and keeps other keys", () => {
+ const { configPath } = sandbox({ defaultProvider: "openrouter", hooks: { modules: [] } });
+ const r = run(["telemetry", "--enable", "--json"], configPath);
+ expect(r.code).toBe(0);
+ expect(JSON.parse(r.stdout).enabled).toBe(true);
+ const saved = JSON.parse(readFileSync(configPath, "utf8"));
+ expect(saved).toEqual({
+ defaultProvider: "openrouter",
+ hooks: { modules: [], telemetry: { enabled: true } },
+ });
+
+ const off = run(["telemetry", "--disable", "--json"], configPath);
+ expect(JSON.parse(off.stdout).enabled).toBe(false);
+ });
+});
+
+describe("generated ambient declaration", () => {
+ it("src/hooks/ambient-dts.generated.ts matches public.ts", () => {
+ const proc = Bun.spawnSync(["bun", "run", "scripts/generate-hooks-dts.ts", "--check"], {
+ cwd: CLI_ROOT,
+ });
+ expect(proc.stderr.toString()).toBe("");
+ expect(proc.exitCode).toBe(0);
+ });
+});
diff --git a/packages/cli/src/hooks-command.ts b/packages/cli/src/hooks-command.ts
new file mode 100644
index 00000000..df739775
--- /dev/null
+++ b/packages/cli/src/hooks-command.ts
@@ -0,0 +1,377 @@
+/**
+ * `claudish hooks` — inspect, check and scaffold hooks.
+ *
+ * claudish hooks list [--json] every hook in effective order, then load errors
+ * claudish hooks check <file> [--json] load one module in isolation and validate it
+ * claudish hooks init [dir] write example-hook.ts + claudish-hooks.d.ts
+ * claudish hooks corpus [--write] [--json] replay recorded transcripts for divergences
+ * claudish hooks telemetry [--enable | --disable] show or change the upload consent
+ *
+ * `list` exists because the hook system is otherwise invisible: a user who edits
+ * `hooks.severity` has no way to tell whether their glob matched, or whether a
+ * built-in is off because it is scoped to foreign routes. It prints the
+ * effective order, which is the order actions are applied in.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { HOOKS_AMBIENT_DTS } from "./hooks/ambient-dts.generated.js";
+import { OBSERVER_HOOK_ID, observerEnabled } from "./hooks/builtins/observer.js";
+import { parseHooksConfig } from "./hooks/config.js";
+import { loadHookSet } from "./hooks/index.js";
+import { loadUserHooks } from "./hooks/loader.js";
+import { buildCorpus } from "./hooks/observer/corpus.js";
+import { HOOK_API_VERSION } from "./hooks/public.js";
+import type { RegisteredHook } from "./hooks/registry.js";
+import { outboxPath } from "./hooks/telemetry/aggregate.js";
+import { activeConfigFile, loadConfig } from "./profile-config.js";
+import { cliAnsi } from "./theme/ansi.js";
+
+// Theme-aware colour helpers. cliAnsi() is resolved inside each helper (at
+// render time), never at module load — theme detection runs at CLI startup,
+// after this module is imported.
+const paint = (code: "GREEN" | "YELLOW" | "DIM" | "BOLD" | "RED") => (s: string) => {
+ const a = cliAnsi();
+ return `${a[code]}${s}${a.RESET}`;
+};
+const green = paint("GREEN");
+const yellow = paint("YELLOW");
+const red = paint("RED");
+const dim = paint("DIM");
+const bold = paint("BOLD");
+
+function severityColor(sev: string): string {
+ if (sev === "fix") return green(sev);
+ if (sev === "warn") return yellow(sev);
+ return dim(sev);
+}
+
+/** A hook as `list --json` and `check --json` print it (§4.9). */
+function hookRow(hook: RegisteredHook, severity: string) {
+ return {
+ id: hook.id,
+ source: hook.source,
+ events: [...hook.events],
+ defaultSeverity: hook.defaultSeverity,
+ severity,
+ routes: hook.routes,
+ models: [...hook.models],
+ order: hook.order,
+ unsafe: hook.unsafe,
+ };
+}
+
+/* ───────────── list ───────────── */
+
+async function list(json: boolean): Promise<number> {
+ // The config-load reporters write to stderr as they do for every claudish run (stdout
+ // stays pure JSON with --json). Per-module warnings are not printed twice: each is in
+ // `errors`, which this command reports.
+ const set = await loadHookSet({ hostMode: "other", moduleWarn: () => {} });
+ const rows = set.registry.hooks.map((h) => hookRow(h, set.registry.severityOf(h)));
+
+ if (json) {
+ console.log(
+ JSON.stringify(
+ {
+ apiVersion: HOOK_API_VERSION,
+ configFile: activeConfigFile(),
+ hooks: rows,
+ errors: set.errors,
+ behaviorConfigFound: set.behaviorConfigFound,
+ },
+ null,
+ 2
+ )
+ );
+ return 0;
+ }
+
+ console.log(bold("\nHooks, in effective order\n"));
+ // A severity says how a hook acts once it runs; the observer also needs its own
+ // switch, so without it a `fix` row would read as active.
+ const observerOff = !observerEnabled(set.config);
+ for (const r of rows) {
+ const overridden =
+ r.severity !== r.defaultSeverity ? dim(` (default ${r.defaultSeverity})`) : "";
+ const unsafe = r.unsafe ? ` ${red("UNSAFE")}` : "";
+ const inactive =
+ r.id === OBSERVER_HOOK_ID && observerOff
+ ? dim(" (inactive: hooks.observer.enabled is off)")
+ : "";
+ console.log(
+ ` ${severityColor(r.severity).padEnd(18)} ${r.id}${overridden}${unsafe}${inactive}`
+ );
+ const scope = [
+ `${r.source}`,
+ `events ${r.events.join(", ")}`,
+ `routes ${r.routes}`,
+ r.models.join(",") !== "*" ? `models ${r.models.join(", ")}` : null,
+ r.order !== "normal" ? `order ${r.order}` : null,
+ ].filter(Boolean);
+ console.log(` ${dim(scope.join(" · "))}\n`);
+ }
+ console.log(dim(` config: ${activeConfigFile()}\n`));
+
+ if (set.errors.length > 0) {
+ console.log(bold("Not loaded\n"));
+ for (const e of set.errors) console.log(` ${yellow(e.module)}\n ${dim(e.reason)}\n`);
+ }
+ if (set.behaviorConfigFound) {
+ console.log(
+ yellow(' A "behavior" block is in the config. It is no longer read: move it to "hooks".\n')
+ );
+ }
+ return 0;
+}
+
+/* ───────────── check ───────────── */
+
+async function check(file: string | undefined, json: boolean): Promise<number> {
+ if (!file) {
+ console.error("Usage: claudish hooks check <file> [--json]");
+ return 1;
+ }
+ const path = resolve(process.cwd(), file);
+ const notes: string[] = [];
+ const loaded = await loadUserHooks({
+ modules: [path],
+ configDir: process.cwd(),
+ hostMode: "other",
+ warn: (line) => notes.push(line),
+ });
+ const valid = loaded.errors.length === 0 && loaded.hooks.length > 0;
+ const hooks = loaded.hooks.map((u) => ({
+ id: u.id,
+ events: Object.keys(u.def.on ?? {})
+ .filter((k) => (u.def.on as Record<string, unknown>)[k] !== undefined)
+ .concat(Object.keys((u.def as { raw?: object }).raw ?? {}).map((k) => `raw.${k}`)),
+ unsafe: (u.def as { unsafe?: boolean }).unsafe === true,
+ }));
+
+ if (json) {
+ console.log(JSON.stringify({ file: path, valid, hooks, errors: loaded.errors }, null, 2));
+ return valid ? 0 : 1;
+ }
+
+ console.log(`\n ${valid ? green("valid") : red("invalid")} ${path}\n`);
+ for (const h of hooks) {
+ console.log(` ${h.id}${h.unsafe ? ` ${red("UNSAFE")}` : ""} ${dim(h.events.join(", "))}`);
+ }
+ if (hooks.length === 0 && loaded.errors.length === 0) {
+ console.log(` ${yellow("the module exports no hook")}`);
+ }
+ for (const e of loaded.errors) console.log(` ${red("✗")} ${e.reason}`);
+ console.log();
+ return valid ? 0 : 1;
+}
+
+/* ───────────── init ───────────── */
+
+const EXAMPLE_HOOK = `/// <reference path="./claudish-hooks.d.ts" />
+/**
+ * An example claudish hook. Add its path to "hooks.modules" in
+ * ~/.claudish/config.json, then run \`claudish hooks list\` to see it.
+ *
+ * Check it with: claudish hooks check example-hook.ts
+ */
+import type { HookDefinition } from "claudish/hooks";
+
+export default {
+ apiVersion: 1,
+ id: "reply-language",
+ description: "Asks foreign models to answer in English",
+ routes: "foreign",
+ on: {
+ request(ctx) {
+ ctx.log(\`request for \${ctx.route.modelId}\`);
+ return [{ type: "injectSystemNote", text: "Always answer in English." }];
+ },
+ },
+} satisfies HookDefinition;
+`;
+
+function init(dirArg: string | undefined): number {
+ const dir = dirArg ? resolve(process.cwd(), dirArg) : join(homedir(), ".claudish", "hooks");
+ const files: Array<[string, string]> = [
+ [join(dir, "example-hook.ts"), EXAMPLE_HOOK],
+ [join(dir, "claudish-hooks.d.ts"), HOOKS_AMBIENT_DTS],
+ ];
+ const existing = files.filter(([path]) => existsSync(path)).map(([path]) => path);
+ if (existing.length > 0) {
+ for (const path of existing) console.error(`${path} already exists; not overwriting it.`);
+ return 1;
+ }
+ mkdirSync(dir, { recursive: true });
+ for (const [path, text] of files) writeFileSync(path, text, { flag: "wx" });
+ console.log(`\n wrote ${files.map(([p]) => p).join("\n wrote ")}\n`);
+ console.log(dim(` Add "${files[0]?.[0]}" to "hooks.modules" in ${activeConfigFile()}.\n`));
+ return 0;
+}
+
+/* ───────────── corpus ───────────── */
+
+/** Per-model breakdown — the actionable part: it says WHICH models need a rule. */
+function printByModel(records: { model?: string; outcome: string }[]): void {
+ const byModel = new Map<string, { ok: number; degraded: number }>();
+ for (const r of records) {
+ const m = r.model ?? "unknown";
+ const e = byModel.get(m) ?? { ok: 0, degraded: 0 };
+ if (r.outcome === "degraded") e.degraded++;
+ else e.ok++;
+ byModel.set(m, e);
+ }
+ if (byModel.size === 0) return;
+
+ console.log(bold(" by model (degraded / ok)\n"));
+ const ranked = [...byModel.entries()].sort(
+ (a, b) => b[1].degraded - a[1].degraded || b[1].ok - a[1].ok
+ );
+ for (const [model, v] of ranked) {
+ const flag = v.degraded > 0 ? yellow(String(v.degraded)) : dim(String(v.degraded));
+ console.log(` ${model.padEnd(26)} ${flag} / ${v.ok}`);
+ }
+ console.log();
+}
+
+function corpus(write: boolean, json: boolean): number {
+ const result = buildCorpus({ write });
+ if (json) {
+ console.log(JSON.stringify(result, null, 2));
+ return 0;
+ }
+
+ const degraded = result.records.filter((r) => r.outcome === "degraded");
+ const ok = result.records.filter((r) => r.outcome === "ok");
+ const catchable = degraded.filter((r) => r.observedPaths.length > 0);
+
+ console.log(bold("\nBehavior divergence corpus\n"));
+ console.log(` transcripts scanned : ${result.scanned}`);
+ console.log(` plan-exit records : ${result.records.length}`);
+ console.log(` ${green("plan found")} : ${ok.length}`);
+ console.log(` ${yellow("degraded (no plan)")} : ${degraded.length}`);
+ console.log(` of those, a hook would have fired on ${catchable.length}\n`);
+
+ printByModel(result.records);
+
+ if (result.outputPath) console.log(dim(` appended to ${result.outputPath}\n`));
+ else if (write) console.log(dim(" nothing to write (no records found)\n"));
+ else console.log(dim(" pass --write to append these records to the divergence log\n"));
+ return 0;
+}
+
+/* ───────────── telemetry ───────────── */
+
+/**
+ * Flip `hooks.telemetry.enabled` in the global config, preserving every other
+ * key byte-for-byte. A RAW read-modify-write, deliberately not
+ * `saveConfig(loadConfig())`: `loadConfig` merges through an allow-list, so any
+ * key it does not enumerate would be dropped on save.
+ */
+function setTelemetryEnabled(value: boolean): void {
+ // The ACTIVE global config: with `--config` / `CLAUDISH_CONFIG` that is the
+ // override, which is also the file `loadConfig` reads back below.
+ const path = activeConfigFile();
+ let cfg: Record<string, unknown> = {};
+ try {
+ if (existsSync(path)) {
+ const parsed = JSON.parse(readFileSync(path, "utf-8")) as unknown;
+ if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+ cfg = parsed as Record<string, unknown>;
+ }
+ }
+ } catch {
+ // Garbled file → start from empty rather than crash. Matches readRawConfig.
+ }
+ const hooks =
+ cfg.hooks && typeof cfg.hooks === "object" && !Array.isArray(cfg.hooks)
+ ? { ...(cfg.hooks as Record<string, unknown>) }
+ : {};
+ hooks.telemetry = { enabled: value };
+ cfg.hooks = hooks;
+ writeFileSync(path, `${JSON.stringify(cfg, null, 2)}\n`, "utf-8");
+}
+
+/**
+ * Show — and change — the behaviour-telemetry opt-in. It states the retention
+ * period and the never-send list up front, because consent to something
+ * unstated is not consent.
+ */
+function telemetry(action: "status" | "enable" | "disable", json: boolean): number {
+ if (action !== "status") setTelemetryEnabled(action === "enable");
+
+ const on = parseHooksConfig(loadConfig().hooks, () => {}).telemetry?.enabled === true;
+ // Reports are spooled at exit and delivered by a LATER run, so a non-zero
+ // count is normal rather than a symptom.
+ let pending = 0;
+ try {
+ const path = outboxPath();
+ if (existsSync(path)) pending = readFileSync(path, "utf8").split("\n").filter(Boolean).length;
+ } catch {
+ // An unreadable outbox is not worth failing a status command over.
+ }
+
+ if (json) {
+ console.log(JSON.stringify({ enabled: on, pendingReports: pending }, null, 2));
+ return 0;
+ }
+
+ console.log(bold("\nBehavior telemetry\n"));
+ console.log(` status : ${on ? green("enabled") : dim("disabled")}`);
+ console.log(` pending : ${pending} session report(s) awaiting delivery\n`);
+
+ if (!on) {
+ console.log(" Opting in shares which models violate Claude Code conventions,");
+ console.log(" so hooks can be written for models we cannot test ourselves.\n");
+ console.log(dim(" Sent : model, provider, built-in hook id, tool name, decision counts,"));
+ console.log(dim(" a coarse context bucket, and categorical path relations"));
+ console.log(dim(" Never : your own hook ids, MCP tool names on their rows, file paths,"));
+ console.log(dim(" argument values, prompts, code, model output, credentials,"));
+ console.log(dim(" or repo/branch/project names"));
+ console.log(dim(" Session : identified by a salted hash, unlinkable across sessions"));
+ console.log(dim(" Kept : 12 months, then non-identifying weekly aggregates only\n"));
+ console.log(` Enable with ${bold("claudish hooks telemetry --enable")}\n`);
+ return 0;
+ }
+
+ console.log(dim(" Local journalling is always on and unaffected by this setting.\n"));
+ console.log(` Disable with ${bold("claudish hooks telemetry --disable")}\n`);
+ return 0;
+}
+
+/* ───────────── dispatch ───────────── */
+
+const USAGE = `Usage:
+ claudish hooks list [--json]
+ claudish hooks check <file> [--json]
+ claudish hooks init [dir]
+ claudish hooks corpus [--write] [--json]
+ claudish hooks telemetry [--enable | --disable] [--json]
+`;
+
+/** Run `claudish hooks <action>`. Returns the process exit code. */
+export async function hooksCommand(argv: string[]): Promise<number> {
+ const json = argv.includes("--json");
+ const positional = argv.filter((a) => !a.startsWith("-"));
+ const action = positional[0] ?? "list";
+
+ switch (action) {
+ case "list":
+ return list(json);
+ case "check":
+ return check(positional[1], json);
+ case "init":
+ return init(positional[1]);
+ case "corpus":
+ return corpus(argv.includes("--write"), json);
+ case "telemetry":
+ return telemetry(
+ argv.includes("--enable") ? "enable" : argv.includes("--disable") ? "disable" : "status",
+ json
+ );
+ default:
+ console.error(`Unknown action "${action}".\n\n${USAGE}`);
+ return 1;
+ }
+}
diff --git a/packages/cli/src/hooks/index.ts b/packages/cli/src/hooks/index.ts
index 7e8ed6d1..c500bafb 100644
--- a/packages/cli/src/hooks/index.ts
+++ b/packages/cli/src/hooks/index.ts
@@ -17,15 +17,9 @@
import { log } from "../logger.js";
import { loadConfig } from "../profile-config.js";
import { builtinHooks } from "./builtins/index.js";
-import {
- type HooksConfig,
- hooksConfigDir,
- parseHooksConfig,
- reportBehaviorBlock,
- reportProjectHooks,
-} from "./config.js";
+import { type HooksConfig, type WarnSink, hooksConfigDir, readHooksConfig } from "./config.js";
import { HookEngine } from "./engine.js";
-import { loadUserHooks } from "./loader.js";
+import { type LoadError, loadUserHooks } from "./loader.js";
import type { HostMode } from "./public.js";
import { HookRegistry, type UserHookInput } from "./registry.js";
@@ -59,7 +53,32 @@ export function resetHookEngineForTests(): void {
loadedEngine = null;
}
-async function buildEngine(hostMode: HostMode): Promise<HookEngine> {
+/** What one load of the hook configuration produced, before an engine is built on it. */
+export interface HookSet {
+ config: HooksConfig;
+ registry: HookRegistry;
+ /** Modules or exports that were skipped, and why. */
+ errors: LoadError[];
+ /** A pre-hook-system `behavior` block is present in the global config. */
+ behaviorConfigFound: boolean;
+}
+
+export interface LoadHookSetOptions {
+ hostMode: HostMode;
+ /** Where the config-load reporters write (`readHooksConfig`). Default: stderr. */
+ warn?: WarnSink;
+ /**
+ * Where per-module load warnings go. Default: `warn`. `claudish hooks list` drops
+ * them, because each one is also in `errors`, which it prints.
+ */
+ moduleWarn?: WarnSink;
+}
+
+/**
+ * Read the global config's `hooks`, report what is no longer read, load the user
+ * modules and build the registry (built-ins first). Never throws.
+ */
+export async function loadHookSet(opts: LoadHookSetOptions): Promise<HookSet> {
let raw: { hooks?: unknown; behavior?: unknown } = {};
try {
raw = loadConfig();
@@ -67,32 +86,39 @@ async function buildEngine(hostMode: HostMode): Promise<HookEngine> {
log(`[hooks] config unreadable, built-in hooks only: ${errorText(err)}`);
}
- const config: HooksConfig = parseHooksConfig(raw.hooks);
- reportBehaviorBlock(raw.behavior);
- reportProjectHooks();
+ const config: HooksConfig = readHooksConfig(raw, opts.warn);
let users: UserHookInput[] = [];
+ let errors: LoadError[] = [];
try {
const loaded = await loadUserHooks({
modules: config.modules,
configDir: hooksConfigDir(),
- hostMode,
+ hostMode: opts.hostMode,
+ warn: opts.moduleWarn ?? opts.warn,
});
users = loaded.hooks;
+ errors = loaded.errors;
} catch (err) {
// The loader reports per module and does not throw; this guards the
// promise contract against anything it did not anticipate.
log(`[hooks] user hook loading failed, built-in hooks only: ${errorText(err)}`);
}
- const builtins = builtinHooks(config);
- const engine = new HookEngine({
- registry: new HookRegistry(builtins, users, config.severity),
+ return {
config,
- hostMode,
- });
+ registry: new HookRegistry(builtinHooks(config), users, config.severity),
+ errors,
+ behaviorConfigFound: raw.behavior !== undefined && raw.behavior !== null,
+ };
+}
+
+async function buildEngine(hostMode: HostMode): Promise<HookEngine> {
+ const set = await loadHookSet({ hostMode });
+ const engine = new HookEngine({ registry: set.registry, config: set.config, hostMode });
+ const users = set.registry.hooks.filter((h) => h.source === "user").length;
log(
- `[hooks] engine ready (host ${hostMode}): ${builtins.length} built-in, ${users.length} user hook(s)`
+ `[hooks] engine ready (host ${hostMode}): ${set.registry.hooks.length - users} built-in, ${users} user hook(s)`
);
return engine;
}
diff --git a/packages/cli/src/behavior/middleware-payload.test.ts b/packages/cli/src/hooks/raw-request-payload.test.ts
similarity index 74%
rename from packages/cli/src/behavior/middleware-payload.test.ts
rename to packages/cli/src/hooks/raw-request-payload.test.ts
index c196c443..b21274ed 100644
--- a/packages/cli/src/behavior/middleware-payload.test.ts
+++ b/packages/cli/src/hooks/raw-request-payload.test.ts
@@ -1,10 +1,18 @@
+/**
+ * Why raw `providerRequest` hooks run BEFORE `buildPayload`: edits to the
+ * converted `messages`/`tools` and to `claudeRequest.system` survive
+ * serialisation on both the Chat Completions and the Codex/Responses adapters
+ * only when made before the payload is built (moved from the behavior layer's
+ * middleware-payload test; the property is the adapters', not the hook tier's).
+ */
+
import { describe, expect, it } from "bun:test";
import { CodexAPIFormat } from "../adapters/codex-api-format.js";
import { OpenAIAPIFormat } from "../adapters/openai-api-format.js";
-const MESSAGE_MARKER = "BEHAVIOR_MESSAGE_MUTATION_SURVIVED";
-const TOOL_MARKER = "BEHAVIOR_TOOL_DESCRIPTION_MUTATION_SURVIVED";
-const SYSTEM_MARKER = "BEHAVIOR_SYSTEM_MUTATION_SURVIVED";
+const MESSAGE_MARKER = "RAW_MESSAGE_MUTATION_SURVIVED";
+const TOOL_MARKER = "RAW_TOOL_DESCRIPTION_MUTATION_SURVIVED";
+const SYSTEM_MARKER = "RAW_SYSTEM_MUTATION_SURVIVED";
function claudeRequest(): any {
return {
@@ -21,7 +29,7 @@ function claudeRequest(): any {
};
}
-describe("middleware mutations before adapter.buildPayload", () => {
+describe("raw providerRequest mutations before adapter.buildPayload", () => {
it("serializes message and tool mutations through OpenAIAPIFormat", () => {
const adapter = new OpenAIAPIFormat("gpt-5.5");
const request = claudeRequest();
diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts
index 5b8b877e..abe4a9b9 100644
--- a/packages/cli/src/index.ts
+++ b/packages/cli/src/index.ts
@@ -1,8 +1,18 @@
-#!/usr/bin/env bun
-
-// FIRST import, on purpose: in an MCP pane child it restores the server's exact
-// environment and cwd at import time — before `.env` loading and before any module
-// below reads the environment while it is being evaluated. A no-op everywhere else.
+#!/usr/bin/env -S bun --no-env-file
+// `env -S` (split the rest into arguments) is in GNU coreutils and BSD `env`, not in
+// BusyBox `env` (Alpine), where this shebang fails. There, start claudish through the npm
+// `claudish` launcher (bin/claudish.cjs passes --no-env-file itself) or run
+// `bun --no-env-file dist/index.js`. Documented in docs/advanced/hooks.md.
+
+// FIRST import, on purpose: drops every control variable (CLAUDISH_CONFIG, the pane
+// markers, …), and every other name those files set, when Bun loaded this directory's
+// env files for the process, before the pane child below can act on one. See
+// launch-env.ts.
+import { droppedAtLaunch } from "./launch-guard.js";
+
+// SECOND: in an MCP pane child it restores the server's exact environment and cwd at
+// import time — before `.env` loading and before any module below reads the
+// environment while it is being evaluated. A no-op everywhere else.
import {
assertNotNested,
assertPaneChildInteractive,
@@ -10,12 +20,44 @@ import {
paneChildBootNotes,
} from "./pane/child-env.js";
-// Load .env file before anything else (quiet mode to suppress verbose output)
-import { config } from "dotenv";
-config({ quiet: true }); // Loads .env from current working directory
-
import { existsSync, readFileSync } from "node:fs";
import { join, resolve } from "node:path";
+import { droppedByAutoloadNotice, takeLauncherDropped } from "./launch-env.js";
+
+// Names left out because Bun loaded this directory's env files: by launch-guard.ts for
+// this process, or by the npm launcher before it started this one.
+const autoloadDropped = [...droppedAtLaunch, ...takeLauncherDropped(process.env)];
+
+// The working directory's `.env`, as dotenv's `config()` reads it (an existing value is
+// never overwritten), for provider API keys and model settings only (dotenv-allowlist.ts).
+// The allowlist is derived from the provider table, so it is imported only when there is
+// a file.
+let dotenvText: Buffer | undefined;
+try {
+ dotenvText = readFileSync(join(process.cwd(), ".env"));
+} catch {
+ // no readable .env: nothing to load
+}
+if (dotenvText !== undefined) {
+ const { loadDotenvText, refusedFromDotenvNotice, rejectedModelNotice } = await import(
+ "./dotenv-allowlist.js"
+ );
+ const rejectedModels: string[] = [];
+ const refused = loadDotenvText(process.env, dotenvText, (name) =>
+ rejectedModels.push(name)
+ ).filter((key) => !autoloadDropped.includes(key));
+ if (refused.length > 0) console.error(refusedFromDotenvNotice(refused));
+ // A name the autoload drop already reports below gets that one line, not a second.
+ const rejected = rejectedModels.filter((key) => !autoloadDropped.includes(key));
+ if (rejected.length > 0) console.error(rejectedModelNotice(rejected));
+}
+// One line for the autoload drops, less any the pane snapshot or the `.env` load above
+// set again (a provider API key in `.env`).
+{
+ const ignored = autoloadDropped.filter((key) => process.env[key] === undefined);
+ if (ignored.length > 0) console.error(droppedByAutoloadNotice(ignored));
+}
+
import { resolveExplicitFlagAuth } from "./auth/credentials/op-source.js";
import { resolveClassifierConfig } from "./classifier-passthrough.js";
import {
@@ -248,6 +290,8 @@ async function applyOpImport(): Promise<void> {
// env→config chain, so it can carry literal provider keys directly.
async function applyConfigOverride(): Promise<void> {
const { planConfigOverride, setConfigFileOverride } = await import("./config-override.js");
+ // CLAUDISH_CONFIG here is the real environment's: no env file in the working
+ // directory can set it (launch-guard.ts and loadDotenvText above).
const plan = planConfigOverride(process.argv.slice(2), process.env, {
resolve,
exists: existsSync,
@@ -363,8 +407,8 @@ const isServeCommand = firstPositional === "serve";
const isProvidersCommand = firstPositional === "providers";
// Keychain subcommand: claudish keychain status|list|import|set|rm|enable|disable
const isKeychainCommand = firstPositional === "keychain";
-// Behavior subcommand: claudish behavior rules|corpus (Layer 4 introspection)
-const isBehaviorCommand = firstPositional === "behavior";
+// Hooks subcommand: claudish hooks list|check|init|corpus|telemetry
+const isHooksCommand = firstPositional === "hooks";
// Team subcommand: claudish team run|run-and-judge (multi-model orchestration)
const isTeamCommand = firstPositional === "team";
// Auth subcommands: claudish login [provider], claudish logout [provider]
@@ -414,15 +458,18 @@ if (isMcpMode) {
process.exit(1);
})
);
-} else if (isBehaviorCommand) {
- // Layer 4 introspection: claudish behavior rules|corpus. Read-only unless
- // --write is passed to `corpus`.
- const behaviorArgIndex = args.indexOf("behavior");
- import("./behavior-command.js").then((m) =>
- m.behaviorCommand(args.slice(behaviorArgIndex + 1)).catch((e) => {
- console.error(`[claudish behavior] ${e instanceof Error ? e.message : String(e)}`);
- process.exit(1);
- })
+} else if (isHooksCommand) {
+ // Hook introspection and scaffolding. Read-only except `init` (writes two new
+ // files, never overwriting), `corpus --write` and `telemetry --enable|--disable`.
+ const hooksArgIndex = args.indexOf("hooks");
+ import("./hooks-command.js").then((m) =>
+ m
+ .hooksCommand(args.slice(hooksArgIndex + 1))
+ .then((code) => process.exit(code))
+ .catch((e) => {
+ console.error(`[claudish hooks] ${e instanceof Error ? e.message : String(e)}`);
+ process.exit(1);
+ })
);
} else if (isTeamCommand) {
// Multi-model orchestration: claudish team run|run-and-judge. Routed here
diff --git a/packages/cli/src/pane/pane-launch.ts b/packages/cli/src/pane/pane-launch.ts
index e0b8b87d..79f21600 100644
--- a/packages/cli/src/pane/pane-launch.ts
+++ b/packages/cli/src/pane/pane-launch.ts
@@ -177,6 +177,12 @@ export interface PaneEnvInput {
cwd: string;
/** the control directory holding `sh-shim` */
ctlDir: string;
+ /**
+ * This process's active `--config` / `CLAUDISH_CONFIG` file (`getConfigFileOverride()`),
+ * or null. Set as the child's `CLAUDISH_CONFIG`, so the child reads the config its
+ * parent reads, whatever `parentEnv` carries.
+ */
+ configFile: string | null;
platform?: NodeJS.Platform;
/** the pane's size at launch (already clamped); DEFAULT_PANE_COLS × DEFAULT_PANE_ROWS when absent */
cols?: number;
@@ -185,8 +191,11 @@ export interface PaneEnvInput {
/**
* magmux's environment: the parent's minus the stripped, terminal-identity and host-
- * identity keys, plus the geometry, the slot env, the pane markers, the snapshot, and
- * finally `SHELL=<ctlDir>/sh-shim` (after the snapshot, which keeps the real `SHELL`).
+ * identity keys, plus the geometry, the slot env, the parent's config file, the pane
+ * markers, the snapshot, and finally `SHELL=<ctlDir>/sh-shim` (after the snapshot,
+ * which keeps the real `SHELL`). The markers and the config travel only here, in the
+ * spawn environment: the child honours them because no env file can set them
+ * (launch-env.ts).
*/
export function buildPaneEnv(input: PaneEnvInput): { magmuxEnv: Record<string, string> } {
const env: Record<string, string> = {};
@@ -208,6 +217,7 @@ export function buildPaneEnv(input: PaneEnvInput): { magmuxEnv: Record<string, s
env.CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC = "1";
if (input.parentEnv.CLAUDE_CODE_NATIVE_CURSOR === undefined) env.CLAUDE_CODE_NATIVE_CURSOR = "1";
Object.assign(env, input.slotEnv);
+ if (input.configFile !== null) env.CLAUDISH_CONFIG = input.configFile;
env[ENV.CLAUDISH_PANE_CHILD] = "1";
env[ENV.CLAUDISH_PANE_CWD] = input.cwd;
delete env[ENV.CLAUDISH_PANE_ENV];
@@ -330,7 +340,7 @@ export const SUBCOMMAND_WORDS = [
"serve",
"providers",
"keychain",
- "behavior",
+ "hooks",
"team",
"login",
"logout",
@@ -585,7 +595,7 @@ export class ClaudishNotFoundError extends Error {
readonly code = "pane_lost";
}
-/** Which claudish the launcher `exec`s: `CLAUDISH_BIN` (`*.ts` → `<bun> run <file>`), else PATH. */
+/** Which claudish the launcher `exec`s: `CLAUDISH_BIN` (`*.ts` → `<bun> --no-env-file run <file>`), else PATH. */
export function resolveClaudishLaunch(
parentEnv: Record<string, string | undefined>
): ClaudishLaunch {