@strands-agents/sdk 1.2.0 → 1.4.0

package/dist/src/vended-interventions/hitl/__tests__/hitl.test.js

@@ -0,0 +1,358 @@
+import { describe, expect, it } from 'vitest';
+import { HumanInTheLoop } from '../hitl.js';
+import { Agent } from '../../../agent/agent.js';
+import { MockMessageModel } from '../../../__fixtures__/mock-message-model.js';
+import { createMockTool } from '../../../__fixtures__/tool-helpers.js';
+describe('HumanInTheLoop', () => {
+    describe('default config (interrupt/resume)', () => {
+        it('pauses agent with interrupt on any tool call', async () => {
+            const model = new MockMessageModel()
+                .addTurn({ type: 'toolUseBlock', name: 'anyTool', toolUseId: 'tool-1', input: { x: 1 } })
+                .addTurn({ type: 'textBlock', text: 'Done' });
+            let toolExecuted = false;
+            const tool = createMockTool('anyTool', () => {
+                toolExecuted = true;
+                return 'result';
+            });
+            const agent = new Agent({
+                model,
+                tools: [tool],
+                interventions: [new HumanInTheLoop()],
+                printer: false,
+            });
+            const result = await agent.invoke('Do something');
+            expect(result.stopReason).toBe('interrupt');
+            expect(result.interrupts).toEqual([
+                expect.objectContaining({
+                    name: 'strands:human-in-the-loop',
+                    reason: expect.stringContaining('anyTool'),
+                }),
+            ]);
+            expect(toolExecuted).toBe(false);
+        });
+    });
+    describe('inline mode (with ask callback)', () => {
+        it('allows tool execution when approved', async () => {
+            const model = new MockMessageModel()
+                .addTurn({ type: 'toolUseBlock', name: 'myTool', toolUseId: 'tool-1', input: {} })
+                .addTurn({ type: 'textBlock', text: 'Done' });
+            let toolExecuted = false;
+            const tool = createMockTool('myTool', () => {
+                toolExecuted = true;
+                return 'executed';
+            });
+            const agent = new Agent({
+                model,
+                tools: [tool],
+                interventions: [new HumanInTheLoop({ ask: async () => 'yes' })],
+                printer: false,
+            });
+            const result = await agent.invoke('Run tool');
+            expect(result.stopReason).toBe('endTurn');
+            expect(toolExecuted).toBe(true);
+        });
+        it('denies tool execution when rejected', async () => {
+            const model = new MockMessageModel()
+                .addTurn({ type: 'toolUseBlock', name: 'myTool', toolUseId: 'tool-1', input: {} })
+                .addTurn({ type: 'textBlock', text: 'Understood' });
+            let toolExecuted = false;
+            const tool = createMockTool('myTool', () => {
+                toolExecuted = true;
+                return 'executed';
+            });
+            const agent = new Agent({
+                model,
+                tools: [tool],
+                interventions: [new HumanInTheLoop({ ask: async () => 'no' })],
+                printer: false,
+            });
+            const result = await agent.invoke('Run tool');
+            expect(result.stopReason).toBe('endTurn');
+            expect(toolExecuted).toBe(false);
+        });
+    });
+    describe('allowedTools config', () => {
+        it('does not prompt for tools in allowedTools', async () => {
+            const model = new MockMessageModel()
+                .addTurn({ type: 'toolUseBlock', name: 'readFile', toolUseId: 'tool-1', input: {} })
+                .addTurn({ type: 'textBlock', text: 'Done' });
+            let toolExecuted = false;
+            const tool = createMockTool('readFile', () => {
+                toolExecuted = true;
+                return 'content';
+            });
+            const agent = new Agent({
+                model,
+                tools: [tool],
+                interventions: [new HumanInTheLoop({ allowedTools: ['readFile'], ask: async () => 'no' })],
+                printer: false,
+            });
+            const result = await agent.invoke('Read it');
+            expect(result.stopReason).toBe('endTurn');
+            expect(toolExecuted).toBe(true);
+        });
+        it('prompts for tools not in allowedTools', async () => {
+            const model = new MockMessageModel()
+                .addTurn({ type: 'toolUseBlock', name: 'deleteFile', toolUseId: 'tool-1', input: {} })
+                .addTurn({ type: 'textBlock', text: 'Done' });
+            let toolExecuted = false;
+            const tool = createMockTool('deleteFile', () => {
+                toolExecuted = true;
+                return 'deleted';
+            });
+            const agent = new Agent({
+                model,
+                tools: [tool],
+                interventions: [new HumanInTheLoop({ allowedTools: ['readFile'], ask: async () => 'no' })],
+                printer: false,
+            });
+            await agent.invoke('Delete it');
+            expect(toolExecuted).toBe(false);
+        });
+        it('allows all tools except negated ones with "!" prefix', async () => {
+            const model = new MockMessageModel()
+                .addTurn([
+                { type: 'toolUseBlock', name: 'readFile', toolUseId: 'tool-1', input: {} },
+                { type: 'toolUseBlock', name: 'deleteFile', toolUseId: 'tool-2', input: {} },
+            ])
+                .addTurn({ type: 'textBlock', text: 'Done' });
+            const execLog = [];
+            const readTool = createMockTool('readFile', () => {
+                execLog.push('read');
+                return 'content';
+            });
+            const deleteTool = createMockTool('deleteFile', () => {
+                execLog.push('delete');
+                return 'deleted';
+            });
+            const agent = new Agent({
+                model,
+                tools: [readTool, deleteTool],
+                interventions: [new HumanInTheLoop({ allowedTools: ['*', '!deleteFile'], ask: async () => 'no' })],
+                printer: false,
+            });
+            await agent.invoke('Do both');
+            expect(execLog).toContain('read');
+            expect(execLog).not.toContain('delete');
+        });
+        it('allows all tools with wildcard "*"', async () => {
+            const model = new MockMessageModel()
+                .addTurn({ type: 'toolUseBlock', name: 'dangerousTool', toolUseId: 'tool-1', input: {} })
+                .addTurn({ type: 'textBlock', text: 'Done' });
+            let toolExecuted = false;
+            const tool = createMockTool('dangerousTool', () => {
+                toolExecuted = true;
+                return 'ran';
+            });
+            const agent = new Agent({
+                model,
+                tools: [tool],
+                interventions: [new HumanInTheLoop({ allowedTools: ['*'], ask: async () => 'no' })],
+                printer: false,
+            });
+            const result = await agent.invoke('Do it');
+            expect(result.stopReason).toBe('endTurn');
+            expect(toolExecuted).toBe(true);
+        });
+    });
+    describe('ask callback', () => {
+        it('passes tool name and input in the prompt', async () => {
+            const prompts = [];
+            const model = new MockMessageModel()
+                .addTurn({ type: 'toolUseBlock', name: 'sendEmail', toolUseId: 'tool-1', input: { to: 'bob@example.com' } })
+                .addTurn({ type: 'textBlock', text: 'Done' });
+            const tool = createMockTool('sendEmail', () => 'sent');
+            const agent = new Agent({
+                model,
+                tools: [tool],
+                interventions: [
+                    new HumanInTheLoop({
+                        ask: async (prompt) => {
+                            prompts.push(prompt);
+                            return 'yes';
+                        },
+                    }),
+                ],
+                printer: false,
+            });
+            await agent.invoke('Send email');
+            expect(prompts[0]).toContain('sendEmail');
+            expect(prompts[0]).toContain('bob@example.com');
+        });
+        it('supports custom evaluate function', async () => {
+            const model = new MockMessageModel()
+                .addTurn({ type: 'toolUseBlock', name: 'myTool', toolUseId: 'tool-1', input: {} })
+                .addTurn({ type: 'textBlock', text: 'Done' });
+            let toolExecuted = false;
+            const tool = createMockTool('myTool', () => {
+                toolExecuted = true;
+                return 'executed';
+            });
+            const agent = new Agent({
+                model,
+                tools: [tool],
+                interventions: [
+                    new HumanInTheLoop({
+                        ask: async () => 'magic-word',
+                        evaluate: (response) => response === 'magic-word',
+                    }),
+                ],
+                printer: false,
+            });
+            const result = await agent.invoke('Go');
+            expect(result.stopReason).toBe('endTurn');
+            expect(toolExecuted).toBe(true);
+        });
+    });
+    describe('trust mode (enableTrust: true)', () => {
+        it('trusts a tool for the session when response is "t"', async () => {
+            let askCount = 0;
+            const model = new MockMessageModel()
+                .addTurn({ type: 'toolUseBlock', name: 'myTool', toolUseId: 'tool-1', input: {} })
+                .addTurn({ type: 'toolUseBlock', name: 'myTool', toolUseId: 'tool-2', input: {} })
+                .addTurn({ type: 'textBlock', text: 'Done' });
+            const tool = createMockTool('myTool', () => 'executed');
+            const agent = new Agent({
+                model,
+                tools: [tool],
+                interventions: [
+                    new HumanInTheLoop({
+                        enableTrust: true,
+                        ask: async () => {
+                            askCount++;
+                            return 't';
+                        },
+                    }),
+                ],
+                printer: false,
+            });
+            await agent.invoke('Run tool twice');
+            expect(askCount).toBe(1);
+        });
+        it('does not trust when enableTrust is false even with "t" response', async () => {
+            let askCount = 0;
+            const model = new MockMessageModel()
+                .addTurn({ type: 'toolUseBlock', name: 'myTool', toolUseId: 'tool-1', input: {} })
+                .addTurn({ type: 'toolUseBlock', name: 'myTool', toolUseId: 'tool-2', input: {} })
+                .addTurn({ type: 'textBlock', text: 'Done' });
+            const tool = createMockTool('myTool', () => 'executed');
+            const agent = new Agent({
+                model,
+                tools: [tool],
+                interventions: [
+                    new HumanInTheLoop({
+                        enableTrust: false,
+                        ask: async () => {
+                            askCount++;
+                            return 't';
+                        },
+                    }),
+                ],
+                printer: false,
+            });
+            await agent.invoke('Run tool twice');
+            // 't' is not recognized as approval when trust is disabled, so tool is denied both times
+            // but ask is still called both times (no trust memory)
+            expect(askCount).toBe(2);
+        });
+        it('"t" response also approves the current tool call', async () => {
+            const model = new MockMessageModel()
+                .addTurn({ type: 'toolUseBlock', name: 'myTool', toolUseId: 'tool-1', input: {} })
+                .addTurn({ type: 'textBlock', text: 'Done' });
+            let toolExecuted = false;
+            const tool = createMockTool('myTool', () => {
+                toolExecuted = true;
+                return 'executed';
+            });
+            const agent = new Agent({
+                model,
+                tools: [tool],
+                interventions: [new HumanInTheLoop({ enableTrust: true, ask: async () => 't' })],
+                printer: false,
+            });
+            const result = await agent.invoke('Run tool');
+            expect(result.stopReason).toBe('endTurn');
+            expect(toolExecuted).toBe(true);
+        });
+        it.each(['trust', 'T', 'TRUST'])('trusts when response is "%s"', async (trustResponse) => {
+            let askCount = 0;
+            const model = new MockMessageModel()
+                .addTurn({ type: 'toolUseBlock', name: 'myTool', toolUseId: 'tool-1', input: {} })
+                .addTurn({ type: 'toolUseBlock', name: 'myTool', toolUseId: 'tool-2', input: {} })
+                .addTurn({ type: 'textBlock', text: 'Done' });
+            const tool = createMockTool('myTool', () => 'executed');
+            const agent = new Agent({
+                model,
+                tools: [tool],
+                interventions: [
+                    new HumanInTheLoop({
+                        enableTrust: true,
+                        ask: async () => {
+                            askCount++;
+                            return trustResponse;
+                        },
+                    }),
+                ],
+                printer: false,
+            });
+            await agent.invoke('Run tool twice');
+            expect(askCount).toBe(1);
+        });
+        it('supports custom evaluateTrust function', async () => {
+            let askCount = 0;
+            const model = new MockMessageModel()
+                .addTurn({ type: 'toolUseBlock', name: 'myTool', toolUseId: 'tool-1', input: {} })
+                .addTurn({ type: 'toolUseBlock', name: 'myTool', toolUseId: 'tool-2', input: {} })
+                .addTurn({ type: 'textBlock', text: 'Done' });
+            const tool = createMockTool('myTool', () => 'executed');
+            const agent = new Agent({
+                model,
+                tools: [tool],
+                interventions: [
+                    new HumanInTheLoop({
+                        enableTrust: true,
+                        evaluateTrust: (r) => r === 'approve-and-remember',
+                        ask: async () => {
+                            askCount++;
+                            return 'approve-and-remember';
+                        },
+                    }),
+                ],
+                printer: false,
+            });
+            await agent.invoke('Run tool twice');
+            expect(askCount).toBe(1);
+        });
+        it('negated tools cannot be trusted even with "t" response', async () => {
+            let askCount = 0;
+            let toolExecuted = false;
+            const model = new MockMessageModel()
+                .addTurn({ type: 'toolUseBlock', name: 'dangerTool', toolUseId: 'tool-1', input: {} })
+                .addTurn({ type: 'toolUseBlock', name: 'dangerTool', toolUseId: 'tool-2', input: {} })
+                .addTurn({ type: 'textBlock', text: 'Done' });
+            const tool = createMockTool('dangerTool', () => {
+                toolExecuted = true;
+                return 'ran';
+            });
+            const agent = new Agent({
+                model,
+                tools: [tool],
+                interventions: [
+                    new HumanInTheLoop({
+                        allowedTools: ['*', '!dangerTool'],
+                        enableTrust: true,
+                        ask: async () => {
+                            askCount++;
+                            return 't';
+                        },
+                    }),
+                ],
+                printer: false,
+            });
+            await agent.invoke('Run danger twice');
+            expect(askCount).toBe(2);
+            expect(toolExecuted).toBe(false);
+        });
+    });
+});
+//# sourceMappingURL=hitl.test.js.map

