cc-improved

1// Optional mod (function hooks, early access API): draws the workflow's state, never decides anything.
2// The gates are the classic hooks in hooks/hooks.json; nothing there reads what this module does, so the plugin
3// behaves the same when the mod is absent, refused or failing. Every hook here calls `next(e)` first and then
4// draws, swallowing its own errors: the worst case is a missing or stale status line.
5import type { EngineInterface, Register } from "claude-code";
6
7import {
8  MOD_PANE,
9  MOD_PLUGIN,
10  MOD_TASK_PATH,
11  addTokens,
12  paneRows,
13  paneText,
14  parseSession,
15  parseTask,
16  statusLine,
17  toTokens,
18  zeroTokens,
19  type TurnTokens,
20  type WfSnapshot,
21} from "./status.ts";
22
23const SESSION_ID = /^[A-Za-z0-9_-]+$/;
24
25// Module state starts over on every reload; it only feeds the drawing.
26let lastTurn: TurnTokens | undefined;
27let totals: TurnTokens | undefined;
28/** Session state file found for this session, so the plugin data folder is searched once. */
29let sessionFile: string | undefined;
30
31async function readText($: EngineInterface, path: string): Promise<string | undefined> {
32  try {
33    const text = await $.fs.read(path);
34    return typeof text === "string" ? text : undefined;
35  } catch {
36    return undefined;
37  }
38}
39
40/**
41 * `${CLAUDE_PLUGIN_DATA}/sessions/<id>.json`, written by the classic hooks. The engine gives a mod no data folder, so
42 * it is looked up: `CLAUDE_PLUGIN_DATA` if this process has it, else the `cc-improved*` folders under
43 * `<config>/plugins/data/` that hold a file for this session id (unique, so another install cannot be picked).
44 */
45async function findSessionFile($: EngineInterface, sessionId: string): Promise<string | undefined> {
46  if (!SESSION_ID.test(sessionId)) return undefined;
47  if (sessionFile?.endsWith(`/${sessionId}.json`)) return sessionFile;
48  const candidates: string[] = [];
49  const data = await $.env.get("CLAUDE_PLUGIN_DATA");
50  if (data) candidates.push(data);
51  const config = (await $.env.get("CLAUDE_CONFIG_DIR")) || `${(await $.env.get("HOME")) ?? ""}/.claude`;
52  const root = `${config}/plugins/data`;
53  try {
54    for (const entry of await $.fs.list(root)) {
55      if (entry.kind === "dir" && entry.name.startsWith(MOD_PLUGIN)) candidates.push(`${root}/${entry.name}`);
56    }
57  } catch {
58    // No plugin data yet: the hooks have not run in this configuration.
59  }
60  for (const dir of candidates) {
61    const file = `${dir}/sessions/${sessionId}.json`;
62    if (await $.fs.exists(file).catch(() => false)) return (sessionFile = file);
63  }
64  return undefined;
65}
66
67/** Reads everything one drawing shows. Never rejects: what cannot be read is left out. */
68async function snapshot($: EngineInterface): Promise<WfSnapshot> {
69  const snap: WfSnapshot = { lastTurn, totals };
70  try {
71    const root = await $.session.root();
72    const taskText = await readText($, `${root}/${MOD_TASK_PATH}`);
73    snap.task = taskText === undefined ? undefined : parseTask(taskText);
74  } catch {
75    // Left out.
76  }
77  try {
78    snap.sessionId = await $.session.id();
79    const file = await findSessionFile($, snap.sessionId);
80    const text = file === undefined ? undefined : await readText($, file);
81    snap.session = text === undefined ? undefined : parseSession(text);
82  } catch {
83    // Left out.
84  }
85  try {
86    snap.costUsd = (await $.session.usage()).cost?.usd;
87  } catch {
88    // Left out.
89  }
90  return snap;
91}
92
93/** Redraws the status line and an open pane. Never rejects. */
94async function refresh($: EngineInterface): Promise<void> {
95  try {
96    $.ui.status(statusLine(await snapshot($)));
97    $.ui.invalidate("ui.render");
98  } catch {
99    // A display that fails stays as it was.
100  }
101}
102
103export const register: Register = (on) => {
104  on("session.start", async ($, e, next) => {
105    const started = await next(e);
106    try {
107      await $.command.register({ name: MOD_PANE, description: "Estado de la tarea del flujo (fase, plan, verify, revisión, coste)" });
108    } catch {
109      // Without the command the status line still works.
110    }
111    await refresh($);
112    return started;
113  });
114
115  on("command.run", { command: "wf" }, async ($) => {
116    try {
117      const snap = await snapshot($);
118      $.ui.status(statusLine(snap));
119      const opened = await $.ui.open({ id: MOD_PANE, title: "cc-improved" }).catch(() => undefined);
120      // Where no pane is drawn (`claude -p`, a narrow terminal) the text answer carries the same rows.
121      return { text: opened?.isPlaced ? "Panel wf abierto." : paneText(snap) };
122    } catch {
123      return { text: "wf: no se pudo leer el estado." };
124    }
125  }).catch(() => ({ text: "wf: no se pudo leer el estado." }));
126
127  on("turn.complete", async ($, e, next) => {
128    const done = await next(e);
129    try {
130      const usage = e.usage ?? done.usage;
131      if (usage) {
132        const tokens = toTokens(usage);
133        totals = addTokens(totals ?? zeroTokens(), tokens);
134        if (e.agentId === undefined) lastTurn = tokens;
135      }
136    } catch {
137      // Counting is best effort.
138    }
139    // Phase changes come from the classic hooks writing task.json during the turn. refresh() never rejects and
140    // costs a few file reads; awaiting it keeps headless runs from exiting before the redraw.
141    await refresh($);
142    return done;
143  });
144
145  on("ui.render", { component: "Pane", requestId: "wf" }, async ($, e) => {
146    const { Box, Text } = $.ui.resolve(e);
147    let rows: Array<[string, string]>;
148    try {
149      rows = paneRows(await snapshot($));
150    } catch {
151      rows = [["wf", "no se pudo leer el estado"]];
152    }
153    return (
154      <Box flexDirection="column">
155        {rows.map(([label, value]) => (
156          <Text>
157            <Text dimColor>{label}: </Text>
158            {value}
159          </Text>
160        ))}
161      </Box>
162    );
163  });
164};
165

