clawvault 3.2.1 → 3.4.0

package/dist/types-CbL-wIKi.d.ts

@@ -0,0 +1,36 @@
+import { a as SearchOptions, b as SearchResult } from './types-DslKvCaj.js';
+import { PluginConfig } from './lib/config.js';
+
+type RecallStrategy = 'quick' | 'entity' | 'temporal' | 'verification' | 'relationship';
+interface RecallQueryClassification {
+    strategy: RecallStrategy;
+    entityName?: string;
+    temporalDays?: number;
+}
+interface RecallOptions {
+    limit?: number;
+    strategy?: RecallStrategy;
+    includeSources?: boolean;
+    vaultPath?: string;
+    agentId?: string;
+    pluginConfig?: PluginConfig;
+    searchOptions?: SearchOptions;
+}
+interface RecallSource {
+    title: string;
+    path: string;
+    category: string;
+    score: number;
+    snippet: string;
+    modified: string;
+}
+interface RecallResult {
+    query: string;
+    strategy: RecallStrategy;
+    entityName?: string;
+    context: string;
+    sources: RecallSource[];
+    rawResults: SearchResult[];
+}
+
+export type { RecallStrategy as R, RecallQueryClassification as a, RecallOptions as b, RecallResult as c, RecallSource as d };

package/dist/{types-BbWJoC1c.d.ts → types-DslKvCaj.d.ts}

