@agent-native/core 0.171.1 → 0.172.0

package/dist/agent/harness/store.js

@@ -1,5 +1,16 @@
 import { getDbExec, intType, isPostgres } from "../../db/client.js";
 import { ensureColumnExists, ensureIndexExists, ensureTableExists, } from "../../db/ddl-guard.js";
+export class AgentHarnessSessionConflictError extends Error {
+    constructor(sessionId) {
+        super(`Harness session ${sessionId} changed concurrently; retry the operation.`);
+        this.name = "AgentHarnessSessionConflictError";
+    }
+}
+export function isAgentHarnessSessionConflictError(error) {
+    return (error instanceof AgentHarnessSessionConflictError ||
+        (error instanceof Error &&
+            error.name === "AgentHarnessSessionConflictError"));
+}
 let initPromise;
 export async function ensureAgentHarnessSessionTables() {
     if (!initPromise) {
@@ -19,6 +30,7 @@ export async function ensureAgentHarnessSessionTables() {
           resolved_approval_ids TEXT,
           owner_email TEXT,
           org_id TEXT,
+          generation ${intType()} NOT NULL DEFAULT 0,
           created_at ${intType()} NOT NULL,
           updated_at ${intType()} NOT NULL,
           stopped_at ${intType()}
@@ -41,6 +53,7 @@ export async function ensureAgentHarnessSessionTables() {
                     await ensureColumnExists("agent_harness_sessions", col, `ALTER TABLE agent_harness_sessions ADD COLUMN IF NOT EXISTS ${col} TEXT`);
                 }
                 await ensureColumnExists("agent_harness_sessions", "stopped_at", `ALTER TABLE agent_harness_sessions ADD COLUMN IF NOT EXISTS stopped_at ${intType()}`);
+                await ensureColumnExists("agent_harness_sessions", "generation", `ALTER TABLE agent_harness_sessions ADD COLUMN IF NOT EXISTS generation ${intType()} NOT NULL DEFAULT 0`);
                 await ensureIndexExists("idx_agent_harness_sessions_thread", `CREATE INDEX IF NOT EXISTS idx_agent_harness_sessions_thread ON agent_harness_sessions(thread_id, updated_at)`);
                 await ensureIndexExists("idx_agent_harness_sessions_status", `CREATE INDEX IF NOT EXISTS idx_agent_harness_sessions_status ON agent_harness_sessions(status, updated_at)`);
                 await ensureIndexExists("idx_agent_harness_sessions_owner", `CREATE INDEX IF NOT EXISTS idx_agent_harness_sessions_owner ON agent_harness_sessions(owner_email, updated_at)`);
@@ -48,6 +61,13 @@ export async function ensureAgentHarnessSessionTables() {
             }
             // SQLite (local dev): no lock problem — keep the original behaviour.
             await client.execute(createSql);
+            try {
+                await client.execute(`ALTER TABLE agent_harness_sessions ADD COLUMN generation ${intType()} NOT NULL DEFAULT 0`);
+            }
+            catch (error) {
+                if (!isDuplicateColumnError(error))
+                    throw error;
+            }
             for (const col of [
                 "run_id",
                 "provider_session_id",
@@ -99,7 +119,9 @@ export async function ensureAgentHarnessSessionTables() {
 export async function saveAgentHarnessSession(input) {
     await ensureAgentHarnessSessionTables();
     const now = Date.now();
-    const existing = await getAgentHarnessSession(input.id);
+    const existing = input.existingSession === undefined
+        ? await getAgentHarnessSession(input.id)
+        : input.existingSession;
     const record = {
         id: input.id,
         harnessName: input.harnessName,
@@ -117,33 +139,60 @@ export async function saveAgentHarnessSession(input) {
         resolvedApprovalIds: input.resolvedApprovalIds ?? existing?.resolvedApprovalIds ?? [],
         ownerEmail: input.ownerEmail ?? existing?.ownerEmail ?? null,
         orgId: input.orgId ?? existing?.orgId ?? null,
+        generation: (input.expectedGeneration ?? existing?.generation ?? 0) + 1,
         createdAt: existing?.createdAt ?? now,
         updatedAt: now,
         stoppedAt: input.stoppedAt ?? existing?.stoppedAt ?? null,
     };
     const client = getDbExec();
-    await client.execute({
-        sql: `INSERT INTO agent_harness_sessions (
-            id, harness_name, thread_id, run_id, provider_session_id, status,
-            resume_state, workspace_ref, pending_approval, resolved_approval_ids,
-            owner_email, org_id, created_at, updated_at, stopped_at
-          ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-          ON CONFLICT(id) DO UPDATE SET
-            harness_name = excluded.harness_name,
-            thread_id = excluded.thread_id,
-            run_id = excluded.run_id,
-            provider_session_id = excluded.provider_session_id,
-            status = excluded.status,
-            resume_state = excluded.resume_state,
-            workspace_ref = excluded.workspace_ref,
-            pending_approval = excluded.pending_approval,
-            resolved_approval_ids = excluded.resolved_approval_ids,
-            owner_email = excluded.owner_email,
-            org_id = excluded.org_id,
-            updated_at = excluded.updated_at,
-            stopped_at = excluded.stopped_at`,
+    const values = [
+        record.id,
+        record.harnessName,
+        record.threadId,
+        record.runId ?? null,
+        record.providerSessionId ?? null,
+        record.status,
+        serializeJson(record.resumeState),
+        record.workspaceRef ?? null,
+        serializeJson(record.pendingApproval),
+        serializeJson(record.resolvedApprovalIds),
+        record.ownerEmail ?? null,
+        record.orgId ?? null,
+        record.generation,
+        record.createdAt,
+        record.updatedAt,
+        record.stoppedAt ?? null,
+    ];
+    if (!existing) {
+        const inserted = await client.execute({
+            sql: `INSERT INTO agent_harness_sessions (
+              id, harness_name, thread_id, run_id, provider_session_id, status,
+              resume_state, workspace_ref, pending_approval, resolved_approval_ids,
+              owner_email, org_id, generation, created_at, updated_at, stopped_at
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            ON CONFLICT(id) DO NOTHING`,
+            args: values,
+        });
+        if (inserted.rowsAffected === 1)
+            return record;
+        const current = await getAgentHarnessSession(input.id);
+        if (!current)
+            throw new Error("Harness session insert did not persist.");
+        return saveAgentHarnessSession({
+            ...input,
+            expectedGeneration: undefined,
+            existingSession: undefined,
+        });
+    }
+    const expectedGeneration = input.expectedGeneration ?? existing.generation;
+    const updated = await client.execute({
+        sql: `UPDATE agent_harness_sessions SET
+            harness_name = ?, thread_id = ?, run_id = ?, provider_session_id = ?,
+            status = ?, resume_state = ?, workspace_ref = ?, pending_approval = ?,
+            resolved_approval_ids = ?, owner_email = ?, org_id = ?, generation = ?,
+            updated_at = ?, stopped_at = ?
+          WHERE id = ? AND generation = ?`,
         args: [
-            record.id,
             record.harnessName,
             record.threadId,
             record.runId ?? null,
@@ -155,11 +204,16 @@ export async function saveAgentHarnessSession(input) {
             serializeJson(record.resolvedApprovalIds),
             record.ownerEmail ?? null,
             record.orgId ?? null,
-            record.createdAt,
+            record.generation,
             record.updatedAt,
             record.stoppedAt ?? null,
+            record.id,
+            expectedGeneration,
         ],
     });
+    if (updated.rowsAffected !== 1) {
+        throw new AgentHarnessSessionConflictError(record.id);
+    }
     return record;
 }
 export async function updateAgentHarnessSession(id, patch) {
@@ -184,6 +238,8 @@ export async function updateAgentHarnessSession(id, patch) {
         ownerEmail: patch.ownerEmail ?? existing.ownerEmail ?? null,
         orgId: patch.orgId ?? existing.orgId ?? null,
         stoppedAt: patch.stoppedAt ?? existing.stoppedAt ?? null,
+        expectedGeneration: existing.generation,
+        existingSession: existing,
     });
 }
 export async function getAgentHarnessSession(id) {
@@ -298,6 +354,7 @@ function rowToHarnessSession(row) {
         resolvedApprovalIds: stringArray(record.resolved_approval_ids),
         ownerEmail: stringOrNull(record.owner_email),
         orgId: stringOrNull(record.org_id),
+        generation: numberValue(record.generation),
         createdAt: numberValue(record.created_at),
         updatedAt: numberValue(record.updated_at),
         stoppedAt: record.stopped_at === null || record.stopped_at === undefined
@@ -344,3 +401,10 @@ function stringOrNull(value) {
 function numberValue(value) {
     return typeof value === "number" ? value : Number(value ?? 0);
 }
+function isDuplicateColumnError(error) {
+    if (!error || typeof error !== "object")
+        return false;
+    const message = error.message;
+    return (typeof message === "string" &&
+        /duplicate column name|column .* already exists/i.test(message));
+}

package/dist/agent/production-agent.d.ts

@@ -730,6 +730,7 @@ export interface ExecuteAgentToolCallOptions {
     approvedToolCalls?: string[];
     onApprovalRequired?: (binding: AgentApprovalBinding) => Promise<string | void>;
     consumeApproval?: (binding: AgentApprovalBinding) => Promise<boolean>;
+    isToolAlwaysAllowed?: (binding: AgentApprovalBinding) => Promise<boolean>;
     send?: (event: AgentChatEvent) => void;
 }
 export interface AgentApprovalBinding {
@@ -915,6 +916,8 @@ export declare function runAgentLoop(opts: {
      */
     onApprovalRequired?: (binding: AgentApprovalBinding) => Promise<string | void>;
     consumeApproval?: (binding: AgentApprovalBinding) => Promise<boolean>;
+    /** User-scoped action-type policy, checked only after needsApproval. */
+    isToolAlwaysAllowed?: (binding: AgentApprovalBinding) => Promise<boolean>;
     /**
      * In-loop processor seam (see `processors.ts`). Each processor can observe
      * streamed chunks, observe model responses around tool execution, and

package/dist/agent/production-agent.js

@@ -43,7 +43,7 @@ import { ProcessorChain, TripWire, toolCallsFromContent, } from "./processors.js
 import { startRun, subscribeToRun, getActiveRunForThread, getActiveRunForThreadAsync, getRun, abortRun, abortRunDurably, abortTurnDurably, tryClaimRunSlot, isHostedRuntime, resolveRunSoftTimeoutMs, resolveRunToolTimeoutCeilingMs, endsAfterCompletedToolWithoutAssistantFinal, } from "./run-manager.js";
 import { writeLedgerEntry, readLedgerEntry, clearLedgerForThread, insertRun, insertRunEvent, isTurnAborted, markRunAborted, updateRunHeartbeat, updateRunStatusIfRunning, setRunError, setRunTerminalReason, claimBackgroundRun, readBackgroundRunClaim, recordRunDiagnostic, countRunsForTurn, RUN_DIAG_STAGE, UNCLAIMED_BACKGROUND_RUN_GRACE_MS, turnRunLedgerExhausted, } from "./run-store.js";
 import { buildCurrentTimeUserContext } from "./runtime-context.js";
-import { consumeAgentToolApproval, createAgentToolApproval, resolveAgentToolApprovalTurnId, } from "./tool-approval-store.js";
+import { consumeAgentToolApproval, createAgentToolApproval, isAgentToolAlwaysAllowed, resolveAgentToolApprovalTurnId, } from "./tool-approval-store.js";
 import { findCompletedJournalEntry, } from "./tool-call-journal.js";
 import { redactSensitiveFields, sanitizeToolErrorText, sanitizeToolErrorValue, } from "./tool-error-redaction.js";
 import { describeToolResultImages, extractAgentImagesFromActionResult, } from "./tool-result-images.js";
@@ -2274,6 +2274,7 @@ export async function executeAgentToolCall(options) {
             approvedToolCalls: options.approvedToolCalls,
             onApprovalRequired: options.onApprovalRequired,
             consumeApproval: options.consumeApproval,
+            isToolAlwaysAllowed: options.isToolAlwaysAllowed,
         });
     }
     catch (error) {
@@ -4359,6 +4360,16 @@ export async function runAgentLoop(opts) {
                     // than silently running a high-consequence action.
                     mustApprove = true;
                 }
+                if (mustApprove && opts.isToolAlwaysAllowed) {
+                    try {
+                        mustApprove = !(await opts.isToolAlwaysAllowed(approvalBinding));
+                    }
+                    catch {
+                        // Fail closed: an unreadable policy must leave the approval gate in
+                        // place instead of turning a storage outage into authorization.
+                        mustApprove = true;
+                    }
+                }
                 if (mustApprove) {
                     // `askId` identifies THIS gate hit, distinct from any earlier ask
                     // for the same approvalKey/toolCallId. A failed resume (expired
@@ -7226,6 +7237,15 @@ export function createProductionAgentHandler(options) {
                     return false;
                 return consumeAgentToolApproval(approvalStoreBinding(binding));
             },
+            isToolAlwaysAllowed: async (binding) => {
+                if (!ownerEmail)
+                    return false;
+                return isAgentToolAlwaysAllowed({
+                    ownerEmail,
+                    orgId: getRequestOrgId() ?? null,
+                    toolName: binding.toolName,
+                });
+            },
         };
         const approvedToolCallsForExecution = requestedApprovedToolCalls;
         if (isBackgroundWorker &&
@@ -8074,6 +8094,7 @@ export function createProductionAgentHandler(options) {
                     : {}),
                 onApprovalRequired: approvalHooks.onApprovalRequired,
                 consumeApproval: approvalHooks.consumeApproval,
+                isToolAlwaysAllowed: approvalHooks.isToolAlwaysAllowed,
                 // A worker PROVEN to be running inside the real 15-min Netlify
                 // `-background` function (`runsInBackgroundFunction`) has minutes of
                 // budget left on THIS invocation. Let it catch a recoverable
@@ -8119,6 +8140,7 @@ export function createProductionAgentHandler(options) {
                         approvedToolCalls: approvedToolCallsForExecution,
                         onApprovalRequired: approvalHooks.onApprovalRequired,
                         consumeApproval: approvalHooks.consumeApproval,
+                        isToolAlwaysAllowed: approvalHooks.isToolAlwaysAllowed,
                         send,
                     });
                     return;

package/dist/agent/run-manager.js

@@ -663,6 +663,9 @@ export function startRun(runId, threadId, runFn, onComplete, options) {
         ? new AbortController()
         : null;
     let chunkBoundaryReason = null;
+    let chunkSoftTimeoutTimer = null;
+    let armChunkSoftTimeout = () => { };
+    let recoverableRunDeadlineAt = null;
     let recoveredChunkBoundaries = 0;
     /** A boundary that has been reached but not yet proven recovered. */
     let pendingBoundary = null;
@@ -706,7 +709,10 @@ export function startRun(runId, threadId, runFn, onComplete, options) {
                 return abort.signal;
             settleBoundary(true);
             chunkBoundaryReason = null;
+            if (chunkSoftTimeoutTimer)
+                clearTimeout(chunkSoftTimeoutTimer);
             chunkAbort = new AbortController();
+            armChunkSoftTimeout();
             // The boundary is behind us; the silence clock restarts with the chunk,
             // or the backstop fires again on the elapsed time of the chunk it just
             // ended and every recovery round dies instantly.
@@ -1079,8 +1085,12 @@ export function startRun(runId, threadId, runFn, onComplete, options) {
     const reachRunBoundary = (reason, diagnostic = {}) => {
         if (run.status !== "running" || abort.signal.aborted)
             return;
-        if (chunkAbort) {
-            if (chunkAbort.signal.aborted)
+        const activeChunkAbort = chunkAbort;
+        const canRecoverChunk = activeChunkAbort !== null &&
+            (recoverableRunDeadlineAt === null ||
+                Date.now() < recoverableRunDeadlineAt);
+        if (canRecoverChunk) {
+            if (activeChunkAbort.signal.aborted)
                 return;
             recoveredChunkBoundaries += 1;
             console.warn(`[run-manager] chunk boundary (${reason}) — recovering in-invocation`, runId, diagnostic);
@@ -1092,9 +1102,11 @@ export function startRun(runId, threadId, runFn, onComplete, options) {
             // direction that hides the failure.
             pendingBoundary = { reason, diagnostic, index: recoveredChunkBoundaries };
             chunkBoundaryReason = reason;
-            chunkAbort.abort(reason);
+            activeChunkAbort.abort(reason);
             return;
         }
+        if (chunkAbort)
+            chunkBoundaryReason = reason;
         // Mirror the soft-timeout semantics exactly: the chunk completes (not
         // aborts) at an auto_continue boundary, so the continuation machinery —
         // server-chained for background workers, client-driven for foreground —
@@ -1277,12 +1289,10 @@ export function startRun(runId, threadId, runFn, onComplete, options) {
         overrideMs: options?.noProgressTimeoutMs,
         backgroundOverrideMs: options?.backgroundNoProgressTimeoutMs,
     });
-    // Not armed for a runFn that recovers boundaries in this invocation. That
-    // runFn already races the SAME wall with its own per-round timer, budgeted
-    // against cumulative elapsed time — so this timer fires at the moment the
-    // wrapper has nothing left to continue with, producing a boundary that is
-    // recoverable in name only and burning the tail of the budget on nothing.
-    // One wall, one clock; the caller's hard abort still backstops it.
+    // A recoverable run uses the cumulative timer below instead of this one-shot
+    // timer. Each successor chunk gets only the remaining invocation budget, so
+    // recovery cannot extend the hosted wall. The caller's hard abort still
+    // backstops both timer paths.
     const softTimeoutTimer = softTimeoutMs > 0 && !recoverChunkBoundaries
         ? setTimeout(() => {
             reachRunBoundary("run_timeout", {
@@ -1290,6 +1300,25 @@ export function startRun(runId, threadId, runFn, onComplete, options) {
             });
         }, softTimeoutMs)
         : null;
+    if (recoverChunkBoundaries && softTimeoutMs > 0) {
+        const runDeadlineAt = Date.now() + softTimeoutMs;
+        recoverableRunDeadlineAt = runDeadlineAt;
+        armChunkSoftTimeout = () => {
+            if (chunkSoftTimeoutTimer)
+                clearTimeout(chunkSoftTimeoutTimer);
+            if (abort.signal.aborted || run.status !== "running")
+                return;
+            chunkSoftTimeoutTimer = setTimeout(() => {
+                chunkSoftTimeoutTimer = null;
+                reachRunBoundary("run_timeout", {
+                    lastEventType: run.events.at(-1)?.event.type,
+                });
+            }, Math.max(0, runDeadlineAt - Date.now()));
+        };
+        // Boundary recovery disables the ordinary one-shot timer, so arm the
+        // cumulative invocation deadline on the initial chunk and each successor.
+        armChunkSoftTimeout();
+    }
     let pendingTerminalEvent = null;
     const captureRunError = (error, phase) => {
         const errorCode = getRunErrorCode(error);
@@ -1638,6 +1667,8 @@ export function startRun(runId, threadId, runFn, onComplete, options) {
         clearInterval(heartbeatTimer);
         if (softTimeoutTimer)
             clearTimeout(softTimeoutTimer);
+        if (chunkSoftTimeoutTimer)
+            clearTimeout(chunkSoftTimeoutTimer);
         if (progressWriteTimer)
             clearTimeout(progressWriteTimer);
         progressWriteTimer = null;

package/dist/agent/tool-approval-migrations.d.ts

@@ -35,6 +35,27 @@ export declare const AGENT_TOOL_APPROVAL_TABLE_SQL: {
 export declare const AGENT_TOOL_APPROVAL_INDEX_SQL = "CREATE INDEX IF NOT EXISTS idx_agent_tool_approvals_binding\n  ON agent_tool_approvals(owner_email, org_id, thread_id, tool_name, call_id, status)";
 export declare const AGENT_TOOL_APPROVAL_LOGICAL_INDEX_SQL = "CREATE INDEX IF NOT EXISTS idx_agent_tool_approvals_logical\n  ON agent_tool_approvals(owner_email, org_id, thread_id, turn_id, tool_name, approval_key_hash, status)";
 export declare const AGENT_TOOL_APPROVAL_RECOVERY_INDEX_SQL = "CREATE INDEX IF NOT EXISTS idx_agent_tool_approvals_recovery\n  ON agent_tool_approvals(owner_email, org_id, thread_id, approval_key_hash, status, turn_id)";
+export declare const AGENT_TOOL_APPROVAL_POLICY_TABLE_SQL: {
+    readonly postgres: `CREATE TABLE IF NOT EXISTS agent_tool_approval_policies (
+  id TEXT PRIMARY KEY,
+  owner_email TEXT NOT NULL,
+  org_id TEXT,
+  tool_name TEXT NOT NULL,
+  enabled BOOLEAN NOT NULL,
+  created_at BIGINT NOT NULL,
+  updated_at BIGINT NOT NULL
+)`;
+    readonly sqlite: `CREATE TABLE IF NOT EXISTS agent_tool_approval_policies (
+  id TEXT PRIMARY KEY,
+  owner_email TEXT NOT NULL,
+  org_id TEXT,
+  tool_name TEXT NOT NULL,
+  enabled INTEGER NOT NULL,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
+)`;
+};
+export declare const AGENT_TOOL_APPROVAL_POLICY_INDEX_SQL = "CREATE INDEX IF NOT EXISTS idx_agent_tool_approval_policies_scope\n  ON agent_tool_approval_policies(owner_email, org_id, tool_name, enabled)";
 /**
  * Durable approval grants are created and consumed on request paths, but their
  * schema belongs to the release migration boundary in production.

package/dist/agent/tool-approval-migrations.js

@@ -37,6 +37,28 @@ export const AGENT_TOOL_APPROVAL_LOGICAL_INDEX_SQL = `CREATE INDEX IF NOT EXISTS
   ON agent_tool_approvals(owner_email, org_id, thread_id, turn_id, tool_name, approval_key_hash, status)`;
 export const AGENT_TOOL_APPROVAL_RECOVERY_INDEX_SQL = `CREATE INDEX IF NOT EXISTS idx_agent_tool_approvals_recovery
   ON agent_tool_approvals(owner_email, org_id, thread_id, approval_key_hash, status, turn_id)`;
+export const AGENT_TOOL_APPROVAL_POLICY_TABLE_SQL = {
+    postgres: `CREATE TABLE IF NOT EXISTS agent_tool_approval_policies (
+  id TEXT PRIMARY KEY,
+  owner_email TEXT NOT NULL,
+  org_id TEXT,
+  tool_name TEXT NOT NULL,
+  enabled BOOLEAN NOT NULL,
+  created_at BIGINT NOT NULL,
+  updated_at BIGINT NOT NULL
+)`,
+    sqlite: `CREATE TABLE IF NOT EXISTS agent_tool_approval_policies (
+  id TEXT PRIMARY KEY,
+  owner_email TEXT NOT NULL,
+  org_id TEXT,
+  tool_name TEXT NOT NULL,
+  enabled INTEGER NOT NULL,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
+)`,
+};
+export const AGENT_TOOL_APPROVAL_POLICY_INDEX_SQL = `CREATE INDEX IF NOT EXISTS idx_agent_tool_approval_policies_scope
+  ON agent_tool_approval_policies(owner_email, org_id, tool_name, enabled)`;
 /**
  * Durable approval grants are created and consumed on request paths, but their
  * schema belongs to the release migration boundary in production.
@@ -68,4 +90,14 @@ ${AGENT_TOOL_APPROVAL_INDEX_SQL}`,
             sqlite: AGENT_TOOL_APPROVAL_RECOVERY_INDEX_SQL,
         },
     },
+    {
+        version: 4,
+        name: "agent-tool-approval-policies-table-and-index",
+        sql: {
+            postgres: `${AGENT_TOOL_APPROVAL_POLICY_TABLE_SQL.postgres};
+${AGENT_TOOL_APPROVAL_POLICY_INDEX_SQL}`,
+            sqlite: `${AGENT_TOOL_APPROVAL_POLICY_TABLE_SQL.sqlite};
+${AGENT_TOOL_APPROVAL_POLICY_INDEX_SQL}`,
+        },
+    },
 ];

package/dist/agent/tool-approval-store.d.ts

@@ -1,4 +1,5 @@
 export declare function ensureAgentToolApprovalTable(): Promise<void>;
+export declare function ensureAgentToolApprovalPolicyTable(): Promise<void>;
 export interface AgentToolApprovalBinding {
     ownerEmail: string;
     orgId?: string | null;
@@ -10,6 +11,16 @@ export interface AgentToolApprovalBinding {
     expiresAt?: number;
 }
 export declare function hashAgentToolApprovalKey(approvalKey: string): string;
+export interface AgentToolApprovalPolicyBinding {
+    ownerEmail: string;
+    orgId?: string | null;
+    toolName: string;
+}
+export declare function setAgentToolApprovalPolicy(input: {
+    binding: AgentToolApprovalPolicyBinding;
+    enabled: boolean;
+}): Promise<void>;
+export declare function isAgentToolAlwaysAllowed(input: AgentToolApprovalPolicyBinding): Promise<boolean>;
 /**
  * Recover the durable scope for an approval continuation when a transport
  * drops the original turn id. A single pending logical turn is safe to

package/dist/agent/tool-approval-store.js

@@ -1,7 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
 import { getDbExec, isPostgres, retryOnDdlRace } from "../db/client.js";
 import { ensureIndexExists, ensureTableExists } from "../db/ddl-guard.js";
-import { AGENT_TOOL_APPROVAL_INDEX_SQL, AGENT_TOOL_APPROVAL_LOGICAL_INDEX_SQL, AGENT_TOOL_APPROVAL_RECOVERY_INDEX_SQL, AGENT_TOOL_APPROVAL_TABLE_SQL, } from "./tool-approval-migrations.js";
+import { AGENT_TOOL_APPROVAL_INDEX_SQL, AGENT_TOOL_APPROVAL_LOGICAL_INDEX_SQL, AGENT_TOOL_APPROVAL_POLICY_INDEX_SQL, AGENT_TOOL_APPROVAL_POLICY_TABLE_SQL, AGENT_TOOL_APPROVAL_RECOVERY_INDEX_SQL, AGENT_TOOL_APPROVAL_TABLE_SQL, } from "./tool-approval-migrations.js";
 // 15 minutes was too short in practice: a user who steps away mid-approval
 // (switching tabs to update their client, checking something else) comes back
 // to a silently expired grant with no visible error — clicking Approve just
@@ -11,6 +11,7 @@ import { AGENT_TOOL_APPROVAL_INDEX_SQL, AGENT_TOOL_APPROVAL_LOGICAL_INDEX_SQL, A
 const APPROVAL_TTL_MS = 60 * 60_000;
 const APPROVAL_CLEANUP_AGE_MS = 24 * 60 * 60_000;
 let initPromise;
+let policyInitPromise;
 export async function ensureAgentToolApprovalTable() {
     if (!initPromise) {
         initPromise = (async () => {
@@ -34,9 +35,83 @@ export async function ensureAgentToolApprovalTable() {
     }
     return initPromise;
 }
+export async function ensureAgentToolApprovalPolicyTable() {
+    if (!policyInitPromise) {
+        policyInitPromise = (async () => {
+            const createSql = AGENT_TOOL_APPROVAL_POLICY_TABLE_SQL[isPostgres() ? "postgres" : "sqlite"];
+            if (isPostgres()) {
+                await ensureTableExists("agent_tool_approval_policies", createSql);
+                await ensureIndexExists("idx_agent_tool_approval_policies_scope", AGENT_TOOL_APPROVAL_POLICY_INDEX_SQL);
+                return;
+            }
+            const client = getDbExec();
+            await retryOnDdlRace(() => client.execute(createSql));
+            await retryOnDdlRace(() => client.execute(AGENT_TOOL_APPROVAL_POLICY_INDEX_SQL));
+        })().catch((error) => {
+            policyInitPromise = undefined;
+            throw error;
+        });
+    }
+    return policyInitPromise;
+}
 export function hashAgentToolApprovalKey(approvalKey) {
     return createHash("sha256").update(approvalKey).digest("hex");
 }
+function normalizeApprovalPolicyBinding(binding) {
+    const ownerEmail = binding.ownerEmail.trim().toLowerCase();
+    const toolName = binding.toolName.trim();
+    if (!ownerEmail)
+        throw new Error("Approval policy owner is required.");
+    if (!toolName)
+        throw new Error("Approval policy tool name is required.");
+    return {
+        ownerEmail,
+        orgId: binding.orgId?.trim() || null,
+        toolName,
+    };
+}
+function approvalPolicyId(binding) {
+    return `agent-tool-approval-policy-${createHash("sha256")
+        .update(`${binding.ownerEmail}\u0000${binding.orgId ?? ""}\u0000${binding.toolName}`)
+        .digest("hex")}`;
+}
+export async function setAgentToolApprovalPolicy(input) {
+    const binding = normalizeApprovalPolicyBinding(input.binding);
+    await ensureAgentToolApprovalPolicyTable();
+    const now = Date.now();
+    const id = approvalPolicyId(binding);
+    await getDbExec().execute({
+        sql: `INSERT INTO agent_tool_approval_policies
+      (id, owner_email, org_id, tool_name, enabled, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET
+        enabled = excluded.enabled,
+        updated_at = excluded.updated_at`,
+        args: [
+            id,
+            binding.ownerEmail,
+            binding.orgId,
+            binding.toolName,
+            input.enabled,
+            now,
+            now,
+        ],
+    });
+}
+export async function isAgentToolAlwaysAllowed(input) {
+    const binding = normalizeApprovalPolicyBinding(input);
+    await ensureAgentToolApprovalPolicyTable();
+    const result = await getDbExec().execute({
+        sql: `SELECT 1 FROM agent_tool_approval_policies
+      WHERE owner_email = ?
+        AND ((org_id IS NULL AND CAST(? AS TEXT) IS NULL) OR org_id = ?)
+        AND tool_name = ?
+        AND enabled = TRUE
+      LIMIT 1`,
+        args: [binding.ownerEmail, binding.orgId, binding.orgId, binding.toolName],
+    });
+    return (result.rows ?? []).length > 0;
+}
 /**
  * Recover the durable scope for an approval continuation when a transport
  * drops the original turn id. A single pending logical turn is safe to

package/dist/cli/code-agent-executor.js

@@ -9,7 +9,7 @@ import { actionsToEngineTools, runAgentLoop, } from "../agent/production-agent.j
 import { createToolSearchEntry, TOOL_SEARCH_ACTION_NAME, } from "../agent/tool-search.js";
 import { getAppConfig } from "../app-config/index.js";
 import { formatPromptWithAttachments, } from "../code-agents/prompt-attachments.js";
-import { createCodingToolRegistry, isReadOnlyShellCommand, runCodingCommand, truncateBashOutput, truncateCodingOutput, } from "../coding-tools/index.js";
+import { createCodingToolRegistry, canonicalizeShellCommand, isReadOnlyShellCommand, runCodingCommand, truncateBashOutput, truncateCodingOutput, } from "../coding-tools/index.js";
 import { buildMergedConfig, McpClientManager, mcpToolsToActionEntries, } from "../mcp-client/index.js";
 import { readAgentsBundleFromFs, generateDevelopmentSkillsPromptBlock, } from "../server/agents-bundle.js";
 import { getAmbientOrgId, getAmbientUserEmail, runWithRequestContext, } from "../server/request-context.js";
@@ -2303,6 +2303,13 @@ export function classifyCodeAgentCommandPermission(command) {
     const normalized = command.trim().toLowerCase();
     if (!normalized)
         return { kind: "read" };
+    // Match every rule below against the quote-stripped form as well as the raw
+    // one. The shell removes quoting before the command word exists, so
+    // `git 'checkout' main` runs the branch operation these rules forbid while
+    // matching none of them verbatim.
+    const { canonical, unanalyzable } = canonicalizeShellCommand(command);
+    const canonicalized = canonical.trim().toLowerCase();
+    const matches = (pattern) => pattern.test(normalized) || pattern.test(canonicalized);
     const blockedPatterns = [
         [
             /\bgit\s+(checkout|switch|reset|rebase|stash|clean|worktree)\b/,
@@ -2315,7 +2322,7 @@ export function classifyCodeAgentCommandPermission(command) {
         [/\bdrizzle-kit\s+push\b/, "drizzle-kit push is not allowed"],
     ];
     for (const [pattern, reason] of blockedPatterns) {
-        if (pattern.test(normalized))
+        if (matches(pattern))
             return { kind: "forbidden", reason };
     }
     const approvalPatterns = [
@@ -2331,10 +2338,20 @@ export function classifyCodeAgentCommandPermission(command) {
         [/\bdelete\s+from\b(?![\s\S]*\bwhere\b)/, "unscoped delete command"],
     ];
     for (const [pattern, reason] of approvalPatterns) {
-        if (pattern.test(normalized)) {
+        if (matches(pattern)) {
             return { kind: "approval-required", reason };
         }
     }
+    // A command whose real text this pass cannot recover is not a command we can
+    // clear. `$(printf git) $(printf checkout) main` runs the forbidden operation
+    // while containing neither token, so a rule that did not match proves nothing.
+    // Ask rather than fall through to `write` on a guess.
+    if (unanalyzable) {
+        return {
+            kind: "approval-required",
+            reason: "command builds its text at runtime (command substitution or $'…' escaping), so policy matching cannot see what will run",
+        };
+    }
     if (isReadOnlyShellCommand(command)) {
         return { kind: "read" };
     }

package/dist/client/AgentPanel.d.ts

@@ -26,6 +26,7 @@ export declare function preloadAgentChatSurface(): Promise<void>;
 import type { AgentChatSurfaceKind } from "./agent-chat-adapter.js";
 import type { AssistantChatProps } from "./AssistantChat.js";
 import type { MultiTabAssistantChatHeaderProps, MultiTabAssistantChatProps } from "./MultiTabAssistantChat.js";
+export declare function shouldHandleAgentSidebarToggle(event: Event, toggleScopeId?: string | null): boolean;
 type PanelMode = "chat" | "cli" | "resources" | "settings";
 export declare function normalizeAgentPanelModeForSurface(mode: PanelMode, allowSettingsMode: boolean, chatOnly?: boolean): PanelMode;
 export declare function deferAgentPanelOverlayOpen(event: {
@@ -249,6 +250,8 @@ export interface AgentSidebarProps {
     onFullscreenRequest?: () => void;
     /** Ambient resource context rendered as a composer chip. */
     scope?: import("./use-chat-threads.js").ChatThreadScope | null;
+    /** Identity used to route host-scoped sidebar toggle events. */
+    toggleScopeId?: string;
     /** Keep app-owned chat history isolated to the supplied scope. */
     isolateHistoryByScope?: boolean;
     /** @deprecated Scope context now appears inside the composer. */
@@ -266,7 +269,7 @@ export interface AgentSidebarProps {
  * Wraps app content with a toggleable agent sidebar.
  * Use AgentToggleButton in your header to open/close it.
  */
-export declare function AgentSidebar({ children, enabled, emptyStateText, suggestions, dynamicSuggestions, composerToolbarSlot, composerSlot, onComposerTextChange, imageModelMenu, availableAgents, availableModels, modelListLoading, selectedAgent, onAgentChange, onConnectLocalRuntime, onConnectProvider, runtime, adapterReloadKey, threadFooterSlot, defaultSidebarWidth, sidebarWidth, position, defaultOpen, animateMobile, animateDesktop, chatViewTransition, chatViewTransitionHandoff, storageKey, openStorageKey, restoreActiveThread, apiUrl, agentChatSurface, desktopIdentityUnauthenticated, desktopIdentityAuthenticated, showTabBar, suppressInlineOpenApp, composerPlaceholder, openOnChatRunning, onFullscreenRequest, scope, isolateHistoryByScope, showScopeBadge, browserTabId, threadUrlSync, agentPageHref, suppressFirstRunOnboarding, }: AgentSidebarProps): React.JSX.Element;
+export declare function AgentSidebar({ children, enabled, emptyStateText, suggestions, dynamicSuggestions, composerToolbarSlot, composerSlot, onComposerTextChange, imageModelMenu, availableAgents, availableModels, modelListLoading, selectedAgent, onAgentChange, onConnectLocalRuntime, onConnectProvider, runtime, adapterReloadKey, threadFooterSlot, defaultSidebarWidth, sidebarWidth, position, defaultOpen, animateMobile, animateDesktop, chatViewTransition, chatViewTransitionHandoff, storageKey, openStorageKey, restoreActiveThread, apiUrl, agentChatSurface, desktopIdentityUnauthenticated, desktopIdentityAuthenticated, showTabBar, suppressInlineOpenApp, composerPlaceholder, openOnChatRunning, onFullscreenRequest, scope, toggleScopeId, isolateHistoryByScope, showScopeBadge, browserTabId, threadUrlSync, agentPageHref, suppressFirstRunOnboarding, }: AgentSidebarProps): React.JSX.Element;
 /**
  * Focus the agent chat composer input.
  * Opens the sidebar if closed, then focuses the text input.