@researchcomputer/agents-sdk 0.1.0

package/dist/middleware/hooks.js

@@ -0,0 +1,71 @@
+/**
+ * Check if a hook matches the given event and tool name.
+ */
+function hookMatches(hook, event, toolName) {
+    if (hook.event !== event)
+        return false;
+    if (hook.matcher && toolName && hook.matcher !== toolName)
+        return false;
+    return true;
+}
+/**
+ * Run all matching PreToolUse hooks, chaining updated args through each hook.
+ * Returns the final (possibly modified) args.
+ */
+export async function runPreToolUseHooks(hooks, toolName, args, runContext) {
+    let currentArgs = args;
+    for (const hook of hooks) {
+        if (!hookMatches(hook, 'PreToolUse', toolName))
+            continue;
+        const context = {
+            event: 'PreToolUse',
+            runContext,
+            toolName,
+            toolArgs: currentArgs,
+        };
+        const result = await hook.handler(context);
+        if (result?.updatedArgs !== undefined) {
+            currentArgs = result.updatedArgs;
+        }
+    }
+    return currentArgs;
+}
+/**
+ * Run all matching PostToolUse hooks, chaining updated results through each hook.
+ * Returns the final (possibly modified) tool result.
+ */
+export async function runPostToolUseHooks(hooks, toolName, toolResult, runContext) {
+    let currentResult = toolResult;
+    for (const hook of hooks) {
+        if (!hookMatches(hook, 'PostToolUse', toolName))
+            continue;
+        const context = {
+            event: 'PostToolUse',
+            runContext,
+            toolName,
+            toolResult: currentResult,
+        };
+        const result = await hook.handler(context);
+        if (result?.updatedResult !== undefined) {
+            currentResult = result.updatedResult;
+        }
+    }
+    return currentResult;
+}
+/**
+ * Run all matching lifecycle hooks (SessionStart, SessionEnd, Stop, etc.).
+ * Lifecycle hooks ignore the matcher field.
+ */
+export async function runLifecycleHooks(hooks, event, runContext, extra) {
+    for (const hook of hooks) {
+        if (hook.event !== event)
+            continue;
+        const context = {
+            event,
+            runContext,
+            ...extra,
+        };
+        await hook.handler(context);
+    }
+}
+//# sourceMappingURL=hooks.js.map

package/dist/middleware/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../../src/middleware/hooks.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,SAAS,WAAW,CAAC,IAAiB,EAAE,KAAgB,EAAE,QAAiB;IACzE,IAAI,IAAI,CAAC,KAAK,KAAK,KAAK;QAAE,OAAO,KAAK,CAAC;IACvC,IAAI,IAAI,CAAC,OAAO,IAAI,QAAQ,IAAI,IAAI,CAAC,OAAO,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACxE,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,KAAoB,EACpB,QAAgB,EAChB,IAAa,EACb,UAAsB;IAEtB,IAAI,WAAW,GAAG,IAAI,CAAC;IAEvB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,YAAY,EAAE,QAAQ,CAAC;YAAE,SAAS;QAEzD,MAAM,OAAO,GAAgB;YAC3B,KAAK,EAAE,YAAY;YACnB,UAAU;YACV,QAAQ;YACR,QAAQ,EAAE,WAAW;SACtB,CAAC;QAEF,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAC3C,IAAI,MAAM,EAAE,WAAW,KAAK,SAAS,EAAE,CAAC;YACtC,WAAW,GAAG,MAAM,CAAC,WAAW,CAAC;QACnC,CAAC;IACH,CAAC;IAED,OAAO,WAAW,CAAC;AACrB,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,KAAoB,EACpB,QAAgB,EAChB,UAAgC,EAChC,UAAsB;IAEtB,IAAI,aAAa,GAAG,UAAU,CAAC;IAE/B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,aAAa,EAAE,QAAQ,CAAC;YAAE,SAAS;QAE1D,MAAM,OAAO,GAAgB;YAC3B,KAAK,EAAE,aAAa;YACpB,UAAU;YACV,QAAQ;YACR,UAAU,EAAE,aAAa;SAC1B,CAAC;QAEF,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAC3C,IAAI,MAAM,EAAE,aAAa,KAAK,SAAS,EAAE,CAAC;YACxC,aAAa,GAAG,MAAM,CAAC,aAAa,CAAC;QACvC,CAAC;IACH,CAAC;IAED,OAAO,aAAa,CAAC;AACvB,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,KAAoB,EACpB,KAAgB,EAChB,UAAsB,EACtB,KAA4D;IAE5D,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,KAAK,KAAK,KAAK;YAAE,SAAS;QAEnC,MAAM,OAAO,GAAgB;YAC3B,KAAK;YACL,UAAU;YACV,GAAG,KAAK;SACT,CAAC;QAEF,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9B,CAAC;AACH,CAAC"}