package/dist/src/vended-interventions/hitl/__tests__/hitl.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hitl.test.js","sourceRoot":"","sources":["../../../../../src/vended-interventions/hitl/__tests__/hitl.test.ts"],"names":[],"mappings":"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"}

package/dist/src/vended-interventions/hitl/hitl.d.ts

@@ -0,0 +1,115 @@
+import { InterventionHandler } from '../../interventions/handler.js';
+import type { InterventionAction } from '../../interventions/actions.js';
+import type { BeforeToolCallEvent } from '../../hooks/events.js';
+import type { JSONValue } from '../../types/json.js';
+/**
+ * Configuration for the {@link HumanInTheLoop} intervention handler.
+ */
+export interface HumanInTheLoopConfig {
+    /**
+     * Tools that can execute WITHOUT human approval. All other tools require approval.
+     *
+     * - Use `'*'` to allow all tools.
+     * - Prefix with `!` to exclude specific tools from `'*'` (they still require approval).
+     *
+     * @example
+     * ```typescript
+     * // Only readFile and listDir run freely; everything else needs approval
+     * { allowedTools: ['readFile', 'listDir'] }
+     *
+     * // All tools run freely (HITL disabled)
+     * { allowedTools: ['*'] }
+     *
+     * // All tools run freely EXCEPT deleteFile and sendEmail
+     * { allowedTools: ['*', '!deleteFile', '!sendEmail'] }
+     * ```
+     */
+    allowedTools?: string[];
+    /**
+     * When true, trust responses approve the tool AND remember it
+     * in `agent.appState` for the rest of the session (won't ask again).
+     * Works in both interrupt/resume and inline `ask` modes.
+     *
+     * Negated tools (`!tool`) cannot be trusted.
+     *
+     * Defaults to `false`.
+     */
+    enableTrust?: boolean;
+    /**
+     * Custom trust response validator. Defaults to accepting `'t'`/`'trust'` (case-insensitive).
+     * When this returns true, the tool is approved AND trusted for the session.
+     *
+     * Only evaluated when `enableTrust` is true.
+     */
+    evaluateTrust?: (response: JSONValue) => boolean;
+    /**
+     * Custom approval response validator. Defaults to accepting `true`, `'y'`/`'yes'` (case-insensitive).
+     */
+    evaluate?: (response: JSONValue) => boolean;
+    /**
+     * Controls how the human's response is collected.
+     *
+     * - **Default** (omitted): uses interrupt/resume — agent pauses, caller resumes with response.
+     * - **`'stdio'`**: prompts via CLI readline (Node.js only). Agent blocks inline until human responds.
+     * - **Custom function**: your own async prompt logic (Slack, web UI, etc.). Agent blocks inline.
+     */
+    ask?: ((prompt: string) => Promise<JSONValue>) | 'stdio';
+}
+/**
+ * Human-in-the-loop intervention handler that pauses agent execution
+ * before tool calls to request human approval.
+ *
+ * By default, ALL tools require approval and the agent pauses via interrupt/resume.
+ * Use `allowedTools` to whitelist tools that run freely, and `ask` to provide
+ * inline prompting (CLI, custom UI).
+ *
+ * @example
+ * ```typescript
+ * import { Agent } from '@strands-agents/sdk'
+ * import { HumanInTheLoop } from '@strands-agents/sdk/vended-interventions/hitl'
+ *
+ * // All tools require approval, agent pauses via interrupt (default)
+ * const agent = new Agent({
+ *   interventions: [new HumanInTheLoop()],
+ * })
+ *
+ * // readFile runs freely, everything else pauses for approval
+ * const agent = new Agent({
+ *   interventions: [new HumanInTheLoop({ allowedTools: ['readFile'] })],
+ * })
+ *
+ * // CLI mode — prompts in terminal inline
+ * const agent = new Agent({
+ *   interventions: [new HumanInTheLoop({ ask: 'stdio' })],
+ * })
+ *
+ * // Custom UI — provide your own prompt function
+ * const agent = new Agent({
+ *   interventions: [new HumanInTheLoop({
+ *     ask: async (prompt) => await slackDM(userId, prompt),
+ *   })],
+ * })
+ * ```
+ */
+export declare class HumanInTheLoop extends InterventionHandler {
+    readonly name = "strands:human-in-the-loop";
+    private readonly _allowedTools;
+    private readonly _enableTrust;
+    private readonly _evaluateTrust;
+    private readonly _evaluate;
+    private readonly _ask;
+    constructor(config?: HumanInTheLoopConfig);
+    beforeToolCall(event: BeforeToolCallEvent): Promise<InterventionAction>;
+    /**
+     * Precedence (first match wins):
+     * 1. Negated (`!tool`) → always requires approval (cannot be trusted)
+     * 2. Trusted at runtime via 't' response (stored in agent.appState) → runs freely
+     * 3. Wildcard (`*`) → runs freely
+     * 4. Explicitly listed → runs freely
+     * 5. Default → requires approval
+     */
+    private _requiresApproval;
+    private _trustTool;
+    private _isTrustResponse;
+}
+//# sourceMappingURL=hitl.d.ts.map

