@qvac/harness 0.7.0 → 1.0.0-rc.0

package/dist-lib/lib/helpers/race-abort.js

@@ -1,10 +1,5 @@
-export class AbortedError extends Error {
-    constructor() {
-        super('aborted');
-        this.name = 'AbortedError';
-        Error.captureStackTrace?.(this, AbortedError);
-    }
-}
+import { AbortedError } from '../machine/index.js';
+export { AbortedError };
 export function raceAbort(promise, signal) {
     if (!signal)
         return promise;

package/dist-lib/lib/helpers/recovery-required.d.ts

@@ -0,0 +1 @@
+export { RecoveryRequired, type Operation } from '../machine/index.ts';

package/dist-lib/lib/helpers/recovery-required.js

@@ -0,0 +1 @@
+export { RecoveryRequired } from '../machine/index.js';

package/dist-lib/lib/helpers/run-outcome.d.ts

@@ -1,5 +1,6 @@
+import type { RunOutcome } from '../machine/index.ts';
 import type { ToolExecutionOutcome } from '../tool-call-display.ts';
-export type RunOutcome = 'answered' | 'mute' | 'exhausted' | 'search-capped' | 'time-capped';
+export type { RunOutcome };
 export declare const DEGENERATE_ANSWER_FALLBACK = "I couldn't complete that step and don't have a useful result to share.";
 export declare const ROUND_CAP_ANSWER = "I ran out of steps before I could finish that. Ask me to continue and I'll pick up where I left off.";
 export declare const SEARCH_CAPPED_ANSWER = "I searched the web but couldn't find the answer in the results I got.";
@@ -19,9 +20,16 @@ export interface RunOutcomeTracker {
     record(result: unknown, outcome: ToolExecutionOutcome): void;
     finishRound(): void;
     confirmWrite(result: unknown): void;
+    snapshot(): RunOutcomeState;
     facts(): RunOutcomeFacts;
 }
-export declare function createRunOutcomeTracker(): RunOutcomeTracker;
+export interface RunOutcomeState {
+    confirmedWrites: string[];
+    roundFailure: string | null;
+    latestFailure: string | null;
+    hasRoundResult: boolean;
+}
+export declare function createRunOutcomeTracker(state?: RunOutcomeState): RunOutcomeTracker;
 export declare function normalizeToolExecutionOutcome(result: unknown, outcome: ToolExecutionOutcome): ToolExecutionOutcome;
 export declare function failureFromToolExecution(result: unknown, outcome: ToolExecutionOutcome): string | null;
 export declare function degenerateAnswer(outcome: Exclude<RunOutcome, 'answered'>, history: ReadonlyArray<HistoryTurn>, facts?: RunOutcomeFacts): string;

package/dist-lib/lib/helpers/run-outcome.js

@@ -13,11 +13,11 @@ const TOOL_RESULT_HEADER_RE = /^\[Tool: [^(\]]+ \([^)]+\)\]\n/;
 const WEB_SEARCH_TURN_RE = /^\[Tool: web_search /;
 const RESULT_ENTRY_RE = /\[\d+\] ([^\n]+)\nSource: (\S+)/g;
 const WRITE_ID_RE = /[0-9a-f]{8}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{12}/gi;
-export function createRunOutcomeTracker() {
-    const confirmedWrites = [];
-    let roundFailure = null;
-    let latestFailure = null;
-    let hasRoundResult = false;
+export function createRunOutcomeTracker(state) {
+    const confirmedWrites = [...(state?.confirmedWrites ?? [])];
+    let roundFailure = state?.roundFailure ?? null;
+    let latestFailure = state?.latestFailure ?? null;
+    let hasRoundResult = state?.hasRoundResult ?? false;
     return {
         confirmedWrites,
         beginRound() {
@@ -42,6 +42,9 @@ export function createRunOutcomeTracker() {
                 confirmedWrites.push(write);
             }
         },
+        snapshot() {
+            return { confirmedWrites: [...confirmedWrites], roundFailure, latestFailure, hasRoundResult };
+        },
         facts() {
             return { latestFailure, confirmedWrites };
         }

package/dist-lib/lib/helpers/tool-call-markup.d.ts

@@ -10,6 +10,8 @@ export interface KnownTool {
     readonly name: string;
 }
 export declare function recoverMarkupToolCalls(text: string, knownTools: ReadonlyArray<KnownTool>): RecoveredToolCall[];
+export declare function redactToolCallMarkup(text: string, redactArgs: (name: string, args: Record<string, unknown>) => Record<string, unknown>): string;
+export declare function redactBareParameterMarkup(text: string, isSensitiveName: (name: string) => boolean): string;
 export declare function stripToolCallMarkup(text: string): string;
 export declare function stripToolResponseBlocks(text: string): string;
 export interface MarkupToolCall {

package/dist-lib/lib/helpers/tool-call-markup.js

@@ -1,47 +1,8 @@
 import { isRecord } from '../guards.js';
-const FUNCTION_OPEN = '<function=';
-const FUNCTION_CLOSE = '</function>';
+import { namedMarkupBlocks, scanNamedMarkup } from './markup-scanner.js';
 const TOOL_RESPONSE = { open: '<tool_response>', close: '</tool_response>' };
 const TOOL_CALL = { open: '<tool_call>', close: '</tool_call>' };
-const PARAMETER_OPEN = '<parameter=';
-const PARAMETER_CLOSE = '</parameter>';
 const MAX_NAME_LENGTH = 64;
-function* markupBlocks(text, open, close) {
-    let cursor = 0;
-    for (;;) {
-        const start = text.indexOf(open, cursor);
-        if (start === -1) {
-            return;
-        }
-        const nameStart = start + open.length;
-        cursor = nameStart;
-        const name = nameOf(text, nameStart);
-        if (name === null) {
-            continue;
-        }
-        const bodyStart = nameStart + name.length + 1;
-        const bodyEnd = text.indexOf(close, bodyStart);
-        if (bodyEnd === -1) {
-            return;
-        }
-        yield {
-            name: name.trim(),
-            body: text.slice(bodyStart, bodyEnd),
-            start,
-            end: bodyEnd + close.length
-        };
-        cursor = bodyEnd + close.length;
-    }
-}
-function nameOf(text, nameStart) {
-    const window = text.slice(nameStart, nameStart + MAX_NAME_LENGTH + 1);
-    const nameEnd = window.indexOf('>');
-    if (nameEnd === -1) {
-        return null;
-    }
-    const name = window.slice(0, nameEnd);
-    return name.includes('\n') ? null : name;
-}
 export const MAX_RAW_CALL_CHARS = 4096;
 export function clipRawCall(raw) {
     return raw.length > MAX_RAW_CALL_CHARS ? raw.slice(0, MAX_RAW_CALL_CHARS) : raw;
@@ -49,34 +10,172 @@ export function clipRawCall(raw) {
 export function recoverMarkupToolCalls(text, knownTools) {
     const known = new Set(knownTools.map((tool) => tool.name));
     const calls = [];
-    for (const block of markupBlocks(text, FUNCTION_OPEN, FUNCTION_CLOSE)) {
-        if (!block.name || !known.has(block.name))
+    for (const block of namedMarkupBlocks(text, 'function', MAX_NAME_LENGTH)) {
+        if (block.nested) {
+            calls.push(...recoverLegacyCalls(text.slice(block.start, block.end), known));
+            continue;
+        }
+        if (!block.name || !known.has(block.name)) {
             continue;
+        }
         calls.push({
-            id: `recovered-markup-${calls.length}`,
+            id: '',
             name: block.name,
-            arguments: decodeArguments(block.body),
+            arguments: decodeArguments(block.body).args,
             raw: clipRawCall(text.slice(block.start, block.end))
         });
     }
-    return calls;
+    return calls.map((call, index) => ({ ...call, id: `recovered-markup-${index}` }));
+}
+function recoverLegacyCalls(text, known) {
+    const calls = [];
+    let cursor = 0;
+    for (;;) {
+        const start = text.indexOf('<function=', cursor);
+        if (start === -1) {
+            return calls;
+        }
+        const nameStart = start + '<function='.length;
+        const nameEnd = text.indexOf('>', nameStart);
+        const close = nameEnd === -1 ? -1 : text.indexOf('</function>', nameEnd + 1);
+        if (nameEnd === -1 || nameEnd - nameStart > MAX_NAME_LENGTH || close === -1) {
+            return calls;
+        }
+        const name = text.slice(nameStart, nameEnd).trim();
+        const end = close + '</function>'.length;
+        if (name && known.has(name)) {
+            calls.push({
+                id: '',
+                name,
+                arguments: decodeLegacyArguments(text.slice(nameEnd + 1, close), 64),
+                raw: clipRawCall(text.slice(start, end))
+            });
+        }
+        cursor = end;
+    }
+}
+export function redactToolCallMarkup(text, redactArgs) {
+    let out = '';
+    let cursor = 0;
+    let changed = false;
+    for (const block of namedMarkupBlocks(text, 'function', Infinity)) {
+        const replacement = redactedMarkupBlock(block, redactArgs);
+        if (replacement === null) {
+            continue;
+        }
+        out += text.slice(cursor, block.start) + replacement;
+        cursor = block.end;
+        changed = true;
+    }
+    out += text.slice(cursor);
+    return changed ? out : text;
+}
+function redactedMarkupBlock(block, redactArgs) {
+    if (block.nested) {
+        return '<function=redacted></function>';
+    }
+    const { args: decoded, ambiguous } = decodeArguments(block.body, Infinity);
+    if (ambiguous) {
+        return `<function=${block.name}></function>`;
+    }
+    const redacted = redactArgs(block.name, decoded);
+    const replacement = deepEqual(decoded, redacted)
+        ? null
+        : markupForCall({ name: block.name, arguments: redacted });
+    return replacement;
+}
+export function redactBareParameterMarkup(text, isSensitiveName) {
+    if (!/<parameter/i.test(text)) {
+        return text;
+    }
+    let out = '';
+    let cursor = 0;
+    let changed = false;
+    for (;;) {
+        const open = scanNamedMarkup(text, 'parameter', { from: cursor, maxNameLength: Infinity }).token;
+        if (!open) {
+            break;
+        }
+        if (open.kind === 'close' || !isSensitiveName(open.name ?? '')) {
+            cursor = open.end;
+            continue;
+        }
+        const close = scanNamedMarkup(text, 'parameter', {
+            from: open.end,
+            maxNameLength: Infinity
+        }).token;
+        out += text.slice(cursor, open.end);
+        changed = true;
+        if (close?.kind === 'close') {
+            out += `[redacted]${text.slice(close.start, close.end)}`;
+            cursor = close.end;
+        }
+        else {
+            out += '[redacted]';
+            cursor = text.length;
+            break;
+        }
+    }
+    out += text.slice(cursor);
+    return redactRunOnParameterOpeners(changed ? out : text, isSensitiveName);
+}
+function redactRunOnParameterOpeners(text, isSensitiveName) {
+    const opener = /<parameter\s*=\s*([^\s<>]+)\s+(?=[^\s>])/gi;
+    const closer = /<\/parameter>/gi;
+    let out = '';
+    let cursor = 0;
+    for (let match = opener.exec(text); match; match = opener.exec(text)) {
+        if (!isSensitiveName(match[1])) {
+            continue;
+        }
+        const valueStart = match.index + match[0].length;
+        closer.lastIndex = valueStart;
+        const close = closer.exec(text);
+        out += `${text.slice(cursor, valueStart)}[redacted]`;
+        if (!close) {
+            return out;
+        }
+        cursor = close.index;
+        opener.lastIndex = close.index;
+    }
+    return cursor === 0 ? text : out + text.slice(cursor);
+}
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) {
+            return false;
+        }
+        return a.every((value, index) => deepEqual(value, b[index]));
+    }
+    if (!isRecord(a) || !isRecord(b)) {
+        return false;
+    }
+    const aKeys = Object.keys(a);
+    const bKeys = Object.keys(b);
+    if (aKeys.length !== bKeys.length) {
+        return false;
+    }
+    return aKeys.every((key) => Object.hasOwn(b, key) && deepEqual(a[key], b[key]));
 }
 export function stripToolCallMarkup(text) {
     let out = '';
     let cursor = 0;
-    for (const block of markupBlocks(text, FUNCTION_OPEN, FUNCTION_CLOSE)) {
+    for (const block of namedMarkupBlocks(text, 'function', MAX_NAME_LENGTH)) {
         out += text.slice(cursor, block.start);
         cursor = block.end;
     }
     out += text.slice(cursor);
-    const dangling = danglingIndex(out);
-    const withoutCalls = dangling === -1 ? out : out.slice(0, dangling);
-    const withoutSpans = stripSpans(stripToolResponseBlocks(withoutCalls), TOOL_CALL);
+    const withoutSpans = stripSpans(stripToolResponseBlocks(out), TOOL_CALL);
     return withoutSpans
         .replace(/<\/?(tool_call|tool_response)>/gi, '')
         .replace(/\n{3,}/g, '\n\n')
         .trim();
 }
+function lowerAscii(char) {
+    return char.toLowerCase();
+}
 function stripSpans(text, span) {
     const hay = text.replace(/[A-Z]/g, lowerAscii);
     let out = '';
@@ -95,26 +194,9 @@ function stripSpans(text, span) {
     }
     return out + text.slice(cursor);
 }
-function lowerAscii(char) {
-    return char.toLowerCase();
-}
 export function stripToolResponseBlocks(text) {
     return stripSpans(text, TOOL_RESPONSE);
 }
-function danglingIndex(text) {
-    let cursor = 0;
-    for (;;) {
-        const start = text.indexOf(FUNCTION_OPEN, cursor);
-        if (start === -1) {
-            return -1;
-        }
-        const nameStart = start + FUNCTION_OPEN.length;
-        if (nameOf(text, nameStart) !== null) {
-            return start;
-        }
-        cursor = nameStart;
-    }
-}
 export function toolCallMarkup(calls) {
     return calls.map(markupForCall).join('\n');
 }
@@ -156,24 +238,55 @@ export function normalizeToolArgs(args, declaredKeys) {
     }
     return args;
 }
-function decodeArguments(block) {
+function decodeArguments(block, maxNameLength = MAX_NAME_LENGTH) {
     const args = {};
-    for (const param of markupBlocks(block, PARAMETER_OPEN, PARAMETER_CLOSE)) {
+    let ambiguous = false;
+    for (const param of namedMarkupBlocks(block, 'parameter', maxNameLength)) {
         if (!param.name)
             continue;
-        const raw = param.body.trim();
-        try {
-            args[param.name] = JSON.parse(raw);
+        ambiguous ||= param.nested;
+        defineArgument(args, param.name, param.body);
+    }
+    return { args: ambiguous ? decodeLegacyArguments(block, maxNameLength) : args, ambiguous };
+}
+function decodeLegacyArguments(block, maxNameLength) {
+    const args = {};
+    let cursor = 0;
+    for (;;) {
+        const start = block.indexOf('<parameter=', cursor);
+        if (start === -1) {
+            return args;
         }
-        catch {
-            args[param.name] = raw;
+        const nameStart = start + '<parameter='.length;
+        const nameEnd = block.indexOf('>', nameStart);
+        if (nameEnd === -1 || nameEnd - nameStart > maxNameLength) {
+            return args;
+        }
+        const end = block.indexOf('</parameter>', nameEnd + 1);
+        if (end === -1) {
+            return args;
+        }
+        const name = block.slice(nameStart, nameEnd).trim();
+        if (name) {
+            defineArgument(args, name, block.slice(nameEnd + 1, end));
         }
+        cursor = end + '</parameter>'.length;
     }
-    return args;
+}
+function defineArgument(args, name, body) {
+    const raw = body.trim();
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        value = raw;
+    }
+    Object.defineProperty(args, name, { value, enumerable: true, configurable: true, writable: true });
 }
 export function recoverSkillNamedCall(text, skillNames, skillToolName) {
     const known = new Set(skillNames);
-    for (const block of markupBlocks(text, FUNCTION_OPEN, FUNCTION_CLOSE)) {
+    for (const block of namedMarkupBlocks(text, 'function', MAX_NAME_LENGTH)) {
         if (!known.has(block.name))
             continue;
         return [
@@ -190,13 +303,7 @@ export function recoverSkillNamedCall(text, skillNames, skillToolName) {
 const SKILL_LOAD_KEYS = new Set(['name', 'skill', 'skill_name', 'file', 'path', 'filename']);
 export function recoverPrintedSkillLoad(text, skillToolName) {
     for (const match of text.matchAll(/\{[^{}]*\}/g)) {
-        let candidate;
-        try {
-            candidate = JSON.parse(match[0]);
-        }
-        catch {
-            continue;
-        }
+        const candidate = parsePrintedCandidate(match[0]);
         if (!isPlainObject(candidate)) {
             continue;
         }
@@ -223,3 +330,11 @@ export function recoverPrintedSkillLoad(text, skillToolName) {
     }
     return [];
 }
+function parsePrintedCandidate(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}

package/dist-lib/lib/hooks/built-in/arg-repair.d.ts

@@ -1,5 +1,6 @@
 import type { HarnessHook, HookContext, HookResult } from '../types.ts';
 export declare class ArgRepairHook implements HarnessHook {
+    readonly name = "arg-repair";
     readonly phase: 'preToolCall';
     run(ctx: HookContext): HookResult;
 }

package/dist-lib/lib/hooks/built-in/arg-repair.js

@@ -3,6 +3,7 @@ import { isRecord } from '../../guards.js';
 import { hlog } from '../../log.js';
 const STRUCTURED_TYPES = new Set(['object', 'array']);
 export class ArgRepairHook {
+    name = 'arg-repair';
     phase = 'preToolCall';
     run(ctx) {
         if (ctx.phase !== 'preToolCall' || !ctx.parameters)

package/dist-lib/lib/hooks/built-in/egress.d.ts

@@ -1,5 +1,6 @@
 import type { HarnessHook, HookContext, HookResult } from '../types.ts';
 export declare class EgressGuardHook implements HarnessHook {
+    readonly name = "egress-guard";
     readonly phase: 'preToolCall';
     run(ctx: HookContext): HookResult;
 }

package/dist-lib/lib/hooks/built-in/egress.js

@@ -1,6 +1,7 @@
 import { mcpTargetUrl } from '../../tools/mcp-call.js';
 import { checkOutboundHost } from '../../tools/url-guard.js';
 export class EgressGuardHook {
+    name = 'egress-guard';
     phase = 'preToolCall';
     run(ctx) {
         if (ctx.phase !== 'preToolCall')
@@ -24,7 +25,7 @@ export class EgressGuardHook {
         }
         const blocked = checkOutboundHost(url);
         if (blocked) {
-            return { error: blocked, guidance: true };
+            return { kind: 'hook-rejection', error: blocked, guidance: true };
         }
     }
 }

package/dist-lib/lib/hooks/built-in/sandbox.d.ts

@@ -1,5 +1,6 @@
 import type { HarnessHook, HookContext, HookResult } from '../types.ts';
 export declare class SandboxHook implements HarnessHook {
+    readonly name = "sandbox";
     readonly phase: 'preToolCall';
     run(ctx: HookContext): HookResult;
 }

package/dist-lib/lib/hooks/built-in/sandbox.js

@@ -26,6 +26,7 @@ const NETWORK_BINS = new Set([
     'openssl'
 ]);
 export class SandboxHook {
+    name = 'sandbox';
     phase = 'preToolCall';
     run(ctx) {
         if (ctx.phase !== 'preToolCall')
@@ -34,7 +35,11 @@ export class SandboxHook {
             return;
         const bin = bareBin(firstCommandToken(String(ctx.args.command ?? '')).replace(/^.*[/\\]/, ''));
         if (bin && NETWORK_BINS.has(bin)) {
-            return { error: `sandbox mode: ${bin} reaches the network`, guidance: true };
+            return {
+                kind: 'hook-rejection',
+                error: `sandbox mode: ${bin} reaches the network`,
+                guidance: true
+            };
         }
     }
 }

package/dist-lib/lib/hooks/built-in/skill-catalog.d.ts

@@ -2,6 +2,7 @@ import type { SkillCatalogEntry } from '../../tools/skills/catalog.ts';
 import type { HarnessHook, HookContext, HookResult } from '../types.ts';
 type SkillCatalogInput = readonly SkillCatalogEntry[] | (() => readonly SkillCatalogEntry[] | readonly string[]);
 export declare class SkillCatalogGuardHook implements HarnessHook {
+    readonly name = "skill-catalog";
     readonly phase: 'preToolCall';
     private readonly _catalog;
     constructor(catalog?: SkillCatalogInput);

package/dist-lib/lib/hooks/built-in/skill-catalog.js

@@ -1,4 +1,5 @@
 export class SkillCatalogGuardHook {
+    name = 'skill-catalog';
     phase = 'preToolCall';
     _catalog;
     constructor(catalog = []) {
@@ -18,6 +19,6 @@ export class SkillCatalogGuardHook {
         const rest = listed
             ? `The only skills are: ${listed}. Nothing else needs a skill load — answer or act with the tools you already have.`
             : 'No skill is available this turn — answer or act with the tools you already have.';
-        return { error: `skill not found: ${name}. ${rest}`, guidance: true };
+        return { kind: 'hook-rejection', error: `skill not found: ${name}. ${rest}`, guidance: true };
     }
 }

package/dist-lib/lib/hooks/pipeline.d.ts

@@ -1,5 +1,5 @@
 import type { ToolExecutionOutcome } from '../tool-call-display.ts';
-import type { HarnessHook, HookRejection, PostToolCallPayload, PreToolCallPayload, RunEndPayload, RunStartPayload } from './types.ts';
+import type { HarnessHook, HookRejection, HookPhase, PostToolCallPayload, PreToolCallPayload, RunEndPayload, RunLifecyclePayload, RunStartPayload } from './types.ts';
 export type PreToolFold = {
     ok: true;
     args: Record<string, unknown>;
@@ -11,9 +11,12 @@ export interface PostToolFold {
     result: unknown;
     outcome?: ToolExecutionOutcome;
 }
+export declare function snapshotHooks(hooks?: readonly HarnessHook[]): readonly HarnessHook[];
 export declare class HookPipeline {
     private readonly _behaviorHooks;
     constructor(hooks?: readonly HarnessHook[]);
+    hasPhase(phase: HookPhase): boolean;
+    onRunLifecycle(payload: RunLifecyclePayload): Promise<void>;
     onRunStart(payload: Omit<RunStartPayload, 'phase'>): Promise<void>;
     onRunEnd(payload: Omit<RunEndPayload, 'phase'>): Promise<void>;
     runPreToolFold(payload: Omit<PreToolCallPayload, 'phase'>): Promise<PreToolFold>;

package/dist-lib/lib/hooks/pipeline.js

@@ -2,10 +2,28 @@ import { hlog } from '../log.js';
 import { normalizeToolExecutionOutcome } from '../helpers/run-outcome.js';
 import { harnessHooks } from './registry.js';
 import { runHooks } from './run.js';
+export function snapshotHooks(hooks = harnessHooks) {
+    const phaseCounts = new Map();
+    return Object.freeze(hooks.map((hook) => {
+        const count = (phaseCounts.get(hook.phase) ?? 0) + 1;
+        phaseCounts.set(hook.phase, count);
+        const name = hook.name?.trim() || `${hook.phase}:${count}`;
+        return Object.freeze({ phase: hook.phase, name, run: hook.run.bind(hook) });
+    }));
+}
 export class HookPipeline {
     _behaviorHooks;
     constructor(hooks = harnessHooks) {
-        this._behaviorHooks = hooks;
+        this._behaviorHooks = snapshotHooks(hooks);
+    }
+    hasPhase(phase) {
+        return this._behaviorHooks.some((hook) => hook.phase === phase);
+    }
+    async onRunLifecycle(payload) {
+        const folded = await runHooks(this._behaviorHooks, payload);
+        if ('guidance' in folded) {
+            hlog('run hook failed', { stage: payload.phase, error: folded.error });
+        }
     }
     async onRunStart(payload) {
         const folded = await runHooks(this._behaviorHooks, { phase: 'runStart', ...payload });
@@ -22,7 +40,11 @@ export class HookPipeline {
     async runPreToolFold(payload) {
         const folded = await runHooks(this._behaviorHooks, { phase: 'preToolCall', ...payload });
         if ('guidance' in folded) {
-            hlog('tool rejected: pre-hook refused the call', { tool: payload.toolName });
+            hlog('tool rejected: pre-hook refused the call', {
+                tool: payload.toolName,
+                hook: folded.hook,
+                phase: folded.phase
+            });
             return { ok: false, rejection: folded };
         }
         return { ok: true, args: folded.args };

package/dist-lib/lib/hooks/run.d.ts

@@ -1,5 +1,6 @@
-import type { HarnessHook, HookRejection, PostToolCallPayload, PreToolCallPayload, RunEndPayload, RunStartPayload } from './types.ts';
+import type { HarnessHook, HookRejection, PostToolCallPayload, PreToolCallPayload, RunEndPayload, RunLifecyclePayload, RunStartPayload } from './types.ts';
 export declare function runHooks(hooks: readonly HarnessHook[], ctx: PreToolCallPayload): Promise<PreToolCallPayload | HookRejection>;
 export declare function runHooks(hooks: readonly HarnessHook[], ctx: PostToolCallPayload): Promise<PostToolCallPayload | HookRejection>;
 export declare function runHooks(hooks: readonly HarnessHook[], ctx: RunStartPayload): Promise<RunStartPayload | HookRejection>;
 export declare function runHooks(hooks: readonly HarnessHook[], ctx: RunEndPayload): Promise<RunEndPayload | HookRejection>;
+export declare function runHooks(hooks: readonly HarnessHook[], ctx: RunLifecyclePayload): Promise<RunLifecyclePayload | HookRejection>;

package/dist-lib/lib/hooks/run.js

@@ -35,8 +35,8 @@ function freshContext(ctx) {
 function isRejection(value) {
     return 'error' in value;
 }
-function rejection(value) {
-    return { error: String(value.error), guidance: true };
+function rejection(value, hook, phase) {
+    return { kind: 'hook-rejection', hook, phase, error: String(value.error), guidance: true };
 }
 function merge(current, returned) {
     if (current.phase === 'preToolCall' && 'args' in returned) {
@@ -53,34 +53,46 @@ function merge(current, returned) {
     }
     return current;
 }
-function rejectionOf(current, err) {
+function rejectionOf(current, err, hook) {
     const message = errorMessage(err);
-    hlog('hook failed', { stage: current.phase, error: message });
+    hlog('hook failed', { stage: current.phase, hook, error: message });
     if (current.phase === 'postToolCall') {
         return {
+            kind: 'hook-rejection',
+            hook,
+            phase: current.phase,
             error: `tool executed; output withheld: post-hook failed: ${message}. Do not retry this call.`,
             guidance: true
         };
     }
-    return { error: `hook failed in ${current.phase}: ${message}`, guidance: true };
+    return {
+        kind: 'hook-rejection',
+        hook,
+        phase: current.phase,
+        error: `hook failed in ${current.phase}: ${message}`,
+        guidance: true
+    };
 }
 export async function runHooks(hooks, ctx) {
     let current = ctx;
+    let phaseIndex = 0;
     for (const hook of hooks) {
         if (hook.phase !== current.phase)
             continue;
+        phaseIndex++;
+        const hookId = hook.name?.trim() || `${current.phase}:${phaseIndex}`;
         try {
             const returned = await hook.run(freshContext(current));
             if (!returned || typeof returned !== 'object') {
                 continue;
             }
             if (isRejection(returned)) {
-                return rejection(returned);
+                return rejection(returned, hookId, current.phase);
             }
             current = merge(current, returned);
         }
         catch (err) {
-            return rejectionOf(current, err);
+            return rejectionOf(current, err, hookId);
         }
     }
     return current;