@qvac/harness 1.0.0-rc.1 → 1.0.0-rc.2

package/dist-lib/lib/agent/plan.js

@@ -0,0 +1,74 @@
+export const PLAN_TOOL_NAME = 'update_plan';
+export const MAX_PLAN_STEPS = 12;
+const STATUSES = ['pending', 'in_progress', 'done'];
+const PARAMETERS = {
+    type: 'object',
+    properties: {
+        steps: {
+            type: 'array',
+            description: `At most ${MAX_PLAN_STEPS} steps, one line each`,
+            items: {
+                type: 'object',
+                properties: {
+                    step: { type: 'string' },
+                    status: { type: 'string', enum: [...STATUSES] }
+                },
+                required: ['step', 'status']
+            }
+        },
+        submit: { type: 'boolean', description: 'Plan mode only: ask the user to approve the plan' }
+    },
+    required: ['steps']
+};
+function isStep(value) {
+    const { step, status } = Object(value);
+    return typeof step === 'string' && step.trim() !== '' && STATUSES.includes(status);
+}
+function planError(args) {
+    const { steps, submit } = args;
+    if (!Array.isArray(steps) || !steps.length || !steps.every(isStep)) {
+        return `steps must be a list of 1 to ${MAX_PLAN_STEPS} items, each { step, status } with status pending, in_progress or done`;
+    }
+    if (steps.length > MAX_PLAN_STEPS) {
+        return `a plan holds at most ${MAX_PLAN_STEPS} steps; merge some`;
+    }
+    if (steps.filter((step) => step.status === 'in_progress').length > 1) {
+        return 'only one step may be in_progress at a time';
+    }
+    return submit === undefined || typeof submit === 'boolean' ? null : 'submit must be true or false';
+}
+export function planSteps(args) {
+    const steps = Array.isArray(args.steps) ? args.steps : [];
+    return steps
+        .filter(isStep)
+        .map(({ step, status }) => ({ step: step.replace(/\s+/g, ' ').trim(), status }));
+}
+export function planFromMessages(messages) {
+    const call = messages
+        .flatMap((message) => message.toolCalls ?? [])
+        .findLast((entry) => entry.name === PLAN_TOOL_NAME && !planError(entry.arguments));
+    const steps = call ? planSteps(call.arguments) : [];
+    return steps.every((step) => step.status === 'done') ? [] : steps;
+}
+export function createPlanTool() {
+    const submits = (args, ctx) => ctx?.planMode === true && args.submit === true;
+    return {
+        name: PLAN_TOOL_NAME,
+        toolset: null,
+        description: 'Keep a short plan for a request that takes several steps. Each call replaces the whole ' +
+            'list: mark the step you are on in_progress and finished ones done. You see the plan ' +
+            'after each tool round. In plan mode writes are refused until the user approves: send ' +
+            'the plan with submit true to ask them.',
+        parameters: PARAMETERS,
+        effect: (args, ctx) => (submits(args, ctx) ? 'write' : 'read'),
+        validate: planError,
+        quote: (args) => planError(args)
+            ? null
+            : planSteps(args)
+                .map(({ step }, at) => `${at + 1}. ${step}`)
+                .join('\n'),
+        execute: (args, ctx) => Promise.resolve({
+            content: submits(args, ctx) ? 'Plan approved. Carry it out.' : 'Plan saved.'
+        })
+    };
+}

package/dist-lib/lib/agent/resolve.d.ts

@@ -0,0 +1,3 @@
+import type { AgentConfig, AgentPolicy, AgentPorts, AgentRequest, AgentSkill, ResolvedAgent } from '../contract/index.ts';
+export declare function agentPolicy(agent: AgentConfig | undefined): AgentPolicy;
+export declare function resolveAgent<Skill extends AgentSkill>(request: AgentRequest<Skill>, ports: AgentPorts<Skill>): ResolvedAgent<Skill>;

package/dist-lib/lib/agent/resolve.js

