patchwork-os 0.2.0-alpha.0

package/dist/automation.d.ts

@@ -0,0 +1,675 @@
+import type { ClaudeOrchestrator } from "./claudeOrchestrator.js";
+import type { ExtensionClient } from "./extensionClient.js";
+/**
+ * Shared fields for prompt resolution in any automation hook.
+ * Exactly one of `prompt` or `promptName` must be provided.
+ *
+ * - `prompt`: inline instruction string with `{{placeholder}}` tokens.
+ * - `promptName`: name of a built-in MCP prompt (e.g. `"unused-in"`, `"why-error"`).
+ * - `promptArgs`: static args passed to the named prompt. Values may contain
+ *   `{{placeholder}}` tokens that are substituted with sanitized event data
+ *   (control chars stripped, length capped) before the prompt is resolved.
+ * - `condition`: optional minimatch glob. If set, the hook only fires when the
+ *   primary event value (file path, branch name, tool name, etc.) matches.
+ *   Prefix with `!` to negate: `"!**\/*.test.ts"` fires for all non-test files.
+ */
+/**
+ * Optional runtime condition checked before a hook fires.
+ * All specified fields must pass for the hook to trigger.
+ */
+export interface AutomationCondition {
+    /** Only fire if the active file's diagnostic count meets this threshold. */
+    minDiagnosticCount?: number;
+    /** Only fire if the active file has a diagnostic of at least this severity. */
+    diagnosticsMinSeverity?: "error" | "warning";
+    /** Only fire if the last test run for any runner had this outcome. */
+    testRunnerLastStatus?: "passed" | "failed" | "any";
+}
+export interface PromptSource {
+    prompt?: string;
+    promptName?: string;
+    promptArgs?: Record<string, string>;
+    condition?: string;
+    /** Optional runtime condition evaluated before the hook fires. */
+    when?: AutomationCondition;
+    /** Per-hook model override. Falls back to policy.defaultModel (Haiku). */
+    model?: string;
+    /** Per-hook effort override. Falls back to policy.defaultEffort ("low"). */
+    effort?: "low" | "medium" | "high" | "max";
+    /**
+     * Number of times to re-enqueue on task error. Default: 0 (no retry).
+     * Retries only fire when the task reaches status "error" — cancellations
+     * and timeouts do not trigger a retry.
+     */
+    retryCount?: number;
+    /**
+     * Milliseconds to wait between retries. Default: 30_000.
+     * Enforced minimum: 5_000.
+     */
+    retryDelayMs?: number;
+}
+export interface OnDiagnosticsErrorPolicy extends PromptSource {
+    enabled: boolean;
+    minSeverity: "error" | "warning";
+    /**
+     * Optional list of diagnostic source or code strings to match (case-insensitive).
+     * If set, only diagnostics whose `source` or `code` matches any value in this
+     * list will trigger the hook. Example: ["typescript", "eslint"].
+     */
+    diagnosticTypes?: string[];
+    /** Placeholders (inline prompt only): {{file}}, {{diagnostics}} */
+    /** Minimum ms between triggers for the same file. Enforced minimum: 5000. */
+    cooldownMs: number;
+    /**
+     * When true, dedupe by (file, diagnostic-content-hash) in addition to file path.
+     * Prevents re-triggering on repeated identical LSP emissions (the common "LSP
+     * republishes the same error after an unrelated workspace event" thrash pattern).
+     * Default: false — file-only dedupe via cooldownMs.
+     */
+    dedupeByContent?: boolean;
+    /**
+     * Cooldown (ms) for identical diagnostic content on the same file. Only used
+     * when `dedupeByContent` is true. Default: 900_000 (15 minutes). Enforced minimum: 5000.
+     */
+    dedupeContentCooldownMs?: number;
+}
+export interface OnFileSavePolicy extends PromptSource {
+    enabled: boolean;
+    /** Minimatch glob patterns, e.g. ["**\/*.ts", "!node_modules/**"] */
+    patterns: string[];
+    /** Placeholders (inline prompt only): {{file}} */
+    cooldownMs: number;
+}
+export interface OnFileChangedPolicy extends PromptSource {
+    enabled: boolean;
+    /** Minimatch glob patterns, e.g. ["**\/*.ts", "!node_modules/**"] */
+    patterns: string[];
+    /** Placeholders (inline prompt only): {{file}} */
+    cooldownMs: number;
+}
+export interface OnPreCompactPolicy extends PromptSource {
+    enabled: boolean;
+    /**
+     * No placeholders — fired just before Claude Code compacts the context window.
+     * Use to snapshot IDE state, write a handoff note, or complete an in-flight task
+     * before Claude loses context. Pairs with onPostCompact.
+     */
+    /** Minimum ms between triggers. Enforced minimum: 5000. */
+    cooldownMs: number;
+}
+export interface OnPostCompactPolicy extends PromptSource {
+    enabled: boolean;
+    /**
+     * No placeholders — fired unconditionally when compaction occurs.
+     * Use promptName (e.g. "project-status") to re-snapshot IDE state.
+     */
+    /** Minimum ms between triggers (prevents repeated compaction storms). Enforced minimum: 5000. */
+    cooldownMs: number;
+}
+/**
+ * Unified compaction hook (v2.43.0+) — replaces `onPreCompact` and
+ * `onPostCompact` with a single schema entry carrying a `phase` discriminator.
+ *
+ * The parser expands `onCompaction` into the internal `onPreCompact` or
+ * `onPostCompact` field before downstream processing; both legacy names still
+ * work but now log a deprecation warning at load time. Scheduled removal:
+ * no earlier than 3 minor versions + 30 days after v2.43.0.
+ */
+export interface OnCompactionPolicy extends PromptSource {
+    enabled: boolean;
+    /** "pre" fires before Claude Code compacts context; "post" fires after. */
+    phase: "pre" | "post";
+    /** Minimum ms between triggers. Enforced minimum: 5000. */
+    cooldownMs: number;
+}
+export interface OnInstructionsLoadedPolicy extends PromptSource {
+    enabled: boolean;
+    /**
+     * No placeholders — fired once per interactive session start.
+     * Use promptName (e.g. "orient-project") to inject tool capability summary.
+     * cooldownMs (default 60000) prevents cascade when automation subprocesses
+     * each fire their own InstructionsLoaded hook.
+     */
+    cooldownMs?: number;
+}
+export interface OnCwdChangedPolicy extends PromptSource {
+    enabled: boolean;
+    /**
+     * Placeholders (inline prompt only): {{cwd}}
+     */
+    /** Minimum ms between triggers. Enforced minimum: 5000. */
+    cooldownMs: number;
+}
+export interface OnTestRunPolicy extends PromptSource {
+    enabled: boolean;
+    /**
+     * Unified test-run trigger (v2.43.0+) replacing `onFailureOnly` and the
+     * separate `onTestPassAfterFailure` hook:
+     *   - "any"             — fire after every test run
+     *   - "failure"         — fire only when the run has failures (= onFailureOnly:true)
+     *   - "pass-after-fail" — fire only when a runner transitions fail → pass;
+     *                         routed internally to the onTestPassAfterFailure slot
+     * Exactly one of `filter` or `onFailureOnly` should be set; the two are
+     * mutually exclusive. If neither is set, defaults to "failure".
+     */
+    filter?: "any" | "failure" | "pass-after-fail";
+    /**
+     * @deprecated v2.43.0 — use `filter: "any"` or `filter: "failure"` instead.
+     * Only trigger when there are test failures or errors.
+     * Set to false to trigger after every test run regardless of outcome.
+     * Default: true.
+     */
+    onFailureOnly?: boolean;
+    /**
+     * Only trigger when the test run duration meets or exceeds this threshold (ms).
+     * Useful to ignore fast unit test runs and only fire on slow integration runs.
+     */
+    minDuration?: number;
+    /**
+     * Placeholders (inline prompt only): {{runner}}, {{failed}}, {{passed}}, {{total}}, {{failures}}
+     */
+    /** Minimum ms between triggers. Enforced minimum: 5000. */
+    cooldownMs: number;
+}
+export interface OnTestPassAfterFailurePolicy extends PromptSource {
+    enabled: boolean;
+    /**
+     * Fired when a test run transitions from failing → passing for the same runner.
+     * Per-runner state is tracked so vitest passing after a jest failure does NOT
+     * trigger — only the runner that was previously failing then passes triggers the hook.
+     * Placeholders (inline prompt only): {{runner}}, {{passed}}, {{total}}
+     */
+    /** Minimum ms between triggers. Enforced minimum: 5000. */
+    cooldownMs: number;
+}
+/** Minimal test run result passed to handleTestRun — avoids importing TestResult from tool files. */
+export interface TestRunResult {
+    runners: string[];
+    summary: {
+        total: number;
+        passed: number;
+        failed: number;
+        skipped: number;
+        errored: number;
+        durationMs?: number;
+    };
+    failures: Array<{
+        name: string;
+        file: string;
+        message: string;
+    }>;
+}
+export interface OnDebugSessionEndPolicy extends PromptSource {
+    enabled: boolean;
+    /**
+     * Placeholders (inline prompt only): {{sessionName}}, {{sessionType}}
+     */
+    cooldownMs: number;
+}
+/** Minimal debug session result passed to handleDebugSessionEnd. */
+export interface DebugSessionEndResult {
+    sessionName: string;
+    sessionType: string;
+}
+/**
+ * Unified debug-session hook (v2.43.0+) — replaces `onDebugSessionStart`
+ * and `onDebugSessionEnd`. Expanded at load time based on `phase`.
+ */
+export interface OnDebugSessionPolicy extends PromptSource {
+    enabled: boolean;
+    phase: "start" | "end";
+    /** Placeholders (inline prompt only): {{sessionName}}, {{sessionType}}, plus {{breakpointCount}}/{{activeFile}} for phase: "start" */
+    cooldownMs: number;
+}
+export interface OnDebugSessionStartPolicy extends PromptSource {
+    enabled: boolean;
+    /**
+     * Placeholders (inline prompt only): {{sessionName}}, {{sessionType}}
+     */
+    cooldownMs: number;
+}
+/** Minimal debug session result passed to handleDebugSessionStart. */
+export interface DebugSessionStartResult {
+    sessionName: string;
+    sessionType: string;
+    /** Number of breakpoints active at session start. */
+    breakpointCount: number;
+    /** Active file at session start (first breakpoint file, if any). */
+    activeFile: string;
+}
+export interface OnGitCommitPolicy extends PromptSource {
+    enabled: boolean;
+    /**
+     * Placeholders (inline prompt only): {{hash}}, {{branch}}, {{message}}, {{files}}, {{count}}
+     */
+    /** Minimum ms between triggers. Enforced minimum: 5000. */
+    cooldownMs: number;
+}
+/** Minimal commit result passed to handleGitCommit — avoids importing from gitWrite. */
+export interface GitCommitResult {
+    hash: string;
+    branch: string;
+    message: string;
+    files: string[];
+    count: number;
+}
+export interface OnGitPushPolicy extends PromptSource {
+    enabled: boolean;
+    /**
+     * Placeholders (inline prompt only): {{remote}}, {{branch}}, {{hash}}
+     */
+    /** Minimum ms between triggers. Enforced minimum: 5000. */
+    cooldownMs: number;
+}
+/** Minimal push result passed to handleGitPush — avoids importing from gitWrite. */
+export interface GitPushResult {
+    remote: string;
+    branch: string;
+    hash: string;
+}
+export interface OnGitPullPolicy extends PromptSource {
+    enabled: boolean;
+    /**
+     * Placeholders (inline prompt only): {{remote}}, {{branch}}
+     */
+    /** Minimum ms between triggers. Enforced minimum: 5000. */
+    cooldownMs: number;
+}
+/** Minimal pull result passed to handleGitPull — avoids importing from gitWrite. */
+export interface GitPullResult {
+    remote: string;
+    branch: string;
+    alreadyUpToDate: boolean;
+}
+export interface OnBranchCheckoutPolicy extends PromptSource {
+    enabled: boolean;
+    /**
+     * Placeholders (inline prompt only): {{branch}}, {{previousBranch}}, {{created}}
+     */
+    /** Minimum ms between triggers. Enforced minimum: 5000. */
+    cooldownMs: number;
+}
+/** Minimal checkout result passed to handleBranchCheckout — avoids importing from gitWrite. */
+export interface BranchCheckoutResult {
+    branch: string;
+    previousBranch: string | null;
+    created: boolean;
+}
+export interface OnPullRequestPolicy extends PromptSource {
+    enabled: boolean;
+    /**
+     * Placeholders (inline prompt only): {{url}}, {{number}}, {{title}}, {{branch}}
+     */
+    /** Minimum ms between triggers. Enforced minimum: 5000. */
+    cooldownMs: number;
+}
+/** Minimal PR result passed to handlePullRequest — avoids importing from github/pr. */
+export interface PullRequestResult {
+    url: string;
+    number: number | null;
+    title: string;
+    branch: string;
+}
+export interface OnTaskCreatedPolicy extends PromptSource {
+    enabled: boolean;
+    /**
+     * Fired by Claude Code 2.1.84+ TaskCreated hook — fires when Claude creates a subagent task.
+     * Placeholders (inline prompt only): {{taskId}}, {{prompt}}
+     */
+    /** Minimum ms between triggers. Enforced minimum: 5000. */
+    cooldownMs: number;
+}
+/** Minimal task-created result passed to handleTaskCreated. */
+export interface TaskCreatedResult {
+    taskId: string;
+    prompt: string;
+}
+export interface OnPermissionDeniedPolicy extends PromptSource {
+    enabled: boolean;
+    /**
+     * Fired by Claude Code 2.1.89+ PermissionDenied hook — fires when a tool call is blocked.
+     * Placeholders (inline prompt only): {{tool}}, {{reason}}
+     */
+    /** Minimum ms between triggers. Enforced minimum: 5000. */
+    cooldownMs: number;
+}
+/** Minimal permission-denied result passed to handlePermissionDenied. */
+export interface PermissionDeniedResult {
+    tool: string;
+    reason: string;
+}
+export interface OnDiagnosticsClearedPolicy extends PromptSource {
+    enabled: boolean;
+    /** Placeholders (inline prompt only): {{file}} */
+    cooldownMs: number;
+}
+/**
+ * Unified diagnostics-state hook (v2.43.0+) — replaces `onDiagnosticsError`
+ * and `onDiagnosticsCleared` with a single schema entry carrying a `state`
+ * discriminator. Expanded at load time. Legacy names still accepted with a
+ * deprecation warning. Removed no earlier than v2.46 + 30 days.
+ */
+export type OnDiagnosticsStateChangePolicy = ({
+    state: "error";
+} & OnDiagnosticsErrorPolicy) | ({
+    state: "cleared";
+} & OnDiagnosticsClearedPolicy);
+export interface OnTaskSuccessPolicy extends PromptSource {
+    enabled: boolean;
+    /** Placeholders (inline prompt only): {{taskId}}, {{output}} */
+    cooldownMs: number;
+}
+/** Minimal task-success result passed to handleTaskSuccess. */
+export interface TaskSuccessResult {
+    taskId: string;
+    output: string;
+}
+export interface AutomationPolicy {
+    /**
+     * Default model for all automation tasks.
+     * Defaults to "claude-haiku-4-5-20251001" to minimise cost.
+     * Override with "claude-sonnet-4-6" etc. for hooks that need more reasoning.
+     */
+    defaultModel?: string;
+    /**
+     * Hard cap on automation tasks spawned per hour (rolling 60-min window).
+     * Defaults to 20. Set to 0 to disable.
+     */
+    maxTasksPerHour?: number;
+    /**
+     * Custom system prompt passed via --system-prompt to every automation subprocess.
+     * Replaces the default Claude Code system prompt, preventing CLAUDE.md from being
+     * loaded as workspace instructions. Keep it short — this is the biggest token lever.
+     * Default: a lean "be brief" prompt. Max 4096 chars.
+     */
+    automationSystemPrompt?: string;
+    /**
+     * Default effort level for all automation tasks (low/medium/high/max).
+     * Defaults to "low" — automation tasks rarely need deep reasoning.
+     * Override per-hook via the hook's own effort field.
+     */
+    defaultEffort?: "low" | "medium" | "high" | "max";
+    /** @deprecated v2.43.0 — use `onDiagnosticsStateChange` with `state: "error"`. */
+    onDiagnosticsError?: OnDiagnosticsErrorPolicy;
+    onFileSave?: OnFileSavePolicy;
+    /** Fired by Claude Code 2.1.83+ FileChanged hook — reacts to any file edit, not just explicit saves. */
+    onFileChanged?: OnFileChangedPolicy;
+    /** Fired by Claude Code 2.1.83+ CwdChanged hook — fires when CC's working directory changes. */
+    onCwdChanged?: OnCwdChangedPolicy;
+    /**
+     * Unified compaction hook (v2.43.0+) — replaces onPreCompact/onPostCompact.
+     * Expanded at load time into the internal `onPreCompact` or `onPostCompact`
+     * slot based on `phase`. Prefer this form in new policies.
+     */
+    onCompaction?: OnCompactionPolicy;
+    /** @deprecated v2.43.0 — use `onCompaction` with `phase: "post"`. Removed no earlier than v2.46 / 30 days. */
+    onPostCompact?: OnPostCompactPolicy;
+    /** @deprecated v2.43.0 — use `onCompaction` with `phase: "pre"`. Removed no earlier than v2.46 / 30 days. */
+    onPreCompact?: OnPreCompactPolicy;
+    /** Fired by Claude Code 2.1.76+ InstructionsLoaded hook — injects bridge status at session start. */
+    onInstructionsLoaded?: OnInstructionsLoadedPolicy;
+    /** Fired after every runTests call. Use `filter` to target failures / pass-after-fail / all runs. */
+    onTestRun?: OnTestRunPolicy;
+    /** Fired when a test run transitions from failing → passing for the same runner. */
+    onTestPassAfterFailure?: OnTestPassAfterFailurePolicy;
+    /** Fired after every successful gitCommit call. */
+    onGitCommit?: OnGitCommitPolicy;
+    /** Fired after every successful gitPush call. */
+    onGitPush?: OnGitPushPolicy;
+    /** Fired after every successful gitPull call. */
+    onGitPull?: OnGitPullPolicy;
+    /** Fired after every successful gitCheckout call (branch switch or creation). */
+    onBranchCheckout?: OnBranchCheckoutPolicy;
+    /** Fired after every successful githubCreatePR call. */
+    onPullRequest?: OnPullRequestPolicy;
+    /** Fired by Claude Code 2.1.84+ TaskCreated hook — fires when Claude creates a subagent task. */
+    onTaskCreated?: OnTaskCreatedPolicy;
+    /** Fired by Claude Code 2.1.89+ PermissionDenied hook — fires when a tool call is blocked. */
+    onPermissionDenied?: OnPermissionDeniedPolicy;
+    /**
+     * Unified diagnostics-state hook (v2.43.0+) — replaces onDiagnosticsError/
+     * onDiagnosticsCleared. Expanded at load time based on `state`.
+     */
+    onDiagnosticsStateChange?: OnDiagnosticsStateChangePolicy;
+    /** @deprecated v2.43.0 — use `onDiagnosticsStateChange` with `state: "cleared"`. */
+    onDiagnosticsCleared?: OnDiagnosticsClearedPolicy;
+    /** Fired when a Claude orchestrator task completes with status done. */
+    onTaskSuccess?: OnTaskSuccessPolicy;
+    /** Unified debug-session hook (v2.43.0+). Expanded to onDebugSessionStart/End based on phase. */
+    onDebugSession?: OnDebugSessionPolicy;
+    /** @deprecated v2.43.0 — use `onDebugSession` with `phase: "end"`. */
+    onDebugSessionEnd?: OnDebugSessionEndPolicy;
+    /** @deprecated v2.43.0 — use `onDebugSession` with `phase: "start"`. */
+    onDebugSessionStart?: OnDebugSessionStartPolicy;
+}
+export interface Diagnostic {
+    message: string;
+    severity: "error" | "warning" | "info" | "information" | "hint";
+    source?: string;
+    code?: string | number;
+}
+/**
+ * Deterministic signature over a diagnostic list — used for content-aware
+ * dedupe in onDiagnosticsError. Sorting by a stable key makes the signature
+ * order-independent so LSP re-emissions with the same diagnostics in a
+ * different order still collide.
+ */
+export declare function diagnosticSignature(diagnostics: Diagnostic[]): string;
+/** Load and validate a JSON automation policy file. Throws on any failure. */
+export declare function loadPolicy(filePath: string): AutomationPolicy;
+/**
+ * Check which CC hook events have at least one settings.json entry whose
+ * command references the matching bridge notify tool. Returns a map of
+ * CC event name → wired (boolean).
+ */
+export declare function checkCcHookWiring(): Record<string, boolean>;
+export declare class AutomationHooks {
+    private readonly policy;
+    private readonly log;
+    /** Compiled AST for the functional interpreter. Null if parse failed. */
+    private _programAST;
+    /** Backend instance for the functional interpreter. */
+    private _interpreterBackend;
+    /**
+     * Pure-value state holding cooldown timestamps, diagnostic error counts, and
+     * test outcomes.  Mutations go through the pure-function helpers from
+     * `src/fp/automationState.ts`; the class re-assigns `_automationState` on
+     * each "write" to maintain immutability semantics at the value level.
+     */
+    private _automationState;
+    /** Accumulated skip counts keyed by hook name → reason. */
+    private _skipCountsByHookAndReason;
+    /** Tracks previous error count per normalized file path for zero-transition detection. */
+    private prevDiagnosticErrors;
+    /**
+     * Per-runner last outcome — used to detect fail→pass transitions for onTestPassAfterFailure.
+     * Key: runner name. Value: "pass" | "fail".
+     */
+    private lastTestOutcomeByRunner;
+    private _lastFiredAt;
+    /** Last interpreter run promise — allows tests to await completion. */
+    private _lastRunPromise;
+    constructor(policy: AutomationPolicy, orchestrator: ClaudeOrchestrator, log: (msg: string) => void, _extensionClient?: ExtensionClient, _workspace?: string);
+    private _runInterpreter;
+    /**
+     * Returns a Promise that resolves once all in-flight interpreter runs finish.
+     * Useful in tests to await async side-effects before asserting on task counts.
+     */
+    flush(): Promise<void>;
+    /** Tear down the instance: nulls interpreter references. */
+    destroy(): void;
+    handleDiagnosticsChanged(file: string, diagnostics: Diagnostic[]): void;
+    /**
+     * Called when Claude Code fires a CwdChanged hook (Claude Code 2.1.83+).
+     * Fires when CC's working directory changes — useful for re-snapshotting workspace context.
+     */
+    handleCwdChanged(newCwd: string): void;
+    /**
+     * Called when Claude Code fires a PreCompact hook.
+     * Fires the onPreCompact automation hook before context trimming — use to snapshot state or
+     * write a handoff note before Claude loses context.
+     */
+    handlePreCompact(): void;
+    /**
+     * Called when Claude Code fires a PostCompact hook (Claude Code 2.1.76+).
+     * Re-enqueues the configured prompt so Claude can re-snapshot IDE state after losing context.
+     */
+    handlePostCompact(): void;
+    /**
+     * Called when Claude Code fires an InstructionsLoaded hook (Claude Code 2.1.76+).
+     * Fires once per session; injects bridge status / tool capability summary at start.
+     */
+    handleInstructionsLoaded(): void;
+    handleFileSaved(_id: string, type: string, file: string): void;
+    /**
+     * Called when the VS Code extension reports a file-changed event (type === "change").
+     * Distinct from handleFileSaved — reacts to any editor buffer change, not just explicit saves.
+     * Useful for triggering tasks on unsaved edits (e.g. lint-as-you-type workflows).
+     */
+    handleFileChanged(_id: string, type: string, file: string): void;
+    /**
+     * Called after every runTests tool invocation completes.
+     * Triggers an automation task when tests fail (or on every run if onFailureOnly is false).
+     */
+    handleTestRun(result: TestRunResult): void;
+    /**
+     * Called after a successful gitCommit tool call.
+     * Fires the onGitCommit automation hook if configured.
+     */
+    handleGitCommit(result: GitCommitResult): Promise<void>;
+    /**
+     * Called after a successful gitPush tool call.
+     * Fires the onGitPush automation hook if configured.
+     */
+    handleGitPush(result: GitPushResult): void;
+    /**
+     * Fires the onGitPull automation hook if configured.
+     */
+    handleGitPull(result: GitPullResult): void;
+    /**
+     * Called after a successful gitCheckout tool call.
+     * Fires the onBranchCheckout automation hook if configured.
+     */
+    handleBranchCheckout(result: BranchCheckoutResult): void;
+    /**
+     * Fires the onPullRequest automation hook if configured.
+     */
+    handlePullRequest(result: PullRequestResult): void;
+    handleTaskCreated(result: TaskCreatedResult): void;
+    handlePermissionDenied(result: PermissionDeniedResult): void;
+    /**
+     * Fires the onDiagnosticsCleared hook when a file transitions from non-zero to zero errors.
+     * Called internally by handleDiagnosticsChanged.
+     */
+    handleDiagnosticsCleared(normalizedFile: string): void;
+    /**
+     * Fires the onTaskSuccess hook when a Claude orchestrator task completes with status "done".
+     * Call from bridge.ts when a task transitions to done.
+     */
+    handleTaskSuccess(result: TaskSuccessResult): void;
+    /**
+     * Called when a VS Code debug session ends (hasActiveSession transitions true→false).
+     * Fires the onDebugSessionEnd automation hook if configured.
+     */
+    handleDebugSessionEnd(result: DebugSessionEndResult): Promise<void>;
+    /**
+     * Called when a VS Code debug session starts (hasActiveSession transitions false→true).
+     * Fires the onDebugSessionStart automation hook if configured.
+     */
+    handleDebugSessionStart(result: DebugSessionStartResult): Promise<void>;
+    /** Summary of automation policy for getBridgeStatus. */
+    getStatus(): {
+        onPreCompact: {
+            enabled: boolean;
+            cooldownMs: number;
+        } | null;
+        onPostCompact: {
+            enabled: boolean;
+            cooldownMs: number;
+        } | null;
+        onDiagnosticsError: {
+            enabled: boolean;
+        } | null;
+        onFileSave: {
+            enabled: boolean;
+            patternCount: number;
+        } | null;
+        onFileChanged: {
+            enabled: boolean;
+            patternCount: number;
+        } | null;
+        onCwdChanged: {
+            enabled: boolean;
+            cooldownMs: number;
+        } | null;
+        onTestRun: {
+            enabled: boolean;
+            onFailureOnly: boolean;
+            cooldownMs: number;
+        } | null;
+        onTestPassAfterFailure: {
+            enabled: boolean;
+            cooldownMs: number;
+        } | null;
+        onGitCommit: {
+            enabled: boolean;
+            cooldownMs: number;
+        } | null;
+        onGitPush: {
+            enabled: boolean;
+            cooldownMs: number;
+        } | null;
+        onBranchCheckout: {
+            enabled: boolean;
+            cooldownMs: number;
+        } | null;
+        onPullRequest: {
+            enabled: boolean;
+            cooldownMs: number;
+        } | null;
+        onTaskCreated: {
+            enabled: boolean;
+            cooldownMs: number;
+        } | null;
+        onInstructionsLoaded: {
+            enabled: boolean;
+            cooldownMs: number;
+        } | null;
+        onPermissionDenied: {
+            enabled: boolean;
+            cooldownMs: number;
+        } | null;
+        onDiagnosticsCleared: {
+            enabled: boolean;
+            cooldownMs: number;
+        } | null;
+        onTaskSuccess: {
+            enabled: boolean;
+            cooldownMs: number;
+        } | null;
+        onGitPull: {
+            enabled: boolean;
+            cooldownMs: number;
+        } | null;
+        onDebugSessionEnd: {
+            enabled: boolean;
+            cooldownMs: number;
+        } | null;
+        onDebugSessionStart: {
+            enabled: boolean;
+            cooldownMs: number;
+        } | null;
+        unwiredEnabledHooks: string[];
+        defaultModel: string;
+        maxTasksPerHour: number;
+        tasksThisHour: number;
+        defaultEffort: string;
+        automationSystemPrompt: string;
+    };
+    isPreCompactEnabled(): boolean;
+    getStats(): {
+        hooksEnabled: number;
+        lastFiredAt: string | null;
+        skipCountsByHookAndReason?: Record<string, Record<string, number>>;
+    };
+}