package/dist/middleware/hooks.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=hooks.test.d.ts.map

package/dist/middleware/hooks.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.test.d.ts","sourceRoot":"","sources":["../../src/middleware/hooks.test.ts"],"names":[],"mappings":""}

package/dist/middleware/hooks.test.js

@@ -0,0 +1,172 @@
+import { describe, it, expect, vi } from 'vitest';
+import { runPreToolUseHooks, runPostToolUseHooks, runLifecycleHooks } from './hooks.js';
+import { createRunContext } from '../context/run-context.js';
+function makeRunContext() {
+    return createRunContext({ cwd: '/tmp' });
+}
+describe('runPreToolUseHooks', () => {
+    it('runs matching PreToolUse hooks and returns updated args', async () => {
+        const hooks = [
+            {
+                event: 'PreToolUse',
+                handler: async (ctx) => ({ updatedArgs: { ...ctx.toolArgs, extra: true } }),
+            },
+        ];
+        const result = await runPreToolUseHooks(hooks, 'ReadFile', { path: '/tmp' }, makeRunContext());
+        expect(result).toEqual({ path: '/tmp', extra: true });
+    });
+    it('chains args through multiple hooks', async () => {
+        const hooks = [
+            {
+                event: 'PreToolUse',
+                handler: async (ctx) => ({ updatedArgs: { ...ctx.toolArgs, first: true } }),
+            },
+            {
+                event: 'PreToolUse',
+                handler: async (ctx) => ({ updatedArgs: { ...ctx.toolArgs, second: true } }),
+            },
+        ];
+        const result = await runPreToolUseHooks(hooks, 'ReadFile', { path: '/tmp' }, makeRunContext());
+        expect(result).toEqual({ path: '/tmp', first: true, second: true });
+    });
+    it('returns original args if no hooks match', async () => {
+        const hooks = [
+            { event: 'PostToolUse', handler: async () => ({}) },
+        ];
+        const args = { path: '/tmp' };
+        const result = await runPreToolUseHooks(hooks, 'ReadFile', args, makeRunContext());
+        expect(result).toBe(args);
+    });
+    it('skips hooks whose matcher does not match toolName', async () => {
+        const handler = vi.fn().mockResolvedValue({ updatedArgs: { changed: true } });
+        const hooks = [
+            { event: 'PreToolUse', matcher: 'WriteFile', handler },
+        ];
+        const result = await runPreToolUseHooks(hooks, 'ReadFile', { path: '/tmp' }, makeRunContext());
+        expect(handler).not.toHaveBeenCalled();
+        expect(result).toEqual({ path: '/tmp' });
+    });
+    it('runs hooks when matcher matches toolName', async () => {
+        const handler = vi.fn().mockResolvedValue({ updatedArgs: { changed: true } });
+        const hooks = [
+            { event: 'PreToolUse', matcher: 'ReadFile', handler },
+        ];
+        const result = await runPreToolUseHooks(hooks, 'ReadFile', { path: '/tmp' }, makeRunContext());
+        expect(handler).toHaveBeenCalled();
+        expect(result).toEqual({ changed: true });
+    });
+    it('preserves args if hook returns void', async () => {
+        const hooks = [
+            { event: 'PreToolUse', handler: async () => undefined },
+        ];
+        const args = { path: '/tmp' };
+        const result = await runPreToolUseHooks(hooks, 'ReadFile', args, makeRunContext());
+        expect(result).toBe(args);
+    });
+    it('preserves args if hook returns empty object', async () => {
+        const hooks = [
+            { event: 'PreToolUse', handler: async () => ({}) },
+        ];
+        const args = { path: '/tmp' };
+        const result = await runPreToolUseHooks(hooks, 'ReadFile', args, makeRunContext());
+        expect(result).toBe(args);
+    });
+});
+describe('runPostToolUseHooks', () => {
+    it('runs matching PostToolUse hooks and returns updated result', async () => {
+        const hooks = [
+            {
+                event: 'PostToolUse',
+                handler: async () => ({
+                    updatedResult: { content: [{ type: 'text', text: 'modified' }], details: {} },
+                }),
+            },
+        ];
+        const original = { content: [{ type: 'text', text: 'original' }], details: {} };
+        const result = await runPostToolUseHooks(hooks, 'ReadFile', original, makeRunContext());
+        expect(result.content[0]).toEqual({ type: 'text', text: 'modified' });
+    });
+    it('chains results through multiple hooks', async () => {
+        const hooks = [
+            {
+                event: 'PostToolUse',
+                handler: async (ctx) => ({
+                    updatedResult: { content: [{ type: 'text', text: 'step1' }], details: ctx.toolResult?.details },
+                }),
+            },
+            {
+                event: 'PostToolUse',
+                handler: async (ctx) => ({
+                    updatedResult: { content: [{ type: 'text', text: 'step2' }], details: ctx.toolResult?.details },
+                }),
+            },
+        ];
+        const original = { content: [{ type: 'text', text: 'original' }], details: {} };
+        const result = await runPostToolUseHooks(hooks, 'ReadFile', original, makeRunContext());
+        expect(result.content[0]).toEqual({ type: 'text', text: 'step2' });
+    });
+    it('returns original result if no hooks match', async () => {
+        const hooks = [
+            { event: 'PreToolUse', handler: async () => ({}) },
+        ];
+        const original = { content: [{ type: 'text', text: 'original' }], details: {} };
+        const result = await runPostToolUseHooks(hooks, 'ReadFile', original, makeRunContext());
+        expect(result).toBe(original);
+    });
+    it('skips hooks with non-matching matcher', async () => {
+        const handler = vi.fn().mockResolvedValue({
+            updatedResult: { content: [{ type: 'text', text: 'changed' }], details: {} },
+        });
+        const hooks = [
+            { event: 'PostToolUse', matcher: 'WriteFile', handler },
+        ];
+        const original = { content: [{ type: 'text', text: 'original' }], details: {} };
+        const result = await runPostToolUseHooks(hooks, 'ReadFile', original, makeRunContext());
+        expect(handler).not.toHaveBeenCalled();
+        expect(result).toBe(original);
+    });
+});
+describe('runLifecycleHooks', () => {
+    it('runs all matching lifecycle hooks', async () => {
+        const handler1 = vi.fn().mockResolvedValue(undefined);
+        const handler2 = vi.fn().mockResolvedValue(undefined);
+        const hooks = [
+            { event: 'SessionStart', handler: handler1 },
+            { event: 'SessionStart', handler: handler2 },
+            { event: 'SessionEnd', handler: vi.fn() },
+        ];
+        await runLifecycleHooks(hooks, 'SessionStart', makeRunContext());
+        expect(handler1).toHaveBeenCalled();
+        expect(handler2).toHaveBeenCalled();
+    });
+    it('passes extra context to hook', async () => {
+        const handler = vi.fn().mockResolvedValue(undefined);
+        const hooks = [
+            { event: 'SessionStart', handler },
+        ];
+        const extra = { agentName: 'test' };
+        await runLifecycleHooks(hooks, 'SessionStart', makeRunContext(), extra);
+        expect(handler).toHaveBeenCalledWith(expect.objectContaining({
+            event: 'SessionStart',
+            agentName: 'test',
+        }));
+    });
+    it('does nothing when no hooks match', async () => {
+        const handler = vi.fn();
+        const hooks = [
+            { event: 'SessionEnd', handler },
+        ];
+        await runLifecycleHooks(hooks, 'SessionStart', makeRunContext());
+        expect(handler).not.toHaveBeenCalled();
+    });
+    it('ignores matcher for lifecycle hooks', async () => {
+        const handler = vi.fn().mockResolvedValue(undefined);
+        const hooks = [
+            { event: 'SessionStart', matcher: 'SomeTool', handler },
+        ];
+        // Lifecycle hooks should still run even with a matcher set (matcher is for tool hooks)
+        await runLifecycleHooks(hooks, 'SessionStart', makeRunContext());
+        expect(handler).toHaveBeenCalled();
+    });
+});
+//# sourceMappingURL=hooks.test.js.map

