Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
/**
* claudish/hooks — the public hook contract.
*
* Everything a hook author can import lives here, and nothing else does. This
* file imports nothing from the rest of claudish and has no side effects, so it
* can be built on its own into `dist/hooks.js` + `dist/hooks.d.ts` and served to
* user modules as the `claudish/hooks` virtual module (see `loader.ts`).
*
* Every internal hooks module takes its types from here, so the contract has a
* single source.
*
* ## Process isolation
*
* A hook module's top-level state is PER PROCESS. In the interactive launcher,
* proxy events (`request` … `responseEnd`, raw) and session events
* (`sessionStart` … `sessionEnd`) run in one process. In `create_session` and
* team children they do not: proxy events run in the pane child, and session
* events run in the MCP server or the CLI process that drives the pane. Pass
* per-turn data from a proxy event to `sessionIdle` with `annotateTurn`, never
* with module variables.
*
* ## Execution: a hook chain
*
* The hooks of one event run one after another, in effective order. Each hook's
* actions are applied before the next hook is called, so `ctx.request`,
* `ctx.tool.args` and `ctx.response` show what the earlier hooks did, and
* `ctx.prior` lists it. A warn-severity or failing hook changes nothing for the
* next one. Each event has a budget for all its hooks together; a hook's timeout
* is cut to what is left of it.
*
* ## Output
*
* Log with `ctx.log`. `console.*` and `process.stdout`/`stderr` writes made by a
* hook are routed to claudish's debug log, never to the terminal or the MCP
* protocol stream.
*/
export const HOOK_API_VERSION = 1;
export type Severity = "off" | "warn" | "fix";
export type HookOrder = "pre" | "normal" | "post";
/** native = RouteInfo.native true; foreign = RouteInfo.native false; all = both */
export type RouteScope = "foreign" | "native" | "all";
export type HostMode = "interactive" | "pane-child" | "serve" | "mcp" | "other";
export type JsonValue =
| string
| number
| boolean
| null
| ReadonlyArray<JsonValue>
| { readonly [k: string]: JsonValue };
/* ───────────── facts ───────────── */
export interface HarnessFacts {
readonly planModeActive: boolean;
readonly planFilePath?: string;
readonly planDir?: string;
/** Claude Code session id from request metadata */
readonly sessionId?: string;
/** empty = no listing found, not "no skills" */
readonly skills?: ReadonlyArray<{ name: string; description: string }>;
}
export interface RouteInfo {
/** bare model name the handler serves, e.g. "glm-5" */
readonly modelId: string;
/** claudish provider name, e.g. "openrouter"; "anthropic" for native */
readonly provider: string;
/**
* true when the request is served by the native Anthropic handler, OR when
* !forceForeignModel && (/^claude[-.]/i.test(modelId) || provider === "anthropic")
* where forceForeignModel is the provider profile's opt-in override. This is the exact
* rule the plan-mode built-in has always used (a claude-* uid on an aggregator that sets
* forceForeignModel is foreign).
*/
readonly native: boolean;
}
export interface ClaudeTool {
name: string;
description?: string;
input_schema?: unknown;
}
/** A Claude-format content block. Only `text` blocks are editable by closed actions. */
export type ClaudeContentBlock =
| { type: "text"; text: string }
| { type: "tool_use"; id: string; name: string; input: unknown }
| { type: "tool_result"; tool_use_id: string; content?: unknown; is_error?: boolean }
| { type: "thinking"; thinking: string; signature?: string }
| { type: string; [k: string]: unknown };
export interface ClaudeMessage {
role: "user" | "assistant";
content: string | ReadonlyArray<ClaudeContentBlock>;
}
/**
* In `request`, the request as the earlier steps of the hook chain left it. On
* the response side and in `claims()`, the request chain's final view.
*/
export interface RequestFacts {
/** as Claude Code asked for it; frozen */
readonly model: string;
/** frozen */
readonly stream: boolean;
/** system prompt flattened to text, after earlier steps */
readonly systemText: string;
/** read-only view after earlier steps; change it through actions */
readonly messages: ReadonlyArray<ClaudeMessage>;
/**
* read-only view after earlier steps; `description` includes earlier description actions as
* stage B will apply them to the Claude-format tool (the provider copy may be summarised)
*/
readonly tools: ReadonlyArray<ClaudeTool>;
}
/** Which session a proxy event belongs to, when claudish knows. */
export interface ProxySessionRef {
readonly kind: SessionKind;
readonly id: string;
readonly role: "slot" | "judge" | null;
}
/** One action an earlier step of this hook chain applied or handed on. */
export interface PriorAction {
readonly hookId: string;
readonly action: HookAction;
}
interface BaseContext {
readonly hookId: string;
/** "warn" or "fix" (an "off" hook is never called) */
readonly severity: Severity;
/** writes to claudish's debug log; never to the terminal */
log(message: string): void;
/**
* this step's own signal: aborted when its step timeout elapses (its own timeout, or the
* event budget left, whichever is shorter) or when the dispatch is aborted. Never shared
* with another hook's step.
*/
readonly signal: AbortSignal;
/**
* actions earlier steps of this hook chain applied (or, for responseEnd/sessionStart/
* sessionIdle, handed on), in order. Empty for the first step and in claims()/the toolCall
* predicate. Never lists warn actions or anything a warn-severity hook returned.
*/
readonly prior: ReadonlyArray<PriorAction>;
}
export interface ProxyContext extends BaseContext {
readonly host: { mode: HostMode };
readonly route: RouteInfo;
readonly request: RequestFacts;
readonly harness: HarnessFacts;
readonly session: ProxySessionRef | null;
}
export interface RequestContext extends ProxyContext {
readonly event: "request";
}
export interface ToolCallContext extends ProxyContext {
readonly event: "toolCall";
readonly tool: {
id: string;
name: string;
/** the arguments after every repair earlier hooks in the chain applied */
args: Readonly<Record<string, unknown>>;
/** the argument JSON exactly as the model produced it; never rewritten */
rawArgs: string;
};
}
export type ResponseBlock =
| { type: "text"; text: string }
| { type: "thinking"; thinking: string }
| { type: "tool_use"; id: string; name: string; input: unknown }
| { type: "other"; blockType: string };
export interface ResponseView {
blocks: ReadonlyArray<ResponseBlock>;
/** every text block, joined with "\n\n" */
text: string;
/** every thinking block, joined with "\n\n" */
reasoning: string;
toolNames: ReadonlyArray<string>;
/** "tool_use" = an intermediate step of a tool loop; the turn continues after the tool runs */
stopReason: string | null;
}
/** response = the held response after every text action earlier hooks in the chain applied */
export interface ResponseRewriteContext extends ProxyContext {
readonly event: "responseRewrite";
readonly response: ResponseView;
}
/** response = the final bytes the client received: after any rewrite AND any raw `response` replacement */
export interface ResponseEndContext extends ProxyContext {
readonly event: "responseEnd";
readonly response: ResponseView;
}
export type SessionKind = "interactive" | "channel" | "team";
export interface SessionInfo {
kind: SessionKind;
/** team only; null otherwise */
role: "slot" | "judge" | null;
/** channel: the 8-hex session_id · team: "<run_id>:<slot id>" · interactive: the Claude Code session id */
id: string;
claudeSessionId: string | null;
/** as the caller asked for it */
model: string;
cwd: string;
/** a one-shot session stays "one-shot" through a hook-extended turn chain */
shape: "interactive" | "one-shot";
injection: "available" | "unavailable";
}
export interface SessionStartContext extends BaseContext {
readonly event: "sessionStart";
readonly session: SessionInfo;
}
export interface TurnAnnotation {
hookId: string;
key: string;
value: JsonValue;
}
export interface SessionIdleContext extends BaseContext {
readonly event: "sessionIdle";
readonly session: SessionInfo;
readonly turn: {
/** 1-based within the session; a re-woken turn keeps its index */
index: number;
/** this turn's assistant text */
answer: string;
stopReason: string | null;
apiError: boolean;
/** this turn was started by an injection */
hookCaused: boolean;
/** annotateTurn actions from this turn's responses, in arrival order */
annotations: ReadonlyArray<TurnAnnotation>;
};
readonly consecutiveHookTurns: number;
/** caller/human input is queued; an injection returned now will be dropped as stale */
readonly callerInputPending: boolean;
}
export interface SessionBlockedContext extends BaseContext {
readonly event: "sessionBlocked";
readonly session: SessionInfo;
readonly block: { kind: "question" | "permission"; text: string };
}
export interface SessionEndContext extends BaseContext {
readonly event: "sessionEnd";
readonly session: SessionInfo;
readonly outcome: { state: string; reason: string | null; exitCode: number | null };
}
/* ───────────── actions (closed) ───────────── */
type TextMatch = { find: string; regex?: boolean; flags?: string };
/** default ["user"] */
type MessageRoles = { roles?: ReadonlyArray<"user" | "assistant"> };
// request: system prompt
export type InjectSystemNote = { type: "injectSystemNote"; text: string };
// request: messages
export type AppendUserText = { type: "appendUserText"; text: string };
export type ReplaceMessageText = { type: "replaceMessageText"; replace: string } & TextMatch &
MessageRoles;
export type RemoveMessageText = { type: "removeMessageText" } & TextMatch & MessageRoles;
// request: tools
export type RewriteToolDescription = {
type: "rewriteToolDescription";
tool: string;
append: string;
};
export type ReplaceToolDescription = {
type: "replaceToolDescription";
tool: string;
description: string;
};
export type ReplaceToolSchema = {
type: "replaceToolSchema";
tool: string;
inputSchema: { type: "object"; [k: string]: unknown };
};
export type RemoveTool = { type: "removeTool"; tool: string };
// toolCall
export type RepairToolArgs = {
type: "repairToolArgs";
args: Record<string, unknown>;
reason: string;
};
// responseRewrite
export type AppendText = { type: "appendText"; text: string };
export type PrependText = { type: "prependText"; text: string };
export type ReplaceText = { type: "replaceText"; replace: string } & TextMatch;
export type RemoveText = { type: "removeText" } & TextMatch;
// responseEnd / session
export type InjectUserTurn = { type: "injectUserTurn"; text: string };
export type AnnotateTurn = { type: "annotateTurn"; key: string; value: JsonValue };
// any
export type Warn = { type: "warn"; message: string };
export type RequestAction =
| InjectSystemNote
| AppendUserText
| ReplaceMessageText
| RemoveMessageText
| RewriteToolDescription
| ReplaceToolDescription
| ReplaceToolSchema
| RemoveTool
| Warn;
export type ToolCallAction = RepairToolArgs | Warn;
export type RewriteAction = AppendText | PrependText | ReplaceText | RemoveText | Warn;
export type ResponseEndAction = InjectSystemNote | InjectUserTurn | AnnotateTurn | Warn;
export type SessionAction = InjectUserTurn | Warn;
export type ObserveAction = Warn;
export type HookAction =
| RequestAction
| ToolCallAction
| RewriteAction
| ResponseEndAction
| SessionAction;
// biome-ignore lint/suspicious/noConfusingVoidType: an `async` handler that returns nothing is Promise<void>; `undefined` would reject it
export type HookResult<A> = A[] | void | Promise<A[] | void>;
/* ───────────── handlers ───────────── */
export interface HookHandlers {
request?(ctx: RequestContext): HookResult<RequestAction>;
toolCall?: {
/** tool names whose completed arguments this hook sees; "*" = every tool (costs streaming of all tool input) */
tools: ReadonlyArray<string>;
/** synchronous, per request; default true. false = not armed for this request */
armed?(ctx: RequestContext): boolean;
/** true = see the call after it was forwarded; can only warn; never holds the stream */
observe?: boolean;
handle(ctx: ToolCallContext): HookResult<ToolCallAction>;
};
responseRewrite?: {
/** synchronous, per request, evaluated before the response starts; default true */
claims?(ctx: RequestContext): boolean;
handle(ctx: ResponseRewriteContext): HookResult<RewriteAction>;
};
responseEnd?(ctx: ResponseEndContext): HookResult<ResponseEndAction>;
sessionStart?(ctx: SessionStartContext): HookResult<SessionAction>;
sessionIdle?(ctx: SessionIdleContext): HookResult<SessionAction>;
sessionBlocked?(ctx: SessionBlockedContext): HookResult<ObserveAction>;
sessionEnd?(ctx: SessionEndContext): HookResult<ObserveAction>;
}
/* ───────────── raw (unsafe) tier ───────────── */
export interface RawProviderRequestContext {
readonly hookId: string;
readonly route: RouteInfo;
// biome-ignore lint/suspicious/noExplicitAny: the raw tier hands out provider-format objects by contract
claudeRequest: any; // a clone of the post-request-stage request
// biome-ignore lint/suspicious/noExplicitAny: provider format
messages: any[]; // a clone, provider format
// biome-ignore lint/suspicious/noExplicitAny: provider format
tools: any[]; // a clone, provider format
}
export interface RawProviderChunkContext {
readonly hookId: string;
readonly route: RouteInfo;
/** A clone of the parsed provider event. Whatever this field holds when the call returns is
* what the parser reads from then on, so it may be edited in place or replaced. */
// biome-ignore lint/suspicious/noExplicitAny: provider format
chunk: any;
/** The delta object inside `chunk` at call time (Responses wire: `chunk` itself). Edit it in
* place; assigning a new object to this field has no effect. */
// biome-ignore lint/suspicious/noExplicitAny: provider format
delta: any;
/** per-stream, shared across this hook's chunk calls; never cloned */
metadata: Map<string, unknown>;
}
export interface RawProviderStreamEndContext {
readonly hookId: string;
readonly route: RouteInfo;
metadata: Map<string, unknown>;
}
export interface RawResponseContext {
readonly hookId: string;
readonly route: RouteInfo;
readonly request: RequestFacts;
/** A replay of the current Claude-format response (SSE, or JSON for stream:false), read at the
* hook's own pace. claudish drains the original itself, so leaving this unread delays nothing. */
response: Response;
}
export interface RawMiddleware {
/**
* Receives clones. They replace the live request only when this call returns (or its promise
* resolves) within its timeout. A throw, a rejection or a timeout discards every change.
*/
providerRequest?(ctx: RawProviderRequestContext): void | Promise<void>;
/**
* MUST be synchronous. Called on the parser's loop, on a clone of the chunk. On a normal return
* of anything but a thenable, the clone (whatever `ctx.chunk` holds then) is committed: it
* becomes the object the parser reads, deletions included. On a throw nothing is committed.
* A declared `async` function is rejected at load. Any other thenable return is an invalid
* invocation: the clone is discarded even if the hook mutated it before returning, the call is
* journaled `invalid` (`async_return`) and counts toward the circuit breaker, and a rejection
* handler is attached, so a rejection is journaled `error` and never becomes an
* unhandledRejection.
*/
providerChunk?(ctx: RawProviderChunkContext): void;
providerStreamEnd?(ctx: RawProviderStreamEndContext): void | Promise<void>;
/**
* Return a replacement Response, or nothing to keep the current one. A replacement is read
* whole and forwarded only when it completes cleanly; on any failure the original is forwarded.
* The client never sees a partial replacement. A replacement must close within this hook's
* timeout after the later of this call's return and the end of the original; the original's end
* never depends on whether `ctx.response` is read.
*/
// biome-ignore lint/suspicious/noConfusingVoidType: an `async` hook that returns nothing is Promise<void>
response?(ctx: RawResponseContext): Response | void | Promise<Response | void>;
}
/* ───────────── definition ───────────── */
interface HookBase {
apiVersion: 1;
id: string;
description?: string;
/** default "fix" for user hooks */
defaultSeverity?: Severity;
/** default "normal" */
order?: HookOrder;
/** globs on RouteInfo.modelId; default "*"; proxy events only */
models?: string | ReadonlyArray<string>;
/** default "all"; proxy events only */
routes?: RouteScope;
/** per call; clamped to the event's maximum and to the event budget left when the hook's turn comes */
timeoutMs?: number;
on?: HookHandlers;
}
export interface SafeHook extends HookBase {
unsafe?: never;
raw?: never;
}
export interface UnsafeHook extends HookBase {
unsafe: true;
raw: RawMiddleware;
}
/**
* One hook. Module-level state is per process: in `create_session` and team
* children, proxy events run in the pane child and session events in the MCP
* server or CLI process. Pass per-turn data from proxy events to `sessionIdle`
* with `annotateTurn`, never with module variables.
*/
export type HookDefinition = SafeHook | UnsafeHook;
/** Identity function: gives editor type-checking and inference. */
export function defineHook<const H extends HookDefinition>(hook: H): H {
return hook;
}
type RegexOpts = { regex?: boolean; flags?: string };
type RoleOpts = { roles?: ReadonlyArray<"user" | "assistant"> };
/** Copy only the options that are set, so a constructed action equals the literal. */
function matchOpts(opts: (RegexOpts & RoleOpts) | undefined): RegexOpts & RoleOpts {
const out: RegexOpts & RoleOpts = {};
if (opts?.regex !== undefined) out.regex = opts.regex;
if (opts?.flags !== undefined) out.flags = opts.flags;
if (opts?.roles !== undefined) out.roles = opts.roles;
return out;
}
/** Action constructors (plain data; equivalent to writing the object literal). */
export const act: {
injectSystemNote(text: string): InjectSystemNote;
appendUserText(text: string): AppendUserText;
replaceMessageText(
find: string,
replace: string,
opts?: { regex?: boolean; flags?: string; roles?: ReadonlyArray<"user" | "assistant"> }
): ReplaceMessageText;
removeMessageText(
find: string,
opts?: { regex?: boolean; flags?: string; roles?: ReadonlyArray<"user" | "assistant"> }
): RemoveMessageText;
rewriteToolDescription(tool: string, append: string): RewriteToolDescription;
replaceToolDescription(tool: string, description: string): ReplaceToolDescription;
replaceToolSchema(
tool: string,
inputSchema: { type: "object"; [k: string]: unknown }
): ReplaceToolSchema;
removeTool(tool: string): RemoveTool;
repairToolArgs(args: Record<string, unknown>, reason: string): RepairToolArgs;
appendText(text: string): AppendText;
prependText(text: string): PrependText;
replaceText(
find: string,
replace: string,
opts?: { regex?: boolean; flags?: string }
): ReplaceText;
removeText(find: string, opts?: { regex?: boolean; flags?: string }): RemoveText;
injectUserTurn(text: string): InjectUserTurn;
annotateTurn(key: string, value: JsonValue): AnnotateTurn;
warn(message: string): Warn;
} = {
injectSystemNote: (text) => ({ type: "injectSystemNote", text }),
appendUserText: (text) => ({ type: "appendUserText", text }),
replaceMessageText: (find, replace, opts) => ({
type: "replaceMessageText",
find,
replace,
...matchOpts(opts),
}),
removeMessageText: (find, opts) => ({ type: "removeMessageText", find, ...matchOpts(opts) }),
rewriteToolDescription: (tool, append) => ({ type: "rewriteToolDescription", tool, append }),
replaceToolDescription: (tool, description) => ({
type: "replaceToolDescription",
tool,
description,
}),
replaceToolSchema: (tool, inputSchema) => ({ type: "replaceToolSchema", tool, inputSchema }),
removeTool: (tool) => ({ type: "removeTool", tool }),
repairToolArgs: (args, reason) => ({ type: "repairToolArgs", args, reason }),
appendText: (text) => ({ type: "appendText", text }),
prependText: (text) => ({ type: "prependText", text }),
replaceText: (find, replace, opts) => ({
type: "replaceText",
find,
replace,
...matchOpts(opts),
}),
removeText: (find, opts) => ({ type: "removeText", find, ...matchOpts(opts) }),
injectUserTurn: (text) => ({ type: "injectUserTurn", text }),
annotateTurn: (key, value) => ({ type: "annotateTurn", key, value }),
warn: (message) => ({ type: "warn", message }),
};