joonecli 0.1.0

package/dist/hitl/bridge.js

@@ -0,0 +1,120 @@
+import { EventEmitter } from "node:events";
+/**
+ * HITLBridge — Human-in-the-Loop communication bridge.
+ *
+ * Provides a typed event-based interface between the tool execution layer
+ * and the TUI rendering layer. When a tool needs user input, it emits
+ * a question event and awaits the response. The TUI listens, renders
+ * the prompt, and resolves the answer.
+ *
+ * Singleton pattern: one bridge per session.
+ */
+export class HITLBridge extends EventEmitter {
+    static instance = null;
+    pendingResolvers = new Map();
+    timeoutMs;
+    questionCounter = 0;
+    constructor(timeoutMs = 5 * 60 * 1000) {
+        super();
+        this.timeoutMs = timeoutMs;
+    }
+    static getInstance(timeoutMs) {
+        if (!HITLBridge.instance) {
+            HITLBridge.instance = new HITLBridge(timeoutMs);
+        }
+        return HITLBridge.instance;
+    }
+    static resetInstance() {
+        HITLBridge.instance = null;
+    }
+    /**
+     * Called by a tool to ask the user a free-form question.
+     * Blocks until the user responds (or times out).
+     *
+     * @returns The user's answer as a string.
+     */
+    async askUser(question, options) {
+        const id = `hitl-q-${++this.questionCounter}-${Date.now()}`;
+        const payload = {
+            id,
+            question,
+            options,
+            createdAt: Date.now(),
+        };
+        return new Promise((resolve, reject) => {
+            this.pendingResolvers.set(id, resolve);
+            // Emit the question so the TUI can render it
+            this.emit("question", payload);
+            // Timeout: auto-reject if user doesn't respond
+            const timer = setTimeout(() => {
+                if (this.pendingResolvers.has(id)) {
+                    this.pendingResolvers.delete(id);
+                    resolve("[No response — the user did not answer within the timeout period.]");
+                }
+            }, this.timeoutMs);
+            // Clean up timer if resolved before timeout
+            const originalResolve = this.pendingResolvers.get(id);
+            this.pendingResolvers.set(id, (answer) => {
+                clearTimeout(timer);
+                originalResolve(answer);
+            });
+        });
+    }
+    /**
+     * Called by the PermissionMiddleware to request tool execution approval.
+     * Blocks until the user responds [y/n] (or times out with denial).
+     *
+     * @returns true if approved, false if denied or timed out.
+     */
+    async requestPermission(toolName, args) {
+        const id = `hitl-perm-${++this.questionCounter}-${Date.now()}`;
+        const payload = {
+            id,
+            toolName,
+            args,
+            createdAt: Date.now(),
+        };
+        return new Promise((resolve) => {
+            const wrappedResolve = (answer) => {
+                const normalized = answer.trim().toLowerCase();
+                resolve(normalized === "y" || normalized === "yes" || normalized === "approve");
+            };
+            this.pendingResolvers.set(id, wrappedResolve);
+            // Emit so the TUI can render the permission prompt
+            this.emit("permission", payload);
+            // Timeout: auto-deny
+            const timer = setTimeout(() => {
+                if (this.pendingResolvers.has(id)) {
+                    this.pendingResolvers.delete(id);
+                    resolve(false); // Denied by timeout
+                }
+            }, this.timeoutMs);
+            // Clean up timer on resolve
+            const current = this.pendingResolvers.get(id);
+            this.pendingResolvers.set(id, (answer) => {
+                clearTimeout(timer);
+                current(answer);
+            });
+        });
+    }
+    /**
+     * Called by the TUI when the user submits an answer.
+     *
+     * @param id - The question/permission request ID.
+     * @param answer - The user's text response.
+     */
+    resolveAnswer(id, answer) {
+        const resolver = this.pendingResolvers.get(id);
+        if (resolver) {
+            this.pendingResolvers.delete(id);
+            resolver(answer);
+        }
+    }
+    /**
+     * Returns true if there is an outstanding question awaiting an answer.
+     */
+    hasPendingQuestion() {
+        return this.pendingResolvers.size > 0;
+    }
+}
+//# sourceMappingURL=bridge.js.map