package/dist/middleware/hooks.test.js.map

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

package/dist/middleware/index.d.ts

@@ -0,0 +1,7 @@
+export { matchRule, findMatchingRule, evaluatePermission } from './permissions.js';
+export { createPermissionMiddleware } from './permission-middleware.js';
+export type { PermissionMiddlewareConfig } from './permission-middleware.js';
+export { runPreToolUseHooks, runPostToolUseHooks, runLifecycleHooks } from './hooks.js';
+export { composePipeline } from './pipeline.js';
+export type { PipelineConfig, Pipeline } from './pipeline.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/middleware/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/middleware/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACnF,OAAO,EAAE,0BAA0B,EAAE,MAAM,4BAA4B,CAAC;AACxE,YAAY,EAAE,0BAA0B,EAAE,MAAM,4BAA4B,CAAC;AAC7E,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACxF,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,YAAY,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC"}

package/dist/middleware/index.js

@@ -0,0 +1,5 @@
+export { matchRule, findMatchingRule, evaluatePermission } from './permissions.js';
+export { createPermissionMiddleware } from './permission-middleware.js';
+export { runPreToolUseHooks, runPostToolUseHooks, runLifecycleHooks } from './hooks.js';
+export { composePipeline } from './pipeline.js';
+//# sourceMappingURL=index.js.map

