Skip to content

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

20.7 KB
Raw Blame
// Auto-generated by scripts/generate-hooks-dts.ts from src/hooks/public.ts — do not edit

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