package/dist/hitl/bridge.js.map

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

package/dist/middleware/commandSanitizer.d.ts

@@ -0,0 +1,18 @@
+import { ToolCallContext, ToolMiddleware } from "./types.js";
+/**
+ * Intercepts bash tool calls to block dangerous or interactive commands.
+ *
+ * Categories of blocked commands:
+ * 1. Destructive: `rm -rf /`, `mkfs`, `dd if=`, fork bombs
+ * 2. Interactive/hanging: `vim`, `nano`, `less`, `top`, `htop`, `man`
+ * 3. Network abuse: `curl | sh`, `wget | bash`
+ */
+export declare class CommandSanitizerMiddleware implements ToolMiddleware {
+    readonly name = "CommandSanitizer";
+    /**
+     * Patterns that will cause a command to be blocked.
+     * Each entry is [regex, human-readable reason].
+     */
+    private readonly blockedPatterns;
+    before(ctx: ToolCallContext): ToolCallContext | string;
+}

package/dist/middleware/commandSanitizer.js

@@ -0,0 +1,50 @@
+/**
+ * Intercepts bash tool calls to block dangerous or interactive commands.
+ *
+ * Categories of blocked commands:
+ * 1. Destructive: `rm -rf /`, `mkfs`, `dd if=`, fork bombs
+ * 2. Interactive/hanging: `vim`, `nano`, `less`, `top`, `htop`, `man`
+ * 3. Network abuse: `curl | sh`, `wget | bash`
+ */
+export class CommandSanitizerMiddleware {
+    name = "CommandSanitizer";
+    /**
+     * Patterns that will cause a command to be blocked.
+     * Each entry is [regex, human-readable reason].
+     */
+    blockedPatterns = [
+        // Destructive
+        [/rm\s+(-\w*r\w*f\w*|-\w*f\w*r\w*)\s+\/(\*)?(?:\s|$)/, "destructive: rm -rf /"],
+        [/mkfs\b/, "destructive: filesystem format"],
+        [/\bdd\s+.*of=\/dev\//, "destructive: raw disk write"],
+        [/chmod\s+(-\w+\s+)*777\s+\//, "dangerous: chmod 777 on root"],
+        // Interactive / hanging
+        [/\b(vim|vi|nano|emacs|pico)\b/, "interactive: text editor (hangs the sandbox)"],
+        [/\b(less|more)\b/, "interactive: pager (hangs the sandbox)"],
+        [/\b(top|htop|glances)\b/, "interactive: process monitor (hangs the sandbox)"],
+        [/\bman\s+\w+/, "interactive: man page (hangs the sandbox)"],
+        // Network abuse: pipe-to-shell
+        [/curl\s+.*\|\s*(sh|bash|zsh)/, "unsafe: pipe remote script to shell"],
+        [/wget\s+.*\|\s*(sh|bash|zsh)/, "unsafe: pipe remote script to shell"],
+    ];
+    before(ctx) {
+        // Only applies to bash/shell tool calls
+        if (ctx.toolName !== "bash") {
+            return ctx;
+        }
+        const command = ctx.args.command;
+        if (typeof command !== "string") {
+            return ctx;
+        }
+        for (const [pattern, reason] of this.blockedPatterns) {
+            if (pattern.test(command)) {
+                return (`⚠ Blocked: Command rejected by sanitizer.\n` +
+                    `Reason: ${reason}\n` +
+                    `Command: ${command}\n` +
+                    `Use a safer alternative or refine your approach.`);
+            }
+        }
+        return ctx;
+    }
+}
+//# sourceMappingURL=commandSanitizer.js.map

package/dist/middleware/commandSanitizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commandSanitizer.js","sourceRoot":"","sources":["../../src/middleware/commandSanitizer.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,MAAM,OAAO,0BAA0B;IAC5B,IAAI,GAAG,kBAAkB,CAAC;IAEnC;;;OAGG;IACc,eAAe,GAAuB;QACrD,cAAc;QACd,CAAC,oDAAoD,EAAE,uBAAuB,CAAC;QAC/E,CAAC,QAAQ,EAAE,gCAAgC,CAAC;QAC5C,CAAC,qBAAqB,EAAE,6BAA6B,CAAC;QACtD,CAAC,4BAA4B,EAAE,8BAA8B,CAAC;QAE9D,wBAAwB;QACxB,CAAC,8BAA8B,EAAE,8CAA8C,CAAC;QAChF,CAAC,iBAAiB,EAAE,wCAAwC,CAAC;QAC7D,CAAC,wBAAwB,EAAE,kDAAkD,CAAC;QAC9E,CAAC,aAAa,EAAE,2CAA2C,CAAC;QAE5D,+BAA+B;QAC/B,CAAC,6BAA6B,EAAE,qCAAqC,CAAC;QACtE,CAAC,6BAA6B,EAAE,qCAAqC,CAAC;KACvE,CAAC;IAEF,MAAM,CAAC,GAAoB;QACzB,wCAAwC;QACxC,IAAI,GAAG,CAAC,QAAQ,KAAK,MAAM,EAAE,CAAC;YAC5B,OAAO,GAAG,CAAC;QACb,CAAC;QAED,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC;QACjC,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;YAChC,OAAO,GAAG,CAAC;QACb,CAAC;QAED,KAAK,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;YACrD,IAAI,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC1B,OAAO,CACL,6CAA6C;oBAC7C,WAAW,MAAM,IAAI;oBACrB,YAAY,OAAO,IAAI;oBACvB,kDAAkD,CACnD,CAAC;YACJ,CAAC;QACH,CAAC;QAED,OAAO,GAAG,CAAC;IACb,CAAC;CACF"}

package/dist/middleware/loopDetection.d.ts

@@ -0,0 +1,28 @@
+import { ToolCallContext, ToolMiddleware } from "./types.js";
+/**
+ * Prevents the "Blind Retry" doom loop.
+ *
+ * Tracks a rolling window of recent tool call signatures. If the same
+ * tool + args combination appears N times consecutively, the call is
+ * rejected with an instruction to try a different approach.
+ *
+ * Reference: docs/02_edge_cases_and_mitigations.md — "The Blind Retry Doom Loop"
+ */
+export declare class LoopDetectionMiddleware implements ToolMiddleware {
+    readonly name = "LoopDetection";
+    private history;
+    private readonly threshold;
+    /**
+     * @param threshold - Number of identical consecutive calls before blocking (default: 3).
+     */
+    constructor(threshold?: number);
+    /**
+     * Creates a signature string for a tool call (name + sorted args JSON).
+     */
+    private signature;
+    before(ctx: ToolCallContext): ToolCallContext | string;
+    /**
+     * Resets the history. Useful for testing or session boundaries.
+     */
+    reset(): void;
+}

package/dist/middleware/loopDetection.js

@@ -0,0 +1,49 @@
+/**
+ * Prevents the "Blind Retry" doom loop.
+ *
+ * Tracks a rolling window of recent tool call signatures. If the same
+ * tool + args combination appears N times consecutively, the call is
+ * rejected with an instruction to try a different approach.
+ *
+ * Reference: docs/02_edge_cases_and_mitigations.md — "The Blind Retry Doom Loop"
+ */
+export class LoopDetectionMiddleware {
+    name = "LoopDetection";
+    history = [];
+    threshold;
+    /**
+     * @param threshold - Number of identical consecutive calls before blocking (default: 3).
+     */
+    constructor(threshold = 3) {
+        this.threshold = threshold;
+    }
+    /**
+     * Creates a signature string for a tool call (name + sorted args JSON).
+     */
+    signature(ctx) {
+        return `${ctx.toolName}:${JSON.stringify(ctx.args, Object.keys(ctx.args).sort())}`;
+    }
+    before(ctx) {
+        const sig = this.signature(ctx);
+        this.history.push(sig);
+        // Keep only the last N entries to avoid unbounded growth
+        if (this.history.length > this.threshold * 2) {
+            this.history = this.history.slice(-this.threshold * 2);
+        }
+        // Check if the last `threshold` entries are all identical
+        const tail = this.history.slice(-this.threshold);
+        if (tail.length >= this.threshold &&
+            tail.every((s) => s === sig)) {
+            return (`⚠ Loop detected: You have called "${ctx.toolName}" with identical arguments ` +
+                `${this.threshold} times consecutively. Stop this approach and try a different strategy.`);
+        }
+        return ctx;
+    }
+    /**
+     * Resets the history. Useful for testing or session boundaries.
+     */
+    reset() {
+        this.history = [];
+    }
+}
+//# sourceMappingURL=loopDetection.js.map

package/dist/middleware/loopDetection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loopDetection.js","sourceRoot":"","sources":["../../src/middleware/loopDetection.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,MAAM,OAAO,uBAAuB;IACzB,IAAI,GAAG,eAAe,CAAC;IAExB,OAAO,GAAa,EAAE,CAAC;IACd,SAAS,CAAS;IAEnC;;OAEG;IACH,YAAY,SAAS,GAAG,CAAC;QACvB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;IAED;;OAEG;IACK,SAAS,CAAC,GAAoB;QACpC,OAAO,GAAG,GAAG,CAAC,QAAQ,IAAI,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;IACrF,CAAC;IAED,MAAM,CAAC,GAAoB;QACzB,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;QAEhC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAEvB,yDAAyD;QACzD,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,SAAS,GAAG,CAAC,EAAE,CAAC;YAC7C,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC;QACzD,CAAC;QAED,0DAA0D;QAC1D,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACjD,IACE,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,SAAS;YAC7B,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,GAAG,CAAC,EAC5B,CAAC;YACD,OAAO,CACL,qCAAqC,GAAG,CAAC,QAAQ,6BAA6B;gBAC9E,GAAG,IAAI,CAAC,SAAS,wEAAwE,CAC1F,CAAC;QACJ,CAAC;QAED,OAAO,GAAG,CAAC;IACb,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,OAAO,GAAG,EAAE,CAAC;IACpB,CAAC;CACF"}

package/dist/middleware/permission.d.ts

@@ -0,0 +1,17 @@
+import { ToolCallContext, ToolMiddleware } from "./types.js";
+export type PermissionMode = "auto" | "ask_dangerous" | "ask_all";
+/**
+ * PermissionMiddleware — gates dangerous tool calls behind user approval.
+ *
+ * Behavior per mode:
+ * - `auto`: All tools execute without asking. (Default for power users.)
+ * - `ask_dangerous`: Only tools in DANGEROUS_TOOLS require approval.
+ * - `ask_all`: Every tool except SAFE_TOOLS requires approval.
+ */
+export declare class PermissionMiddleware implements ToolMiddleware {
+    name: string;
+    private mode;
+    constructor(mode?: PermissionMode);
+    before(ctx: ToolCallContext): Promise<ToolCallContext | string | void>;
+    private requiresApproval;
+}

package/dist/middleware/permission.js

@@ -0,0 +1,59 @@
+import { HITLBridge } from "../hitl/bridge.js";
+/** Tools that are always safe and never need user approval. */
+const SAFE_TOOLS = new Set([
+    "read_file",
+    "view_file_outline",
+    "search_skills",
+    "load_skill",
+    "search_tools",
+    "ask_user_question", // Meta: the ask tool itself is always safe
+]);
+/** Tools that perform destructive or side-effect-heavy operations. */
+const DANGEROUS_TOOLS = new Set([
+    "bash",
+    "write_file",
+    "replace_file_content",
+    "multi_replace_file_content",
+    "install_deps",
+]);
+/**
+ * PermissionMiddleware — gates dangerous tool calls behind user approval.
+ *
+ * Behavior per mode:
+ * - `auto`: All tools execute without asking. (Default for power users.)
+ * - `ask_dangerous`: Only tools in DANGEROUS_TOOLS require approval.
+ * - `ask_all`: Every tool except SAFE_TOOLS requires approval.
+ */
+export class PermissionMiddleware {
+    name = "PermissionMiddleware";
+    mode;
+    constructor(mode = "auto") {
+        this.mode = mode;
+    }
+    async before(ctx) {
+        if (this.mode === "auto")
+            return ctx;
+        const toolName = ctx.toolName;
+        const needsApproval = this.requiresApproval(toolName);
+        if (!needsApproval)
+            return ctx;
+        const bridge = HITLBridge.getInstance();
+        const approved = await bridge.requestPermission(toolName, ctx.args);
+        if (!approved) {
+            // Short-circuit: return a string to deny the tool call
+            return (`Permission denied: The user declined to approve the execution of "${toolName}". ` +
+                `Try an alternative approach or ask the user for guidance using the ask_user_question tool.`);
+        }
+        return ctx;
+    }
+    requiresApproval(toolName) {
+        if (SAFE_TOOLS.has(toolName))
+            return false;
+        if (this.mode === "ask_all")
+            return true;
+        if (this.mode === "ask_dangerous")
+            return DANGEROUS_TOOLS.has(toolName);
+        return false;
+    }
+}
+//# sourceMappingURL=permission.js.map

package/dist/middleware/permission.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission.js","sourceRoot":"","sources":["../../src/middleware/permission.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAK/C,+DAA+D;AAC/D,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC;IACvB,WAAW;IACX,mBAAmB;IACnB,eAAe;IACf,YAAY;IACZ,cAAc;IACd,mBAAmB,EAAE,2CAA2C;CACnE,CAAC,CAAC;AAEH,sEAAsE;AACtE,MAAM,eAAe,GAAG,IAAI,GAAG,CAAC;IAC5B,MAAM;IACN,YAAY;IACZ,sBAAsB;IACtB,4BAA4B;IAC5B,cAAc;CACjB,CAAC,CAAC;AAEH;;;;;;;GAOG;AACH,MAAM,OAAO,oBAAoB;IAC7B,IAAI,GAAG,sBAAsB,CAAC;IACtB,IAAI,CAAiB;IAE7B,YAAY,OAAuB,MAAM;QACrC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACrB,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAoB;QAC7B,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM;YAAE,OAAO,GAAG,CAAC;QAErC,MAAM,QAAQ,GAAG,GAAG,CAAC,QAAQ,CAAC;QAC9B,MAAM,aAAa,GAAG,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC;QAEtD,IAAI,CAAC,aAAa;YAAE,OAAO,GAAG,CAAC;QAE/B,MAAM,MAAM,GAAG,UAAU,CAAC,WAAW,EAAE,CAAC;QACxC,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,iBAAiB,CAAC,QAAQ,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;QAEpE,IAAI,CAAC,QAAQ,EAAE,CAAC;YACZ,uDAAuD;YACvD,OAAO,CACH,qEAAqE,QAAQ,KAAK;gBAClF,4FAA4F,CAC/F,CAAC;QACN,CAAC;QAED,OAAO,GAAG,CAAC;IACf,CAAC;IAEO,gBAAgB,CAAC,QAAgB;QACrC,IAAI,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC;YAAE,OAAO,KAAK,CAAC;QAE3C,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC;QACzC,IAAI,IAAI,CAAC,IAAI,KAAK,eAAe;YAAE,OAAO,eAAe,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAExE,OAAO,KAAK,CAAC;IACjB,CAAC;CACJ"}

package/dist/middleware/pipeline.d.ts

@@ -0,0 +1,31 @@
+import { ToolCallContext, ToolMiddleware } from "./types.js";
+import { ToolResult } from "../tools/index.js";
+/**
+ * Executes tool calls through a chain of middleware hooks.
+ *
+ * Execution flow:
+ * 1. Run all `before()` hooks in registration order.
+ *    - If any returns a string → short-circuit (tool is NOT executed).
+ * 2. Execute the actual tool function.
+ * 3. Run all `after()` hooks in reverse registration order.
+ *    - Each can transform the result before it enters conversation history.
+ */
+export declare class MiddlewarePipeline {
+    private middlewares;
+    /**
+     * Register a middleware. Middlewares run in the order they are added.
+     */
+    use(middleware: ToolMiddleware): void;
+    /**
+     * Returns the number of registered middlewares.
+     */
+    get length(): number;
+    /**
+     * Execute a tool call through the middleware pipeline.
+     *
+     * @param ctx - The tool call context (name, args, callId).
+     * @param executeFn - The actual tool execution function.
+     * @returns The final result string (possibly transformed by after-hooks).
+     */
+    run(ctx: ToolCallContext, executeFn: (ctx: ToolCallContext) => Promise<ToolResult> | ToolResult): Promise<string>;
+}

package/dist/middleware/pipeline.js

@@ -0,0 +1,62 @@
+/**
+ * Executes tool calls through a chain of middleware hooks.
+ *
+ * Execution flow:
+ * 1. Run all `before()` hooks in registration order.
+ *    - If any returns a string → short-circuit (tool is NOT executed).
+ * 2. Execute the actual tool function.
+ * 3. Run all `after()` hooks in reverse registration order.
+ *    - Each can transform the result before it enters conversation history.
+ */
+export class MiddlewarePipeline {
+    middlewares = [];
+    /**
+     * Register a middleware. Middlewares run in the order they are added.
+     */
+    use(middleware) {
+        this.middlewares.push(middleware);
+    }
+    /**
+     * Returns the number of registered middlewares.
+     */
+    get length() {
+        return this.middlewares.length;
+    }
+    /**
+     * Execute a tool call through the middleware pipeline.
+     *
+     * @param ctx - The tool call context (name, args, callId).
+     * @param executeFn - The actual tool execution function.
+     * @returns The final result string (possibly transformed by after-hooks).
+     */
+    async run(ctx, executeFn) {
+        // ── Before phase: run hooks in order ──
+        let currentCtx = ctx;
+        for (const mw of this.middlewares) {
+            if (mw.before) {
+                const result = await mw.before(currentCtx);
+                if (typeof result === "string") {
+                    // Short-circuit: middleware rejected the call
+                    return result;
+                }
+                if (result !== undefined) {
+                    currentCtx = result;
+                }
+            }
+        }
+        // ── Execute the tool ──
+        let output = await executeFn(currentCtx);
+        // ── After phase: run hooks in reverse order ──
+        for (let i = this.middlewares.length - 1; i >= 0; i--) {
+            const mw = this.middlewares[i];
+            if (mw.after) {
+                const transformed = await mw.after(currentCtx, output);
+                if (transformed !== undefined) {
+                    output = transformed;
+                }
+            }
+        }
+        return output.content;
+    }
+}
+//# sourceMappingURL=pipeline.js.map

package/dist/middleware/pipeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.js","sourceRoot":"","sources":["../../src/middleware/pipeline.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH,MAAM,OAAO,kBAAkB;IACrB,WAAW,GAAqB,EAAE,CAAC;IAE3C;;OAEG;IACH,GAAG,CAAC,UAA0B;QAC5B,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACpC,CAAC;IAED;;OAEG;IACH,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC;IACjC,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,GAAG,CACP,GAAoB,EACpB,SAAqE;QAErE,yCAAyC;QACzC,IAAI,UAAU,GAAG,GAAG,CAAC;QAErB,KAAK,MAAM,EAAE,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YAClC,IAAI,EAAE,CAAC,MAAM,EAAE,CAAC;gBACd,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;gBAE3C,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;oBAC/B,8CAA8C;oBAC9C,OAAO,MAAM,CAAC;gBAChB,CAAC;gBAED,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;oBACzB,UAAU,GAAG,MAAM,CAAC;gBACtB,CAAC;YACH,CAAC;QACH,CAAC;QAED,yBAAyB;QACzB,IAAI,MAAM,GAAe,MAAM,SAAS,CAAC,UAAU,CAAC,CAAC;QAErD,gDAAgD;QAChD,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YACtD,MAAM,EAAE,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;YAC/B,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC;gBACb,MAAM,WAAW,GAAG,MAAM,EAAE,CAAC,KAAK,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;gBACvD,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;oBAC9B,MAAM,GAAG,WAAW,CAAC;gBACvB,CAAC;YACH,CAAC;QAAI,CAAC;QAER,OAAO,MAAM,CAAC,OAAO,CAAC;IACxB,CAAC;CACF"}

package/dist/middleware/preCompletion.d.ts

@@ -0,0 +1,29 @@
+import { ToolCallContext, ToolMiddleware } from "./types.js";
+import { ToolResult } from "../tools/index.js";
+/**
+ * Prevents the agent from marking a task as "done" without running tests.
+ *
+ * Tracks whether any test command has been executed during the session.
+ * If the agent attempts to signal completion without running tests first,
+ * the middleware intercepts and forces verification.
+ *
+ * Reference: docs/02_edge_cases_and_mitigations.md — "The Fake Success Verification"
+ */
+export declare class PreCompletionMiddleware implements ToolMiddleware {
+    readonly name = "PreCompletion";
+    private testsPassed;
+    /** Patterns in bash commands that count as "running tests". */
+    private readonly testPatterns;
+    /** Tool names that signal the agent is trying to complete the task. */
+    private readonly completionSignals;
+    before(ctx: ToolCallContext): ToolCallContext | string;
+    after(ctx: ToolCallContext, result: ToolResult): void;
+    /**
+     * Returns whether tests have been run and passed in this session.
+     */
+    hasPassedTests(): boolean;
+    /**
+     * Resets state. Useful for testing or session boundaries.
+     */
+    reset(): void;
+}

package/dist/middleware/preCompletion.js

@@ -0,0 +1,82 @@
+/**
+ * Prevents the agent from marking a task as "done" without running tests.
+ *
+ * Tracks whether any test command has been executed during the session.
+ * If the agent attempts to signal completion without running tests first,
+ * the middleware intercepts and forces verification.
+ *
+ * Reference: docs/02_edge_cases_and_mitigations.md — "The Fake Success Verification"
+ */
+export class PreCompletionMiddleware {
+    name = "PreCompletion";
+    testsPassed = false;
+    /** Patterns in bash commands that count as "running tests". */
+    testPatterns = [
+        /\bvitest\b/,
+        /\bjest\b/,
+        /\bpytest\b/,
+        /\bmocha\b/,
+        /\bnpm\s+test\b/,
+        /\bnpm\s+run\s+test\b/,
+        /\byarn\s+test\b/,
+        /\bpnpm\s+test\b/,
+        /\bgo\s+test\b/,
+        /\bcargo\s+test\b/,
+    ];
+    /** Tool names that signal the agent is trying to complete the task. */
+    completionSignals = new Set([
+        "task_complete",
+        "attempt_completion",
+        "finish_task",
+        "submit_result",
+    ]);
+    before(ctx) {
+        // When a test command is initiated, assume it hasn't passed yet
+        if (ctx.toolName === "bash" && typeof ctx.args.command === "string") {
+            for (const pattern of this.testPatterns) {
+                if (pattern.test(ctx.args.command)) {
+                    this.testsPassed = false;
+                    break;
+                }
+            }
+        }
+        // Intercept completion attempts
+        if (this.completionSignals.has(ctx.toolName)) {
+            if (!this.testsPassed) {
+                return ("⚠ You must run tests before completing the task, AND they must pass.\n" +
+                    "Use the bash tool to execute your test suite (e.g., `npm test`, `vitest`, `pytest`).\n" +
+                    "If tests fail, fix the issues. Once tests pass cleanly, you may attempt completion again.");
+            }
+        }
+        return ctx;
+    }
+    after(ctx, result) {
+        if (ctx.toolName === "bash" && typeof ctx.args.command === "string") {
+            for (const pattern of this.testPatterns) {
+                if (pattern.test(ctx.args.command)) {
+                    // Robustly check the exact exit code from the tool metadata
+                    if (result.metadata?.exitCode === 0) {
+                        this.testsPassed = true;
+                    }
+                    else {
+                        this.testsPassed = false;
+                    }
+                    break;
+                }
+            }
+        }
+    }
+    /**
+     * Returns whether tests have been run and passed in this session.
+     */
+    hasPassedTests() {
+        return this.testsPassed;
+    }
+    /**
+     * Resets state. Useful for testing or session boundaries.
+     */
+    reset() {
+        this.testsPassed = false;
+    }
+}
+//# sourceMappingURL=preCompletion.js.map

package/dist/middleware/preCompletion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preCompletion.js","sourceRoot":"","sources":["../../src/middleware/preCompletion.ts"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AACH,MAAM,OAAO,uBAAuB;IACzB,IAAI,GAAG,eAAe,CAAC;IAExB,WAAW,GAAG,KAAK,CAAC;IAE5B,+DAA+D;IAC9C,YAAY,GAAG;QAC9B,YAAY;QACZ,UAAU;QACV,YAAY;QACZ,WAAW;QACX,gBAAgB;QAChB,sBAAsB;QACtB,iBAAiB;QACjB,iBAAiB;QACjB,eAAe;QACf,kBAAkB;KACnB,CAAC;IAEF,uEAAuE;IACtD,iBAAiB,GAAG,IAAI,GAAG,CAAC;QAC3C,eAAe;QACf,oBAAoB;QACpB,aAAa;QACb,eAAe;KAChB,CAAC,CAAC;IAEH,MAAM,CAAC,GAAoB;QACzB,gEAAgE;QAChE,IAAI,GAAG,CAAC,QAAQ,KAAK,MAAM,IAAI,OAAO,GAAG,CAAC,IAAI,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;YACpE,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;gBACxC,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;oBACnC,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC;oBACzB,MAAM;gBACR,CAAC;YACH,CAAC;QACH,CAAC;QAED,gCAAgC;QAChC,IAAI,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC7C,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;gBACtB,OAAO,CACL,wEAAwE;oBACxE,wFAAwF;oBACxF,2FAA2F,CAC5F,CAAC;YACJ,CAAC;QACH,CAAC;QAED,OAAO,GAAG,CAAC;IACb,CAAC;IAED,KAAK,CAAC,GAAoB,EAAE,MAAkB;QAC5C,IAAI,GAAG,CAAC,QAAQ,KAAK,MAAM,IAAI,OAAO,GAAG,CAAC,IAAI,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;YACpE,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;gBACxC,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;oBACnC,4DAA4D;oBAC5D,IAAI,MAAM,CAAC,QAAQ,EAAE,QAAQ,KAAK,CAAC,EAAE,CAAC;wBACpC,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;oBAC1B,CAAC;yBAAM,CAAC;wBACN,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC;oBAC3B,CAAC;oBACD,MAAM;gBACR,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED;;OAEG;IACH,cAAc;QACZ,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC;IAC3B,CAAC;CACF"}

package/dist/middleware/types.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Middleware types for the tool execution pipeline.
+ *
+ * Each middleware can hook into both the "before" and "after" phases
+ * of a tool call. The pipeline chains them in order.
+ */
+import { ToolResult } from "../tools/index.js";
+/**
+ * Context object passed through the middleware chain for each tool call.
+ */
+export interface ToolCallContext {
+    /** Name of the tool being called (e.g., "bash", "read_file"). */
+    toolName: string;
+    /** Arguments passed to the tool. */
+    args: Record<string, any>;
+    /** Unique ID of this tool call (from the LLM response). */
+    callId: string;
+}
+/**
+ * A middleware that can intercept tool calls before and after execution.
+ *
+ * - `before()`: Runs before the tool executes. Return the (possibly modified)
+ *   context to continue, or a `string` to short-circuit with an error/warning.
+ * - `after()`: Runs after the tool executes. Can transform the result before
+ *   it enters the conversation history.
+ */
+export interface ToolMiddleware {
+    /** Human-readable name for logging and debugging. */
+    name: string;
+    /**
+     * Pre-execution hook.
+     * @returns ToolCallContext to mutate, a string to short-circuit, or void to pass through unmodified.
+     */
+    before?(ctx: ToolCallContext): Promise<ToolCallContext | string | void> | ToolCallContext | string | void;
+    /**
+     * Post-execution hook.
+     * @returns The transformed tool result object, or void to pass through unmodified.
+     */
+    after?(ctx: ToolCallContext, result: ToolResult): Promise<ToolResult | void> | ToolResult | void;
+}

package/dist/middleware/types.js

@@ -0,0 +1,8 @@
+/**
+ * Middleware types for the tool execution pipeline.
+ *
+ * Each middleware can hook into both the "before" and "after" phases
+ * of a tool call. The pipeline chains them in order.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/middleware/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/middleware/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}