Skip to content

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

10.4 KB
Raw Blame
/**
 * Hook decision journal (`~/.claudish/behavior-journal.jsonl`).
 *
 * The file keeps its name: it names the behaviour-telemetry product and its
 * `POST /v1/behavior` endpoint, not the deleted `behavior/` module.
 *
 * Records what the supervisor SAW and what it DECIDED, so the decisions can be
 * analysed later and turned into deterministic rules. This is the input to the
 * dream session (see MTL-77).
 *
 * ## Two payloads, on purpose
 *
 * A LOCAL record keeps full detail — real paths, real values-shapes. It lives on
 * the user's own machine alongside the debug log, and a local analysis pass
 * genuinely needs it: "the model wrote to <this> instead of <that>" is the whole
 * signal, and stripping it leaves nothing to learn from.
 *
 * What may LEAVE the machine carries no paths at all. Not sanitized paths — none. The
 * existing `sanitizeForReport()` masks the home directory but keeps the rest, so
 * `/Users/***\/dev/acme/acme-portal/...` still names a client. For aggregate
 * analysis the literal path is not needed anyway: what matters is the CATEGORY
 * of what happened ("wrote inside the plan dir but not to the assigned file"),
 * which is non-identifying and just as useful across many users.
 *
 * This mirrors the two-level rule already established in redact.ts:
 * `redactSecrets` for text staying on the machine, `sanitizeForReport` for text
 * leaving it — this module just takes it further, because a behavior record is
 * structural data rather than prose.
 *
 * ## Consent
 *
 * Local journalling is always on and needs no consent: it is the user's own data
 * on their own disk, exactly like `logs/`. Upload is a SEPARATE opt-in
 * (`hooks.telemetry.enabled`) and deliberately does NOT ride on the existing
 * `stats.enabled` consent — that consent was given for usage statistics, and
 * silently reusing it to ship behavioural records would be consent laundering.
 */

import { appendFile, mkdir, readFile, rename, stat, writeFile } from "node:fs/promises";
import { homedir } from "node:os";
import { dirname, join } from "node:path";
import { log } from "../logger.js";

/**
 * Local journal line schema. 2 since the hook system: the line names the event,
 * the hook and the action. Uploads are NOT journal lines — they are the session
 * aggregate built by `telemetry/aggregate.ts`, which keeps its own schema (1).
 */
export const JOURNAL_SCHEMA_VERSION = 2;

/** Which supervision surface produced this decision. */
export type Surface =
  | "request"
  | "tool_call"
  | "model_output"
  | "sequence"
  | "response"
  | "session";

/**
 * The surfaces the telemetry backend accepts. A CLOSED set fixed by the server
 * contract (`docs/specs/behavior-telemetry-backend.md`); `response` and
 * `session` are local only.
 */
export type UploadSurface = "request" | "tool_call" | "model_output" | "sequence";

/** What the supervisor did. */
export type Decision =
  | "ignored" // no rule matched
  | "matched" // a rule matched and applied
  | "warned" // a rule matched but severity was warn
  | "repaired" // arguments were rewritten
  | "novel" // nothing matched and the observer was consulted
  | "superseded" // a duplicate of an earlier step's text, or an action on a removed tool
  | "invalid" // the action was refused (shape, limit, not allowed for the event)
  | "timeout" // the handler did not return within its timeout
  | "error" // the handler threw or rejected
  | "disabled" // the circuit breaker disabled the hook
  | "dropped" // an injection or annotation was dropped
  | "queued" // an injection or note was queued
  | "delivered" // an injection was delivered
  | "raw" // a raw (unsafe) hook touched the request or response
  | "skipped"; // the event budget was spent before the hook's step (local only)

/**
 * The decision values the telemetry backend accepts — the `counts.*` keys of
 * the server contract. Everything added since is local only.
 */
export type UploadDecision = "ignored" | "matched" | "warned" | "repaired" | "novel";

const UPLOAD_SURFACES: ReadonlySet<string> = new Set<UploadSurface>([
  "request",
  "tool_call",
  "model_output",
  "sequence",
]);
const UPLOAD_DECISIONS: ReadonlySet<string> = new Set<UploadDecision>([
  "ignored",
  "matched",
  "warned",
  "repaired",
  "novel",
]);

export function isUploadSurface(surface: Surface): surface is UploadSurface {
  return UPLOAD_SURFACES.has(surface);
}

export function isUploadDecision(decision: Decision): decision is UploadDecision {
  return UPLOAD_DECISIONS.has(decision);
}

/**
 * How a file path related to the one the harness expected.
 *
 * This is the uploadable stand-in for the path itself — it preserves the entire
 * signal the plan-mode rule keys off, while carrying no user data.
 */
export type PathRelation =
  | "as_expected"
  | "same_dir_wrong_name"
  | "outside_expected_dir"
  | "no_expectation"
  | "not_applicable";

/** Hook events, plus `raw` for every raw-tier stage. */
export type JournalEvent =
  | "request"
  | "toolCall"
  | "responseRewrite"
  | "responseEnd"
  | "sessionStart"
  | "sessionIdle"
  | "sessionBlocked"
  | "sessionEnd"
  | "raw";

/**
 * One local journal line. Never uploaded as-is: the upload is the per-session
 * aggregate, and the only fields that reach it are passed explicitly by the
 * hook engine's `journal()` fan-out, which also applies the user-hook privacy
 * rules there.
 */