package/dist/middleware/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/middleware/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACnF,OAAO,EAAE,0BAA0B,EAAE,MAAM,4BAA4B,CAAC;AAExE,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACxF,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC"}

package/dist/middleware/permission-middleware.d.ts

@@ -0,0 +1,11 @@
+import type { BeforeToolCallContext, BeforeToolCallResult } from '@mariozechner/pi-agent-core';
+import type { SdkTool, PermissionMode, PermissionRule, RunContext } from '../types.js';
+export interface PermissionMiddlewareConfig {
+    mode: PermissionMode;
+    rules: PermissionRule[];
+    tools: SdkTool<any, any>[];
+    runContext: RunContext;
+    onAsk?: (toolName: string, args: unknown) => Promise<boolean>;
+}
+export declare function createPermissionMiddleware(config: PermissionMiddlewareConfig): (context: BeforeToolCallContext, signal?: AbortSignal) => Promise<BeforeToolCallResult | undefined>;
+//# sourceMappingURL=permission-middleware.d.ts.map

package/dist/middleware/permission-middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-middleware.d.ts","sourceRoot":"","sources":["../../src/middleware/permission-middleware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAC/F,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,UAAU,EAAkC,MAAM,aAAa,CAAC;AAGvH,MAAM,WAAW,0BAA0B;IACzC,IAAI,EAAE,cAAc,CAAC;IACrB,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,KAAK,EAAE,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC;IAC3B,UAAU,EAAE,UAAU,CAAC;IACvB,KAAK,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC/D;AAED,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,0BAA0B,GACjC,CAAC,OAAO,EAAE,qBAAqB,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC,CAkDrG"}

