@workit-dev/core 0.0.1 → 1.0.0

package/src/hooks/agent-model.ts

@@ -0,0 +1,149 @@
+// Role models on a Claude Code subagent spawn (#420, #654): a spawn runs on
+// its role's model (and effort) from the role config. A model the spawn names
+// wins over a built-in default, and over a configured one only with
+// `models.allowLeadOverride`. A spawn that lacks its role's values is filled
+// through PreToolUse `updatedInput` with a note naming them for next time,
+// except under auto mode, which refuses a hook-rewritten call (retro
+// 2026-11-07 R1): there it is denied once with the exact Agent args to pass.
+// A type with no role, or a value the Agent tool cannot take, runs as written.
+// Before choosing, the hook reads this project's recent transcripts for a
+// usage limit (model-limit.ts, #655): a role whose list names a model of
+// another provider then runs on it, and the lead learns which worker to
+// re-dispatch.
+import {
+  CLAUDE_EFFORTS,
+  chooseSpawnModel,
+  claudeAgentModel,
+  roleForAgentType,
+} from "../core/role-models";
+import { scanClaudeTranscripts } from "./model-limit";
+import type { HookDecision } from "./protocol";
+
+const given = (value: unknown): boolean => typeof value === "string" && value.trim() !== "";
+
+/** Keys a respawn lists first; `description` and `prompt` stay as written and are not repeated. */
+const LEADING = ["subagent_type", "model", "effort", "run_in_background"];
+const UNLISTED = new Set(["description", "prompt"]);
+
+/** The Agent args to pass, as `key: value` pairs in a fixed order, `description` and `prompt` aside. */
+const spawnArgsText = (input: Record<string, unknown>): string =>
+  [...LEADING.filter((key) => Object.hasOwn(input, key)), ...Object.keys(input)]
+    .filter(
+      (key, at, keys) => !UNLISTED.has(key) && input[key] !== undefined && keys.indexOf(key) === at,
+    )
+    .map((key) => `${key}: ${JSON.stringify(input[key])}`)
+    .join(", ");
+
+/**
+ * What an earlier gate changed on the spawn: the keys it removed, why (for a
+ * deny) and the note for a rewrite.
+ */
+export type SpawnChange = { dropped: string[]; reasons: string[]; notes: string[] };
+
+const NO_CHANGE: SpawnChange = { dropped: [], reasons: [], notes: [] };
+
+/**
+ * One deny with the exact args of the spawn Workit would run, the same text
+ * every time, so the lead retries once and the retry passes as written.
+ */
+const respawn = (
+  input: Record<string, unknown>,
+  reasons: string[],
+  dropped: string[],
+  limits: string,
+): HookDecision => {
+  const args = spawnArgsText(input);
+  const without = dropped.length ? ` and no ${dropped.join(" or ")}` : "";
+  return {
+    kind: "deny",
+    reason: [
+      `workit spawn args: spawn again with exactly ${args} (description and prompt as written${without}).`,
+      ...reasons,
+      "Workit denies instead of rewriting the spawn: Claude Code's auto mode refuses a hook-rewritten spawn.",
+      limits,
+    ]
+      .filter(Boolean)
+      .join(" "),
+    unblock: args,
+  };
+};
+
+/** The exact values the lead's next spawn should pass (W2.21), so it runs as written. */
+const withNextSpawn = (text: string, input: Record<string, unknown>): string => {
+  if (text.includes("Next time pass")) return text;
+  const values = [
+    given(input.model) ? `model: ${String(input.model)}` : null,
+    given(input.effort) ? `effort: ${String(input.effort)}` : null,
+  ].filter(Boolean);
+  return values.length
+    ? `${text} Next time pass ${values.join(", ")} on the spawn, so it runs as written.`
+    : text;
+};
+
+export type SpawnOptions = {
+  env?: NodeJS.ProcessEnv;
+  /** What the spawn gate already changed (isolation). */
+  change?: SpawnChange;
+  /** The session's permission mode (Claude Code `permission_mode`). */
+  permissionMode?: string | null;
+};
+
+/**
+ * A spawn missing its role's model or effort: under auto mode a deny naming
+ * the exact args (retro 2026-11-07 R1: auto mode refuses an `updatedInput`
+ * rewrite), in any other mode an `updatedInput` fill with a note naming them.
+ */
+export const agentModelDecision = (
+  cwd: string,
+  tool: Record<string, unknown>,
+  options: SpawnOptions = {},
+): HookDecision => {
+  const env = options.env ?? process.env;
+  const change = options.change ?? NO_CHANGE;
+  const auto = options.permissionMode === "auto";
+  const limits = scanClaudeTranscripts(cwd, env).join("\n");
+  const changed = change.dropped.length > 0;
+  const asWritten = (note: string | null): HookDecision => {
+    if (changed && auto) return respawn(tool, change.reasons, change.dropped, limits);
+    const text = [...change.notes, note, limits].filter(Boolean).join("\n");
+    if (changed) return { kind: "update-input", input: tool, text };
+    return text ? { kind: "context", text } : { kind: "none" };
+  };
+  // The host fixes the model itself: nothing to fill, and `model` is not in its schema.
+  if (env.CLAUDE_CODE_SUBAGENT_MODEL_FORCE) return asWritten(null);
+  const selector = roleForAgentType(tool.subagent_type, tool.prompt);
+  if (!selector) return asWritten(null);
+  const choice = chooseSpawnModel(cwd, selector, "claude_code", tool, claudeAgentModel);
+  const effort = choice.effort?.toLowerCase() ?? null;
+  const input: Record<string, unknown> = { ...tool };
+  if (choice.model) input.model = choice.model;
+  if (effort && CLAUDE_EFFORTS.has(effort) && !given(tool.effort)) input.effort = effort;
+  const needs = [
+    input.model === tool.model ? null : `model ${String(input.model)}`,
+    input.effort === tool.effort ? null : `effort ${String(input.effort)}`,
+  ].filter(Boolean);
+  if (!needs.length) return asWritten(choice.note);
+  if (!auto) {
+    const note =
+      choice.note ??
+      `Workit set effort ${String(input.effort)} on this spawn: its role's configured effort.`;
+    return {
+      kind: "update-input",
+      input,
+      text: [...change.notes, withNextSpawn(note, input), limits].filter(Boolean).join("\n"),
+    };
+  }
+  const replaced = given(tool.model) && input.model !== tool.model;
+  return respawn(
+    input,
+    [
+      ...change.reasons,
+      `It needs ${needs.join(" and ")}: ${choice.basis ?? "its role"}.`,
+      replaced
+        ? `That replaces model ${String(tool.model)}: a configured role model wins unless "allowLeadOverride": true is set under models in workspaces.json.`
+        : "",
+    ].filter(Boolean),
+    change.dropped,
+    limits,
+  );
+};