export interface JournalEntry {
  /** JOURNAL_SCHEMA_VERSION. Absent on lines written by the pre-hook engine. */
  schema?: number;
  ts: string;
  event?: JournalEvent;
  /** The real hook id — local only. */
  hookId?: string;
  action?: string;
  model: string;
  provider: string;
  sessionId?: string;
  surface: Surface;
  decision: Decision;
  /** Same as hookId (kept for readers of schema 1). */
  ruleId?: string;
  toolName?: string;
  /** Argument KEYS only — never values. */
  argKeys?: string[];
  pathRelation?: PathRelation;
  /** Full local detail. Never uploaded. */
  local?: {
    observedPath?: string;
    expectedPath?: string;
    note?: string;
  };
  /** At most 200 chars. Local only. */
  detail?: string;
}

/** The longest `detail` a journal line carries. */
export const MAX_DETAIL_CHARS = 200;

/** Classify an observed path against the expected one, without keeping either. */
export function classifyPath(observed?: string, expected?: string): PathRelation {
  if (!observed) return "not_applicable";
  if (!expected) return "no_expectation";
  if (observed === expected) return "as_expected";
  const dirOf = (p: string) => p.slice(0, Math.max(0, p.lastIndexOf("/")));
  return dirOf(observed) === dirOf(expected) ? "same_dir_wrong_name" : "outside_expected_dir";
}

export function journalPath(): string {
  return join(homedir(), ".claudish", "behavior-journal.jsonl");
}

/**
 * Size ceiling for the local journal. It is append-only and a busy session
 * writes an entry per watched tool call, so it needs a bound.
 */
export const MAX_JOURNAL_BYTES = 32 * 1024 * 1024;

/**
 * Prune target. Dropping to well under the cap rather than just below it means
 * the (relatively expensive) rewrite happens once per many appends instead of
 * on nearly every write once the file is full.
 */
const PRUNE_TO_BYTES = Math.floor(MAX_JOURNAL_BYTES * 0.6);

/**
 * Drop the oldest entries until the file fits under PRUNE_TO_BYTES.
 *
 * Oldest-first is the right eviction order here: the value of a decision record
 * decays: recent entries describe the models and rules currently in play, while
 * a record from six months and four claudish versions ago describes a system
 * that no longer exists.
 *
 * Written to a temp file and renamed so a reader never observes a half-pruned
 * journal. A concurrent append from another claudish process during the rewrite
 * can be lost — acceptable for diagnostic data, and far preferable to holding a
 * cross-process lock on the request path.
 */
async function prune(path: string): Promise<void> {
  const content = await readFile(path, "utf8");
  const lines = content.split("\n").filter(Boolean);

  // Walk backwards from the newest, keeping lines until the budget is spent.
  let kept = 0;
  let firstKept = lines.length;
  for (let i = lines.length - 1; i >= 0; i--) {
    const cost = Buffer.byteLength(lines[i]) + 1;
    if (kept + cost > PRUNE_TO_BYTES) break;
    kept += cost;
    firstKept = i;
  }

  const survivors = lines.slice(firstKept);
  const tmp = `${path}.pruning`;
  await writeFile(tmp, survivors.length ? `${survivors.join("\n")}\n` : "");
  await rename(tmp, path);
  log(
    `[behavior:journal] pruned ${lines.length - survivors.length} of ${lines.length} entries ` +
      `to stay under ${Math.round(MAX_JOURNAL_BYTES / 1e6)}MB`
  );
}

/**
 * The last pending append per journal path in this process.
 *
 * The request path fires `recordDecision` without awaiting it, so one hook step's actions start
 * several appends in the same tick. Each append first awaits a `stat` (and on a fresh journal a
 * `mkdir`), and those settle in no particular order: unchained, the lines reached the file in a
 * shuffled order, and the last decision could be on disk while an earlier one was still pending.
 * Chaining keeps the file in decision order, so a reader that sees a line also sees every line
 * this process decided before it. Cross-process appends stay unordered, as before.
 */
const pendingAppends = new Map<string, Promise<void>>();

/**
 * Append one decision. Never throws, never awaited by the request path. Appends from one process
 * reach the file in call order.
 */
export function recordDecision(entry: JournalEntry, path = journalPath()): Promise<void> {
  const previous = pendingAppends.get(path) ?? Promise.resolve();
  const next = previous.then(() => appendDecision(entry, path));
  pendingAppends.set(path, next);
  // Drop the entry once the chain is idle, so the map holds at most one promise per busy path.
  void next.then(() => {
    if (pendingAppends.get(path) === next) pendingAppends.delete(path);
  });
  return next;
}

async function appendDecision(entry: JournalEntry, path: string): Promise<void> {
  try {
    const size = await stat(path).then(
      (s) => s.size,
      () => 0
    );
    if (size === 0) await mkdir(dirname(path), { recursive: true }).catch(() => {});
    if (size > MAX_JOURNAL_BYTES) {
      await prune(path).catch((err) => log(`[behavior:journal] prune failed: ${err}`));
    }
    await appendFile(path, `${JSON.stringify(entry)}\n`);
  } catch (err) {
    // Journalling is diagnostic. It must never affect the user's request.
    log(`[behavior:journal] could not record: ${err}`);
  }
}