@particle-academy/prism-harness 0.0.0

package/dist/subagent-runner.js

@@ -0,0 +1,89 @@
+import { MAX_DEPTH } from './subagents.js';
+/**
+ * Turns a declared `Subagent` into a TOOL the parent run can call.
+ *
+ * The parent is mid-run and holding its own session lock when this executes.
+ * Everything here is arranged so that fact stays harmless:
+ *
+ *  - the child resolves its OWN session address, so it takes a different lock;
+ *  - the child's authority comes from its declared mode, never the parent's;
+ *  - the child's budget is drawn from the tree's remaining allowance;
+ *  - EVERY way the child can end returns a framed result rather than throwing,
+ *    because the parent is a legitimate audience for "that did not work" and
+ *    tearing down the parent run would discard work it had already done.
+ */
+export class SubagentRunner {
+    harness;
+    runtime;
+    constructor(harness, runtime) {
+        this.harness = harness;
+        this.runtime = runtime;
+    }
+    tool(subagent, parent, context, parentRunId) {
+        return {
+            name: subagent.name,
+            description: subagent.description,
+            handle: async (args) => {
+                const task = typeof args.task === 'string' ? args.task : '';
+                return (await this.run(subagent, parent, context, parentRunId, task)).toToolResult();
+            },
+        };
+    }
+    async run(subagent, parent, context, parentRunId, task) {
+        const runId = `run_${Math.random().toString(16).slice(2, 14)}`;
+        // Checked BEFORE spawning, so an exhausted tree does not pay for a session,
+        // a thread write and a provider call to discover it is exhausted.
+        const stop = context.ledger.exhaustion(context.budget);
+        if (stop !== null) {
+            return refused(subagent.name, runId, parentRunId, context.ledger.cancelled ? 'cancelled' : 'exhausted', stop);
+        }
+        const childContext = context.forChild(subagent, parentRunId);
+        // Refused BEFORE the child's address is built. Two modes naming each other
+        // as subagents form a cycle budgets would eventually stop — but only after
+        // each level had appended `::sub::<name>` to an address that may truncate
+        // rather than error, and two children truncated to the same string are one
+        // conversation.
+        if (childContext.tooDeep()) {
+            return refused(subagent.name, runId, parentRunId, 'denied', `subagent nesting reached the maximum depth of ${MAX_DEPTH}`);
+        }
+        const child = this.harness
+            .for(parent.participant)
+            .session(subagent.scopeUnder(parent.scope));
+        // The child's authority comes from ITS mode, not the parent's.
+        await child.usingMode(subagent.mode);
+        await child.usingProvider((await parent.provider()) ?? 'unknown');
+        await child.usingModel((await parent.model()) ?? 'unknown');
+        try {
+            const response = await this.runtime.send(child, task, undefined, childContext);
+            return {
+                subagent: subagent.name,
+                runId: response.runId,
+                parentRunId,
+                outcome: response.stoppedBecause === null ? 'completed' : 'exhausted',
+                text: response.text,
+                toToolResult() {
+                    return response.stoppedBecause === null
+                        ? response.text
+                        : `The [${subagent.name}] subagent stopped early: ${response.stoppedBecause}. Partial answer: ${response.text}`;
+                },
+            };
+        }
+        catch (error) {
+            // Framed, not thrown. Tearing down the parent run would discard work it
+            // has already done, and "that subagent failed" is something the parent
+            // can act on.
+            return refused(subagent.name, runId, parentRunId, 'failed', error instanceof Error ? error.message : String(error));
+        }
+    }
+}
+function refused(subagent, runId, parentRunId, outcome, reason) {
+    const text = `The [${subagent}] subagent did not run: ${reason}.`;
+    return {
+        subagent,
+        runId,
+        parentRunId,
+        outcome,
+        text,
+        toToolResult: () => text,
+    };
+}

package/dist/subagents.d.ts