package/dist/src/vended-interventions/hitl/hitl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hitl.d.ts","sourceRoot":"","sources":["../../../../src/vended-interventions/hitl/hitl.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAA;AAEpE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAA;AACxE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAA;AAChE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AA6BpD;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;;;;;;;;;;;;;OAiBG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;IAEvB;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;IAErB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,SAAS,KAAK,OAAO,CAAA;IAEhD;;OAEG;IACH,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,SAAS,KAAK,OAAO,CAAA;IAE3C;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC,GAAG,OAAO,CAAA;CACzD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,qBAAa,cAAe,SAAQ,mBAAmB;IACrD,QAAQ,CAAC,IAAI,+BAA8B;IAE3C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAa;IAC3C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAkC;IACjE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgD;IAC1E,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAsD;gBAE/D,MAAM,CAAC,EAAE,oBAAoB;IAS1B,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAmCtF;;;;;;;OAOG;IACH,OAAO,CAAC,iBAAiB;IAUzB,OAAO,CAAC,UAAU;IAOlB,OAAO,CAAC,gBAAgB;CAIzB"}

package/dist/src/vended-interventions/hitl/hitl.js

@@ -0,0 +1,138 @@
+import { InterventionHandler } from '../../interventions/handler.js';
+import { confirm, proceed, defaultEvaluate } from '../../interventions/actions.js';
+const TRUST_RESPONSES = new Set(['t', 'trust']);
+const TRUSTED_TOOLS_KEY = 'hitl:trustedTools';
+/**
+ * CLI prompt that reads from stdin.
+ * Serializes prompts so concurrent tool calls don't collide on stdin.
+ */
+function createStdioAsk(includeTrust) {
+    const options = includeTrust ? '(y/n/t)' : '(y/n)';
+    let queue = Promise.resolve();
+    return (prompt) => {
+        const task = queue.then(async () => {
+            const { createInterface } = await import('node:readline');
+            const rl = createInterface({ input: process.stdin, output: process.stdout });
+            return new Promise((resolve) => {
+                rl.question(`${prompt} ${options}: `, (answer) => {
+                    rl.close();
+                    resolve(answer.trim());
+                });
+            });
+        });
+        queue = task.catch(() => { });
+        return task;
+    };
+}
+/**
+ * Human-in-the-loop intervention handler that pauses agent execution
+ * before tool calls to request human approval.
+ *
+ * By default, ALL tools require approval and the agent pauses via interrupt/resume.
+ * Use `allowedTools` to whitelist tools that run freely, and `ask` to provide
+ * inline prompting (CLI, custom UI).
+ *
+ * @example
+ * ```typescript
+ * import { Agent } from '@strands-agents/sdk'
+ * import { HumanInTheLoop } from '@strands-agents/sdk/vended-interventions/hitl'
+ *
+ * // All tools require approval, agent pauses via interrupt (default)
+ * const agent = new Agent({
+ *   interventions: [new HumanInTheLoop()],
+ * })
+ *
+ * // readFile runs freely, everything else pauses for approval
+ * const agent = new Agent({
+ *   interventions: [new HumanInTheLoop({ allowedTools: ['readFile'] })],
+ * })
+ *
+ * // CLI mode — prompts in terminal inline
+ * const agent = new Agent({
+ *   interventions: [new HumanInTheLoop({ ask: 'stdio' })],
+ * })
+ *
+ * // Custom UI — provide your own prompt function
+ * const agent = new Agent({
+ *   interventions: [new HumanInTheLoop({
+ *     ask: async (prompt) => await slackDM(userId, prompt),
+ *   })],
+ * })
+ * ```
+ */
+export class HumanInTheLoop extends InterventionHandler {
+    name = 'strands:human-in-the-loop';
+    _allowedTools;
+    _enableTrust;
+    _evaluateTrust;
+    _evaluate;
+    _ask;
+    constructor(config) {
+        super();
+        this._allowedTools = new Set(config?.allowedTools ?? []);
+        this._enableTrust = config?.enableTrust ?? false;
+        this._evaluateTrust = config?.evaluateTrust ?? ((r) => this._isTrustResponse(r));
+        this._evaluate = config?.evaluate;
+        this._ask = config?.ask === 'stdio' ? createStdioAsk(this._enableTrust) : config?.ask;
+    }
+    async beforeToolCall(event) {
+        const toolName = event.toolUse.name;
+        if (!this._requiresApproval(event)) {
+            return proceed();
+        }
+        const prompt = `Tool "${toolName}" requires human approval. Input: ${JSON.stringify(event.toolUse.input)}`;
+        const isNegated = this._allowedTools.has(`!${toolName}`);
+        const evaluate = (response) => {
+            if (!isNegated && this._enableTrust && this._evaluateTrust(response)) {
+                this._trustTool(event, toolName);
+                return true;
+            }
+            return this._evaluate ? this._evaluate(response) : defaultEvaluate(response);
+        };
+        if (!this._ask) {
+            return confirm(prompt, { evaluate });
+        }
+        const response = await this._ask(prompt);
+        if (!isNegated && this._enableTrust && this._evaluateTrust(response)) {
+            this._trustTool(event, toolName);
+            return proceed();
+        }
+        return confirm(prompt, {
+            response,
+            evaluate: this._evaluate ?? defaultEvaluate,
+        });
+    }
+    /**
+     * Precedence (first match wins):
+     * 1. Negated (`!tool`) → always requires approval (cannot be trusted)
+     * 2. Trusted at runtime via 't' response (stored in agent.appState) → runs freely
+     * 3. Wildcard (`*`) → runs freely
+     * 4. Explicitly listed → runs freely
+     * 5. Default → requires approval
+     */
+    _requiresApproval(event) {
+        const toolName = event.toolUse.name;
+        if (this._allowedTools.has(`!${toolName}`))
+            return true;
+        const trusted = event.agent.appState.get(TRUSTED_TOOLS_KEY) ?? [];
+        if (trusted.includes(toolName))
+            return false;
+        if (this._allowedTools.has('*'))
+            return false;
+        if (this._allowedTools.has(toolName))
+            return false;
+        return true;
+    }
+    _trustTool(event, toolName) {
+        const trusted = event.agent.appState.get(TRUSTED_TOOLS_KEY) ?? [];
+        if (!trusted.includes(toolName)) {
+            event.agent.appState.set(TRUSTED_TOOLS_KEY, [...trusted, toolName]);
+        }
+    }
+    _isTrustResponse(response) {
+        if (typeof response === 'string')
+            return TRUST_RESPONSES.has(response.toLowerCase().trim());
+        return false;
+    }
+}
+//# sourceMappingURL=hitl.js.map

package/dist/src/vended-interventions/hitl/hitl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hitl.js","sourceRoot":"","sources":["../../../../src/vended-interventions/hitl/hitl.ts"],"names":[],"mappings":"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"}