@@ -0,0 +1,78 @@
+import { selectEnabledTools } from './tools.js';
+import { collectToolGrants, isSelected, NETWORK_TOOLSETS, permittedTools, skillIsActive, skillsAreSelected } from './tool-selection.js';
+import { createPlanTool } from './plan.js';
+import { createTransferTool } from './transfer.js';
+export function agentPolicy(agent) {
+    return { sandbox: agent?.sandboxMode === true, skipApprovals: agent?.approvalMode === 'skip-all' };
+}
+export function resolveAgent(request, ports) {
+    const { agent, messages, fsRoots, fsWriteRoots } = request;
+    const disabledToolsets = agent?.sandboxMode
+        ? [...(agent.disabledToolsets ?? []), ...NETWORK_TOOLSETS]
+        : agent?.disabledToolsets;
+    const writableRoots = [
+        ...fsWriteRoots,
+        ...fsRoots.filter((root) => root.kind === 'hyper' && root.writable && !fsWriteRoots.includes(root))
+    ];
+    const skillsSelected = skillsAreSelected(agent?.skillsScope, Boolean(agent));
+    const mention = ports.mention(messages, request.skills);
+    const activation = {
+        skillsSelected,
+        enabledSkills: agent?.enabledSkills ?? [],
+        mention: mention?.name ?? null,
+        loadedSkills: new Set(request.loadedSkills)
+    };
+    const activeSkills = request.skills.filter((skill) => skillIsActive(skill.name, activation));
+    const { grantedNames, grantedOwners, grantedOps } = collectToolGrants(activeSkills);
+    const selection = {
+        responseFormat: Boolean(request.responseFormat),
+        tools: permittedTools([...request.tools], disabledToolsets),
+        toolsSelected: isSelected(agent?.toolsScope, agent?.enabledTools),
+        allowlist: agent?.enabledTools ?? [],
+        activeSkills,
+        grantedNames,
+        grantedOwners,
+        hasRoots: fsRoots.length > 0,
+        hasWriteRoots: writableRoots.length > 0
+    };
+    const transfer = agent?.handoffs?.length && !request.responseFormat ? [createTransferTool(agent.handoffs)] : [];
+    const plan = (agent?.plan || request.planning || request.planMode) && !request.responseFormat
+        ? [createPlanTool()]
+        : [];
+    const select = (loaded) => [
+        ...selectEnabledTools({ ...selection, loadedSkills: new Set(loaded) }),
+        ...plan,
+        ...transfer
+    ];
+    const enabled = select(activation.loadedSkills);
+    return {
+        enabled,
+        system: ports.systemPrompt({
+            bio: agent?.bio,
+            toolNames: enabled.map((tool) => tool.name),
+            skills: activeSkills
+        }),
+        activation,
+        activeSkills,
+        mention,
+        preload: mention ?? ports.implicitSkill(messages, activeSkills),
+        grantedOps,
+        writableRoots,
+        generationParams: generationParams(request, ports),
+        policy: agentPolicy(agent),
+        select
+    };
+}
+function generationParams({ agent, model, thinkingDefault, generationParams: override }, ports) {
+    const resolved = ports.generationParams(model, settingEnabled(agent?.reasoning), settingEnabled(thinkingDefault));
+    return override ? { ...resolved, ...override } : resolved;
+}
+function settingEnabled(value) {
+    if (value === 'enabled') {
+        return true;
+    }
+    if (value === 'disabled') {
+        return false;
+    }
+    return undefined;
+}

package/dist-lib/lib/{capabilities → agent}/tool-names.d.ts

@@ -1,3 +1,2 @@
 export declare const SKILL_TOOL_NAME = "skill";
 export declare const WEB_SEARCH_TOOL_NAME = "web_search";
-export declare const MCP_CALL_TOOL_NAME = "mcp_call";

package/dist-lib/lib/{capabilities → agent}/tool-names.js

@@ -1,3 +1,2 @@
 export const SKILL_TOOL_NAME = 'skill';
 export const WEB_SEARCH_TOOL_NAME = 'web_search';