@@ -0,0 +1,182 @@
+/**
+ * How deep a run tree may nest.
+ *
+ * Budgets alone do bound a cycle — mode A calling B calling A terminates when
+ * the steps run out — but they do not bound it CHEAPLY, and they do not bound
+ * the child's address, which grows by `::sub::<name>` at every level. A tree
+ * deep enough would produce session keys long enough to truncate in a store
+ * with a fixed-width key and collide two distinct children onto one
+ * conversation.
+ *
+ * Depth is also the honest limit to state: nobody debugs a six-deep agent tree,
+ * and a config that produced one is a mistake worth reporting rather than
+ * executing.
+ */
+export declare const MAX_DEPTH = 4;
+/**
+ * What a run is ALLOWED TO SPEND.
+ *
+ * `maxSteps` alone was never a budget. It bounds ITERATIONS, and twenty steps
+ * each calling an expensive tool sits comfortably inside it — so a run could
+ * respect its declared limit and still cost more than anyone intended. Cost and
+ * wall-clock are the two a person actually cares about when they say "bounded".
+ */
+export declare class RunBudget {
+    readonly maxSteps: number;
+    readonly maxCostUsd: number | null;
+    readonly maxSeconds: number | null;
+    constructor(maxSteps: number, maxCostUsd?: number | null, maxSeconds?: number | null);
+    static fromConfig(config: Record<string, unknown>, defaultSteps?: number): RunBudget;
+    /**
+     * The budget a CHILD actually gets, as a TREE-ABSOLUTE ceiling.
+     *
+     * BUDGETS NEST; THEY DO NOT RESET. A resetting budget is not a budget: a
+     * parent limited to 8 steps that may spawn subagents each entitled to a fresh
+     * 8 has no bound at all — it has a bound per node in a tree whose width it
+     * also controls, which is unbounded spend wearing a limit's clothing.
+     *
+     * ## Absolute, not remaining — and this is a FIX, not a port
+     *
+     * The reference computes the child's budget as what REMAINS
+     * (`min(declared, parent.maxSteps - ledger.steps)`) and then `exhaustion()`
+     * compares the ledger's CUMULATIVE steps against it. Those two are in
+     * different units, and the result is that a child is refused the moment its
+     * parent has spent anything: parent 8, ledger 7, child declares 2 gives a
+     * budget of 1, and `7 >= 1` is immediately exhausted — so the child gets
+     * ZERO steps while the tree genuinely has one left. Verified against the
+     * reference's own arithmetic, not inferred.
+     *
+     * Expressing the child's budget as a ceiling THE TREE MAY REACH makes both
+     * halves the same unit and gives the right answer in every case: an unspent
+     * parent still hands a child exactly what it declared, and a nearly-spent one
+     * hands it exactly what is left.
+     *
+     * Recorded in the envelope's port gaps register as a divergence the reference
+     * should adopt.
+     */
+    nestedWithin(parent: RunBudget, ledger: RunLedger): RunBudget;
+}
+/**
+ * What a run TREE has actually spent, and whether it has been cancelled.
+ *
+ * SHARED BY REFERENCE from a parent to every descendant, which is the whole
+ * point: budgets nest, and nesting is only real if the child's spend lands in
+ * the same account the parent is measured against. A per-run ledger would let
+ * each node report itself within budget while the tree went far past it.
+ *
+ * Mutable on purpose, and the only mutable thing here. Spend is a running
+ * total; modelling it immutably would mean threading a new instance back up
+ * through every return, and the one place that must not be missed is the
+ * failure path.
+ */
+export declare class RunLedger {
+    #private;
+    readonly rootRunId: string;
+    private readonly startedAt;
+    constructor(rootRunId: string, startedAt?: number);
+    static start(rootRunId: string): RunLedger;
+    get steps(): number;
+    get costUsd(): number;
+    get unmeteredRuns(): number;
+    elapsedSeconds(): number;
+    recordSteps(steps: number): void;
+    /**
+     * Charge a run's cost to the tree.
+     *
+     * NULL IS NOT ZERO. A provider's reported cost is nullable because not every
+     * provider reports one, and folding that into `+= 0` would leave a cost
+     * budget that can never trip — enforced in the documentation, absent at
+     * runtime, and indistinguishable from a tree that genuinely spent nothing.
+     * Counted separately so `exhaustion()` can say the cap is UNENFORCEABLE
+     * instead of quietly failing open.
+     */
+    recordCost(usd: number | null): void;
+    /**
+     * Stop the tree.
+     *
+     * COOPERATIVE rather than pre-emptive: a running tool cannot be interrupted,
+     * and pretending otherwise would be the more dangerous lie. A half-executed
+     * tool is precisely the state the durability layer exists to protect, so the
+     * in-flight call is allowed to finish and the NEXT step is refused.
+     */
+    cancel(reason?: string): void;
+    get cancelled(): boolean;
+    get cancelReason(): string | null;
+    remainingCost(budget: RunBudget): number | null;
+    remainingSeconds(budget: RunBudget): number | null;
+    /**
+     * Why the tree may not spend again — or null when it may.
+     *
+     * Returns a REASON rather than a boolean. The states are genuinely different
+     * (cancelled / out of steps / out of money / out of time) and a caller that
+     * cannot tell them apart writes one message for four causes, which is the
+     * collapse this ecosystem keeps finding. See prism-parity decision 0020.
+     */
+    exhaustion(budget: RunBudget): string | null;
+}
+/**
+ * A nested agent a parent run may call, and the AUTHORITY IT GETS.
+ *
+ * The authority is DECLARED rather than inherited. A subagent that ran with
+ * whatever its parent happened to hold would make "narrowed toolset" a
+ * description instead of a constraint — and the narrowing is the entire reason
+ * to reach for a subagent rather than another turn of the parent.
+ */
+export declare class Subagent {
+    readonly name: string;
+    readonly description: string;
+    readonly mode: string;
+    readonly budget: RunBudget;
+    /**
+     * The scope suffix the child's own session and thread live under.
+     *
+     * Deterministic, so a cold worker resuming the tree lands on the same child
+     * conversation instead of starting a fresh one. Defaults to the name.
+     */
+    readonly scopeSuffix: string | null;
+    constructor(name: string, description: string, mode: string, budget: RunBudget, 
+    /**
+     * The scope suffix the child's own session and thread live under.
+     *
+     * Deterministic, so a cold worker resuming the tree lands on the same child
+     * conversation instead of starting a fresh one. Defaults to the name.
+     */
+    scopeSuffix?: string | null);
+    /**
+     * The scope the child session resolves under.
+     *
+     * A DIFFERENT scope from the parent, which is what keeps this from
+     * deadlocking. A session's lock is taken on its address, and a nested run
+     * asking for the parent's address inside the parent's own lock would wait for
+     * a lock it is already holding. Giving the child its own address removes the
+     * contention rather than making the lock reentrant — which would let a child
+     * mutate parent state mid-run, the precise thing the lock is for.
+     */
+    scopeUnder(parentScope: string): string;
+}
+export declare function subagentFromConfig(name: string, config: Record<string, unknown>): Subagent;
+/**
+ * Where a run sits in its tree, and what the tree has left to spend.
+ *
+ * A run with NO context is a root: that is the ordinary case and stays free of
+ * all of this.
+ */
+export declare class RunContext {
+    readonly ledger: RunLedger;
+    readonly budget: RunBudget;
+    readonly parentRunId: string | null;
+    readonly depth: number;
+    constructor(ledger: RunLedger, budget: RunBudget, parentRunId?: string | null, depth?: number);
+    static root(runId: string, budget: RunBudget): RunContext;
+    get rootRunId(): string;
+    isChild(): boolean;
+    /**
+     * The context a child inherits: SAME LEDGER, narrowed budget.
+     *
+     * Same ledger by reference is the load-bearing part. A child with its own
+     * ledger would let every node report itself inside budget while the tree
+     * spent without limit.
+     */
+    forChild(subagent: Subagent, parentRunId: string): RunContext;
+    tooDeep(): boolean;
+}