1// What the optional mod shows, as pure functions over the workflow's files. No engine and no Node imports here: the
2// mod's environment has neither, and `npm test` / `npm run typecheck` cover this file through test/mod-status.test.ts.
3// The gates live in the classic hooks (hooks/hooks.json → lib/hooks/); this file only describes their state.
4import type { SessionState, Task } from "../lib/types.ts";
5
6/**
7 * Same value as `TASK_PATH` in lib/paths.ts, which cannot be imported here (it loads `node:path`, and the mod has no
8 * Node). test/mod-status.test.ts fails if the two drift apart.
9 */
10export const MOD_TASK_PATH = ".claude/workflow/task.json";
11/** Plugin name; its data folder under `plugins/data/` starts with it (`cc-improved-<marketplace>`). */
12export const MOD_PLUGIN = "cc-improved";
13/** Id of the pane and name of the slash command. */
14export const MOD_PANE = "wf";
15
16/** Token counts of one turn, as `turn.complete` reports them (`ModelUsage`). */
17export interface TurnTokens {
18  input_tokens: number;
19  output_tokens: number;
20  cache_read_input_tokens: number;
21  cache_creation_input_tokens: number;
22}
23
24/** Everything one drawing needs, read fresh from disk and from the engine. */
25export interface WfSnapshot {
26  /** task.json, `undefined` when there is none or it does not parse. */
27  task?: Task | undefined;
28  /** This session's gate counters, `undefined` when the hooks have not written them (or they could not be found). */
29  session?: SessionState | undefined;
30  /** This session's id, to tell a task owned by another session. */
31  sessionId?: string | undefined;
32  /** Tokens of the last main-loop turn. */
33  lastTurn?: TurnTokens | undefined;
34  /** Tokens summed over the turns this load of the mod saw (main loop and subagents). */
35  totals?: TurnTokens | undefined;
36  /** What the session has cost so far, as /cost totals it. */
37  costUsd?: number | undefined;
38}
39
40export const zeroTokens = (): TurnTokens => ({ input_tokens: 0, output_tokens: 0, cache_read_input_tokens: 0, cache_creation_input_tokens: 0 });
41
42const count = (v: unknown): number => (typeof v === "number" && Number.isFinite(v) && v > 0 ? v : 0);
43
44/** Reads a usage object defensively: any field missing or not a number counts as 0. */
45export function toTokens(usage: unknown): TurnTokens {
46  const u = (usage && typeof usage === "object" ? usage : {}) as Record<string, unknown>;
47  return {
48    input_tokens: count(u.input_tokens),
49    output_tokens: count(u.output_tokens),
50    cache_read_input_tokens: count(u.cache_read_input_tokens),
51    cache_creation_input_tokens: count(u.cache_creation_input_tokens),
52  };
53}
54
55export function addTokens(a: TurnTokens, b: TurnTokens): TurnTokens {
56  return {
57    input_tokens: a.input_tokens + b.input_tokens,
58    output_tokens: a.output_tokens + b.output_tokens,
59    cache_read_input_tokens: a.cache_read_input_tokens + b.cache_read_input_tokens,
60    cache_creation_input_tokens: a.cache_creation_input_tokens + b.cache_creation_input_tokens,
61  };
62}
63
64/** Input side of a turn: fresh, cache read and cache write together. */
65export const inputSide = (t: TurnTokens) => t.input_tokens + t.cache_read_input_tokens + t.cache_creation_input_tokens;
66
67/** 950 → "950", 12_345 → "12.3k", 2_500_000 → "2.5M". */
68export function formatCount(n: number): string {
69  if (n < 1000) return String(Math.round(n));
70  if (n < 1_000_000) return `${(n / 1000).toFixed(1)}k`;
71  return `${(n / 1_000_000).toFixed(1)}M`;
72}
73
74export const formatTokens = (t: TurnTokens) => `${formatCount(inputSide(t))} in / ${formatCount(t.output_tokens)} out`;
75
76export const formatUsd = (usd: number) => `$${usd.toFixed(usd < 1 ? 3 : 2)}`;
77
78/** Parses task.json text; `undefined` for anything that is not a task. */
79export function parseTask(text: string): Task | undefined {
80  try {
81    const v: unknown = JSON.parse(text);
82    if (!v || typeof v !== "object" || Array.isArray(v)) return undefined;
83    const t = v as Partial<Task>;
84    if (typeof t.id !== "string" || typeof t.status !== "string") return undefined;
85    return { ...(t as Task), title: typeof t.title === "string" ? t.title : t.id };
86  } catch {
87    return undefined;
88  }
89}
90
91/** Parses a session state file; `undefined` for anything that is not one. */
92export function parseSession(text: string): SessionState | undefined {
93  try {
94    const v: unknown = JSON.parse(text);
95    if (!v || typeof v !== "object" || Array.isArray(v)) return undefined;
96    const s = v as Partial<SessionState>;
97    if (typeof s.sessionId !== "string") return undefined;
98    return {
99      ...(s as SessionState),
100      retries: count(s.retries),
101      reviews: count(s.reviews),
102      failures: count(s.failures),
103      planChecks: count(s.planChecks),
104      updatedAt: typeof s.updatedAt === "string" ? s.updatedAt : "",
105    };
106  } catch {
107    return undefined;
108  }
109}
110
111/** True when task.json belongs to another session open on the project (the hooks ignore it here too). */
112export const isForeign = (snap: WfSnapshot) => !!snap.task?.sessionId && !!snap.sessionId && snap.task.sessionId !== snap.sessionId;
113
114/** Session counters that belong to the current task (the gates reset them on another task). */
115function ownSession(snap: WfSnapshot): SessionState | undefined {
116  const s = snap.session;
117  if (!s || !snap.task) return undefined;
118  if (s.taskId !== undefined && s.taskId !== snap.task.id) return undefined;
119  return s;
120}
121
122/** The phase in one word, in Spanish, as the person reads it. */
123export function phaseLabel(snap: WfSnapshot): string {
124  const t = snap.task;
125  if (!t) return "sin tarea";
126  if (isForeign(snap)) return "tarea de otra sesión";
127  switch (t.status) {
128    case "planning":
129      return "plan";
130    case "implementing":
131      return "implementación";
132    case "done":
133      return "hecha";
134    default:
135      return String(t.status);
136  }
137}
138
139/** Plan line: title and how many files it may touch. */
140export function planLabel(snap: WfSnapshot): string {
141  const t = snap.task;
142  if (!t || isForeign(snap)) return "—";
143  if (!t.plan) return t.status === "planning" ? "en redacción" : "sin plan";
144  const files = t.plan.files.length + (t.allowedExtra?.length ?? 0);
145  const verdict = ownSession(snap)?.planVerdict;
146  return `${t.plan.title} (${files} archivo${files === 1 ? "" : "s"}${verdict ? `, chequeo ${verdict}` : ""})`;
147}
148
149/** Verify line, from the Stop/SubagentStop gate counters. */
150export function verifyLabel(snap: WfSnapshot): string {
151  if (!snap.task || isForeign(snap)) return "—";
152  const s = ownSession(snap);
153  if (!s) return "sin datos";
154  if (s.failures > 0) return `falla (${s.failures} seguida${s.failures === 1 ? "" : "s"})`;
155  if (s.verifiedFingerprint) return "pasa";
156  return "sin ejecutar";
157}
158
159/** Review line: the strong-model diff review, at most one round per task. */
160export function reviewLabel(snap: WfSnapshot): string {
161  if (!snap.task || isForeign(snap)) return "—";
162  const s = ownSession(snap);
163  if (!s) return "sin datos";
164  if (s.reviewVerdict) return s.reviewVerdict;
165  if (s.reviews > 0) return "omitida o sin veredicto";
166  return "pendiente";
167}
168
169/** The status line under the prompt: `wf: implementación · turno 12.3k in / 800 out`. */
170export function statusLine(snap: WfSnapshot): string {
171  const parts = [`wf: ${phaseLabel(snap)}`];
172  if (snap.lastTurn) parts.push(`turno ${formatTokens(snap.lastTurn)}`);
173  return parts.join(" · ");
174}
175
176/** The pane's rows as label/value pairs, in order. */
177export function paneRows(snap: WfSnapshot): Array<[label: string, value: string]> {
178  const rows: Array<[string, string]> = [
179    ["fase", phaseLabel(snap)],
180    ["tarea", snap.task && !isForeign(snap) ? snap.task.title : "—"],
181    ["plan", planLabel(snap)],
182    ["verify", verifyLabel(snap)],
183    ["revisión", reviewLabel(snap)],
184    ["último turno", snap.lastTurn ? formatTokens(snap.lastTurn) : "—"],
185    ["tokens (sesión)", snap.totals ? formatTokens(snap.totals) : "—"],
186    ["coste acumulado", snap.costUsd === undefined ? "—" : formatUsd(snap.costUsd)],
187  ];
188  return rows;
189}
190
191/** The same rows as plain text, for the `/wf` command's answer. */
192export const paneText = (snap: WfSnapshot) => paneRows(snap).map(([k, v]) => `${k}: ${v}`).join("\n");
193