package/dist/middleware/permission-middleware.js

@@ -0,0 +1,56 @@
+import { evaluatePermission } from './permissions.js';
+export function createPermissionMiddleware(config) {
+    const { mode, rules, tools, runContext, onAsk } = config;
+    return async (context, _signal) => {
+        const toolName = context.toolCall.name;
+        const args = context.args;
+        // Look up tool to get capabilities
+        const tool = tools.find(t => t.name === toolName);
+        const capabilities = tool?.capabilities ?? [];
+        // Check tool-specific permissionCheck first
+        if (tool?.permissionCheck) {
+            const checkResult = tool.permissionCheck(args, rules);
+            if (checkResult.behavior === 'deny') {
+                logDecision(runContext, toolName, args, 'deny', undefined, toolName);
+                return { block: true, reason: checkResult.reason };
+            }
+            if (checkResult.behavior === 'allow') {
+                logDecision(runContext, toolName, args, 'allow', undefined, toolName);
+                return undefined;
+            }
+            // 'ask' falls through to evaluatePermission
+        }
+        // Fall back to evaluatePermission
+        const result = evaluatePermission(mode, rules, toolName, args, capabilities);
+        if (result.behavior === 'allow') {
+            logDecision(runContext, toolName, args, 'allow', undefined, toolName);
+            return undefined;
+        }
+        if (result.behavior === 'deny') {
+            logDecision(runContext, toolName, args, 'deny', undefined, toolName);
+            return { block: true, reason: result.reason };
+        }
+        // 'ask' behavior
+        if (onAsk) {
+            const allowed = await onAsk(toolName, args);
+            if (allowed) {
+                logDecision(runContext, toolName, args, 'allow', undefined, toolName);
+                return undefined;
+            }
+        }
+        logDecision(runContext, toolName, args, 'deny', undefined, toolName);
+        return { block: true, reason: 'Permission denied by user' };
+    };
+}
+function logDecision(runContext, toolName, args, behavior, matchedRule, normalizedTarget) {
+    const decision = {
+        toolName,
+        args,
+        behavior,
+        matchedRule,
+        normalizedTarget,
+        timestamp: Date.now(),
+    };
+    runContext.permissionDecisions.push(decision);
+}
+//# sourceMappingURL=permission-middleware.js.map

package/dist/middleware/permission-middleware.js.map

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

package/dist/middleware/permission-middleware.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=permission-middleware.test.d.ts.map

package/dist/middleware/permission-middleware.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-middleware.test.d.ts","sourceRoot":"","sources":["../../src/middleware/permission-middleware.test.ts"],"names":[],"mappings":""}

package/dist/middleware/permission-middleware.test.js