-export const MCP_CALL_TOOL_NAME = 'mcp_call';

package/dist-lib/lib/{capabilities → agent}/tool-selection.d.ts

@@ -1,3 +1,4 @@
+import type { SkillActivation, Toolset, ToolsetScoped } from '../contract/index.ts';
 export interface ToolGrantSource<T extends {
     bin: string;
 }> {
@@ -15,12 +16,6 @@ export interface ToolGrants<T extends {
 export declare function collectToolGrants<T extends {
     bin: string;
 }>(skills: ReadonlyArray<ToolGrantSource<T>>): ToolGrants<T>;
-export interface SkillActivation {
-    skillsSelected: boolean;
-    enabledSkills: ReadonlyArray<string>;
-    mention: string | null;
-    loadedSkills: ReadonlySet<string>;
-}
 export declare function skillsAreSelected(scope: 'all' | 'selected' | null | undefined, hasAgent: boolean): boolean;
 export declare function skillIsActive(name: string, { skillsSelected, enabledSkills, mention, loadedSkills }: SkillActivation): boolean;
 export interface SelectableTool {
@@ -42,3 +37,5 @@ export interface ToolGateInputs {
 }
 export declare function isSelected(scope: 'all' | 'selected' | null | undefined, list?: ReadonlyArray<string> | null): boolean;
 export declare function enabledTools<T extends SelectableTool>(tools: ReadonlyArray<T>, { toolsSelected, allowlist, grantedNames, grantedOwners, loadedGrantedNames, hasRoots, hasWriteRoots, hasActiveSkills }: ToolGateInputs): T[];
+export declare const NETWORK_TOOLSETS: ReadonlyArray<Toolset>;
+export declare function permittedTools<T extends ToolsetScoped>(tools: ReadonlyArray<T>, disabled?: ReadonlyArray<string> | null): T[];

package/dist-lib/lib/{capabilities → agent}/tool-selection.js

@@ -1,4 +1,4 @@
-import { parseToolGrant } from '../tools/skills/tool-grants.js';
+import { parseToolGrant } from './tool-grants.js';
 import { SKILL_TOOL_NAME, WEB_SEARCH_TOOL_NAME } from './tool-names.js';
 export function collectToolGrants(skills) {
     const grants = {
@@ -59,3 +59,11 @@ export function enabledTools(tools, { toolsSelected, allowlist, grantedNames, gr
         return allowlist.includes(tool.name) || grantedNames.has(tool.name);
     });
 }
+export const NETWORK_TOOLSETS = ['web-search', 'http-request', 'mcp-call'];
+export function permittedTools(tools, disabled) {
+    if (!disabled?.length) {
+        return [...tools];
+    }
+    const off = new Set(disabled);
+    return tools.filter((tool) => !tool.toolset || !off.has(tool.toolset));
+}

package/dist-lib/lib/agent/tools.d.ts

@@ -0,0 +1,14 @@
+import type { AgentSkill, ToolDefinition } from '../contract/index.ts';
+export interface ToolSelectionInputs {
+    responseFormat: boolean;
+    tools: readonly ToolDefinition[];
+    toolsSelected: boolean;
+    allowlist: ReadonlyArray<string>;
+    activeSkills: readonly AgentSkill[];
+    loadedSkills: ReadonlySet<string>;
+    grantedNames: ReadonlySet<string>;
+    grantedOwners: ReadonlyMap<string, ReadonlySet<string>>;
+    hasRoots: boolean;
+    hasWriteRoots: boolean;
+}
+export declare function selectEnabledTools(inputs: ToolSelectionInputs): ToolDefinition[];

package/dist-lib/lib/agent/tools.js

@@ -0,0 +1,16 @@
+import { collectToolGrants, enabledTools } from './tool-selection.js';
+export function selectEnabledTools(inputs) {
+    if (inputs.responseFormat)
+        return [];
+    const loaded = inputs.activeSkills.filter((skill) => inputs.loadedSkills.has(skill.name));
+    return enabledTools(inputs.tools, {
+        toolsSelected: inputs.toolsSelected,
+        allowlist: inputs.allowlist,
+        grantedNames: inputs.grantedNames,
+        grantedOwners: inputs.grantedOwners,
+        loadedGrantedNames: collectToolGrants(loaded).grantedNames,
+        hasRoots: inputs.hasRoots,
+        hasWriteRoots: inputs.hasWriteRoots,
+        hasActiveSkills: inputs.activeSkills.length > 0
+    });
+}

package/dist-lib/lib/agent/transfer.d.ts

@@ -0,0 +1,7 @@
+import type { AgentHandoff, ToolDefinition } from '../contract/index.ts';
+export declare const TRANSFER_TOOL_NAME = "transfer_to_agent";
+export interface TransferResult {
+    readonly transferred: string;
+    readonly reason: string;
+}
+export declare function createTransferTool(handoffs: readonly AgentHandoff[]): ToolDefinition;

package/dist-lib/lib/agent/transfer.js

@@ -0,0 +1,26 @@
+export const TRANSFER_TOOL_NAME = 'transfer_to_agent';
+export function createTransferTool(handoffs) {
+    const ids = handoffs.map((handoff) => handoff.id);
+    const roster = handoffs.map((handoff) => `- ${handoff.id}: ${handoff.description}`).join('\n');
+    return {
+        name: TRANSFER_TOOL_NAME,
+        toolset: null,
+        description: 'Hand the conversation to another agent that is better suited to it. The other agent ' +
+            `answers the user next; do not answer yourself after transferring. Agents:\n${roster}`,
+        parameters: {
+            type: 'object',
+            properties: {
+                agent: { type: 'string', enum: ids, description: 'The agent to hand to' },
+                reason: { type: 'string', description: 'What the user needs, in one sentence' }
+            },
+            required: ['agent', 'reason']
+        },
+        autoApprove: true,
+        endsRun: true,
+        effect: () => 'read',
+        validate: (args) => typeof args.agent === 'string' && ids.includes(args.agent)
+            ? null
+            : `agent must be one of ${ids.join(', ')}`,
+        execute: (args) => Promise.resolve({ transferred: String(args.agent), reason: String(args.reason ?? '') })
+    };
+}

package/dist-lib/lib/capabilities/agent-ports.d.ts

@@ -0,0 +1,3 @@
+import type { AgentPorts } from '../contract/index.ts';
+import type { CompletionSkillEntry } from './skill-entry.ts';
+export declare const defaultAgentPorts: AgentPorts<CompletionSkillEntry>;

package/dist-lib/lib/capabilities/agent-ports.js

@@ -0,0 +1,9 @@
+import { resolveLlmGenerationParams } from '../models/llm-presets.js';
+import { lastUserContent, skillsPromptSection, systemPromptParts } from '../prompt.js';
+import { resolveImplicitSkill, resolveSkillMention } from '../tools/skills/mention.js';
+export const defaultAgentPorts = {
+    generationParams: resolveLlmGenerationParams,
+    systemPrompt: ({ bio, toolNames, skills }) => systemPromptParts({ bio, toolNames, skillsSection: skillsPromptSection(skills) }),
+    mention: (messages, skills) => resolveSkillMention(lastUserContent([...messages]), skills),
+    implicitSkill: (messages, skills) => resolveImplicitSkill(lastUserContent([...messages]), skills)
+};

package/dist-lib/lib/capabilities/completion-engine/actors/answering.d.ts

@@ -1,3 +1,3 @@
-import type { AnsweredPayload } from '../../../machine/index.ts';
 import type { CompletionActor } from '../session.ts';
+import type { AnsweredPayload } from '../stages.ts';
 export declare const answering: CompletionActor<AnsweredPayload>;

package/dist-lib/lib/capabilities/completion-engine/actors/answering.js

@@ -2,16 +2,32 @@ import { assembleAnswer } from './stream.js';
 import { stripToolCallMarkup } from '../../../helpers/tool-call-markup.js';
 export const answering = async function answering({ emit, input: { session }, context }) {
     const round = context.lastRound;
-    if (round.response && !round.contentText.trim() && !round.replay) {
+    let response;
+    if (context.answer !== null) {
+        emit({ type: 'content', text: context.answer });
+        response = context.answer;
+    }
+    else if (round.response && !round.contentText.trim() && !round.replay) {
         emit({ type: 'content', text: round.response });
-        return { response: round.response };
+        response = round.response;
+    }
+    else {
+        const replay = round.replay ? stripToolCallMarkup(round.replay) : '';
+        response = await assembleAnswer({
+            contentText: round.contentText,
+            replay,
+            landed: session.landed,
+            emit
+        });
+    }
+    if (context.outcome !== null) {
+        return { response };
     }
-    const replay = round.replay ? stripToolCallMarkup(round.replay) : '';
-    const response = await assembleAnswer({
-        contentText: round.contentText,
-        replay,
-        landed: session.landed,
-        emit
+    const reason = await session.pipeline.stop({
+        runId: session.runId,
+        agentId: context.agentId,
+        round: context.round,
+        response
     });
-    return { response };
+    return reason === undefined ? { response } : { response, continue: reason };
 };

package/dist-lib/lib/capabilities/completion-engine/actors/batching.d.ts

@@ -0,0 +1,3 @@
+import type { CompletionActor } from '../session.ts';
+import type { BatchDonePayload } from '../stages.ts';
+export declare const batching: CompletionActor<BatchDonePayload>;

package/dist-lib/lib/capabilities/completion-engine/actors/batching.js

@@ -0,0 +1,90 @@
+import { spliceFrom } from '../splice.js';
+import { executionPlan } from './execution-plan.js';
+import { inspectCall } from './inspecting.js';
+import { runCall, settleCall } from './executing.js';
+import { CompletionMachine } from '../../../machine/index.js';
+const MAX_BATCH = 4;
+export const batching = async function batching(input) {
+    const { input: deps, context } = input;
+    const members = batchMembers(deps, context);
+    if (members.length < 2) {
+        return { results: [] };
+    }
+    const order = modelOrder(input.emit, members.map((member) => member.call.id));
+    const running = members.map(async (member, at) => {
+        try {
+            const plan = executionPlan(deps, context, member);
+            const emit = order.emitFor(at);
+            return { ran: await runCall(input, { plan, execution: member.execution, emit }) };
+        }
+        catch (error) {
+            return { error };
+        }
+    });
+    const results = [];
+    const entries = [];
+    for (let at = 0; at < members.length; at++) {
+        order.open(at);
+        const settled = await running[at];
+        if ('error' in settled) {
+            order.close();
+            await Promise.all(running);
+            throw settled.error;
+        }
+        const { entry, ...result } = settleCall(input, {
+            ran: settled.ran,
+            direct: false,
+            emit: order.emitFor(at)
+        });
+        results.push(result);
+        entries.push(entry);
+    }
+    return { history: spliceFrom(context.history, [...context.history, ...entries]), results };
+};
+function modelOrder(emit, ids) {
+    let turn = 0;
+    const held = ids.map(() => []);
+    return {
+        emitFor: (at) => (event) => {
+            const stamped = { ...event, callId: ids[at] };
+            if (at === turn) {
+                emit(stamped);
+            }
+            else {
+                held[at].push(stamped);
+            }
+        },
+        open(at) {
+            turn = at;
+            for (const event of held[at].splice(0)) {
+                emit(event);
+            }
+        },
+        close() {
+            turn = -1;
+        }
+    };
+}
+function batchMembers(deps, context) {
+    const members = [];
+    for (const call of context.toolQueue) {
+        if (members.length === MAX_BATCH ||
+            !call.concurrent ||
+            context.failedCalls[call.key] ||
+            members.some((member) => member.call.key === call.key)) {
+            break;
+        }
+        const { rejection, execution } = inspectCall(deps, context, call);
+        const facts = execution?.gate?.facts;
+        if (rejection ||
+            !execution ||
+            facts?.effect !== 'read' ||
+            !CompletionMachine.runsUnasked(facts) ||
+            execution.origin === 'skill' ||
+            execution.webSearch) {
+            break;
+        }
+        members.push({ call, execution });
+    }
+    return members;
+}

package/dist-lib/lib/capabilities/completion-engine/actors/direct-search.d.ts

@@ -1,4 +1,5 @@
-import type { CompletionMachineContext as CompletionContext, DirectToolOutput, SearchingOutput } from '../../../machine/index.ts';
 import type { CompletionActor, CompletionDeps } from '../session.ts';
+import type { CompletionContext } from '../../../machine/index.ts';
+import type { DirectToolOutput, SearchingOutput } from '../stages.ts';
 export declare const directSearch: CompletionActor<SearchingOutput>;
 export declare function startDirectSearch(deps: CompletionDeps, context: CompletionContext, query: string): Promise<DirectToolOutput | null>;

package/dist-lib/lib/capabilities/completion-engine/actors/direct-search.js

@@ -1,5 +1,5 @@
 import { AbortedError } from '../../../helpers/race-abort.js';
-import { WEB_SEARCH_TOOL_NAME } from '../../tool-names.js';
+import { Agent } from '../../../agent/index.js';
 import { DIRECT_CALL_ID } from '../../tool-turns.js';
 import { approvalGate, trustedSources } from './execution-plan.js';
 import { detachJson } from '../../../helpers/detach-json.js';
@@ -13,7 +13,7 @@ export const directSearch = async function directSearch({ input: deps, context }
 };
 export async function startDirectSearch(deps, context, query) {
     const { args, session } = deps;
-    const webSearch = session.enabled.find((tool) => tool.name === WEB_SEARCH_TOOL_NAME);
+    const webSearch = session.enabled.find((tool) => tool.name === Agent.WEB_SEARCH_TOOL_NAME);
     if (!webSearch) {
         return null;
     }
@@ -21,8 +21,11 @@ export async function startDirectSearch(deps, context, query) {
         runId: session.runId,
         callId: DIRECT_CALL_ID,
         toolName: webSearch.name,
+        effect: webSearch.effect({ query }),
+        resource: detachJson(webSearch.resource?.({ query }) ?? null),
         args: { query },
-        agentId: args.agent?.id ?? null,
+        agentId: context.agentId,
+        egress: webSearch.egress,
         signal: args.signal
     });
     const searchArgs = fold.ok ? detachJson(fold.args) : { query };
@@ -33,10 +36,16 @@ export async function startDirectSearch(deps, context, query) {
         id: DIRECT_CALL_ID,
         key: session.callKey(webSearch.name, searchArgs),
         name: webSearch.name,
-        args: searchArgs
+        args: searchArgs,
+        permission: fold.ok ? fold.permission : undefined
     };
     const effect = webSearch.effect(detachJson(searchArgs));
-    const execution = { kind: 'direct', effect, skillName: null, webSearch: true };
+    const execution = {
+        kind: 'direct',
+        effect,
+        origin: 'tool-result',
+        webSearch: true
+    };
     if (fold.ok) {
         const sources = trustedSources(deps, context);
         const gate = approvalGate({

package/dist-lib/lib/capabilities/completion-engine/actors/execute.d.ts

@@ -1,8 +1,8 @@
-import { type ToolCallDisplay, type ToolExecutionOutcome, type ToolPreflight, type ToolActivityEvent } from '../../../machine/index.ts';
-import type { ToolDefinition, ToolExecuteContext } from '../../completion.ts';
+import { type ToolPreflight } from '../tool-execution.ts';
+import type { OutboundGuard, ToolActivityEvent, ToolCallDisplay, ToolDefinition, ToolExecuteContext, ToolExecutionOutcome } from '../../../contract/index.ts';
 import type { AbortSignal as BareAbortSignal } from 'bare-abort-controller';
 import type { ToolPolicySources } from './execution-plan.ts';
-import type { HookPipeline } from '../../../hooks/pipeline.ts';
+import type { HookPipeline } from '../../../hooks/index.ts';
 export interface ToolCallPlan {
     resolved: {
         call: {
@@ -21,12 +21,14 @@ export interface ToolCallPlan {
 export interface ToolCallRunOptions {
     approve?: () => Promise<boolean>;
     sources: ToolPolicySources;
+    outbound: OutboundGuard;
     preflight: ToolPreflight;
     onDisplay?: (event: ToolActivityEvent) => void;
     signal?: BareAbortSignal;
     denied: Set<string>;
     pipeline: HookPipeline;
     runId: string;
+    deniedMessage: string;
     callId: string;
     skipApprovals: boolean;
     intent?: string;

package/dist-lib/lib/capabilities/completion-engine/actors/execute.js

@@ -1,18 +1,21 @@
 import { AbortedError } from '../../../helpers/race-abort.js';
-import { RecoveryRequired, ToolPolicyChanged } from '../../../machine/index.js';
-import { executeCall } from '../../completion-loop/index.js';
+import { executeCall } from '../tool-execution.js';
 import { errorMessage } from '../../../guards.js';
+import { HookHalt, RecoveryRequired } from '../../../helpers/engine-error.js';
+import { ToolPolicyChanged } from '../operations.js';
 export async function runToolCall(plan, options) {
     let activity = null;
     try {
         const executed = await executeCall(plan.resolved.tool, plan.resolved.call.arguments, plan.context, {
             runId: options.runId,
+            deniedMessage: options.deniedMessage,
             approve: options.approve,
             signal: options.signal,
             denied: options.denied,
             preflight: options.preflight,
             sources: options.sources.sources,
             sourceFacts: options.sources.sourceFacts,
+            outbound: options.outbound,
             pipeline: options.pipeline,
             effect: plan.effect,
             callId: options.callId,
@@ -32,7 +35,9 @@ export async function runToolCall(plan, options) {
         };
     }
     catch (error) {
-        if (error instanceof RecoveryRequired || error instanceof ToolPolicyChanged) {
+        if (error instanceof RecoveryRequired ||
+            error instanceof ToolPolicyChanged ||
+            error instanceof HookHalt) {
             throw error;
         }
         if (error instanceof AbortedError || options.signal?.aborted) {

package/dist-lib/lib/capabilities/completion-engine/actors/executing.d.ts

@@ -1,3 +1,30 @@
-import { type ToolDonePayload } from '../../../machine/index.ts';
-import type { CompletionActor } from '../session.ts';
+import type { CompletionActor, CompletionActorInput } from '../session.ts';
+import { type ToolExecutionPlan } from './execution-plan.ts';
+import { type ToolCallRunResult } from './execute.ts';
+import type { CompletionContext } from '../../../machine/index.ts';
+import type { CompletionEvent } from '../../../contract/index.ts';
+import type { ToolDonePayload, ToolExecutionSnapshot } from '../stages.ts';
 export declare const executing: CompletionActor<ToolDonePayload>;
+interface RunCallInput {
+    plan: ToolExecutionPlan;
+    execution: ToolExecutionSnapshot;
+    emit(event: CompletionEvent): void;
+}
+export interface RanCall {
+    plan: ToolExecutionPlan;
+    denied: Set<string>;
+    landedBefore: number;
+    executed: ToolCallRunResult;
+    durationMs: number;
+}
+export declare function runCall({ input: deps, context }: CompletionActorInput, { plan: vetted, execution, emit }: RunCallInput): Promise<RanCall>;
+interface SettleCallInput {
+    ran: RanCall;
+    direct: boolean;
+    emit(event: CompletionEvent): void;
+}
+export interface SettledCall extends Omit<ToolDonePayload, 'history' | 'endedRun'> {
+    entry: CompletionContext['history'][number];
+}
+export declare function settleCall({ input: { session }, context }: CompletionActorInput, { ran, direct, emit }: SettleCallInput): SettledCall;
+export {};