1// Shared contracts. Every lib module, hook and script imports its types from here and never redefines them.
2// Field names follow the files on disk and Claude Code's hook JSON exactly (snake_case where the harness uses it).
3
4// ---------------------------------------------------------------------------
5// Project manifest: `.claude/workflow.json` (committed)
6// ---------------------------------------------------------------------------
7
8/** Where `/setup` stands for this project. `declined`: the user opted out; hooks stay quiet. */
9export type SetupStatus = "pending" | "running" | "done" | "declined";
10
11/** How much review a diff needs: none (skip), low (cheap model), high (strong model). */
12export type RiskLevel = "none" | "low" | "high";
13
14/** When a model reviews the diff or the plan. Default (no `review`): never; the deterministic gates still run (D-015). */
15export interface ReviewPolicy {
16  /** Repo-relative paths or prefixes (ending in `/`) whose changes always count as risky. */
17  paths?: string[];
18  /** Review every task, whatever the risk. Wins over `never`. */
19  always?: boolean;
20  /** Never pay for a diff review. */
21  never?: boolean;
22  /** Model check of the plan before the user approves it. Default: off. `true` turns it on (risky plans get the strong model, big ones the cheap one); `review.always` or a `minLevel` of `low`/`high` check risky plans; `false` never. */
23  plan?: boolean;
24  /** Lowest risk level that requests a model review: `off` (default, none), `high` or `low`. The level is recorded either way. */
25  minLevel?: "off" | "low" | "high";
26  /** Diff size above which a (cheap-model) review is requested. Defaults: 200 lines, 6 files. */
27  maxLines?: number;
28  maxFiles?: number;
29  /** Diff size above which the strong-model review is requested. Defaults: 600 lines, 15 files. */
30  highLines?: number;
31  highFiles?: number;
32  /** A plan with more files / interface entries / decisions than this is not small (no fast route) and, with `plan: true`, gets the plan check. Defaults: 8, 6, 2. Risky paths always do. */
33  planFiles?: number;
34  planInterface?: number;
35  planDecisions?: number;
36}
37
38/** A read-only ticket or docs source enabled by `/setup`. Its MCP server lives in the project's `.mcp.json`. */
39export interface Connector {
40  /** Catalog id, e.g. "github", "jira", "linear". */
41  id: string;
42  /** Server key in `.mcp.json`; its tools arrive as `mcp__<server>__<tool>`. Absent when the user configures it by hand. */
43  server?: string;
44}
45
46/** Runtime a project verification tool declares: a python 3 stdlib script, or a script whose nix env pins its dependencies. */
47export type ToolRuntime = "python" | "nix";
48
49/**
50 * A verification tool `/setup` wrote inside the project. The plugin ships none: each one is generated for the repo.
51 * `wf-setup-finish` checks it exists, is executable and answers `--help`; `/wf-doctor` checks its runtime is installed.
52 */
53export interface VerifyTool {
54  /** Repo-relative executable script. */
55  path: string;
56  runtime: ToolRuntime;
57  /** nix only: repo-relative `shell.nix` or `flake.nix` next to the script that pins its dependencies. */
58  env?: string;
59}
60
61/** How the project works by default: `direct` (cheap model with what /setup left; gates only with an open /task) or `flow` (/task recommended). */
62export type WorkflowMode = "direct" | "flow";
63
64/** Project state committed to the repo at `.claude/workflow.json`. */
65export interface Manifest {
66  version: 1;
67  setup: SetupStatus;
68  /** Default way of working; optional and additive, absent means `direct`. Gates only ever run with an open /task. */
69  mode?: WorkflowMode;
70  /** Main language as `/setup` recorded it; informative only, nothing branches on it. */
71  language?: string;
72  /** ISO 8601 timestamps of the setup run. */
73  startedAt?: string;
74  completedAt?: string;
75  /** Shell commands run in order from the project root; all must exit 0. The only source of verification commands. */
76  verify: string[];
77  /** Verification tools generated for this project and referenced by `.claude/skills/verify-app/SKILL.md`. */
78  tools?: VerifyTool[];
79  review?: ReviewPolicy;
80  connectors: Connector[];
81  /** agentlint command prefix when the project enforces agentlint rules, e.g. "pnpm agentlint". */
82  agentlint?: string;
83}
84
85// ---------------------------------------------------------------------------
86// Plan: the ```wf-plan block inside the plan-mode file (schema: lib/plan.schema.json)
87// ---------------------------------------------------------------------------
88
89/** Names the implementation must expose in one file, pinned before any code is written. */
90export interface InterfaceEntry {
91  /** Repo-relative file path. */
92  file: string;
93  /** Exported names; each must appear literally (as a word) in `file` once implemented. */
94  exports: string[];
95  /** Optional signatures, in the project's own language, as plain text. */
96  signatures?: string[];
97  /** Where the names come from: ticket key, spec path or existing file. Names are checked against this evidence. */
98  source?: string;
99}
100
101/** Where a test attaches and what it does and does not cover. */
102export interface Seam {
103  name: string;
104  /** Repo-relative test file. */
105  testFile: string;
106  /** What this test catches. */
107  catches: string;
108  /** What it leaves uncovered. */
109  misses?: string;
110}
111
112/** A design decision the plan depends on. Without a `source` the plan is denied: ask the user and write an ADR. */
113export interface Decision {
114  question: string;
115  /** Options considered; may be empty when only one was viable. */
116  options: string[];
117  /** The chosen option or the user's answer. Absent when `source` already settles it. */
118  answer?: string;
119  /** Where it is settled: an ADR path (`docs/adr/...`), a spec, the ticket, or an existing file. */
120  source: string;
121}
122
123/** Structured part of a plan, parsed from the ```wf-plan fenced block. */
124export interface Plan {
125  title: string;
126  /** Ticket key such as "PAY-142"; absent when the task has no ticket. */
127  ticket?: string;
128  /** Repo-relative spec files whose text counts as evidence for interface names. */
129  spec: string[];
130  /** Repo-relative files the task may create or change. An entry ending in `/` covers a directory. */
131  files: string[];
132  interface: InterfaceEntry[];
133  seams: Seam[];
134  decisions: Decision[];
135}
136
137// ---------------------------------------------------------------------------
138// Active task: `.claude/workflow/task.json` (local, gitignored)
139// ---------------------------------------------------------------------------
140
141/** planning: plan accepted by the hook, waiting for approval; implementing: approved; done: closed by `/done`. */
142export type TaskStatus = "planning" | "implementing" | "done";
143
144/** The active task of this working copy. */
145export interface Task {
146  id: string;
147  title: string;
148  ticket?: string;
149  status: TaskStatus;
150  plan?: Plan;
151  /** Absolute path of the plan-mode file the plan was parsed from. */
152  planFilePath?: string;
153  /** Repo-relative files outside the plan the user allowed during implementation. */
154  allowedExtra: string[];
155  /** ISO 8601 timestamps. */
156  startedAt: string;
157  completedAt?: string;
158  /**
159   * `session_id` of the session that last wrote `task.json`. Hooks of any other session skip their handlers, since
160   * hooks fire in every session open on the project. Stamped by the dispatcher's `saveTask`; absent means "any session".
161   */
162  sessionId?: string;
163  /** HEAD when the task entered planning; diffs are measured against it. Absent (no git, older task): against HEAD. */
164  baseCommit?: string;
165}
166
167// ---------------------------------------------------------------------------
168// Session state: `${CLAUDE_PLUGIN_DATA}/sessions/<session_id>.json`
169// ---------------------------------------------------------------------------
170
171/**
172 * Per-session gate counters. Hooks fire in every session open on the project, so each one reads and writes only
173 * the file of its own `session_id`. A missing file means all counters are zero.
174 */
175export interface SessionState {
176  sessionId: string;
177  /** Gate continuations (`decision: "block"`) spent since the last user prompt; bounded to avoid loops. */
178  retries: number;
179  /** Diff reviews spent (or skipped as low risk) on the current task; one round only. */
180  reviews: number;
181  /** Consecutive verify failures since the last pass: the 2nd escalates to the fixer (D-009). */
182  failures: number;
183  /** Strong-model plan checks spent on the current task. */
184  planChecks: number;
185  /** ISO 8601 time of the last write. */
186  updatedAt: string;
187  // Optional, written by the Stop/SubagentStop gates (lib/hooks/gate.ts). Absent means "not yet".
188  /** `prompt_id` the per-prompt counters (`retries`, `failures`, `setupNudges`, `lastBlock`) belong to; a new prompt resets them. */
189  promptId?: string | undefined;
190  /** Pushes back to work while `setup` is `running`, since the last user prompt (at most 2). */
191  setupNudges?: number | undefined;
192  /** Task id the per-task fields belong to; another task resets them. */
193  taskId?: string | undefined;
194  /** Gate counters per subagent, keyed by `agent_id`: `stop_hook_active` cannot count retries (spike 0.3). */
195  agents?: Record<string, AgentGateState> | undefined;
196  /** Last `VERDICT:` of plan-check on the current task. */
197  planVerdict?: Verdict | undefined;
198  /** Last `VERDICT:` of the diff reviewer on the current task. */
199  reviewVerdict?: Verdict | undefined;
200  /** What the gate last decided about the diff review on the current task (level, reasons, whether it was requested). */
201  review?: ReviewRecord | undefined;
202  /** What the orchestrator's last Stop block asked for, so the same request is not repeated in a loop. */
203  lastBlock?: string | undefined;
204  /** Fingerprint of the working copy when verify last passed in the orchestrator's Stop; unchanged means no rerun. */
205  verifiedFingerprint?: string | undefined;
206}
207
208/** The gate's last review decision, recorded in the session state. */
209export interface ReviewRecord {
210  level: RiskLevel;
211  reasons: string[];
212  requested: boolean;
213}
214
215/** Verdict line a strong-model checker ends with: `VERDICT: OK` or `VERDICT: FIX`. */
216export type Verdict = "OK" | "FIX";
217
218/** Gate state of one implementer or fixer run (one `agent_id`). */
219export interface AgentGateState {
220  /** Role without plugin prefix or model suffix: "implementer", "fixer", "reviewer", "plan-check". */
221  role: string;
222  /** Blocks spent on a missing interface contract. */
223  contractBlocks: number;
224  /** Consecutive verify failures: 1 fix (with the diagnosis method), 2 released with FAILED (D-009). */
225  failures: number;
226  /** Blocks spent on agentlint (policy) failures; the second one goes to the person, not to a smarter model. */
227  policyBlocks: number;
228  /** Set when the gate last let the agent out: passed, or failed (escalate). */
229  outcome?: "passed" | "failed" | undefined;
230}
231
232// ---------------------------------------------------------------------------
233// Hook input: the JSON Claude Code writes to a command hook's stdin (fixtures: test/fixtures/hooks/)
234// ---------------------------------------------------------------------------
235
236/** Known permission modes; other strings may appear in newer Claude Code versions. */
237export type PermissionMode = "default" | "plan" | "acceptEdits" | "bypassPermissions" | "dontAsk" | "auto" | (string & {});
238
239/** Fields present in every hook event. */
240export interface HookInputBase {
241  session_id: string;
242  /** Main session transcript (JSONL), also inside a subagent. */
243  transcript_path: string;
244  cwd: string;
245}
246
247/** Present only when the event fires inside a subagent: hooks tell the orchestrator from a child by these. */
248export interface SubagentContext {
249  agent_id?: string;
250  /** Agent name, e.g. "implementer"; plugin agents may carry the plugin prefix. */
251  agent_type?: string;
252}
253
254/** Fields of events that belong to a turn. */
255export interface TurnFields {
256  /** Id of the user prompt that started the turn. */
257  prompt_id: string;
258  permission_mode: PermissionMode;
259}
260
261export interface Effort {
262  level: string;
263}
264
265/** A background task listed at Stop time (e.g. a subagent launched asynchronously). */
266export interface BackgroundTask {
267  id: string;
268  type: "subagent" | (string & {});
269  status: string;
270  description: string;
271  agent_type?: string;
272}
273
274export interface SessionStartInput extends HookInputBase {
275  hook_event_name: "SessionStart";
276  source: "startup" | "resume" | "clear" | "compact" | (string & {});
277}
278
279export interface UserPromptSubmitInput extends HookInputBase, TurnFields {
280  hook_event_name: "UserPromptSubmit";
281  prompt: string;
282}
283
284export interface PreToolUseInput extends HookInputBase, TurnFields, SubagentContext {
285  hook_event_name: "PreToolUse";
286  effort?: Effort;
287  tool_name: string;
288  /** Narrow with the `*ToolInput` types below after checking `tool_name`. */
289  tool_input: Record<string, unknown>;
290  tool_use_id: string;
291}
292
293export interface PostToolUseInput extends HookInputBase, TurnFields, SubagentContext {
294  hook_event_name: "PostToolUse";
295  effort?: Effort;
296  tool_name: string;
297  tool_input: Record<string, unknown>;
298  /** Tool-specific result; its shape varies by tool and version. */
299  tool_response: unknown;
300  tool_use_id: string;
301  duration_ms?: number;
302}
303
304export interface SubagentStartInput extends HookInputBase {
305  hook_event_name: "SubagentStart";
306  prompt_id?: string;
307  agent_id: string;
308  agent_type: string;
309}
310
311/** Fields shared by Stop and SubagentStop. */
312export interface StopFields extends TurnFields {
313  effort?: Effort;
314  /** True when this stop follows a `decision: "block"` from a Stop hook; use it to avoid loops. */
315  stop_hook_active: boolean;
316  last_assistant_message: string;
317  background_tasks?: BackgroundTask[];
318  session_crons?: unknown[];
319}
320
321export interface StopInput extends HookInputBase, StopFields {
322  hook_event_name: "Stop";
323}
324
325export interface SubagentStopInput extends HookInputBase, StopFields {
326  hook_event_name: "SubagentStop";
327  agent_id: string;
328  agent_type: string;
329  /** The subagent's own transcript (JSONL). */
330  agent_transcript_path: string;
331}
332
333export interface SessionEndInput extends HookInputBase {
334  hook_event_name: "SessionEnd";
335  prompt_id?: string;
336  reason: "clear" | "logout" | "prompt_input_exit" | "other" | (string & {});
337}
338
339/** Every hook event the plugin handles, discriminated by `hook_event_name`. */
340export type HookInput =
341  | SessionStartInput
342  | UserPromptSubmitInput
343  | PreToolUseInput
344  | PostToolUseInput
345  | SubagentStartInput
346  | SubagentStopInput
347  | StopInput
348  | SessionEndInput;
349
350export type HookEventName = HookInput["hook_event_name"];
351
352/** The input type of one event: `HookInputOf<"Stop">` is `StopInput`. */
353export type HookInputOf<E extends HookEventName> = Extract<HookInput, { hook_event_name: E }>;
354
355// Tool inputs the hooks inspect (from `tool_input`).
356
357export interface BashToolInput {
358  command: string;
359  description?: string;
360  timeout?: number;
361  run_in_background?: boolean;
362}
363
364export interface ReadToolInput {
365  file_path: string;
366  offset?: number;
367  limit?: number;
368}
369
370export interface WriteToolInput {
371  file_path: string;
372  content: string;
373}
374
375export interface EditToolInput {
376  file_path: string;
377  old_string: string;
378  new_string: string;
379  replace_all?: boolean;
380}
381
382export interface AgentToolInput {
383  description: string;
384  prompt: string;
385  subagent_type?: string;
386  model?: string;
387  run_in_background?: boolean;
388}
389
390/** ExitPlanMode `tool_input` in PreToolUse and PermissionRequest: the plan Markdown and its file (seen in spike 0.1). In PostToolUse it is `{}`; see `ExitPlanModeToolResponse`. */
391export interface ExitPlanModeToolInput {
392  plan?: string;
393  planFilePath?: string;
394}
395
396/** ExitPlanMode `tool_response` in PostToolUse once the plan is approved (seen in spike 0.1). */
397export interface ExitPlanModeToolResponse {
398  plan?: string;
399  filePath?: string;
400  isAgent?: boolean;
401}
402
403// ---------------------------------------------------------------------------
404// Hook output: the JSON a command hook prints to stdout (empty output + exit 0 = no opinion)
405// ---------------------------------------------------------------------------
406
407/** Fields every event accepts. */
408export interface HookOutputBase {
409  /** false stops Claude entirely; `stopReason` is shown to the user. */
410  continue?: boolean;
411  stopReason?: string;
412  suppressOutput?: boolean;
413  /** Message shown to the user, not to the model. */
414  systemMessage?: string;
415}
416
417export type PermissionDecision = "allow" | "deny" | "ask";
418
419export interface PreToolUseOutput extends HookOutputBase {
420  hookSpecificOutput: {
421    hookEventName: "PreToolUse";
422    permissionDecision?: PermissionDecision;
423    /** Shown to the model on deny; to the user on allow/ask. Write it so the model knows what to do next. */
424    permissionDecisionReason?: string;
425    /** Replaces the tool input before it runs. */
426    updatedInput?: Record<string, unknown>;
427    additionalContext?: string;
428  };
429}
430
431export interface PostToolUseOutput extends HookOutputBase {
432  decision?: "block";
433  reason?: string;
434  hookSpecificOutput?: { hookEventName: "PostToolUse"; additionalContext?: string };
435}
436
437/** Stop and SubagentStop: `block` keeps the agent working and `reason` is what the model reads. */
438export interface StopOutput extends HookOutputBase {
439  decision?: "block";
440  reason?: string;
441}
442
443/** Events that can only add context for the model. */
444export interface ContextOutput extends HookOutputBase {
445  hookSpecificOutput?: { hookEventName: "SessionStart" | "UserPromptSubmit" | "SubagentStart"; additionalContext?: string };
446}
447
448/** What each event's handler may print. */
449export interface HookOutputMap {
450  SessionStart: ContextOutput;
451  UserPromptSubmit: ContextOutput;
452  PreToolUse: PreToolUseOutput;
453  PostToolUse: PostToolUseOutput;
454  SubagentStart: ContextOutput;
455  SubagentStop: StopOutput;
456  Stop: StopOutput;
457  SessionEnd: HookOutputBase;
458}
459
460export type HookOutput = HookOutputMap[HookEventName];
461