/** * `openlore hook ` (change: add-agent-loop-hook-surfaces). * * One command per moment of the agent loop, wired by `openlore install` into the harness's hook * events, so the agent receives OpenLore's deterministic receipts without having to call a tool: * * | Moment | Claude Code event | Receipt | * |---------------|------------------------------|-------------------------------------------------------------| * | `before-edit` | `PreToolUse` (edit tools) | the target is a generated file: its source and command | * | `after-tools` | `PostToolUse` (edit tools) | the edit recorded for the session ledger; new ledger facts; | * | | | generated-file, phantom-reference and check-weakening facts | * | | | for the edited file | * | `before-stop` | `Stop` | the `verify_change` receipt for the session's diff, shown | * | | | to the user; the agent sees it only as a policy block | * | `after-compact` | `SessionStart` (`compact`) | the handoff briefing of the in-flight change | * | `before-subagent` | `PreToolUse` (`Agent|Task`) | nothing: queues the sub-agent's task | * | `subagent-start` | `SubagentStart` | the sub-agent's task-scoped briefing and the board's peers | * * Every hook reads the harness payload from stdin and prints at most one budgeted receipt as the * event's `additionalContext`; it prints nothing when it has nothing new. A fact already delivered * under the payload's `session_id` is not repeated. Hooks are advisory: they exit 0, and on a * timeout or an error they print nothing. Only a finding code the repository's `enforcement.policy` * makes blocking can block, and only at `before-stop`. A moment is turned off with * `hooks.: false` in `.openlore/config.json`. */ import { Command } from 'commander'; import { type HookOutcome } from '../../core/services/hook-health.js'; import { HOOK_MOMENTS, type FindingProof, type HookMoment } from '../../core/services/hook-session.js'; export { HOOK_MOMENTS, type HookMoment }; /** The harness event each moment is wired to (Claude Code). */ export declare const HOOK_EVENT: Record; /** * Hard time limit per moment, timed in-process; past it the hook prints nothing. before-edit, * after-tools, and before-stop were set from measurement (hook-reliability design section 2, * `npm run bench:hooks`); each stays below its harness timeout in `MANAGED_HOOKS`. */ export declare const TIMEOUT_MS: Record; /** * One fact for the receipt. `code`, `subject`, and `proof` give its identity for the per-session * dedupe (`findingIdentity`; without a code, the `key` is the identity); `key` is still recorded * for an older CLI reading the same session record. */ /** * What the agent does with a finding (change: reframe-governance-as-agent-evidence, design 4): * `fix` — the repair is in its own diff; `decide` — a trade-off it may take (and record); * `raise` — only a human can accept it. */ export type HookAction = 'fix' | 'decide' | 'raise'; export interface HookItem { key: string; severity: string; text: string; next?: string; action?: HookAction; code?: string; subject?: string; proof?: FindingProof; id?: string; check?: string; file?: string; } /** A finding item states its evidence: a file, a cited line, or a receipt discriminator. */ export declare function hasProof(item: HookItem): boolean; export interface HookPayload { sessionId?: string; cwd?: string; toolName?: string; /** Files the tool call writes, as given (absolute or relative). */ files: string[]; /** The shell command of a shell tool call, and its exit status when the payload carries one. */ command?: string; exit?: number; /** The shell call was interrupted before it finished. */ interrupted?: boolean; stopHookActive: boolean; /** An Agent/Task tool call: the sub-agent's task and type. */ agentPrompt?: string; subagentType?: string; /** A SubagentStart event: the starting sub-agent's type. */ agentType?: string; /** An edit tool call's pending change: Write's content, or Edit/MultiEdit's replacements. */ edit?: { content?: string; edits?: Array<{ oldString: string; newString: string; replaceAll: boolean; }>; }; } /** Read the fields OpenLore uses from a harness hook payload (Claude Code's shape). */ export declare function parseHookPayload(raw: string): HookPayload; /** The files a Codex `apply_patch` patch adds, updates, deletes, or moves to, in order, once each. */ export declare function patchFiles(patch: string): string[]; /** * The text a pending edit would produce from `current` (null: the file does not exist), or undefined * when it cannot be told exactly — an old string that is absent or (without replace-all) not unique, * as the edit tool itself would refuse it. */ export declare function applyPendingEdit(current: string | null, edit: NonNullable): string | undefined; /** * A payload path as a root-relative path with forward slashes, or `undefined` when it is outside * the repository. The file need not exist yet (a `Write` of a new file). */ export declare function repoPath(root: string, file: string): string | undefined; /** Keep the most severe items within the budget; the rest are counted. */ export declare function renderReceipt(moment: HookMoment, items: HookItem[], budgetChars?: number): string | null; /** Each certificate's own limit inside before-stop, and its item cap (change: * reframe-governance-as-agent-evidence, design section 3). */ export declare const CERTIFICATE_MS = 10000; /** * Run one certificate source. Its items (at most {@link CERTIFICATE_ITEMS}), or none when it throws, * rejects, or passes its limit: a certificate that did not finish says nothing, never "passed". */ export declare function certificateSlice(run: () => Promise, ms?: number): Promise; /** The files whose exports the public-surface certificate classifies. */ export declare const PUBLIC_SURFACE_FILE: RegExp; /** The files the service-contract reader may accept (OpenAPI, protobuf, GraphQL). */ export declare const CONTRACT_FILE: RegExp; export interface HookRunResult { stdout: string; exitCode: 0; } /** What one run did, for the hook-health record (change: hook-reliability, task 6.1). */ export interface HookRunReport { root?: string; outcome: HookOutcome; shown: number; reason?: string; } /** * Run one moment over a payload, then SCREEN the result. * * Never throws and always exits 0: a timeout or an error prints nothing. Exported for tests; the * CLI prints `stdout`. * * Screening happens here rather than in each moment, because every moment's payload is * repository-derived text going straight into model context and only `subagent-start` screened its * own. The class only removes characters inside the JSON's string literals, so the harness still * parses exactly one object. */ export declare function runHook(moment: HookMoment, raw: string, opts?: { cwd?: string; timeoutMs?: number; userScope?: boolean; onRun?: (report: HookRunReport) => void; }): Promise; export declare const hookCommand: Command; //# sourceMappingURL=hook.d.ts.map