@@ -0,0 +1,170 @@
+import { describe, it, expect, vi } from 'vitest';
+import { Type } from '@sinclair/typebox';
+import { createPermissionMiddleware } from './permission-middleware.js';
+import { createRunContext } from '../context/run-context.js';
+function makeTool(name, capabilities = [], permissionCheck) {
+    return {
+        name,
+        label: name,
+        description: `Tool ${name}`,
+        parameters: Type.Object({}),
+        capabilities,
+        permissionCheck,
+        execute: async () => ({ content: [{ type: 'text', text: 'ok' }], details: {} }),
+    };
+}
+function makeContext(toolName, args = {}) {
+    return {
+        assistantMessage: {
+            role: 'assistant',
+            content: [],
+            api: 'openai-completions',
+            provider: 'openai',
+            model: 'gpt-4',
+            usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
+            stopReason: 'stop',
+            timestamp: Date.now(),
+        },
+        toolCall: { type: 'toolCall', id: 'tc-1', name: toolName, arguments: args },
+        args,
+        context: { systemPrompt: '', messages: [], tools: [] },
+    };
+}
+function makeRunContext() {
+    return createRunContext({ cwd: '/tmp' });
+}
+describe('createPermissionMiddleware', () => {
+    it('returns undefined (allow) for allowAll mode', async () => {
+        const middleware = createPermissionMiddleware({
+            mode: 'allowAll',
+            rules: [],
+            tools: [makeTool('ReadFile', ['fs:read'])],
+            runContext: makeRunContext(),
+        });
+        const result = await middleware(makeContext('ReadFile'));
+        expect(result).toBeUndefined();
+    });
+    it('returns block for denied tool', async () => {
+        const rules = [
+            { target: { type: 'tool', name: 'WriteFile' }, behavior: 'deny', source: 'user' },
+        ];
+        const middleware = createPermissionMiddleware({
+            mode: 'default',
+            rules,
+            tools: [makeTool('WriteFile', ['fs:write'])],
+            runContext: makeRunContext(),
+        });
+        const result = await middleware(makeContext('WriteFile'));
+        expect(result).toEqual({ block: true, reason: expect.any(String) });
+    });
+    it('uses tool-specific permissionCheck if defined', async () => {
+        const permissionCheck = vi.fn().mockReturnValue({ behavior: 'deny', reason: 'custom deny' });
+        const tool = makeTool('CustomTool', ['fs:write'], permissionCheck);
+        const middleware = createPermissionMiddleware({
+            mode: 'default',
+            rules: [],
+            tools: [tool],
+            runContext: makeRunContext(),
+        });
+        const result = await middleware(makeContext('CustomTool'));
+        expect(permissionCheck).toHaveBeenCalled();
+        expect(result).toEqual({ block: true, reason: 'custom deny' });
+    });
+    it('falls back to evaluatePermission when permissionCheck returns allow', async () => {
+        const permissionCheck = vi.fn().mockReturnValue({ behavior: 'allow' });
+        const tool = makeTool('CustomTool', ['fs:write'], permissionCheck);
+        const middleware = createPermissionMiddleware({
+            mode: 'default',
+            rules: [],
+            tools: [tool],
+            runContext: makeRunContext(),
+        });
+        // permissionCheck allows, but evaluatePermission should ask for mutation cap
+        const result = await middleware(makeContext('CustomTool'));
+        // Since permissionCheck returned allow, we trust it
+        expect(result).toBeUndefined();
+    });
+    it('calls onAsk callback for ask behavior and allows if true', async () => {
+        const onAsk = vi.fn().mockResolvedValue(true);
+        const middleware = createPermissionMiddleware({
+            mode: 'default',
+            rules: [],
+            tools: [makeTool('WriteFile', ['fs:write'])],
+            runContext: makeRunContext(),
+            onAsk,
+        });
+        const result = await middleware(makeContext('WriteFile'));
+        expect(onAsk).toHaveBeenCalledWith('WriteFile', {});
+        expect(result).toBeUndefined();
+    });
+    it('calls onAsk callback for ask behavior and blocks if false', async () => {
+        const onAsk = vi.fn().mockResolvedValue(false);
+        const middleware = createPermissionMiddleware({
+            mode: 'default',
+            rules: [],
+            tools: [makeTool('WriteFile', ['fs:write'])],
+            runContext: makeRunContext(),
+            onAsk,
+        });
+        const result = await middleware(makeContext('WriteFile'));
+        expect(result).toEqual({ block: true, reason: expect.any(String) });
+    });
+    it('denies when ask behavior and no onAsk callback', async () => {
+        const middleware = createPermissionMiddleware({
+            mode: 'default',
+            rules: [],
+            tools: [makeTool('WriteFile', ['fs:write'])],
+            runContext: makeRunContext(),
+        });
+        const result = await middleware(makeContext('WriteFile'));
+        expect(result).toEqual({ block: true, reason: expect.any(String) });
+    });
+    it('logs permission decision to runContext', async () => {
+        const runContext = makeRunContext();
+        const middleware = createPermissionMiddleware({
+            mode: 'allowAll',
+            rules: [],
+            tools: [makeTool('ReadFile', ['fs:read'])],
+            runContext,
+        });
+        await middleware(makeContext('ReadFile'));
+        expect(runContext.permissionDecisions).toHaveLength(1);
+        const decision = runContext.permissionDecisions[0];
+        expect(decision.toolName).toBe('ReadFile');
+        expect(decision.behavior).toBe('allow');
+        expect(decision.timestamp).toBeGreaterThan(0);
+    });
+    it('handles unknown tool (not in tools list) with empty capabilities', async () => {
+        const middleware = createPermissionMiddleware({
+            mode: 'default',
+            rules: [],
+            tools: [],
+            runContext: makeRunContext(),
+        });
+        // Unknown tool in default mode with no caps → allow (no mutation capabilities)
+        const result = await middleware(makeContext('UnknownTool'));
+        expect(result).toBeUndefined();
+    });
+    it('allows read-only tools in default mode without rules', async () => {
+        const middleware = createPermissionMiddleware({
+            mode: 'default',
+            rules: [],
+            tools: [makeTool('ReadFile', ['fs:read'])],
+            runContext: makeRunContext(),
+        });
+        const result = await middleware(makeContext('ReadFile'));
+        expect(result).toBeUndefined();
+    });
+    it('passes signal to middleware', async () => {
+        const controller = new AbortController();
+        const middleware = createPermissionMiddleware({
+            mode: 'allowAll',
+            rules: [],
+            tools: [makeTool('ReadFile', ['fs:read'])],
+            runContext: makeRunContext(),
+        });
+        const result = await middleware(makeContext('ReadFile'), controller.signal);
+        expect(result).toBeUndefined();
+    });
+});
+//# sourceMappingURL=permission-middleware.test.js.map