package/dist/subagents.js

@@ -0,0 +1,286 @@
+/**
+ * How deep a run tree may nest.
+ *
+ * Budgets alone do bound a cycle — mode A calling B calling A terminates when
+ * the steps run out — but they do not bound it CHEAPLY, and they do not bound
+ * the child's address, which grows by `::sub::<name>` at every level. A tree
+ * deep enough would produce session keys long enough to truncate in a store
+ * with a fixed-width key and collide two distinct children onto one
+ * conversation.
+ *
+ * Depth is also the honest limit to state: nobody debugs a six-deep agent tree,
+ * and a config that produced one is a mistake worth reporting rather than
+ * executing.
+ */
+export const MAX_DEPTH = 4;
+/**
+ * What a run is ALLOWED TO SPEND.
+ *
+ * `maxSteps` alone was never a budget. It bounds ITERATIONS, and twenty steps
+ * each calling an expensive tool sits comfortably inside it — so a run could
+ * respect its declared limit and still cost more than anyone intended. Cost and
+ * wall-clock are the two a person actually cares about when they say "bounded".
+ */
+export class RunBudget {
+    maxSteps;
+    maxCostUsd;
+    maxSeconds;
+    constructor(maxSteps, maxCostUsd = null, maxSeconds = null) {
+        this.maxSteps = maxSteps;
+        this.maxCostUsd = maxCostUsd;
+        this.maxSeconds = maxSeconds;
+    }
+    static fromConfig(config, defaultSteps = 8) {
+        return new RunBudget(numberOr(config.max_steps, defaultSteps), numberOrNull(config.max_cost_usd), numberOrNull(config.max_seconds));
+    }
+    /**
+     * The budget a CHILD actually gets, as a TREE-ABSOLUTE ceiling.
+     *
+     * BUDGETS NEST; THEY DO NOT RESET. A resetting budget is not a budget: a
+     * parent limited to 8 steps that may spawn subagents each entitled to a fresh
+     * 8 has no bound at all — it has a bound per node in a tree whose width it
+     * also controls, which is unbounded spend wearing a limit's clothing.
+     *
+     * ## Absolute, not remaining — and this is a FIX, not a port
+     *
+     * The reference computes the child's budget as what REMAINS
+     * (`min(declared, parent.maxSteps - ledger.steps)`) and then `exhaustion()`
+     * compares the ledger's CUMULATIVE steps against it. Those two are in
+     * different units, and the result is that a child is refused the moment its
+     * parent has spent anything: parent 8, ledger 7, child declares 2 gives a
+     * budget of 1, and `7 >= 1` is immediately exhausted — so the child gets
+     * ZERO steps while the tree genuinely has one left. Verified against the
+     * reference's own arithmetic, not inferred.
+     *
+     * Expressing the child's budget as a ceiling THE TREE MAY REACH makes both
+     * halves the same unit and gives the right answer in every case: an unspent
+     * parent still hands a child exactly what it declared, and a nearly-spent one
+     * hands it exactly what is left.
+     *
+     * Recorded in the envelope's port gaps register as a divergence the reference
+     * should adopt.
+     */
+    nestedWithin(parent, ledger) {
+        return new RunBudget(Math.min(parent.maxSteps, ledger.steps + this.maxSteps), lesser(parent.maxCostUsd, this.maxCostUsd === null ? null : ledger.costUsd + this.maxCostUsd), lesser(parent.maxSeconds, this.maxSeconds === null ? null : Math.trunc(ledger.elapsedSeconds()) + this.maxSeconds));
+    }
+}
+/**
+ * What a run TREE has actually spent, and whether it has been cancelled.
+ *
+ * SHARED BY REFERENCE from a parent to every descendant, which is the whole
+ * point: budgets nest, and nesting is only real if the child's spend lands in
+ * the same account the parent is measured against. A per-run ledger would let
+ * each node report itself within budget while the tree went far past it.
+ *
+ * Mutable on purpose, and the only mutable thing here. Spend is a running
+ * total; modelling it immutably would mean threading a new instance back up
+ * through every return, and the one place that must not be missed is the
+ * failure path.
+ */
+export class RunLedger {
+    rootRunId;
+    startedAt;
+    #steps = 0;
+    #costUsd = 0;
+    #unmeteredRuns = 0;
+    #cancelled = false;
+    #cancelReason = null;
+    constructor(rootRunId, startedAt = Date.now()) {
+        this.rootRunId = rootRunId;
+        this.startedAt = startedAt;
+    }
+    static start(rootRunId) {
+        return new RunLedger(rootRunId);
+    }
+    get steps() {
+        return this.#steps;
+    }
+    get costUsd() {
+        return this.#costUsd;
+    }
+    get unmeteredRuns() {
+        return this.#unmeteredRuns;
+    }
+    elapsedSeconds() {
+        return (Date.now() - this.startedAt) / 1000;
+    }
+    recordSteps(steps) {
+        this.#steps += Math.max(0, steps);
+    }
+    /**
+     * Charge a run's cost to the tree.
+     *
+     * NULL IS NOT ZERO. A provider's reported cost is nullable because not every
+     * provider reports one, and folding that into `+= 0` would leave a cost
+     * budget that can never trip — enforced in the documentation, absent at
+     * runtime, and indistinguishable from a tree that genuinely spent nothing.
+     * Counted separately so `exhaustion()` can say the cap is UNENFORCEABLE
+     * instead of quietly failing open.
+     */
+    recordCost(usd) {
+        if (usd === null) {
+            this.#unmeteredRuns += 1;
+            return;
+        }
+        this.#costUsd += Math.max(0, usd);
+    }
+    /**
+     * Stop the tree.
+     *
+     * COOPERATIVE rather than pre-emptive: a running tool cannot be interrupted,
+     * and pretending otherwise would be the more dangerous lie. A half-executed
+     * tool is precisely the state the durability layer exists to protect, so the
+     * in-flight call is allowed to finish and the NEXT step is refused.
+     */
+    cancel(reason = 'cancelled') {
+        this.#cancelled = true;
+        this.#cancelReason = reason;
+    }
+    get cancelled() {
+        return this.#cancelled;
+    }
+    get cancelReason() {
+        return this.#cancelReason;
+    }
+    remainingCost(budget) {
+        return budget.maxCostUsd === null ? null : Math.max(0, budget.maxCostUsd - this.#costUsd);
+    }
+    remainingSeconds(budget) {
+        return budget.maxSeconds === null
+            ? null
+            : Math.max(0, Math.trunc(budget.maxSeconds - this.elapsedSeconds()));
+    }
+    /**
+     * Why the tree may not spend again — or null when it may.
+     *
+     * Returns a REASON rather than a boolean. The states are genuinely different
+     * (cancelled / out of steps / out of money / out of time) and a caller that
+     * cannot tell them apart writes one message for four causes, which is the
+     * collapse this ecosystem keeps finding. See prism-parity decision 0020.
+     */
+    exhaustion(budget) {
+        if (this.#cancelled) {
+            return this.#cancelReason ?? 'cancelled';
+        }
+        if (this.#steps >= budget.maxSteps) {
+            return `step budget exhausted (${this.#steps} of ${budget.maxSteps} used)`;
+        }
+        if (budget.maxCostUsd !== null && this.#unmeteredRuns > 0) {
+            // Failing CLOSED. A cost cap the provider gives us no numbers to enforce
+            // is not a cap, and continuing would spend without limit under a budget
+            // the operator believes is holding.
+            return (`cost budget cannot be enforced: ${this.#unmeteredRuns} run(s) reported no cost, ` +
+                `so spend against the ${budget.maxCostUsd.toFixed(4)} USD cap is unknown`);
+        }
+        if (budget.maxCostUsd !== null && this.#costUsd >= budget.maxCostUsd) {
+            return `cost budget exhausted (${this.#costUsd.toFixed(4)} of ${budget.maxCostUsd.toFixed(4)} USD used)`;
+        }
+        if (budget.maxSeconds !== null && this.elapsedSeconds() >= budget.maxSeconds) {
+            return `time budget exhausted (${Math.trunc(this.elapsedSeconds())}s of ${budget.maxSeconds}s used)`;
+        }
+        return null;
+    }
+}
+/**
+ * A nested agent a parent run may call, and the AUTHORITY IT GETS.
+ *
+ * The authority is DECLARED rather than inherited. A subagent that ran with
+ * whatever its parent happened to hold would make "narrowed toolset" a
+ * description instead of a constraint — and the narrowing is the entire reason
+ * to reach for a subagent rather than another turn of the parent.
+ */
+export class Subagent {
+    name;
+    description;
+    mode;
+    budget;
+    scopeSuffix;
+    constructor(name, description, mode, budget, 
+    /**
+     * The scope suffix the child's own session and thread live under.
+     *
+     * Deterministic, so a cold worker resuming the tree lands on the same child
+     * conversation instead of starting a fresh one. Defaults to the name.
+     */
+    scopeSuffix = null) {
+        this.name = name;
+        this.description = description;
+        this.mode = mode;
+        this.budget = budget;
+        this.scopeSuffix = scopeSuffix;
+    }
+    /**
+     * The scope the child session resolves under.
+     *
+     * A DIFFERENT scope from the parent, which is what keeps this from
+     * deadlocking. A session's lock is taken on its address, and a nested run
+     * asking for the parent's address inside the parent's own lock would wait for
+     * a lock it is already holding. Giving the child its own address removes the
+     * contention rather than making the lock reentrant — which would let a child
+     * mutate parent state mid-run, the precise thing the lock is for.
+     */
+    scopeUnder(parentScope) {
+        return `${parentScope}::sub::${this.scopeSuffix ?? this.name}`;
+    }
+}
+export function subagentFromConfig(name, config) {
+    const description = config.description;
+    const mode = config.mode;
+    const scope = config.scope;
+    return new Subagent(name, typeof description === 'string' && description !== ''
+        ? description
+        : `Run the [${name}] subagent and return its result.`, typeof mode === 'string' && mode !== '' ? mode : name, RunBudget.fromConfig(config), typeof scope === 'string' ? scope : null);
+}
+/**
+ * Where a run sits in its tree, and what the tree has left to spend.
+ *
+ * A run with NO context is a root: that is the ordinary case and stays free of
+ * all of this.
+ */
+export class RunContext {
+    ledger;
+    budget;
+    parentRunId;
+    depth;
+    constructor(ledger, budget, parentRunId = null, depth = 0) {
+        this.ledger = ledger;
+        this.budget = budget;
+        this.parentRunId = parentRunId;
+        this.depth = depth;
+    }
+    static root(runId, budget) {
+        return new RunContext(RunLedger.start(runId), budget);
+    }
+    get rootRunId() {
+        return this.ledger.rootRunId;
+    }
+    isChild() {
+        return this.parentRunId !== null;
+    }
+    /**
+     * The context a child inherits: SAME LEDGER, narrowed budget.
+     *
+     * Same ledger by reference is the load-bearing part. A child with its own
+     * ledger would let every node report itself inside budget while the tree
+     * spent without limit.
+     */
+    forChild(subagent, parentRunId) {
+        return new RunContext(this.ledger, subagent.budget.nestedWithin(this.budget, this.ledger), parentRunId, this.depth + 1);
+    }
+    tooDeep() {
+        return this.depth >= MAX_DEPTH;
+    }
+}
+function lesser(a, b) {
+    if (a === null)
+        return b;
+    if (b === null)
+        return a;
+    return Math.min(a, b);
+}
+function numberOr(value, fallback) {
+    return typeof value === 'number' && Number.isFinite(value) ? Math.trunc(value) : fallback;
+}
+function numberOrNull(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}

package/dist/task-tools.d.ts

@@ -0,0 +1,55 @@
+import type { ToolAuthorizer, ToolFactory } from './tools.js';
+import type { AgentTask, AgentTaskSource } from './tasks.js';
+export interface CompletionToolOptions {
+    /** Where the task lives. */
+    source: AgentTaskSource;
+    /** The task this tool may close. ONE task, the one the worker is holding. */
+    task: AgentTask;
+    /**
+     * The worker holding the task. REQUIRED, and load-bearing.
+     *
+     * A completion tool that names only a source can close any task in the list,
+     * including one another worker is midway through -- and a tool the model can
+     * call is the last place to leave that reachable. Passing the worker through
+     * means the source refuses anything this worker is not actually holding.
+     */
+    worker: string;
+    /** Must be ENABLED. See below for why that is checked rather than assumed. */
+    authorizer: ToolAuthorizer;
+    /** Defaults to `complete_task`. */
+    name?: string;
+}
+/**
+ * A tool that lets the AGENT close its own task. OFF UNLESS A CONSUMER BUILDS IT.
+ *
+ * ## Why this is not the default
+ *
+ * If the model can set its own task to `done`, then "run until the goal is met"
+ * silently becomes "run until it decides it is met", and a run that has stalled
+ * ends by declaring victory. That is the same failure `prism-human-plus`
+ * addresses by reserving confirmation for the human, and the same reason the
+ * default here is off in all three languages. A port that ships it on has
+ * changed an observable decision, not a default.
+ *
+ * By default `release()` is called by the APPLICATION, from evidence. Nothing
+ * in this package registers this tool, and a `StoreTaskSource` on its own gives
+ * an agent no route to a terminal state.
+ *
+ * ## Why the authorizer is checked
+ *
+ * Through the EXISTING `ToolAuthorizer` -- no new permission mechanism, because
+ * a second mechanism is a second place to grant something by accident.
+ *
+ * A disabled authorizer is refused rather than tolerated. `ToolAuthorizer`
+ * defaults to off, and off means every registered tool is offered to every run
+ * and every call is allowed; a consumer who wires this tool up against one has
+ * granted the agent completion authority while believing a control is in place.
+ * Same argument, and the same error code, as a policy that is defined and never
+ * consulted.
+ *
+ * The returned factory produces a tool wrapped by `authorizedTool`, so the call
+ * policy is asked again AT CALL TIME with the arguments -- an offer-time check
+ * alone can say "may complete tasks" and never "only this task, only once the
+ * tests pass".
+ */
+export declare function agentCompletionTool(options: CompletionToolOptions): ToolFactory;