@@ -14,6 +14,8 @@ interface VaultConfig {
     qmdRoot?: string;
     /** Custom templates path (optional) */
     templatesPath?: string;
+    /** Search configuration */
+    search?: VaultSearchConfig;
 }
 interface VaultMeta {
     name: string;
@@ -26,6 +28,37 @@ interface VaultMeta {
     qmdCollection?: string;
     /** Root path for qmd collection (defaults to vault path) */
     qmdRoot?: string;
+    /** Search configuration */
+    search?: VaultSearchConfig;
+}
+type SearchBackend = 'in-process' | 'qmd';
+type EmbeddingProvider = 'none' | 'openai' | 'gemini' | 'ollama';
+type RerankProvider = 'none' | 'jina' | 'voyage' | 'siliconflow' | 'pinecone';
+interface VaultSearchConfig {
+    /**
+     * Default backend used for search commands.
+     * in-process is default and recommended for constrained devices.
+     */
+    backend?: SearchBackend;
+    /** Allow qmd fallback when installed and in-process search fails */
+    qmdFallback?: boolean;
+    /** Chunk size in characters for in-process BM25 indexing */
+    chunkSize?: number;
+    /** Chunk overlap in characters for in-process BM25 indexing */
+    chunkOverlap?: number;
+    embeddings?: {
+        provider?: EmbeddingProvider;
+        model?: string;
+        baseUrl?: string;
+        apiKey?: string;
+    };
+    rerank?: {
+        provider?: RerankProvider;
+        model?: string;
+        endpoint?: string;
+        apiKey?: string;
+        weight?: number;
+    };
 }
 interface Document {
     /** Unique ID (relative path without extension) */
@@ -89,6 +122,23 @@ interface StoreOptions {
     /** Optional qmd index name override (defaults to configured/global index) */
     qmdIndexName?: string;
 }
+type PatchMode = 'append' | 'replace' | 'content';
+interface PatchOptions {
+    /** Document id/path to patch (e.g. decisions/my-note or decisions/my-note.md) */
+    idOrPath: string;
+    /** Patch mode */
+    mode: PatchMode;
+    /** Text to append when mode=append */
+    append?: string;
+    /** Search text when mode=replace */
+    replace?: string;
+    /** Replacement text when mode=replace */
+    with?: string;
+    /** Replacement body when mode=content */
+    content?: string;
+    /** Optional markdown section heading (without #) to scope the patch */
+    section?: string;
+}
 interface SyncOptions {
     /** Target directory to sync to */
     target: string;
@@ -159,4 +209,4 @@ interface SessionRecap {
 }
 declare const DEFAULT_CONFIG: Partial<VaultConfig>;
 
-export { type Category as C, type Document as D, type HandoffDocument as H, type MemoryType as M, type SessionRecap as S, TYPE_TO_CATEGORY as T, type VaultConfig as V, type StoreOptions as a, type SearchOptions as b, type SearchResult as c, type SyncOptions as d, type SyncResult as e, DEFAULT_CATEGORIES as f, DEFAULT_CONFIG as g, MEMORY_TYPES as h, type VaultMeta as i };
+export { type Category as C, type Document as D, type EmbeddingProvider as E, type HandoffDocument as H, type MemoryType as M, type PatchOptions as P, type RerankProvider as R, type StoreOptions as S, TYPE_TO_CATEGORY as T, type VaultConfig as V, type SearchOptions as a, type SearchResult as b, type SyncOptions as c, type SyncResult as d, type SessionRecap as e, type VaultSearchConfig as f, DEFAULT_CATEGORIES as g, DEFAULT_CONFIG as h, MEMORY_TYPES as i, type PatchMode as j, type SearchBackend as k, type VaultMeta as l };

package/hooks/clawvault/HOOK.md

@@ -81,33 +81,50 @@ Configure the plugin via OpenClaw's config system:
 
 ```bash
 # Set vault path
-openclaw config set plugins.clawvault.config.vaultPath ~/my-vault
+openclaw config set plugins.entries.clawvault.config.vaultPath ~/my-vault
 
 # View current config
-openclaw config get plugins.clawvault.config
+openclaw config get plugins.entries.clawvault
 ```
 
-Available configuration options:
+Available configuration options (all privileged actions are opt-in):
 
 | Key | Type | Default | Description |
 |-----|------|---------|-------------|
 | `vaultPath` | string | (auto-detected) | Path to the ClawVault vault directory |
-| `autoCheckpoint` | boolean | `true` | Enable automatic checkpointing on session events |
+| `agentVaults` | object | `{}` | Per-agent vault mapping |
+| `allowClawvaultExec` | boolean | `false` | Required gate for all `child_process` calls |
+| `clawvaultBinaryPath` | string | (PATH lookup) | Optional absolute path to `clawvault` binary |
+| `clawvaultBinarySha256` | string | (unset) | Optional SHA-256 executable integrity check |
+| `allowEnvAccess` | boolean | `false` | Allow env fallbacks (`OPENCLAW_*`, `CLAWVAULT_PATH`) |
+| `enableStartupRecovery` | boolean | `false` | Enable `gateway:startup` recovery check |
+| `enableSessionContextInjection` | boolean | `false` | Enable `session:start` recap/context injection |
+| `enableAutoCheckpoint` | boolean | `false` | Enable checkpoint on `command:new` |
+| `enableObserveOnNew` | boolean | `false` | Enable observer flush on `command:new` |
+| `enableHeartbeatObservation` | boolean | `false` | Enable heartbeat-driven observation |
+| `enableCompactionObservation` | boolean | `false` | Enable observer flush on compaction |
+| `enableWeeklyReflection` | boolean | `false` | Enable weekly reflection cron |
+| `enableFactExtraction` | boolean | `false` | Enable local fact extraction/entity graph updates |
+| `autoCheckpoint` | boolean | `false` | Deprecated alias for `enableAutoCheckpoint` |
 | `contextProfile` | string | `"auto"` | Default context profile (`default`, `planning`, `incident`, `handoff`, `auto`) |
 | `maxContextResults` | integer | `4` | Maximum context results to inject on session start |
-| `observeOnHeartbeat` | boolean | `true` | Enable observation threshold checks on heartbeat |
-| `weeklyReflection` | boolean | `true` | Enable weekly reflection on Sunday midnight UTC |
+| `observeOnHeartbeat` | boolean | `false` | Deprecated alias for `enableHeartbeatObservation` |
+| `weeklyReflection` | boolean | `false` | Deprecated alias for `enableWeeklyReflection` |
+
+Security details and threat model: see [SECURITY.md](../../SECURITY.md).
 
 ### Vault Path Resolution
 
-The hook resolves the vault path in this order:
+When `allowEnvAccess=true`, the hook resolves the vault path in this order:
 
-1. Plugin config (`plugins.clawvault.config.vaultPath` set via `openclaw config`)
+1. Plugin config (`plugins.entries.clawvault.config.vaultPath` set via `openclaw config`)
 2. `OPENCLAW_PLUGIN_CLAWVAULT_VAULTPATH` environment variable
 3. `CLAWVAULT_PATH` environment variable
 4. Walking up from cwd to find `.clawvault.json`
 5. Checking `memory/` subdirectory (OpenClaw convention)
 
+When `allowEnvAccess=false` (default), steps 2 and 3 are skipped.
+
 ### Troubleshooting
 
 If `openclaw hooks enable clawvault` fails with hook-not-found, run `openclaw hooks install clawvault` first and verify discovery with `openclaw hooks list --verbose`.

package/hooks/clawvault/handler.js

@@ -16,6 +16,11 @@ import { createHash, randomUUID } from 'crypto';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
+import {
+  resolveExecutablePath,
+  sanitizeExecArgs,
+  verifyExecutableIntegrity
+} from './integrity.js';
 
 const MAX_CONTEXT_RESULTS = 4;
 const MAX_CONTEXT_PROMPT_LENGTH = 500;
@@ -36,6 +41,7 @@ const MAX_FACT_TEXT_LENGTH = 600;
 const FACT_SENTENCE_SPLIT_RE = /[.!?]+\s+|\r?\n+/;
 const EXCLUSIVE_FACT_RELATIONS = new Set(['lives_in', 'works_at', 'age']);
 const ENTITY_TARGET_RELATIONS = new Set(['works_at', 'lives_in', 'partner_name', 'dog_name', 'parent_name']);
+const CLAWVAULT_EXECUTABLE = 'clawvault';
 
 // Sanitize string for safe display (prevent prompt injection via control chars)
 function sanitizeForDisplay(str) {
@@ -107,15 +113,17 @@ function normalizeAbsoluteEnvPath(value) {
   return resolved;
 }
 
-function getOpenClawAgentsDir() {
-  const stateDir = normalizeAbsoluteEnvPath(process.env.OPENCLAW_STATE_DIR);
-  if (stateDir) {
-    return path.join(stateDir, 'agents');
-  }
+function getOpenClawAgentsDir(pluginConfig) {
+  if (allowsEnvAccess(pluginConfig)) {
+    const stateDir = normalizeAbsoluteEnvPath(process.env.OPENCLAW_STATE_DIR);
+    if (stateDir) {
+      return path.join(stateDir, 'agents');
+    }
 
-  const openClawHome = normalizeAbsoluteEnvPath(process.env.OPENCLAW_HOME);
-  if (openClawHome) {
-    return path.join(openClawHome, 'agents');
+    const openClawHome = normalizeAbsoluteEnvPath(process.env.OPENCLAW_HOME);
+    if (openClawHome) {
+      return path.join(openClawHome, 'agents');
+    }
   }
 
   return path.join(os.homedir(), '.openclaw', 'agents');
@@ -155,8 +163,8 @@ function getScaledObservationThresholdBytes(fileSizeBytes) {
   return LARGE_SESSION_THRESHOLD_BYTES;
 }
 
-function parseSessionIndex(agentId) {
-  const sessionsDir = path.join(getOpenClawAgentsDir(), agentId, 'sessions');
+function parseSessionIndex(agentId, pluginConfig) {
+  const sessionsDir = path.join(getOpenClawAgentsDir(pluginConfig), agentId, 'sessions');
   const sessionsJsonPath = path.join(sessionsDir, 'sessions.json');
   if (!fs.existsSync(sessionsJsonPath)) {
     return { sessionsDir, index: {} };
@@ -173,9 +181,9 @@ function parseSessionIndex(agentId) {
   }
 }
 
-function shouldObserveActiveSessions(vaultPath, agentId) {
+function shouldObserveActiveSessions(vaultPath, agentId, pluginConfig) {
   const cursors = loadObserveCursors(vaultPath);
-  const { sessionsDir, index } = parseSessionIndex(agentId);
+  const { sessionsDir, index } = parseSessionIndex(agentId, pluginConfig);
   const entries = Object.entries(index);
   if (entries.length === 0) {
     return false;
@@ -457,6 +465,8 @@ function extractPluginConfig(event) {
   const candidates = [
     event?.pluginConfig,
     event?.context?.pluginConfig,
+    event?.config?.plugins?.entries?.clawvault?.config,
+    event?.context?.config?.plugins?.entries?.clawvault?.config,
     event?.config?.plugins?.clawvault?.config,
     event?.context?.config?.plugins?.clawvault?.config
   ];
@@ -470,6 +480,31 @@ function extractPluginConfig(event) {
   return {};
 }
 
+function isOptInEnabled(pluginConfig, ...keys) {
+  for (const key of keys) {
+    if (pluginConfig?.[key] === true) return true;
+  }
+  return false;
+}
+
+function allowsEnvAccess(pluginConfig) {
+  return isOptInEnabled(pluginConfig, 'allowEnvAccess');
+}
+
+function getConfiguredExecutablePath(pluginConfig) {
+  const value = pluginConfig?.clawvaultBinaryPath;
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  return trimmed || null;
+}
+
+function getConfiguredExecutableSha256(pluginConfig) {
+  const value = pluginConfig?.clawvaultBinarySha256;
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim().toLowerCase();
+  return trimmed || null;
+}
+
 // Resolve vault path for a specific agent from agentVaults config
 function resolveAgentVaultPath(pluginConfig, agentId) {
   if (!agentId || typeof agentId !== 'string') return null;
@@ -487,11 +522,9 @@ function resolveAgentVaultPath(pluginConfig, agentId) {
 
 // Find vault by walking up directories
 // Supports per-agent vault paths via agentVaults config
-function findVaultPath(event, options = {}) {
-  const pluginConfig = extractPluginConfig(event);
-  
+function findVaultPath(event, pluginConfig, options = {}) {
   // Determine agent ID for per-agent vault resolution
-  const agentId = options.agentId || resolveAgentIdForEvent(event);
+  const agentId = options.agentId || resolveAgentIdForEvent(event, pluginConfig);
   
   // Check agentVaults first (per-agent vault paths)
   if (agentId) {
@@ -508,15 +541,17 @@ function findVaultPath(event, options = {}) {
     if (validated) return validated;
   }
 
-  // Check OPENCLAW_PLUGIN_CLAWVAULT_VAULTPATH env (injected by OpenClaw from plugin config)
-  if (process.env.OPENCLAW_PLUGIN_CLAWVAULT_VAULTPATH) {
-    const validated = validateVaultPath(process.env.OPENCLAW_PLUGIN_CLAWVAULT_VAULTPATH);
-    if (validated) return validated;
-  }
+  if (allowsEnvAccess(pluginConfig)) {
+    // Check OPENCLAW_PLUGIN_CLAWVAULT_VAULTPATH env (injected by OpenClaw from plugin config)
+    if (process.env.OPENCLAW_PLUGIN_CLAWVAULT_VAULTPATH) {
+      const validated = validateVaultPath(process.env.OPENCLAW_PLUGIN_CLAWVAULT_VAULTPATH);
+      if (validated) return validated;
+    }
 
-  // Check CLAWVAULT_PATH env
-  if (process.env.CLAWVAULT_PATH) {
-    return validateVaultPath(process.env.CLAWVAULT_PATH);
+    // Check CLAWVAULT_PATH env
+    if (process.env.CLAWVAULT_PATH) {
+      return validateVaultPath(process.env.CLAWVAULT_PATH);
+    }
   }
 
   // Walk up from cwd
@@ -539,16 +574,54 @@ function findVaultPath(event, options = {}) {
 }
 
 // Run clawvault command safely (no shell)
-function runClawvault(args, options = {}) {
+function runClawvault(args, pluginConfig, options = {}) {
+  if (!isOptInEnabled(pluginConfig, 'allowClawvaultExec')) {
+    return {
+      success: false,
+      skipped: true,
+      output: 'ClawVault CLI execution is disabled. Set allowClawvaultExec=true to enable.',
+      code: 0
+    };
+  }
+
   const timeoutMs = Number.isFinite(options.timeoutMs) ? Math.max(1000, Number(options.timeoutMs)) : 15000;
+  const executablePath = resolveExecutablePath(CLAWVAULT_EXECUTABLE, {
+    explicitPath: getConfiguredExecutablePath(pluginConfig)
+  });
+  if (!executablePath) {
+    return {
+      success: false,
+      output: 'Unable to resolve clawvault executable path. Set clawvaultBinaryPath to an absolute executable path.',
+      code: 1
+    };
+  }
+
+  const expectedSha256 = getConfiguredExecutableSha256(pluginConfig);
+  const integrityResult = verifyExecutableIntegrity(executablePath, expectedSha256);
+  if (!integrityResult.ok) {
+    return {
+      success: false,
+      output: `Executable integrity verification failed for ${executablePath}.`,
+      code: 1
+    };
+  }
+
+  let sanitizedArgs;
   try {
-    // Use execFileSync to avoid shell injection
-    // Arguments are passed as array, not interpolated into shell
-    const output = execFileSync('clawvault', args, {
+    sanitizedArgs = sanitizeExecArgs(args);
+  } catch (err) {
+    return {
+      success: false,
+      output: err?.message || 'Invalid command arguments',
+      code: 1
+    };
+  }
+
+  try {
+    const output = execFileSync(executablePath, sanitizedArgs, {
       encoding: 'utf-8',
       timeout: timeoutMs,
       stdio: ['pipe', 'pipe', 'pipe'],
-      // Explicitly no shell
       shell: false
     });
     return { success: true, output: output.trim(), code: 0 };
@@ -586,23 +659,29 @@ function parseRecoveryOutput(output) {
   return { hadDeath, workingOn };
 }
 
-function resolveAgentIdForEvent(event) {
+function resolveAgentIdForEvent(event, pluginConfig) {
   const fromSessionKey = extractAgentIdFromSessionKey(extractSessionKey(event));
   if (fromSessionKey) return fromSessionKey;
 
-  const fromEnv = sanitizeAgentId(process.env.OPENCLAW_AGENT_ID);
-  if (fromEnv) return fromEnv;
+  if (allowsEnvAccess(pluginConfig)) {
+    const fromEnv = sanitizeAgentId(process.env.OPENCLAW_AGENT_ID);
+    if (fromEnv) return fromEnv;
+  }
 
   return 'main';
 }
 
-function runObserverCron(vaultPath, agentId, options = {}) {
+function runObserverCron(vaultPath, agentId, pluginConfig, options = {}) {
   const args = ['observe', '--cron', '--agent', agentId, '-v', vaultPath];
   if (Number.isFinite(options.minNewBytes) && Number(options.minNewBytes) > 0) {
     args.push('--min-new', String(Math.floor(Number(options.minNewBytes))));
   }
 
-  const result = runClawvault(args, { timeoutMs: 120000 });
+  const result = runClawvault(args, pluginConfig, { timeoutMs: 120000 });
+  if (result.skipped) {
+    console.log('[clawvault] Observer cron skipped: allowClawvaultExec is disabled');
+    return false;
+  }
   if (!result.success) {
     console.warn(`[clawvault] Observer cron failed (${options.reason || 'unknown reason'})`);
     return false;
@@ -1312,7 +1391,12 @@ function isSundayMidnightUtc(date) {
 }
 
 async function handleWeeklyReflect(event) {
-  const vaultPath = findVaultPath(event);
+  const pluginConfig = extractPluginConfig(event);
+  if (!isOptInEnabled(pluginConfig, 'enableWeeklyReflection', 'weeklyReflection')) {
+    return;
+  }
+
+  const vaultPath = findVaultPath(event, pluginConfig);
   if (!vaultPath) {
     console.log('[clawvault] No vault found, skipping weekly reflection');
     return;
@@ -1324,7 +1408,11 @@ async function handleWeeklyReflect(event) {
     return;
   }
 
-  const result = runClawvault(['reflect', '-v', vaultPath], { timeoutMs: 120000 });
+  const result = runClawvault(['reflect', '-v', vaultPath], pluginConfig, { timeoutMs: 120000 });
+  if (result.skipped) {
+    console.log('[clawvault] Weekly reflection skipped: allowClawvaultExec is disabled');
+    return;
+  }
   if (!result.success) {
     console.warn('[clawvault] Weekly reflection failed');
     return;
@@ -1334,7 +1422,12 @@ async function handleWeeklyReflect(event) {
 
 // Handle gateway startup - check for context death
 async function handleStartup(event) {
-  const vaultPath = findVaultPath(event);
+  const pluginConfig = extractPluginConfig(event);
+  if (!isOptInEnabled(pluginConfig, 'enableStartupRecovery')) {
+    return;
+  }
+
+  const vaultPath = findVaultPath(event, pluginConfig);
   if (!vaultPath) {
     console.log('[clawvault] No vault found, skipping recovery check');
     return;
@@ -1343,7 +1436,11 @@ async function handleStartup(event) {
   console.log(`[clawvault] Checking for context death`);
 
   // Pass vault path as separate argument (not interpolated)
-  const result = runClawvault(['recover', '--clear', '-v', vaultPath]);
+  const result = runClawvault(['recover', '--clear', '-v', vaultPath], pluginConfig);
+  if (result.skipped) {
+    console.log('[clawvault] Recovery check skipped: allowClawvaultExec is disabled');
+    return;
+  }
   
   if (!result.success) {
     console.warn('[clawvault] Recovery check failed');
@@ -1373,7 +1470,15 @@ async function handleStartup(event) {
 
 // Handle /new command - auto-checkpoint before reset
 async function handleNew(event) {
-  const vaultPath = findVaultPath(event);
+  const pluginConfig = extractPluginConfig(event);
+  const autoCheckpointEnabled = isOptInEnabled(pluginConfig, 'enableAutoCheckpoint', 'autoCheckpoint');
+  const observerOnNewEnabled = isOptInEnabled(pluginConfig, 'enableObserveOnNew');
+  const factExtractionEnabled = isOptInEnabled(pluginConfig, 'enableFactExtraction');
+  if (!autoCheckpointEnabled && !observerOnNewEnabled && !factExtractionEnabled) {
+    return;
+  }
+
+  const vaultPath = findVaultPath(event, pluginConfig);
   if (!vaultPath) {
     console.log('[clawvault] No vault found, skipping auto-checkpoint');
     return;
@@ -1387,33 +1492,44 @@ async function handleNew(event) {
     ? event.context.commandSource.replace(/[^a-zA-Z0-9_-]/g, '').slice(0, 50)
     : 'cli';
 
-  console.log('[clawvault] Auto-checkpoint before /new');
-
-  // Pass each argument separately (no shell interpolation)
-  const result = runClawvault([
-    'checkpoint',
-    '--working-on', `Session reset via /new from ${source}`,
-    '--focus', `Pre-reset checkpoint, session: ${sessionKey}`,
-    '-v', vaultPath
-  ]);
+  if (autoCheckpointEnabled) {
+    console.log('[clawvault] Auto-checkpoint before /new');
+    const result = runClawvault([
+      'checkpoint',
+      '--working-on', `Session reset via /new from ${source}`,
+      '--focus', `Pre-reset checkpoint, session: ${sessionKey}`,
+      '-v', vaultPath
+    ], pluginConfig);
 
-  if (result.success) {
-    console.log('[clawvault] Auto-checkpoint created');
-  } else {
-    console.warn('[clawvault] Auto-checkpoint failed');
+    if (result.skipped) {
+      console.log('[clawvault] Auto-checkpoint skipped: allowClawvaultExec is disabled');
+    } else if (result.success) {
+      console.log('[clawvault] Auto-checkpoint created');
+    } else {
+      console.warn('[clawvault] Auto-checkpoint failed');
+    }
   }
 
-  const agentId = resolveAgentIdForEvent(event);
-  runObserverCron(vaultPath, agentId, {
-    minNewBytes: 1,
-    reason: 'command:new flush'
-  });
-  runFactExtractionForEvent(vaultPath, event, 'command:new');
+  const agentId = resolveAgentIdForEvent(event, pluginConfig);
+  if (observerOnNewEnabled) {
+    runObserverCron(vaultPath, agentId, pluginConfig, {
+      minNewBytes: 1,
+      reason: 'command:new flush'
+    });
+  }
+  if (factExtractionEnabled) {
+    runFactExtractionForEvent(vaultPath, event, 'command:new');
+  }
 }
 
 // Handle session start - inject dynamic context for first prompt
 async function handleSessionStart(event) {
-  const vaultPath = findVaultPath(event);
+  const pluginConfig = extractPluginConfig(event);
+  if (!isOptInEnabled(pluginConfig, 'enableSessionContextInjection')) {
+    return;
+  }
+
+  const vaultPath = findVaultPath(event, pluginConfig);
   if (!vaultPath) {
     console.log('[clawvault] No vault found, skipping context injection');
     return;
@@ -1432,11 +1548,14 @@ async function handleSessionStart(event) {
       recapArgs.push('--agent', agentId);
     }
 
-    const recapResult = runClawvault(recapArgs);
-    if (!recapResult.success) {
-      console.warn('[clawvault] Session recap lookup failed');
-    } else {
+    const recapResult = runClawvault(recapArgs, pluginConfig);
+    if (recapResult.skipped) {
+      console.log('[clawvault] Session recap skipped: allowClawvaultExec is disabled');
+    }
+    if (recapResult.success) {
       recapEntries = parseSessionRecapJson(recapResult.output);
+    } else if (!recapResult.skipped) {
+      console.warn('[clawvault] Session recap lookup failed');
     }
   } else {
     console.log('[clawvault] No session key found, skipping session recap');
@@ -1450,12 +1569,14 @@ async function handleSessionStart(event) {
       '--format', 'json',
       '--profile', 'auto',
       '-v', vaultPath
-    ]);
+    ], pluginConfig);
 
-    if (!contextResult.success) {
-      console.warn('[clawvault] Context lookup failed');
-    } else {
+    if (contextResult.success) {
       memoryEntries = parseContextJson(contextResult.output);
+    } else if (contextResult.skipped) {
+      console.log('[clawvault] Context lookup skipped: allowClawvaultExec is disabled');
+    } else {
+      console.warn('[clawvault] Context lookup failed');
     }
   } else {
     console.log('[clawvault] No initial prompt, skipping vault memory lookup');
@@ -1475,35 +1596,51 @@ async function handleSessionStart(event) {
 
 // Handle heartbeat events - cheap stat-based trigger for active observation
 async function handleHeartbeat(event) {
-  const vaultPath = findVaultPath(event);
+  const pluginConfig = extractPluginConfig(event);
+  if (!isOptInEnabled(pluginConfig, 'enableHeartbeatObservation', 'observeOnHeartbeat')) {
+    return;
+  }
+
+  const vaultPath = findVaultPath(event, pluginConfig);
   if (!vaultPath) {
     console.log('[clawvault] No vault found, skipping heartbeat observation check');
     return;
   }
 
-  const agentId = resolveAgentIdForEvent(event);
-  if (!shouldObserveActiveSessions(vaultPath, agentId)) {
+  const agentId = resolveAgentIdForEvent(event, pluginConfig);
+  if (!shouldObserveActiveSessions(vaultPath, agentId, pluginConfig)) {
     console.log('[clawvault] Heartbeat: no sessions crossed active-observe threshold');
     return;
   }
 
-  runObserverCron(vaultPath, agentId, { reason: 'heartbeat threshold crossed' });
+  runObserverCron(vaultPath, agentId, pluginConfig, { reason: 'heartbeat threshold crossed' });
 }
 
 // Handle context compaction - force flush any pending session deltas
 async function handleContextCompaction(event) {
-  const vaultPath = findVaultPath(event);
+  const pluginConfig = extractPluginConfig(event);
+  const compactionObserveEnabled = isOptInEnabled(pluginConfig, 'enableCompactionObservation');
+  const factExtractionEnabled = isOptInEnabled(pluginConfig, 'enableFactExtraction');
+  if (!compactionObserveEnabled && !factExtractionEnabled) {
+    return;
+  }
+
+  const vaultPath = findVaultPath(event, pluginConfig);
   if (!vaultPath) {
     console.log('[clawvault] No vault found, skipping compaction observation');
     return;
   }
 
-  const agentId = resolveAgentIdForEvent(event);
-  runObserverCron(vaultPath, agentId, {
-    minNewBytes: 1,
-    reason: 'context compaction'
-  });
-  runFactExtractionForEvent(vaultPath, event, 'compaction:memoryFlush');
+  const agentId = resolveAgentIdForEvent(event, pluginConfig);
+  if (compactionObserveEnabled) {
+    runObserverCron(vaultPath, agentId, pluginConfig, {
+      minNewBytes: 1,
+      reason: 'context compaction'
+    });
+  }
+  if (factExtractionEnabled) {
+    runFactExtractionForEvent(vaultPath, event, 'compaction:memoryFlush');
+  }
 }
 
 // Main handler - route events