@vellumai/assistant 0.3.18 → 0.3.19

package/src/calls/guardian-dispatch.ts

@@ -27,6 +27,10 @@ export interface GuardianDispatchParams {
   conversationId: string;
   assistantId: string;
   pendingQuestion: CallPendingQuestion;
+  /** Tool identity for tool-approval requests (absent for informational ASK_GUARDIAN). */
+  toolName?: string;
+  /** Canonical SHA-256 digest of tool input for tool-approval requests. */
+  inputDigest?: string;
 }
 
 function applyDeliveryStatus(deliveryId: string, result: NotificationDeliveryResult): void {
@@ -48,6 +52,8 @@ export async function dispatchGuardianQuestion(params: GuardianDispatchParams):
     conversationId,
     assistantId,
     pendingQuestion,
+    toolName,
+    inputDigest,
   } = params;
 
   try {
@@ -63,6 +69,8 @@ export async function dispatchGuardianQuestion(params: GuardianDispatchParams):
       pendingQuestionId: pendingQuestion.id,
       questionText: pendingQuestion.questionText,
       expiresAt,
+      toolName,
+      inputDigest,
     });
 
     log.info(

package/src/calls/relay-server.ts

@@ -12,6 +12,7 @@ import type { ServerWebSocket } from 'bun';
 
 import { getConfig } from '../config/loader.js';
 import * as conversationStore from '../memory/conversation-store.js';
+import { revokeScopedApprovalGrantsForContext } from '../memory/scoped-approval-grants.js';
 import {
   getPendingChallenge,
   validateAndConsumeChallenge,
@@ -351,6 +352,18 @@ export class RelayConnection {
     }
 
     expirePendingQuestions(this.callSessionId);
+
+    // Revoke any scoped approval grants bound to this call session.
+    // Revoke by both callSessionId and conversationId because the
+    // guardian-approval-interception minting path sets callSessionId: null
+    // but always sets conversationId.
+    try {
+      revokeScopedApprovalGrantsForContext({ callSessionId: this.callSessionId });
+      revokeScopedApprovalGrantsForContext({ conversationId: session.conversationId });
+    } catch (err) {
+      log.warn({ err, callSessionId: this.callSessionId }, 'Failed to revoke scoped grants on transport close');
+    }
+
     persistCallCompletionMessage(session.conversationId, this.callSessionId).catch((err) => {
       log.error({ err, conversationId: session.conversationId, callSessionId: this.callSessionId }, 'Failed to persist call completion message');
     });

package/src/calls/voice-session-bridge.ts

@@ -18,7 +18,9 @@ import type { GuardianRuntimeContext } from '../daemon/session-runtime-assembly.
 import { resolveChannelCapabilities } from '../daemon/session-runtime-assembly.js';
 import { buildAssistantEvent } from '../runtime/assistant-event.js';
 import { assistantEventHub } from '../runtime/assistant-event-hub.js';
+import { consumeScopedApprovalGrantByToolSignature } from '../memory/scoped-approval-grants.js';
 import { checkIngressForSecrets } from '../security/secret-ingress.js';
+import { computeToolApprovalDigest } from '../security/tool-approval-digest.js';
 import { IngressBlockedError } from '../util/errors.js';
 import { getLogger } from '../util/logger.js';
 
@@ -81,6 +83,8 @@ export interface VoiceRunEventSink {
 export interface VoiceTurnOptions {
   /** The conversation ID for this voice call's session. */
   conversationId: string;
+  /** The call session ID for scoped grant matching. */
+  callSessionId?: string;
   /** The transcribed caller utterance or synthetic marker. */
   content: string;
   /** Assistant scope for multi-assistant channels. */
@@ -147,7 +151,12 @@ function buildVoiceCallControlPrompt(opts: {
     '1. Be concise — keep responses to 1-3 sentences. Phone conversations should be brief and natural.',
     ...(opts.isCallerGuardian
       ? ['2. You are speaking directly with your guardian (your user). Do NOT use [ASK_GUARDIAN:]. If you need permission, information, or confirmation, ask them directly in the conversation. They can answer you right now.']
-      : ['2. You can consult your guardian at any time by including [ASK_GUARDIAN: your question here] in your response. When you do, add a natural hold message like "Let me check on that for you."']
+      : [[
+          '2. You can consult your guardian in two ways:',
+          '   - For general questions or information: [ASK_GUARDIAN: your question here]',
+          '   - For tool/action permission requests: [ASK_GUARDIAN_APPROVAL: {"question":"Describe what you need permission for","toolName":"the_tool_name","input":{...tool input object...}}]',
+          '   Use ASK_GUARDIAN_APPROVAL when you need permission to execute a specific tool or action. Use ASK_GUARDIAN for everything else (general questions, advice, information). When you use either marker, add a natural hold message like "Let me check on that for you."',
+        ].join('\n')]
     ),
   );
 
@@ -194,7 +203,7 @@ function buildVoiceCallControlPrompt(opts: {
 
   lines.push(
     '9. After the opening greeting turn, treat the Task field as background context only — do not re-execute its instructions on subsequent turns.',
-    '10. Do not make up information. If you are unsure, use [ASK_GUARDIAN: your question] to consult your guardian.',
+    '10. Do not make up information. If you are unsure, use [ASK_GUARDIAN: your question] to consult your guardian. For tool permission requests, use [ASK_GUARDIAN_APPROVAL: {"question":"...","toolName":"...","input":{...}}].',
     '</voice_call_control>',
   );
 
@@ -339,9 +348,39 @@ export async function startVoiceTurn(opts: VoiceTurnOptions): Promise<VoiceTurnH
   session.updateClient((msg: ServerMessage) => {
     if (msg.type === 'confirmation_request') {
       if (autoDeny) {
+        // Before auto-denying, check if a guardian from another channel
+        // has pre-approved this exact tool invocation via a scoped grant.
+        const inputDigest = computeToolApprovalDigest(msg.toolName, msg.input);
+        const consumeResult = consumeScopedApprovalGrantByToolSignature({
+          toolName: msg.toolName,
+          inputDigest,
+          consumingRequestId: msg.requestId,
+          assistantId: opts.assistantId,
+          executionChannel: 'voice',
+          conversationId: opts.conversationId,
+          callSessionId: opts.callSessionId,
+          requesterExternalUserId: opts.guardianContext?.requesterExternalUserId,
+        });
+
+        if (consumeResult.ok) {
+          log.info(
+            { turnId, toolName: msg.toolName, grantId: consumeResult.grant?.id },
+            'Consumed scoped grant — allowing non-guardian voice confirmation',
+          );
+          session.handleConfirmationResponse(
+            msg.requestId,
+            'allow',
+            undefined,
+            undefined,
+            `Permission approved for "${msg.toolName}": guardian pre-approved via scoped grant.`,
+          );
+          publishToHub(msg);
+          return;
+        }
+
         log.info(
           { turnId, toolName: msg.toolName },
-          'Auto-denying confirmation request for voice turn (forceStrictSideEffects)',
+          'Auto-denying confirmation request for voice turn (no matching scoped grant)',
         );
         session.handleConfirmationResponse(
           msg.requestId,

package/src/config/bundled-skills/notifications/SKILL.md

@@ -12,6 +12,24 @@ Use `send_notification` for user-facing alerts and notifications. This tool rout
 - `preferred_channels` are **routing hints**, not hard channel forcing. The notification router makes the final delivery decision based on user preferences, channel availability, and urgency.
 - Channel selection and delivery are handled entirely by the notification router -- do not attempt to control delivery manually.
 
+## Deduplication (`dedupe_key`)
+
+- `dedupe_key` suppresses duplicate signals. A second notification with the same key is **dropped entirely** within a **1-hour window**. After the window expires, the same key is accepted again.
+- Never reuse a `dedupe_key` across logically distinct notifications, even if they are related. The key means "this exact event already fired," not "these events are in the same category."
+- If you omit `dedupe_key`, the LLM decision engine may generate one automatically based on signal context. This means even keyless signals can be deduplicated if the engine considers them duplicates of a recent event.
+
+## Threading
+
+Thread grouping is handled by the LLM-powered decision engine, not by any parameter you pass. There is no explicit "post to thread X" parameter — thread reuse is inferred, not commanded.
+
+**How it works:** The engine evaluates recent notification thread candidates and decides whether a new signal is a continuation of an existing thread based on `source_event_name`, provenance metadata, and message content. Use natural, descriptive titles and bodies — the engine groups by semantic relatedness, not string matching.
+
+**`source_event_name` is the primary grouping signal.** Use a stable event name for notifications that belong to the same logical stream (e.g. `dog.news.thread.reply` for all replies in a thread). Use a distinct event name when the notification represents a genuinely different kind of event.
+
+**Practical constraints:**
+- Thread candidates are scoped to the **last 24 hours** (max 5 per channel). You cannot reuse an old thread from days ago.
+- The engine will only reuse conversations originally created by the notification system (`source === 'notification'`). It will never append to a user-initiated conversation, even if it looks related.
+
 ## Important
 
 - Do **NOT** use AppleScript `display notification` or other OS-level notification commands for assistant-managed alerts. Always use `send_notification`.

package/src/config/schema.ts

@@ -117,12 +117,18 @@ export {
   SandboxConfigSchema,
 } from './sandbox-schema.js';
 export type {
+  RemotePolicyConfig,
+  RemoteProviderConfig,
+  RemoteProvidersConfig,
   SkillEntryConfig,
   SkillsConfig,
   SkillsInstallConfig,
   SkillsLoadConfig,
 } from './skills-schema.js';
 export {
+  RemotePolicyConfigSchema,
+  RemoteProviderConfigSchema,
+  RemoteProvidersConfigSchema,
   SkillEntryConfigSchema,
   SkillsConfigSchema,
   SkillsInstallConfigSchema,

package/src/config/skills-schema.ts

@@ -19,14 +19,41 @@ export const SkillsInstallConfigSchema = z.object({
   }).default('npm'),
 });
 
+export const RemoteProviderConfigSchema = z.object({
+  enabled: z.boolean({ error: 'skills.remoteProviders.<provider>.enabled must be a boolean' }).default(true),
+});
+
+export const RemoteProvidersConfigSchema = z.object({
+  skillssh: RemoteProviderConfigSchema.default({} as any),
+  clawhub: RemoteProviderConfigSchema.default({} as any),
+});
+
+const VALID_SKILLS_SH_RISK_LEVELS = ['safe', 'low', 'medium', 'high', 'critical', 'unknown'] as const;
+// 'unknown' is valid as a risk label on a skill but not as a threshold — setting the threshold
+// to 'unknown' would silently disable fail-closed behavior since nothing can exceed it.
+const VALID_MAX_RISK_LEVELS = ['safe', 'low', 'medium', 'high', 'critical'] as const;
+
+export const RemotePolicyConfigSchema = z.object({
+  blockSuspicious: z.boolean({ error: 'skills.remotePolicy.blockSuspicious must be a boolean' }).default(true),
+  blockMalware: z.boolean({ error: 'skills.remotePolicy.blockMalware must be a boolean' }).default(true),
+  maxSkillsShRisk: z.enum(VALID_MAX_RISK_LEVELS, {
+    error: `skills.remotePolicy.maxSkillsShRisk must be one of: ${VALID_MAX_RISK_LEVELS.join(', ')}`,
+  }).default('medium'),
+});
+
 export const SkillsConfigSchema = z.object({
   entries: z.record(z.string(), SkillEntryConfigSchema).default({} as any),
   load: SkillsLoadConfigSchema.default({} as any),
   install: SkillsInstallConfigSchema.default({} as any),
   allowBundled: z.array(z.string()).nullable().default(null),
+  remoteProviders: RemoteProvidersConfigSchema.default({} as any),
+  remotePolicy: RemotePolicyConfigSchema.default({} as any),
 });
 
 export type SkillEntryConfig = z.infer<typeof SkillEntryConfigSchema>;
 export type SkillsLoadConfig = z.infer<typeof SkillsLoadConfigSchema>;
 export type SkillsInstallConfig = z.infer<typeof SkillsInstallConfigSchema>;
+export type RemoteProviderConfig = z.infer<typeof RemoteProviderConfigSchema>;
+export type RemoteProvidersConfig = z.infer<typeof RemoteProvidersConfigSchema>;
+export type RemotePolicyConfig = z.infer<typeof RemotePolicyConfigSchema>;
 export type SkillsConfig = z.infer<typeof SkillsConfigSchema>;

package/src/daemon/handlers/config-channels.ts

@@ -2,6 +2,7 @@ import * as net from 'node:net';
 
 import type { ChannelId } from '../../channels/types.js';
 import * as externalConversationStore from '../../memory/external-conversation-store.js';
+import { findMember, revokeMember } from '../../memory/ingress-member-store.js';
 import {
   createVerificationChallenge,
   findActiveSession,
@@ -173,8 +174,25 @@ export function handleGuardianVerification(
       const result = getGuardianStatus(channel, assistantId);
       ctx.send(socket, { type: 'guardian_verification_response', ...result });
     } else if (msg.action === 'revoke') {
+      // Capture binding before revoking so we can revoke the guardian's
+      // ingress member record — without this, the guardian would still pass
+      // the ACL check after unbinding.
+      const bindingBeforeRevoke = getGuardianBinding(assistantId, channel);
       revokeGuardianBinding(assistantId, channel);
       revokePendingChallenges(assistantId, channel);
+
+      if (bindingBeforeRevoke) {
+        const member = findMember({
+          assistantId,
+          sourceChannel: channel,
+          externalUserId: bindingBeforeRevoke.guardianExternalUserId,
+          externalChatId: bindingBeforeRevoke.guardianDeliveryChatId,
+        });
+        if (member) {
+          revokeMember(member.id, 'guardian_binding_revoked');
+        }
+      }
+
       ctx.send(socket, {
         type: 'guardian_verification_response',
         success: true,

package/src/daemon/handlers/skills.ts

@@ -4,7 +4,7 @@ import { join } from 'node:path';
 
 import { getConfig, invalidateConfigCache,loadRawConfig, saveRawConfig } from '../../config/loader.js';
 import { resolveSkillStates } from '../../config/skill-state.js';
-import { ensureSkillIcon,loadSkillBySelector, loadSkillCatalog } from '../../config/skills.js';
+import { ensureSkillIcon,loadSkillBySelector, loadSkillCatalog, type SkillSummary } from '../../config/skills.js';
 import { createTimeout,extractText, getConfiguredProvider, userMessage } from '../../providers/provider-send-message.js';
 import { clawhubCheckUpdates, clawhubInspect, clawhubInstall, clawhubSearch, type ClawhubSearchResultItem,clawhubUpdate } from '../../skills/clawhub.js';
 import { createManagedSkill,deleteManagedSkill, removeSkillsIndexEntry, validateManagedSkillId } from '../../skills/managed-store.js';
@@ -26,6 +26,48 @@ import type {
 } from '../ipc-protocol.js';
 import { CONFIG_RELOAD_DEBOUNCE_MS, defineHandlers, ensureSkillEntry, type HandlerContext,log } from './shared.js';
 
+// ─── Provenance resolution ──────────────────────────────────────────────────
+
+interface SkillProvenance {
+  kind: 'first-party' | 'third-party' | 'local';
+  provider?: string;
+  originId?: string;
+  sourceUrl?: string;
+}
+
+const CLAWHUB_BASE_URL = 'https://skills.sh';
+
+function resolveProvenance(summary: SkillSummary): SkillProvenance {
+  // Bundled skills are always first-party (shipped with Vellum)
+  if (summary.source === 'bundled') {
+    return { kind: 'first-party', provider: 'Vellum' };
+  }
+
+  // Managed skills could be either first-party (installed from Vellum catalog)
+  // or third-party (installed from clawhub). The homepage field serves as a
+  // heuristic: Vellum catalog skills don't typically have a clawhub homepage.
+  if (summary.source === 'managed') {
+    if (summary.homepage?.includes('skills.sh') || summary.homepage?.includes('clawhub')) {
+      return {
+        kind: 'third-party',
+        provider: 'skills.sh',
+        originId: summary.id,
+        sourceUrl: summary.homepage ?? `${CLAWHUB_BASE_URL}/skills/${encodeURIComponent(summary.id)}`,
+      };
+    }
+    // No positive evidence of origin -- could be user-authored or from Vellum catalog.
+    // Default to "local" to avoid mislabeling user-created skills as first-party.
+    return { kind: 'local' };
+  }
+
+  // Workspace and extra skills are user-provided
+  if (summary.source === 'workspace' || summary.source === 'extra') {
+    return { kind: 'local' };
+  }
+
+  return { kind: 'local' };
+}
+
 export function handleSkillsList(socket: net.Socket, ctx: HandlerContext): void {
   const config = getConfig();
   const catalog = loadSkillCatalog();
@@ -37,12 +79,13 @@ export function handleSkillsList(socket: net.Socket, ctx: HandlerContext): void
     description: r.summary.description,
     emoji: r.summary.emoji,
     homepage: r.summary.homepage,
-    source: r.summary.source as 'bundled' | 'managed' | 'workspace' | 'clawhub' | 'extra',
+    source: r.summary.source,
     state: (r.state === 'degraded' ? 'enabled' : r.state) as 'enabled' | 'disabled' | 'available',
     degraded: r.degraded,
     missingRequirements: r.missingRequirements,
     updateAvailable: false,
     userInvocable: r.summary.userInvocable,
+    provenance: resolveProvenance(r.summary),
   }));
 
   ctx.send(socket, { type: 'skills_list_response', skills });

package/src/daemon/ipc-contract/skills.ts

@@ -95,6 +95,7 @@ export interface SkillsListResponse {
     updateAvailable: boolean;
     userInvocable: boolean;
     clawhub?: { author: string; stars: number; installs: number; reports: number; publishedAt: string };
+    provenance?: { kind: 'first-party' | 'third-party' | 'local'; provider?: string; originId?: string; sourceUrl?: string };
   }>;
 }
 

package/src/daemon/session-process.ts

@@ -28,6 +28,7 @@ import { createPreference } from '../notifications/preferences-store.js';
 import type { Message } from '../providers/types.js';
 import { processGuardianFollowUpTurn } from '../runtime/guardian-action-conversation-turn.js';
 import { executeFollowupAction } from '../runtime/guardian-action-followup-executor.js';
+import { tryMintGuardianActionGrant } from '../runtime/guardian-action-grant-minter.js';
 import { composeGuardianActionMessageGenerative } from '../runtime/guardian-action-message-composer.js';
 import type { GuardianActionCopyGenerator, GuardianFollowUpConversationGenerator } from '../runtime/http-types.js';
 import { getLogger } from '../util/logger.js';
@@ -491,6 +492,17 @@ export async function processMessage(
 
         if ('ok' in answerResult && answerResult.ok) {
           const resolved = resolveGuardianActionRequest(guardianRequest.id, answerText, 'vellum');
+
+          // Mint a scoped grant so the voice call can consume it
+          // for subsequent tool confirmations.
+          if (resolved) {
+            tryMintGuardianActionGrant({
+              resolvedRequest: resolved,
+              answerText,
+              decisionChannel: 'vellum',
+            });
+          }
+
           const replyText = resolved
             ? 'Your answer has been relayed to the call.'
             : await composeGuardianActionMessageGenerative({ scenario: 'guardian_stale_answered' }, {}, _guardianActionCopyGenerator);

package/src/memory/db-init.ts

@@ -8,6 +8,7 @@ import {
   createConversationAttentionTables,
   createCoreIndexes,
   createCoreTables,
+  createScopedApprovalGrantsTable,
   createExternalConversationBindingsTables,
   createFollowupsTables,
   createMediaAssetsTables,
@@ -21,6 +22,7 @@ import {
   migrateConversationsThreadTypeIndex,
   migrateFkCascadeRebuilds,
   migrateGuardianActionFollowup,
+  migrateGuardianActionToolMetadata,
   migrateGuardianBootstrapToken,
   migrateGuardianDeliveryConversationIndex,
   migrateGuardianVerificationPurpose,
@@ -102,6 +104,9 @@ export function initializeDb(): void {
   // 14c. Guardian action follow-up lifecycle columns (timeout reason, late answers)
   migrateGuardianActionFollowup(database);
 
+  // 14c2. Guardian action tool-approval metadata columns (tool_name, input_digest)
+  migrateGuardianActionToolMetadata(database);
+
   // 14d. Index on conversations.thread_type for frequent WHERE filters
   migrateConversationsThreadTypeIndex(database);
 
@@ -130,7 +135,10 @@ export function initializeDb(): void {
   // 21. Rebuild tables to add ON DELETE CASCADE to FK constraints
   migrateFkCascadeRebuilds(database);
 
-  // 22. Thread decision audit columns on notification_deliveries
+  // 22. Scoped approval grants (channel-agnostic one-time-use grants)
+  createScopedApprovalGrantsTable(database);
+
+  // 23. Thread decision audit columns on notification_deliveries
   migrateNotificationDeliveryThreadDecision(database);
 
   validateMigrationState(database);

package/src/memory/embedding-local.ts

@@ -1,3 +1,5 @@
+import { dirname, join } from 'node:path';
+
 import { getLogger } from '../util/logger.js';
 import { PromiseGuard } from '../util/promise-guard.js';
 import type { EmbeddingBackend, EmbeddingRequestOptions } from './embedding-backend.js';
@@ -59,13 +61,20 @@ export class LocalEmbeddingBackend implements EmbeddingBackend {
     let transformers: typeof import('@huggingface/transformers');
     try {
       transformers = await import('@huggingface/transformers');
-    } catch (err) {
-      // onnxruntime-node is not bundled in compiled binaries, so the import
-      // fails at runtime. Surface a clear error so callers can fall back to
-      // another embedding backend.
-      throw new Error(
-        `Local embedding backend unavailable: failed to load @huggingface/transformers (${err instanceof Error ? err.message : String(err)})`,
-      );
+    } catch {
+      // In compiled Bun binaries, bare specifier resolution starts from the
+      // virtual /$bunfs/root/ filesystem and can't find externalized packages.
+      // Fall back to resolving from the executable's real disk location where
+      // node_modules/ is co-located.
+      try {
+        const execDir = dirname(process.execPath);
+        const modulePath = join(execDir, 'node_modules', '@huggingface', 'transformers');
+        transformers = await import(modulePath);
+      } catch (err) {
+        throw new Error(
+          `Local embedding backend unavailable: failed to load @huggingface/transformers (${err instanceof Error ? err.message : String(err)})`,
+        );
+      }
     }
     this.extractor = await transformers.pipeline('feature-extraction', this.model, {
       dtype: 'fp32',

package/src/memory/guardian-action-store.ts

@@ -51,6 +51,8 @@ export interface GuardianActionRequest {
   lateAnsweredAt: number | null;
   followupAction: FollowupAction | null;
   followupCompletedAt: number | null;
+  toolName: string | null;
+  inputDigest: string | null;
   createdAt: number;
   updatedAt: number;
 }
@@ -97,6 +99,8 @@ function rowToRequest(row: typeof guardianActionRequests.$inferSelect): Guardian
     lateAnsweredAt: row.lateAnsweredAt ?? null,
     followupAction: (row.followupAction as FollowupAction) ?? null,
     followupCompletedAt: row.followupCompletedAt ?? null,
+    toolName: row.toolName ?? null,
+    inputDigest: row.inputDigest ?? null,
     createdAt: row.createdAt,
     updatedAt: row.updatedAt,
   };
@@ -137,6 +141,8 @@ export function createGuardianActionRequest(params: {
   pendingQuestionId: string;
   questionText: string;
   expiresAt: number;
+  toolName?: string;
+  inputDigest?: string;
 }): GuardianActionRequest {
   const db = getDb();
   const now = Date.now();
@@ -164,6 +170,8 @@ export function createGuardianActionRequest(params: {
     lateAnsweredAt: null,
     followupAction: null,
     followupCompletedAt: null,
+    toolName: params.toolName ?? null,
+    inputDigest: params.inputDigest ?? null,
     createdAt: now,
     updatedAt: now,
   };

package/src/memory/guardian-verification.ts

@@ -131,8 +131,8 @@ export function createChallenge(params: {
     nextResendAt: null,
     codeDigits: 6,
     maxAttempts: 3,
-    bootstrapTokenHash: null,
     verificationPurpose: 'guardian' as const,
+    bootstrapTokenHash: null,
     createdAt: now,
     updatedAt: now,
   };

package/src/memory/migrations/033-scoped-approval-grants.ts

@@ -0,0 +1,51 @@
+import type { DrizzleDb } from '../db-connection.js';
+
+/**
+ * Create the scoped_approval_grants table for channel-agnostic scoped
+ * approval grants.  Supports two scope modes:
+ *   - request_id: grant is scoped to a specific request
+ *   - tool_signature: grant is scoped to a tool name + input digest
+ *
+ * Grants are one-time-use (active -> consumed via CAS) and carry a
+ * mandatory TTL (expires_at).
+ */
+export function createScopedApprovalGrantsTable(database: DrizzleDb): void {
+  database.run(/*sql*/ `
+    CREATE TABLE IF NOT EXISTS scoped_approval_grants (
+      id TEXT PRIMARY KEY,
+      assistant_id TEXT NOT NULL,
+      scope_mode TEXT NOT NULL,
+      request_id TEXT,
+      tool_name TEXT,
+      input_digest TEXT,
+      request_channel TEXT NOT NULL,
+      decision_channel TEXT NOT NULL,
+      execution_channel TEXT,
+      conversation_id TEXT,
+      call_session_id TEXT,
+      requester_external_user_id TEXT,
+      guardian_external_user_id TEXT,
+      status TEXT NOT NULL,
+      expires_at TEXT NOT NULL,
+      consumed_at TEXT,
+      consumed_by_request_id TEXT,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    )
+  `);
+
+  // Index for request_id-based lookups (scope_mode = 'request_id')
+  database.run(
+    /*sql*/ `CREATE INDEX IF NOT EXISTS idx_scoped_grants_request_id ON scoped_approval_grants(request_id) WHERE request_id IS NOT NULL`,
+  );
+
+  // Index for tool_signature-based lookups (scope_mode = 'tool_signature')
+  database.run(
+    /*sql*/ `CREATE INDEX IF NOT EXISTS idx_scoped_grants_tool_sig ON scoped_approval_grants(tool_name, input_digest) WHERE tool_name IS NOT NULL`,
+  );
+
+  // Index for expiry sweeps
+  database.run(
+    /*sql*/ `CREATE INDEX IF NOT EXISTS idx_scoped_grants_status_expires ON scoped_approval_grants(status, expires_at)`,
+  );
+}

package/src/memory/migrations/034-guardian-action-tool-metadata.ts

@@ -0,0 +1,12 @@
+import type { DrizzleDb } from '../db-connection.js';
+
+/**
+ * Add tool_name and input_digest columns to guardian_action_requests for
+ * structured tool-approval tracking. These are nullable — informational
+ * ASK_GUARDIAN requests leave them NULL while tool-approval requests
+ * carry the tool identity and canonical input digest.
+ */
+export function migrateGuardianActionToolMetadata(database: DrizzleDb): void {
+  try { database.run(/*sql*/ `ALTER TABLE guardian_action_requests ADD COLUMN tool_name TEXT`); } catch { /* already exists */ }
+  try { database.run(/*sql*/ `ALTER TABLE guardian_action_requests ADD COLUMN input_digest TEXT`); } catch { /* already exists */ }
+}

package/src/memory/migrations/index.ts

@@ -33,6 +33,8 @@ export { migrateGuardianActionFollowup } from './030-guardian-action-followup.js
 export { migrateGuardianVerificationPurpose } from './030-guardian-verification-purpose.js';
 export { migrateConversationsThreadTypeIndex } from './031-conversations-thread-type-index.js';
 export { migrateGuardianDeliveryConversationIndex } from './032-guardian-delivery-conversation-index.js';
+export { createScopedApprovalGrantsTable } from './033-scoped-approval-grants.js';
+export { migrateGuardianActionToolMetadata } from './034-guardian-action-tool-metadata.js';
 export { migrateNotificationDeliveryThreadDecision } from './032-notification-delivery-thread-decision.js';
 export { createCoreTables } from './100-core-tables.js';
 export { createWatchersAndLogsTables } from './101-watchers-and-logs.js';

package/src/memory/schema.ts

@@ -843,6 +843,8 @@ export const guardianActionRequests = sqliteTable('guardian_action_requests', {
   lateAnsweredAt: integer('late_answered_at'),
   followupAction: text('followup_action'),                          // call_back | message_back | decline
   followupCompletedAt: integer('followup_completed_at'),
+  toolName: text('tool_name'),                                        // tool identity for tool-approval requests
+  inputDigest: text('input_digest'),                                  // canonical SHA-256 digest of tool input
   createdAt: integer('created_at').notNull(),
   updatedAt: integer('updated_at').notNull(),
 });
@@ -1075,3 +1077,31 @@ export const conversationAssistantAttentionState = sqliteTable('conversation_ass
   index('idx_conv_attn_state_assistant_latest_msg').on(table.assistantId, table.latestAssistantMessageAt),
   index('idx_conv_attn_state_assistant_last_seen').on(table.assistantId, table.lastSeenAssistantMessageAt),
 ]);
+
+// ── Scoped Approval Grants ──────────────────────────────────────────
+
+export const scopedApprovalGrants = sqliteTable('scoped_approval_grants', {
+  id: text('id').primaryKey(),
+  assistantId: text('assistant_id').notNull(),
+  scopeMode: text('scope_mode').notNull(),           // 'request_id' | 'tool_signature'
+  requestId: text('request_id'),
+  toolName: text('tool_name'),
+  inputDigest: text('input_digest'),
+  requestChannel: text('request_channel').notNull(),
+  decisionChannel: text('decision_channel').notNull(),
+  executionChannel: text('execution_channel'),        // null = any channel
+  conversationId: text('conversation_id'),
+  callSessionId: text('call_session_id'),
+  requesterExternalUserId: text('requester_external_user_id'),
+  guardianExternalUserId: text('guardian_external_user_id'),
+  status: text('status').notNull(),                   // 'active' | 'consumed' | 'expired' | 'revoked'
+  expiresAt: text('expires_at').notNull(),
+  consumedAt: text('consumed_at'),
+  consumedByRequestId: text('consumed_by_request_id'),
+  createdAt: text('created_at').notNull(),
+  updatedAt: text('updated_at').notNull(),
+}, (table) => [
+  index('idx_scoped_grants_request_id').on(table.requestId),
+  index('idx_scoped_grants_tool_sig').on(table.toolName, table.inputDigest),
+  index('idx_scoped_grants_status_expires').on(table.status, table.expiresAt),
+]);