package/src/hooks/budget-signal.ts

@@ -0,0 +1,284 @@
+// The worker tool-call budget (retro P9, ruling mvrhg6lc). A brief's TIMEBOX
+// names `N tool calls`; the spawn that carries it records N for the next
+// subagent of that type (`<store>/budget/spawns-<lead>.jsonl`), SubagentStart
+// binds it to the agent (`<store>/budget/<agent>.json`: limit and the last
+// multiple told), and every pre-tool hook of that agent appends one byte to
+// `<store>/budget/<agent>.calls`. At N calls (and 2N, 3N…) one line rides the
+// standing-order channel; the call is never denied. An agent without a
+// budget file is never counted.
+// fs, path and crypto only: the Codex launcher imports this before the
+// runtime, and the Claude Code launcher (bin/workit-hook.mjs) keeps a copy of
+// spawnBudget, noteSpawnBudget and tickBudget that
+// test/workit-core/hooks/budget-signal.test.ts holds equal.
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { gitStoreDir } from "./standing-signal";
+import type { HookInput } from "./protocol";
+
+const hash = (text: string): string => createHash("sha256").update(text).digest("hex").slice(0, 32);
+
+const budgetDir = (store: string): string => path.join(store, "budget");
+
+/** The same key as the standing seen file: one per host session or subagent. */
+const agentBase = (store: string, session: string, agentId: string | null): string =>
+  path.join(budgetDir(store), hash(`${session}\0${agentId ?? ""}`));
+
+const spawnsFile = (store: string, session: string): string =>
+  path.join(budgetDir(store), `spawns-${hash(session)}.jsonl`);
+
+/** `N tool calls` on a brief's TIMEBOX line, else null. */
+export const spawnBudget = (prompt: string): number | null => {
+  const found = /^TIMEBOX:[^\n]*?\b(\d+)\s+tool calls\b/mu.exec(prompt);
+  const n = found ? Number(found[1]) : NaN;
+  return Number.isInteger(n) && n > 0 ? n : null;
+};
+
+/**
+ * A lead's spawn that will run: queue its budget, or an explicit none, for
+ * the next subagent of `type`. Every spawn of a type queues one entry, so the
+ * FIFO stays aligned with the SubagentStart order. Call it only once the
+ * spawn is allowed: a denied spawn must leave no entry.
+ */
+export const noteSpawnBudget = (
+  cwd: string,
+  session: string,
+  type: string | null,
+  prompt: string,
+): void => {
+  try {
+    const store = session ? gitStoreDir(cwd) : null;
+    if (!store) return;
+    fs.mkdirSync(budgetDir(store), { recursive: true });
+    fs.appendFileSync(
+      spawnsFile(store, session),
+      `${JSON.stringify({ type: type ?? "", n: spawnBudget(prompt) })}\n`,
+    );
+  } catch {
+    // Without the note the worker runs unbudgeted.
+  }
+};
+
+type Budget = { limit: number; told: number };
+
+/** Small files written whole; a torn read fails open as "no budget". */
+const readBudget = (file: string): Budget | null => {
+  try {
+    const { limit, told } = JSON.parse(fs.readFileSync(file, "utf8")) as Partial<Budget>;
+    return typeof limit === "number" && limit > 0 ? { limit, told: Number(told) || 0 } : null;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * SubagentStart: take the head entry queued for this agent's type and bind
+ * its budget to the agent. Returns the limit, or null when the entry says
+ * none or nothing was queued.
+ */
+export const claimSpawnBudget = (
+  cwd: string,
+  session: string,
+  agentId: string,
+  agentType: string | null,
+): number | null => {
+  try {
+    const store = session ? gitStoreDir(cwd) : null;
+    if (!store) return null;
+    const file = spawnsFile(store, session);
+    const entries = fs
+      .readFileSync(file, "utf8")
+      .split("\n")
+      .filter(Boolean)
+      .map((line) => JSON.parse(line) as { type?: unknown; n?: unknown });
+    const at = entries.findIndex((entry) => entry.type === (agentType ?? ""));
+    if (at < 0) return null;
+    const [{ n }] = entries.splice(at, 1);
+    fs.writeFileSync(file, entries.map((entry) => `${JSON.stringify(entry)}\n`).join(""));
+    if (typeof n !== "number" || n <= 0) return null;
+    startBudget(store, session, agentId, n);
+    return n;
+  } catch {
+    return null;
+  }
+};
+
+/** Starts a budget; first ages out files of agents that never stopped, older than 7 days. */
+const startBudget = (store: string, session: string, agentId: string | null, n: number): void => {
+  const dir = budgetDir(store);
+  fs.mkdirSync(dir, { recursive: true });
+  const cutoff = Date.now() - 6048e5;
+  for (const name of fs.readdirSync(dir))
+    try {
+      if (fs.statSync(path.join(dir, name)).mtimeMs < cutoff) fs.rmSync(path.join(dir, name));
+    } catch {
+      // Another hook removed it first.
+    }
+  const base = agentBase(store, session, agentId);
+  fs.writeFileSync(`${base}.json`, JSON.stringify({ limit: n, told: 0 }));
+  fs.rmSync(`${base}.calls`, { force: true });
+};
+
+/**
+ * A host that launches the worker itself (Pi) binds the budget its prompt
+ * names straight to the worker's session. Returns the limit, else null.
+ */
+export const bindBudget = (
+  cwd: string,
+  session: string,
+  agentId: string | null,
+  prompt: string,
+): number | null => {
+  try {
+    const n = spawnBudget(prompt);
+    const store = n && session ? gitStoreDir(cwd) : null;
+    if (!n || !store) return null;
+    startBudget(store, session, agentId, n);
+    return n;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Count one tool call of a budgeted agent. True when the count reached the
+ * next untold multiple of the budget, so the runtime must load to tell it.
+ */
+export const tickBudget = (cwd: string, session: string, agentId: string | null): boolean => {
+  try {
+    const store = session ? gitStoreDir(cwd) : null;
+    if (!store) return false;
+    const base = agentBase(store, session, agentId);
+    const budget = readBudget(`${base}.json`);
+    if (!budget) return false;
+    fs.appendFileSync(`${base}.calls`, ".");
+    return fs.statSync(`${base}.calls`).size >= budget.limit * (budget.told + 1);
+  } catch {
+    return false;
+  }
+};
+
+const lineFor = (calls: number): string =>
+  `Tool-call budget reached (${calls}): commit your work, write your report, stop.`;
+
+/** The agent's base path, its budget, and how many multiples of it its calls reached. */
+const reachedOf = (cwd: string, session: string, agentId: string | null) => {
+  const store = session ? gitStoreDir(cwd) : null;
+  const base = store && agentBase(store, session, agentId);
+  const budget = base && readBudget(`${base}.json`);
+  if (!budget) return null;
+  return { base, budget, reached: Math.floor(fs.statSync(`${base}.calls`).size / budget.limit) };
+};
+
+/** SubagentStop: the agent's budget and counter go. */
+export const dropBudget = (cwd: string, session: string, agentId: string | null): void => {
+  const store = session ? gitStoreDir(cwd) : null;
+  if (store)
+    for (const ext of [".json", ".calls"])
+      fs.rmSync(agentBase(store, session, agentId) + ext, { force: true });
+};
+
+/** The one line for a budget reached and not yet told (marked told), else null. */
+export const budgetLine = (cwd: string, session: string, agentId: string | null): string | null => {
+  try {
+    const at = reachedOf(cwd, session, agentId);
+    if (!at || at.reached <= at.budget.told) return null;
+    fs.writeFileSync(`${at.base}.json`, JSON.stringify({ ...at.budget, told: at.reached }));
+    return lineFor(at.budget.limit * at.reached);
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * For a host that rebuilds its context on every model call (OpenCode): the
+ * line while the budget stands reached, else null. Never marks it told.
+ */
+export const budgetStanding = (
+  cwd: string,
+  session: string,
+  agentId: string | null,
+): string | null => {
+  try {
+    const at = reachedOf(cwd, session, agentId);
+    return at && at.reached > 0 ? lineFor(at.budget.limit * at.reached) : null;
+  } catch {
+    return null;
+  }
+};
+
+/** Codex tools Workit may deny; any other PreToolUse is never denied there. */
+const CODEX_GATED = new Set(["bash", "unifiedexec", "shell", "applypatch", "edit", "write"]);
+
+/**
+ * One native Codex PreToolUse payload: a lead's spawn (a tool input naming an
+ * agent type, or carrying a brief) queues its budget or an explicit none, and
+ * a budgeted subagent's call is counted. A spawn is a tool Workit never denies
+ * on Codex, so queueing here cannot outlive a denied call. True when the
+ * count reached the budget, so the runtime tells it.
+ */
+export const observeHookBudget = (payload: string): boolean => {
+  try {
+    const value = JSON.parse(payload) as Record<string, unknown>;
+    if (value.hook_event_name !== "PreToolUse" || typeof value.session_id !== "string")
+      return false;
+    const cwd = typeof value.cwd === "string" ? value.cwd : ".";
+    const agentId =
+      typeof value.agent_id === "string" && value.agent_id.trim() ? value.agent_id : null;
+    if (agentId) return tickBudget(cwd, value.session_id, agentId);
+    const tool = typeof value.tool_name === "string" ? value.tool_name : "";
+    const spawn = value.tool_input;
+    if (
+      CODEX_GATED.has(tool.toLowerCase().replace(/[_-]/g, "")) ||
+      !spawn ||
+      typeof spawn !== "object"
+    )
+      return false;
+    const fields = spawn as Record<string, unknown>;
+    const prompt = Object.values(fields).find(
+      (field): field is string => typeof field === "string" && field.includes("TIMEBOX:"),
+    );
+    const type = [fields.agent_type, fields.subagent_type].find(
+      (field): field is string => typeof field === "string",
+    );
+    if (prompt !== undefined || type !== undefined)
+      noteSpawnBudget(cwd, value.session_id, type ?? null, prompt ?? "");
+    return false;
+  } catch {
+    return false;
+  }
+};
+
+/** What handleHook does with a budget, for the hosts whose entry passes it (HookDeps.budget). */
+export type BudgetHooks = {
+  /** A pre-tool answer that lets the call run: the line once reached. */
+  line: (input: HookInput) => string | null;
+  /** SubagentStart: bind the queued budget. */
+  start: (input: HookInput, agentId: string, agentType: string) => void;
+  /** A lead's spawn the gate let through (Claude Code: untyped is general-purpose). */
+  spawn: (input: HookInput, spawn: Record<string, unknown>) => void;
+  /** SubagentStop: drop the agent's files. */
+  stop: (input: HookInput, agentId: string) => void;
+};
+
+export const budgetHooks: BudgetHooks = {
+  line: (input) => budgetLine(input.cwd, input.session.id ?? "", input.session.agentId),
+  start: (input, agentId, agentType) =>
+    void claimSpawnBudget(input.cwd, input.session.id ?? "", agentId, agentType),
+  spawn: (input, spawn) => {
+    if (!input.session.agentId)
+      noteSpawnBudget(
+        input.cwd,
+        input.session.id ?? "",
+        String(spawn.subagent_type || "general-purpose"),
+        String(spawn.prompt ?? ""),
+      );
+  },
+  stop: (input, agentId) => {
+    try {
+      dropBudget(input.cwd, input.session.id ?? "", agentId);
+    } catch {
+      // Aged out by the next startBudget.
+    }
+  },
+};