@agentic-kit/pi 0.26.2 → 0.27.0

package/embed/lanes.d.ts

@@ -11,6 +11,7 @@ import type { MeteredIdentity } from '@agentic-kit/metering';
 import type { ExtensionFactory } from '@earendil-works/pi-coding-agent';
 import { type GateExtension, type GateExtensionOptions } from '../extensions/gate';
 import { type MeteredModelExtension, type MeteredModelExtensionOptions } from '../extensions/metered-model';
+import { type PermissionsExtension, type PermissionsExtensionOptions } from '../extensions/permissions';
 import { type RunLogExtension, type RunLogExtensionOptions } from '../extensions/run-log';
 import { type UsageReportExtension, type UsageReportExtensionOptions } from '../extensions/usage-report';
 /** Run log lane — `runId` comes from the run, not from here. */
@@ -28,10 +29,17 @@ export type MeteringLane = ({
 } & UsageReportExtensionOptions);
 /** Approval lane — `runId` comes from the run. */
 export type GateLane = Omit<GateExtensionOptions, 'runId'>;
+/**
+ * Permissions lane — the built-in tools (read, write, edit, bash, grep, find,
+ * ls) and secret redaction of every tool result. `runId` comes from the run.
+ */
+export type PermissionsLane = Omit<PermissionsExtensionOptions, 'runId'>;
 export interface ComposeRunOptions {
     runId: string;
     log?: RunLogLane;
     metering?: MeteringLane;
+    /** Loaded before `gate`: it owns the built-in tools, the gate owns the rest. */
+    permissions?: PermissionsLane;
     gate?: GateLane;
     /**
      * The host's own extensions — workspace tools, prompts, UI glue. Loaded after
@@ -43,11 +51,12 @@ export interface ComposedLanes {
     log?: RunLogExtension;
     meteredModel?: MeteredModelExtension;
     usageReport?: UsageReportExtension;
+    permissions?: PermissionsExtension;
     gate?: GateExtension;
 }
 export interface ComposedRun {
     runId: string;
-    /** In load order: log, metering, gate, then the host's own. */
+    /** In load order: log, metering, permissions, gate, then the host's own. */
     extensions: ExtensionFactory[];
     lanes: ComposedLanes;
     /**

package/embed/lanes.js

@@ -12,6 +12,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.composeRun = composeRun;
 const gate_1 = require("../extensions/gate");
 const metered_model_1 = require("../extensions/metered-model");
+const permissions_1 = require("../extensions/permissions");
 const run_log_1 = require("../extensions/run-log");
 const usage_report_1 = require("../extensions/usage-report");
 function composeRun(options) {
@@ -40,6 +41,10 @@ function composeRun(options) {
         });
         extensions.push(lanes.usageReport.extension);
     }
+    if (options.permissions) {
+        lanes.permissions = (0, permissions_1.createPermissionsExtension)({ runId: options.runId, ...options.permissions });
+        extensions.push(lanes.permissions.extension);
+    }
     if (options.gate) {
         lanes.gate = (0, gate_1.createGateExtension)({ runId: options.runId, ...options.gate });
         extensions.push(lanes.gate.extension);

package/esm/embed/lanes.d.ts

@@ -11,6 +11,7 @@ import type { MeteredIdentity } from '@agentic-kit/metering';
 import type { ExtensionFactory } from '@earendil-works/pi-coding-agent';
 import { type GateExtension, type GateExtensionOptions } from '../extensions/gate';
 import { type MeteredModelExtension, type MeteredModelExtensionOptions } from '../extensions/metered-model';
+import { type PermissionsExtension, type PermissionsExtensionOptions } from '../extensions/permissions';
 import { type RunLogExtension, type RunLogExtensionOptions } from '../extensions/run-log';
 import { type UsageReportExtension, type UsageReportExtensionOptions } from '../extensions/usage-report';
 /** Run log lane — `runId` comes from the run, not from here. */
@@ -28,10 +29,17 @@ export type MeteringLane = ({
 } & UsageReportExtensionOptions);
 /** Approval lane — `runId` comes from the run. */
 export type GateLane = Omit<GateExtensionOptions, 'runId'>;
+/**
+ * Permissions lane — the built-in tools (read, write, edit, bash, grep, find,
+ * ls) and secret redaction of every tool result. `runId` comes from the run.
+ */
+export type PermissionsLane = Omit<PermissionsExtensionOptions, 'runId'>;
 export interface ComposeRunOptions {
     runId: string;
     log?: RunLogLane;
     metering?: MeteringLane;
+    /** Loaded before `gate`: it owns the built-in tools, the gate owns the rest. */
+    permissions?: PermissionsLane;
     gate?: GateLane;
     /**
      * The host's own extensions — workspace tools, prompts, UI glue. Loaded after
@@ -43,11 +51,12 @@ export interface ComposedLanes {
     log?: RunLogExtension;
     meteredModel?: MeteredModelExtension;
     usageReport?: UsageReportExtension;
+    permissions?: PermissionsExtension;
     gate?: GateExtension;
 }
 export interface ComposedRun {
     runId: string;
-    /** In load order: log, metering, gate, then the host's own. */
+    /** In load order: log, metering, permissions, gate, then the host's own. */
     extensions: ExtensionFactory[];
     lanes: ComposedLanes;
     /**

package/esm/embed/lanes.js

@@ -9,6 +9,7 @@
  */
 import { createGateExtension } from '../extensions/gate';
 import { createMeteredModelExtension } from '../extensions/metered-model';
+import { createPermissionsExtension } from '../extensions/permissions';
 import { createRunLogExtension } from '../extensions/run-log';
 import { createUsageReportExtension } from '../extensions/usage-report';
 export function composeRun(options) {
@@ -37,6 +38,10 @@ export function composeRun(options) {
         });
         extensions.push(lanes.usageReport.extension);
     }
+    if (options.permissions) {
+        lanes.permissions = createPermissionsExtension({ runId: options.runId, ...options.permissions });
+        extensions.push(lanes.permissions.extension);
+    }
     if (options.gate) {
         lanes.gate = createGateExtension({ runId: options.runId, ...options.gate });
         extensions.push(lanes.gate.extension);

package/esm/extensions/permissions.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The pi side of the permissions layer: classify every built-in tool call with
+ * the neutral engine, ask through the run's approval channel when it must, and
+ * keep secret values out of every tool result the model sees.
+ *
+ * Loaded by `composeRun` before the DB gate, so it decides on the input after
+ * every file-based extension ran and before trusted host code. It abstains on
+ * tools that are not pi built-ins: the DB gate and the host own those.
+ *
+ * Fails closed: an engine error blocks the call, and a redaction error
+ * withholds the output (pi swallows a `tool_result` throw and would send the
+ * raw output, so the catch here is the only guard).
+ */
+import type { ApprovalChannel, ApprovalGrantScope } from '@agentic-kit/harness';
+import { type Grant, type GrantStore, type PermissionDecision, type PermissionEngine, type PermissionMode, type Signal } from '@agentic-kit/permissions';
+import type { createBashToolDefinition, ExtensionFactory } from '@earendil-works/pi-coding-agent';
+/** The session entry that carries one chat-scope grant. Not sent to the model. */
+export declare const PERMISSION_GRANT_ENTRY = "agentic.permissions.grant";
+export declare const PERMISSION_INTERNAL_ERROR = "permissions: internal error \u2014 the call was blocked";
+export declare const PERMISSION_OUTPUT_WITHHELD = "permissions: output withheld \u2014 redaction failed, so the result was not sent to the model";
+export interface PermissionDecisionRecord {
+    runId: string;
+    toolCallId: string;
+    toolName: string;
+    /** What the engine said before any human answered. */
+    verdict: PermissionDecision['decision'];
+    /** How the call was finally settled. */
+    decision: 'allow' | 'deny';
+    reason?: string;
+    signals: Signal[];
+    targets: {
+        path: string;
+        access: string;
+        zone: string;
+    }[];
+    /** On an approved ask: how far the answer reaches. */
+    scope?: 'once' | ApprovalGrantScope;
+    actorId?: string;
+    decidedAt: string;
+}
+export interface PermissionsExtensionOptions {
+    runId: string;
+    engine: PermissionEngine;
+    /** Read at every decision, so a mode change applies to the next tool call. */
+    getMode: () => PermissionMode | Promise<PermissionMode>;
+    /** Required for `ask`. Without one, an ask becomes a deny that tells the model why. */
+    approvals?: ApprovalChannel;
+    /** Where "always in this project" grants live (a file per project on desktop). */
+    projectGrants?: GrantStore;
+    /** Every settled decision, for the run log / audit trail. */
+    onDecision?: (record: PermissionDecisionRecord) => void;
+    /** Internal failures (the call is already blocked or withheld). */
+    onError?: (error: unknown, phase: 'tool_call' | 'tool_result' | 'session_start') => void;
+    /**
+     * Replace pi's `bash` with one whose commands run without the secret-looking
+     * variables of the host environment, so a command cannot send a provider key
+     * or token it never saw. The host passes pi's own factory (this package
+     * imports pi as types only).
+     */
+    bash?: {
+        cwd: string;
+        createDefinition: typeof createBashToolDefinition;
+    };
+    now?: () => Date;
+}
+export interface PermissionsExtension {
+    extension: ExtensionFactory;
+    /** The grants this chat holds (restored from the session on start). */
+    readonly chatGrants: readonly Grant[];
+}
+export declare function createPermissionsExtension(options: PermissionsExtensionOptions): PermissionsExtension;

package/esm/extensions/permissions.js

@@ -0,0 +1,150 @@
+/**
+ * The pi side of the permissions layer: classify every built-in tool call with
+ * the neutral engine, ask through the run's approval channel when it must, and
+ * keep secret values out of every tool result the model sees.
+ *
+ * Loaded by `composeRun` before the DB gate, so it decides on the input after
+ * every file-based extension ran and before trusted host code. It abstains on
+ * tools that are not pi built-ins: the DB gate and the host own those.
+ *
+ * Fails closed: an engine error blocks the call, and a redaction error
+ * withholds the output (pi swallows a `tool_result` throw and would send the
+ * raw output, so the catch here is the only guard).
+ */
+import { BUILTIN_TOOLS, grantFrom, scrubEnv } from '@agentic-kit/permissions';
+/** The session entry that carries one chat-scope grant. Not sent to the model. */
+export const PERMISSION_GRANT_ENTRY = 'agentic.permissions.grant';
+export const PERMISSION_INTERNAL_ERROR = 'permissions: internal error — the call was blocked';
+export const PERMISSION_OUTPUT_WITHHELD = 'permissions: output withheld — redaction failed, so the result was not sent to the model';
+export function createPermissionsExtension(options) {
+    const { engine, runId } = options;
+    const now = options.now ?? (() => new Date());
+    const chatGrants = [];
+    const record = (decision, settled, extra = {}) => {
+        options.onDecision?.({
+            runId,
+            toolCallId: decision.request.toolCallId,
+            toolName: decision.request.toolName,
+            verdict: decision.decision,
+            decision: settled,
+            ...(extra.reason === undefined ? {} : { reason: extra.reason }),
+            signals: decision.request.signals,
+            targets: decision.request.targets.map(({ path, access, zone }) => ({ path, access, zone })),
+            ...(extra.scope === undefined ? {} : { scope: extra.scope }),
+            ...(extra.actorId === undefined ? {} : { actorId: extra.actorId }),
+            decidedAt: now().toISOString()
+        });
+    };
+    const remember = async (pi, decision, scope) => {
+        const option = decision.grantOptions.find((candidate) => candidate.scope === scope);
+        if (!option)
+            return;
+        const grant = grantFrom(option);
+        if (scope === 'chat') {
+            chatGrants.push(grant);
+            pi.appendEntry(PERMISSION_GRANT_ENTRY, grant);
+        }
+        else {
+            await options.projectGrants?.add(grant);
+        }
+    };
+    const decide = async (pi, event) => {
+        const input = (event.input ?? {});
+        const call = { toolCallId: event.toolCallId, toolName: event.toolName, input };
+        const projectGrants = (await options.projectGrants?.list()) ?? [];
+        const decision = await engine.evaluate(call, {
+            mode: await options.getMode(),
+            grants: [...chatGrants, ...projectGrants]
+        });
+        if (!decision)
+            return undefined;
+        if (decision.decision === 'allow') {
+            engine.restoreInput(decision, input);
+            record(decision, 'allow');
+            return undefined;
+        }
+        if (decision.decision === 'deny') {
+            record(decision, 'deny', { reason: decision.reason });
+            return { block: true, reason: decision.reason };
+        }
+        if (!options.approvals) {
+            const reason = `${decision.reason} — this needs user approval, and no one can approve it here; ask the user to allow it`;
+            record(decision, 'deny', { reason });
+            return { block: true, reason };
+        }
+        const outcome = await options.approvals.request({
+            runId,
+            toolCallId: event.toolCallId,
+            toolName: event.toolName,
+            input,
+            reason: decision.reason,
+            requestedAt: now().toISOString(),
+            permission: decision.prompt
+        });
+        if (outcome.decision !== 'allow') {
+            const reason = outcome.reason ?? `permissions: the user denied this ${event.toolName} call`;
+            record(decision, 'deny', { reason, actorId: outcome.actorId });
+            return { block: true, reason };
+        }
+        const scope = outcome.grant?.scope;
+        if (scope)
+            await remember(pi, decision, scope);
+        engine.restoreInput(decision, input, { approved: true });
+        record(decision, 'allow', { scope: scope ?? 'once', actorId: outcome.actorId });
+        return undefined;
+    };
+    const extension = (pi) => {
+        if (options.bash) {
+            const { cwd, createDefinition } = options.bash;
+            pi.registerTool(createDefinition(cwd, { spawnHook: (spawn) => ({ ...spawn, env: scrubEnv(spawn.env) }) }));
+        }
+        pi.on('session_start', async (_event, ctx) => {
+            chatGrants.length = 0;
+            try {
+                for (const entry of ctx.sessionManager.getEntries()) {
+                    if (entry.type === 'custom' && entry.customType === PERMISSION_GRANT_ENTRY && entry.data) {
+                        chatGrants.push(entry.data);
+                    }
+                }
+            }
+            catch (error) {
+                options.onError?.(error, 'session_start');
+            }
+        });
+        pi.on('tool_call', async (event) => {
+            if (!BUILTIN_TOOLS.has(event.toolName))
+                return undefined;
+            try {
+                return await decide(pi, event);
+            }
+            catch (error) {
+                options.onError?.(error, 'tool_call');
+                return { block: true, reason: PERMISSION_INTERNAL_ERROR };
+            }
+        });
+        // Every tool's output passes through redaction, not only the built-ins: a
+        // host tool can echo a token as easily as `cat .env` can.
+        pi.on('tool_result', async (event) => {
+            try {
+                const redacted = await engine.redactResult({
+                    toolName: event.toolName,
+                    content: event.content ?? [],
+                    details: event.details
+                });
+                if (!redacted.changed)
+                    return undefined;
+                // Redaction keeps every block's shape and only rewrites the text in it.
+                return { content: redacted.content, details: redacted.details };
+            }
+            catch (error) {
+                options.onError?.(error, 'tool_result');
+                return {
+                    content: [{ type: 'text', text: PERMISSION_OUTPUT_WITHHELD }],
+                    details: undefined,
+                    isError: true
+                };
+            }
+        });
+    };
+    return { extension, chatGrants };
+}

package/esm/index.d.ts

@@ -12,10 +12,11 @@ export declare const dbTools: ExtensionFactory;
 /** Configure the host and get the extension in one call. */
 export declare function createDbTools(host: ToolsHost): ExtensionFactory;
 export { type ConfirmGate, type ConfirmGateDeps, type ConfirmGateOptions, createConfirmGate, } from './confirm-gate';
-export { type ComposedLanes, type ComposedRun, composeRun, type ComposeRunOptions, type GateLane, type MeteringLane, type RunLogLane, } from './embed/lanes';
+export { type ComposedLanes, type ComposedRun, composeRun, type ComposeRunOptions, type GateLane, type MeteringLane, type PermissionsLane, type RunLogLane, } from './embed/lanes';
 export { type CreateResourceLoader, type EmbeddedRun, type PiModule, type ResourceLoaderRequest, startRun, type StartRunOptions, } from './embed/session';
 export { createGateExtension, type GateExtension, type GateExtensionOptions, } from './extensions/gate';
 export { createMeteredModelExtension, type MeteredModelExtension, type MeteredModelExtensionOptions, piProviderConfig, } from './extensions/metered-model';
+export { createPermissionsExtension, PERMISSION_GRANT_ENTRY, PERMISSION_INTERNAL_ERROR, PERMISSION_OUTPUT_WITHHELD, type PermissionDecisionRecord, type PermissionsExtension, type PermissionsExtensionOptions, } from './extensions/permissions';
 export { createRunLogExtension, MIRROR_EVENTS, type MirrorEvent, type RunLogExtension, type RunLogExtensionOptions, } from './extensions/run-log';
 export { createUsageReportExtension, type UsageReportExtension, type UsageReportExtensionOptions, } from './extensions/usage-report';
 export { PI_HARNESS_ID, piHarness, type PiHarnessRun } from './harness';

package/esm/index.js

@@ -31,6 +31,7 @@ export { composeRun, } from './embed/lanes';
 export { startRun, } from './embed/session';
 export { createGateExtension, } from './extensions/gate';
 export { createMeteredModelExtension, piProviderConfig, } from './extensions/metered-model';
+export { createPermissionsExtension, PERMISSION_GRANT_ENTRY, PERMISSION_INTERNAL_ERROR, PERMISSION_OUTPUT_WITHHELD, } from './extensions/permissions';
 export { createRunLogExtension, MIRROR_EVENTS, } from './extensions/run-log';
 export { createUsageReportExtension, } from './extensions/usage-report';
 export { PI_HARNESS_ID, piHarness } from './harness';

package/extensions/permissions.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The pi side of the permissions layer: classify every built-in tool call with
+ * the neutral engine, ask through the run's approval channel when it must, and
+ * keep secret values out of every tool result the model sees.
+ *
+ * Loaded by `composeRun` before the DB gate, so it decides on the input after
+ * every file-based extension ran and before trusted host code. It abstains on
+ * tools that are not pi built-ins: the DB gate and the host own those.
+ *
+ * Fails closed: an engine error blocks the call, and a redaction error
+ * withholds the output (pi swallows a `tool_result` throw and would send the
+ * raw output, so the catch here is the only guard).
+ */
+import type { ApprovalChannel, ApprovalGrantScope } from '@agentic-kit/harness';
+import { type Grant, type GrantStore, type PermissionDecision, type PermissionEngine, type PermissionMode, type Signal } from '@agentic-kit/permissions';
+import type { createBashToolDefinition, ExtensionFactory } from '@earendil-works/pi-coding-agent';
+/** The session entry that carries one chat-scope grant. Not sent to the model. */
+export declare const PERMISSION_GRANT_ENTRY = "agentic.permissions.grant";
+export declare const PERMISSION_INTERNAL_ERROR = "permissions: internal error \u2014 the call was blocked";
+export declare const PERMISSION_OUTPUT_WITHHELD = "permissions: output withheld \u2014 redaction failed, so the result was not sent to the model";
+export interface PermissionDecisionRecord {
+    runId: string;
+    toolCallId: string;
+    toolName: string;
+    /** What the engine said before any human answered. */
+    verdict: PermissionDecision['decision'];
+    /** How the call was finally settled. */
+    decision: 'allow' | 'deny';
+    reason?: string;
+    signals: Signal[];
+    targets: {
+        path: string;
+        access: string;
+        zone: string;
+    }[];
+    /** On an approved ask: how far the answer reaches. */
+    scope?: 'once' | ApprovalGrantScope;
+    actorId?: string;
+    decidedAt: string;
+}
+export interface PermissionsExtensionOptions {
+    runId: string;
+    engine: PermissionEngine;
+    /** Read at every decision, so a mode change applies to the next tool call. */
+    getMode: () => PermissionMode | Promise<PermissionMode>;
+    /** Required for `ask`. Without one, an ask becomes a deny that tells the model why. */
+    approvals?: ApprovalChannel;
+    /** Where "always in this project" grants live (a file per project on desktop). */
+    projectGrants?: GrantStore;
+    /** Every settled decision, for the run log / audit trail. */
+    onDecision?: (record: PermissionDecisionRecord) => void;
+    /** Internal failures (the call is already blocked or withheld). */
+    onError?: (error: unknown, phase: 'tool_call' | 'tool_result' | 'session_start') => void;
+    /**
+     * Replace pi's `bash` with one whose commands run without the secret-looking
+     * variables of the host environment, so a command cannot send a provider key
+     * or token it never saw. The host passes pi's own factory (this package
+     * imports pi as types only).
+     */
+    bash?: {
+        cwd: string;
+        createDefinition: typeof createBashToolDefinition;
+    };
+    now?: () => Date;
+}
+export interface PermissionsExtension {
+    extension: ExtensionFactory;
+    /** The grants this chat holds (restored from the session on start). */
+    readonly chatGrants: readonly Grant[];
+}
+export declare function createPermissionsExtension(options: PermissionsExtensionOptions): PermissionsExtension;

package/extensions/permissions.js

@@ -0,0 +1,154 @@
+"use strict";
+/**
+ * The pi side of the permissions layer: classify every built-in tool call with
+ * the neutral engine, ask through the run's approval channel when it must, and
+ * keep secret values out of every tool result the model sees.
+ *
+ * Loaded by `composeRun` before the DB gate, so it decides on the input after
+ * every file-based extension ran and before trusted host code. It abstains on
+ * tools that are not pi built-ins: the DB gate and the host own those.
+ *
+ * Fails closed: an engine error blocks the call, and a redaction error
+ * withholds the output (pi swallows a `tool_result` throw and would send the
+ * raw output, so the catch here is the only guard).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PERMISSION_OUTPUT_WITHHELD = exports.PERMISSION_INTERNAL_ERROR = exports.PERMISSION_GRANT_ENTRY = void 0;
+exports.createPermissionsExtension = createPermissionsExtension;
+const permissions_1 = require("@agentic-kit/permissions");
+/** The session entry that carries one chat-scope grant. Not sent to the model. */
+exports.PERMISSION_GRANT_ENTRY = 'agentic.permissions.grant';
+exports.PERMISSION_INTERNAL_ERROR = 'permissions: internal error — the call was blocked';
+exports.PERMISSION_OUTPUT_WITHHELD = 'permissions: output withheld — redaction failed, so the result was not sent to the model';
+function createPermissionsExtension(options) {
+    const { engine, runId } = options;
+    const now = options.now ?? (() => new Date());
+    const chatGrants = [];
+    const record = (decision, settled, extra = {}) => {
+        options.onDecision?.({
+            runId,
+            toolCallId: decision.request.toolCallId,
+            toolName: decision.request.toolName,
+            verdict: decision.decision,
+            decision: settled,
+            ...(extra.reason === undefined ? {} : { reason: extra.reason }),
+            signals: decision.request.signals,
+            targets: decision.request.targets.map(({ path, access, zone }) => ({ path, access, zone })),
+            ...(extra.scope === undefined ? {} : { scope: extra.scope }),
+            ...(extra.actorId === undefined ? {} : { actorId: extra.actorId }),
+            decidedAt: now().toISOString()
+        });
+    };
+    const remember = async (pi, decision, scope) => {
+        const option = decision.grantOptions.find((candidate) => candidate.scope === scope);
+        if (!option)
+            return;
+        const grant = (0, permissions_1.grantFrom)(option);
+        if (scope === 'chat') {
+            chatGrants.push(grant);
+            pi.appendEntry(exports.PERMISSION_GRANT_ENTRY, grant);
+        }
+        else {
+            await options.projectGrants?.add(grant);
+        }
+    };
+    const decide = async (pi, event) => {
+        const input = (event.input ?? {});
+        const call = { toolCallId: event.toolCallId, toolName: event.toolName, input };
+        const projectGrants = (await options.projectGrants?.list()) ?? [];
+        const decision = await engine.evaluate(call, {
+            mode: await options.getMode(),
+            grants: [...chatGrants, ...projectGrants]
+        });
+        if (!decision)
+            return undefined;
+        if (decision.decision === 'allow') {
+            engine.restoreInput(decision, input);
+            record(decision, 'allow');
+            return undefined;
+        }
+        if (decision.decision === 'deny') {
+            record(decision, 'deny', { reason: decision.reason });
+            return { block: true, reason: decision.reason };
+        }
+        if (!options.approvals) {
+            const reason = `${decision.reason} — this needs user approval, and no one can approve it here; ask the user to allow it`;
+            record(decision, 'deny', { reason });
+            return { block: true, reason };
+        }
+        const outcome = await options.approvals.request({
+            runId,
+            toolCallId: event.toolCallId,
+            toolName: event.toolName,
+            input,
+            reason: decision.reason,
+            requestedAt: now().toISOString(),
+            permission: decision.prompt
+        });
+        if (outcome.decision !== 'allow') {
+            const reason = outcome.reason ?? `permissions: the user denied this ${event.toolName} call`;
+            record(decision, 'deny', { reason, actorId: outcome.actorId });
+            return { block: true, reason };
+        }
+        const scope = outcome.grant?.scope;
+        if (scope)
+            await remember(pi, decision, scope);
+        engine.restoreInput(decision, input, { approved: true });
+        record(decision, 'allow', { scope: scope ?? 'once', actorId: outcome.actorId });
+        return undefined;
+    };
+    const extension = (pi) => {
+        if (options.bash) {
+            const { cwd, createDefinition } = options.bash;
+            pi.registerTool(createDefinition(cwd, { spawnHook: (spawn) => ({ ...spawn, env: (0, permissions_1.scrubEnv)(spawn.env) }) }));
+        }
+        pi.on('session_start', async (_event, ctx) => {
+            chatGrants.length = 0;
+            try {
+                for (const entry of ctx.sessionManager.getEntries()) {
+                    if (entry.type === 'custom' && entry.customType === exports.PERMISSION_GRANT_ENTRY && entry.data) {
+                        chatGrants.push(entry.data);
+                    }
+                }
+            }
+            catch (error) {
+                options.onError?.(error, 'session_start');
+            }
+        });
+        pi.on('tool_call', async (event) => {
+            if (!permissions_1.BUILTIN_TOOLS.has(event.toolName))
+                return undefined;
+            try {
+                return await decide(pi, event);
+            }
+            catch (error) {
+                options.onError?.(error, 'tool_call');
+                return { block: true, reason: exports.PERMISSION_INTERNAL_ERROR };
+            }
+        });
+        // Every tool's output passes through redaction, not only the built-ins: a
+        // host tool can echo a token as easily as `cat .env` can.
+        pi.on('tool_result', async (event) => {
+            try {
+                const redacted = await engine.redactResult({
+                    toolName: event.toolName,
+                    content: event.content ?? [],
+                    details: event.details
+                });
+                if (!redacted.changed)
+                    return undefined;
+                // Redaction keeps every block's shape and only rewrites the text in it.
+                return { content: redacted.content, details: redacted.details };
+            }
+            catch (error) {
+                options.onError?.(error, 'tool_result');
+                return {
+                    content: [{ type: 'text', text: exports.PERMISSION_OUTPUT_WITHHELD }],
+                    details: undefined,
+                    isError: true
+                };
+            }
+        });
+    };
+    return { extension, chatGrants };
+}

package/index.d.ts

@@ -12,10 +12,11 @@ export declare const dbTools: ExtensionFactory;
 /** Configure the host and get the extension in one call. */
 export declare function createDbTools(host: ToolsHost): ExtensionFactory;
 export { type ConfirmGate, type ConfirmGateDeps, type ConfirmGateOptions, createConfirmGate, } from './confirm-gate';
-export { type ComposedLanes, type ComposedRun, composeRun, type ComposeRunOptions, type GateLane, type MeteringLane, type RunLogLane, } from './embed/lanes';
+export { type ComposedLanes, type ComposedRun, composeRun, type ComposeRunOptions, type GateLane, type MeteringLane, type PermissionsLane, type RunLogLane, } from './embed/lanes';
 export { type CreateResourceLoader, type EmbeddedRun, type PiModule, type ResourceLoaderRequest, startRun, type StartRunOptions, } from './embed/session';
 export { createGateExtension, type GateExtension, type GateExtensionOptions, } from './extensions/gate';
 export { createMeteredModelExtension, type MeteredModelExtension, type MeteredModelExtensionOptions, piProviderConfig, } from './extensions/metered-model';
+export { createPermissionsExtension, PERMISSION_GRANT_ENTRY, PERMISSION_INTERNAL_ERROR, PERMISSION_OUTPUT_WITHHELD, type PermissionDecisionRecord, type PermissionsExtension, type PermissionsExtensionOptions, } from './extensions/permissions';
 export { createRunLogExtension, MIRROR_EVENTS, type MirrorEvent, type RunLogExtension, type RunLogExtensionOptions, } from './extensions/run-log';
 export { createUsageReportExtension, type UsageReportExtension, type UsageReportExtensionOptions, } from './extensions/usage-report';
 export { PI_HARNESS_ID, piHarness, type PiHarnessRun } from './harness';

package/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getModulePreset = exports.allModulePresets = exports.toolSchema = exports.resolveProvisionModules = exports.resolveProjectContext = exports.resolveDataToken = exports.PROVISION_MANIFEST_FILE = exports.parseProvisionManifest = exports.moduleKey = exports.loadProvisionManifest = exports.getHost = exports.fromEnvironment = exports.fromEnvFile = exports.deriveSubdomainEndpoint = exports.DEFAULT_PROVISION_PRESET = exports.createTemplatePreviewTables = exports.CONTEXT_ENV_PREFIX = exports.CONTEXT_ENV_KEYS = exports.constructiveDbTools = exports.configureHost = exports.toPiTools = exports.toPiTool = exports.piHarness = exports.PI_HARNESS_ID = exports.createUsageReportExtension = exports.MIRROR_EVENTS = exports.createRunLogExtension = exports.piProviderConfig = exports.createMeteredModelExtension = exports.createGateExtension = exports.startRun = exports.composeRun = exports.createConfirmGate = exports.dbTools = void 0;
+exports.getModulePreset = exports.allModulePresets = exports.toolSchema = exports.resolveProvisionModules = exports.resolveProjectContext = exports.resolveDataToken = exports.PROVISION_MANIFEST_FILE = exports.parseProvisionManifest = exports.moduleKey = exports.loadProvisionManifest = exports.getHost = exports.fromEnvironment = exports.fromEnvFile = exports.deriveSubdomainEndpoint = exports.DEFAULT_PROVISION_PRESET = exports.createTemplatePreviewTables = exports.CONTEXT_ENV_PREFIX = exports.CONTEXT_ENV_KEYS = exports.constructiveDbTools = exports.configureHost = exports.toPiTools = exports.toPiTool = exports.piHarness = exports.PI_HARNESS_ID = exports.createUsageReportExtension = exports.MIRROR_EVENTS = exports.createRunLogExtension = exports.PERMISSION_OUTPUT_WITHHELD = exports.PERMISSION_INTERNAL_ERROR = exports.PERMISSION_GRANT_ENTRY = exports.createPermissionsExtension = exports.piProviderConfig = exports.createMeteredModelExtension = exports.createGateExtension = exports.startRun = exports.composeRun = exports.createConfirmGate = exports.dbTools = void 0;
 exports.createDbTools = createDbTools;
 const db_tools_1 = require("@agentic-kit/db-tools");
 const confirm_gate_1 = require("./confirm-gate");
@@ -42,6 +42,11 @@ Object.defineProperty(exports, "createGateExtension", { enumerable: true, get: f
 var metered_model_1 = require("./extensions/metered-model");
 Object.defineProperty(exports, "createMeteredModelExtension", { enumerable: true, get: function () { return metered_model_1.createMeteredModelExtension; } });
 Object.defineProperty(exports, "piProviderConfig", { enumerable: true, get: function () { return metered_model_1.piProviderConfig; } });
+var permissions_1 = require("./extensions/permissions");
+Object.defineProperty(exports, "createPermissionsExtension", { enumerable: true, get: function () { return permissions_1.createPermissionsExtension; } });
+Object.defineProperty(exports, "PERMISSION_GRANT_ENTRY", { enumerable: true, get: function () { return permissions_1.PERMISSION_GRANT_ENTRY; } });
+Object.defineProperty(exports, "PERMISSION_INTERNAL_ERROR", { enumerable: true, get: function () { return permissions_1.PERMISSION_INTERNAL_ERROR; } });
+Object.defineProperty(exports, "PERMISSION_OUTPUT_WITHHELD", { enumerable: true, get: function () { return permissions_1.PERMISSION_OUTPUT_WITHHELD; } });
 var run_log_1 = require("./extensions/run-log");
 Object.defineProperty(exports, "createRunLogExtension", { enumerable: true, get: function () { return run_log_1.createRunLogExtension; } });
 Object.defineProperty(exports, "MIRROR_EVENTS", { enumerable: true, get: function () { return run_log_1.MIRROR_EVENTS; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentic-kit/pi",
-  "version": "0.26.2",
+  "version": "0.27.0",
   "author": "Dan Lynch <pyramation@gmail.com>",
   "description": "the pi adapter for agentic-kit — Constructive's typed db tools, confirm gate, and the run-log/metering/gate lanes attached to a pi coding-agent session",
   "main": "index.js",
@@ -29,9 +29,10 @@
     "test:watch": "jest --watch"
   },
   "dependencies": {
-    "@agentic-kit/db-tools": "^0.10.2",
-    "@agentic-kit/harness": "^0.17.0",
+    "@agentic-kit/db-tools": "^0.10.3",
+    "@agentic-kit/harness": "^0.18.0",
     "@agentic-kit/metering": "^0.6.0",
+    "@agentic-kit/permissions": "^0.2.0",
     "@agentic-kit/run-log": "^0.8.0",
     "zod": "^4.4.3"
   },
@@ -47,5 +48,5 @@
     "coding-agent",
     "constructive"
   ],
-  "gitHead": "91e18cc80da92331fb3aadd5baa43251c8934bc8"
+  "gitHead": "9d1255b0e72a134fbc96190b2e1b8b0b0155bc29"
 }