package/dist/middleware/permission-middleware.test.js.map

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

package/dist/middleware/permissions.d.ts

@@ -0,0 +1,14 @@
+import type { PermissionRule, PermissionResult, PermissionMode, Capability } from '../types.js';
+/**
+ * Check if a rule matches a tool invocation.
+ */
+export declare function matchRule(rule: PermissionRule, toolName: string, args: unknown, capabilities: Capability[]): boolean;
+/**
+ * Find the best matching rule by combined score (specificity * 10 + source_priority).
+ */
+export declare function findMatchingRule(rules: PermissionRule[], toolName: string, args: unknown, capabilities: Capability[]): PermissionRule | null;
+/**
+ * Evaluate permission result based on mode, rules, and capabilities.
+ */
+export declare function evaluatePermission(mode: PermissionMode, rules: PermissionRule[], toolName: string, args: unknown, capabilities: Capability[]): PermissionResult;
+//# sourceMappingURL=permissions.d.ts.map

package/dist/middleware/permissions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../../src/middleware/permissions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AA8ChG;;GAEG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,cAAc,EACpB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,OAAO,EACb,YAAY,EAAE,UAAU,EAAE,GACzB,OAAO,CAwBT;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,cAAc,EAAE,EACvB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,OAAO,EACb,YAAY,EAAE,UAAU,EAAE,GACzB,cAAc,GAAG,IAAI,CAcvB;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,cAAc,EACpB,KAAK,EAAE,cAAc,EAAE,EACvB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,OAAO,EACb,YAAY,EAAE,UAAU,EAAE,GACzB,gBAAgB,CA0BlB"}