claude-flow 3.47.1 → 3.49.0

package/v3/@claude-flow/cli/dist/src/memory/memory-initializer.d.ts

@@ -205,7 +205,9 @@ export interface MemoryInitResult {
  * Ensure memory_entries table has all required columns
  * Adds missing columns for older databases (e.g., 'content' column)
  */
-export declare function ensureSchemaColumns(dbPath: string): Promise<{
+export declare function ensureSchemaColumns(dbPath: string, options?: {
+    encryptWrites?: boolean;
+}): Promise<{
     success: boolean;
     columnsAdded: string[];
     error?: string;
@@ -496,6 +498,8 @@ export declare function listEntries(options: {
     limit?: number;
     offset?: number;
     dbPath?: string;
+    /** Internal native-mirror writes must remain plaintext, including schema migration. */
+    encryptWrites?: boolean;
     /** #2073: When true, include the entry's full `content` string in each result. */
     includeContent?: boolean;
     /** ADR-323: restrict rows to these provenance types. */
@@ -549,6 +553,8 @@ export declare function deleteEntry(options: {
     key: string;
     namespace?: string;
     dbPath?: string;
+    /** Internal native-mirror writes must remain plaintext, including schema migration. */
+    encryptWrites?: boolean;
 }): Promise<{
     success: boolean;
     deleted: boolean;
@@ -573,6 +579,8 @@ export declare function withMemoryDbLock<T>(dbPath: string, fn: () => Promise<T>
 export declare function purgeNamespace(options: {
     namespace: string;
     dbPath?: string;
+    /** Internal native-mirror writes must remain plaintext, including schema migration. */
+    encryptWrites?: boolean;
 }): Promise<{
     success: boolean;
     deletedCount: number;

package/v3/@claude-flow/cli/dist/src/memory/memory-initializer.js

@@ -8,12 +8,14 @@
  *
  * @module v3/cli/memory-initializer
  */
+import { liveMemoryRowSql } from './live-memory-row.js';
 import * as fs from 'fs';
 import * as path from 'path';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { createRequire } from 'node:module';
 import { readFileMaybeEncrypted, writeFileAtomic, writeFileRestricted } from '../fs-secure.js';
 import { restoreMemoryDbFromBackup } from '../services/memory-backup.js';
+import { validateIdentifier } from '../mcp-tools/validate-input.js';
 /**
  * ADR-323 — typed memory provenance. Distinguishes WHO/WHAT wrote a memory
  * entry (a user's stated claim vs an agent's own output vs a tool result vs
@@ -208,14 +210,14 @@ async function getBridge() {
  * missing better-sqlite3. Appending the recorded reason turns an unactionable
  * message into a diagnosis.
  */
-async function walRefusalError(operation) {
+async function walRefusalError(operation, bridgeDbPath) {
     const base = 'memory database has an active native WAL connection '
         + '(found -wal/-shm sidecar files) — refusing an unsafe sql.js '
         + `whole-image ${operation}. Retry once the native writer completes, or `
         + 'restore the native better-sqlite3 bridge.';
     try {
         const bridge = await getBridge();
-        const reason = bridge?.getBridgeFailureReason?.();
+        const reason = bridge?.getBridgeFailureReason?.(bridgeDbPath);
         if (reason)
             return `${base} Bridge unavailable: ${reason}`;
     }
@@ -1141,7 +1143,7 @@ INSERT OR IGNORE INTO vector_indexes (id, name, dimensions) VALUES
  * Ensure memory_entries table has all required columns
  * Adds missing columns for older databases (e.g., 'content' column)
  */
-export async function ensureSchemaColumns(dbPath) {
+export async function ensureSchemaColumns(dbPath, options = {}) {
     const columnsAdded = [];
     try {
         if (!fs.existsSync(dbPath)) {
@@ -1213,7 +1215,7 @@ export async function ensureSchemaColumns(dbPath) {
             if (modified) {
                 // Save updated database
                 const data = db.export();
-                writeFileRestricted(dbPath, Buffer.from(data), { encrypt: true });
+                writeFileRestricted(dbPath, Buffer.from(data), { encrypt: options.encryptWrites ?? true });
             }
             db.close();
             return { success: true, columnsAdded };
@@ -1312,13 +1314,12 @@ async function activateControllerRegistry(verbose) {
         if (!bridge) {
             return { activated, failed, initTimeMs: performance.now() - startTime };
         }
-        const registry = await bridge.getControllerRegistry();
-        if (!registry) {
+        const controllers = await bridge.bridgeListControllers();
+        if (!controllers) {
             return { activated, failed, initTimeMs: performance.now() - startTime };
         }
         // Collect controller status from the registry
-        if (typeof registry.listControllers === 'function') {
-            const controllers = registry.listControllers();
+        if (controllers) {
             for (const ctrl of controllers) {
                 if (ctrl.enabled) {
                     activated.push(ctrl.name);
@@ -1879,7 +1880,7 @@ export async function checkMemoryInitialization(dbPath) {
         // Try to load with sql.js
         const initSqlJs = (await import('sql.js')).default;
         const SQL = await initSqlJs();
-        const fileBuffer = fs.readFileSync(path_);
+        const fileBuffer = readFileMaybeEncrypted(path_, null);
         db = new SQL.Database(fileBuffer);
         // Check for metadata table
         const tables = db.exec("SELECT name FROM sqlite_master WHERE type='table'");
@@ -2579,7 +2580,7 @@ export async function storeEntry(options) {
             return {
                 success: false,
                 id: '',
-                error: await walRefusalError('write'),
+                error: await walRefusalError('write', options.dbPath),
             };
         }
         const id = `entry_${Date.now()}_${Math.random().toString(36).substring(7)}`;
@@ -2751,8 +2752,8 @@ export async function searchEntries(options) {
                     // query (no extra round-trip) so a provenance-filtered search
                     // still gets RaBitQ's speedup instead of falling back to brute
                     // force.
-                    const stmt = db.prepare('SELECT content, embedding, provenance_type FROM memory_entries WHERE id = ? AND status = ?');
-                    stmt.bind([candidate.id, 'active']);
+                    const stmt = db.prepare(`SELECT content, embedding, provenance_type FROM memory_entries WHERE id = ? AND ${liveMemoryRowSql()}`);
+                    stmt.bind([candidate.id]);
                     if (stmt.step()) {
                         const [content, embeddingJson, provenanceTypeVal] = stmt.get();
                         if (provenanceFilter?.length && !provenanceFilter.includes(provenanceTypeVal || 'unknown')) {
@@ -2812,29 +2813,28 @@ export async function searchEntries(options) {
                     const db = new SQL.Database(fileBuffer);
                     const provenanceByKey = new Map();
                     for (const r of filtered) {
-                        const stmt = db.prepare('SELECT provenance_type FROM memory_entries WHERE namespace = ? AND key = ? LIMIT 1');
+                        const stmt = db.prepare(`SELECT provenance_type FROM memory_entries WHERE namespace = ? AND key = ? AND ${liveMemoryRowSql()} LIMIT 1`);
                         stmt.bind([r.namespace, r.key]);
                         if (stmt.step()) {
-                            provenanceByKey.set(`${r.namespace}::${r.key}`, stmt.get()[0] || 'unknown');
+                            provenanceByKey.set(JSON.stringify([r.namespace, r.key]), stmt.get()[0] || 'unknown');
                         }
                         stmt.free();
                     }
                     db.close();
                     filtered = filtered
-                        .map(r => ({ ...r, provenanceType: provenanceByKey.get(`${r.namespace}::${r.key}`) || 'unknown' }));
+                        .filter(r => provenanceByKey.has(JSON.stringify([r.namespace, r.key])))
+                        .map(r => ({ ...r, provenanceType: provenanceByKey.get(JSON.stringify([r.namespace, r.key])) || 'unknown' }));
                     if (provenanceFilter?.length) {
                         filtered = filtered.filter(r => provenanceFilter.includes(r.provenanceType));
                     }
                 }
                 catch {
-                    // A requested trust filter fails closed. Unfiltered callers retain
-                    // backward-compatible results with an explicit unknown label.
-                    filtered = provenanceFilter?.length
-                        ? []
-                        : filtered.map(r => ({ ...r, provenanceType: 'unknown' }));
+                    // An ANN hit alone cannot prove the row is still live. Fall back
+                    // to the authoritative SQL scan if liveness cannot be checked.
+                    filtered = [];
                 }
             }
-            if (!provenanceFilter?.length || filtered.length >= limit) {
+            if (filtered.length >= limit) {
                 return {
                     success: true,
                     results: filtered.slice(0, limit),
@@ -2853,7 +2853,7 @@ export async function searchEntries(options) {
         // Get entries with embeddings
         // ADR-323: build the WHERE clause incrementally so namespace and
         // provenance filters compose (both, either, or neither).
-        const whereClauses = [`status = 'active'`];
+        const whereClauses = [liveMemoryRowSql()];
         const whereParams = [];
         if (effectiveNamespace !== 'all') {
             whereClauses.push('namespace = ?');
@@ -2980,8 +2980,14 @@ export async function listEntries(options) {
         if (!fs.existsSync(dbPath)) {
             return { success: false, entries: [], total: 0, error: 'Database not found' };
         }
+        // Listing can migrate/backfill the schema, so it is also a whole-image
+        // writer. The newly selected native mirror may still have a live WAL.
+        await releaseOwnNativeHandle(dbPath);
+        if (hasNativeWalSidecars(dbPath)) {
+            return { success: false, entries: [], total: 0, error: await walRefusalError('read/write') };
+        }
         // Ensure schema has all required columns (migration for older DBs)
-        await ensureSchemaColumns(dbPath);
+        await ensureSchemaColumns(dbPath, options);
         const initSqlJs = (await import('sql.js')).default;
         const SQL = await initSqlJs();
         const fileBuffer = readFileMaybeEncrypted(dbPath, null);
@@ -2990,7 +2996,7 @@ export async function listEntries(options) {
         // that predate the status column may have NULL after migration.
         // See memory-bridge.ts:bridgeListEntries for full context.
         // Get total count
-        const whereClauses = [ACTIVE_MEMORY_ROW_SQL];
+        const whereClauses = [liveMemoryRowSql()];
         const whereParams = [];
         if (namespace) {
             whereClauses.push('namespace = ?');
@@ -3088,7 +3094,7 @@ export async function getEntry(options) {
             return {
                 success: false,
                 found: false,
-                error: await walRefusalError('read/write'),
+                error: await walRefusalError('read/write', options.dbPath),
             };
         }
         // #2878: this is a mutator, not a reader — the access_count bump below
@@ -3107,7 +3113,7 @@ export async function getEntry(options) {
             const getStmt = db.prepare(`
         SELECT id, key, namespace, content, embedding, access_count, created_at, updated_at, tags
         FROM memory_entries
-        WHERE ${ACTIVE_MEMORY_ROW_SQL}
+        WHERE ${liveMemoryRowSql()}
           AND key = ?
           AND namespace = ?
         LIMIT 1
@@ -3211,14 +3217,14 @@ export async function deleteEntry(options) {
                 key,
                 namespace,
                 remainingEntries: 0,
-                error: await walRefusalError('write'),
+                error: await walRefusalError('write', options.dbPath),
             };
         }
         // #2878: whole-image read-modify-write — without the lock a concurrent
         // writer's flush resurrects the row this call just tombstoned.
         return await withMemoryDbLock(dbPath, async () => {
             // Ensure schema has all required columns (migration for older DBs)
-            await ensureSchemaColumns(dbPath);
+            await ensureSchemaColumns(dbPath, options);
             const initSqlJs = (await import('sql.js')).default;
             const SQL = await initSqlJs();
             const fileBuffer = readFileMaybeEncrypted(dbPath, null);
@@ -3268,7 +3274,7 @@ export async function deleteEntry(options) {
             const remainingEntries = countResult[0]?.values?.[0]?.[0] || 0;
             // Save updated database
             const data = db.export();
-            writeFileRestricted(dbPath, Buffer.from(data), { encrypt: true });
+            writeFileRestricted(dbPath, Buffer.from(data), { encrypt: options.encryptWrites ?? true });
             db.close();
             // Clean up in-memory HNSW index so ghost vectors don't appear in searches.
             // Remove the entry from the HNSW entries map and invalidate the index.
@@ -3387,11 +3393,13 @@ export async function withMemoryDbLock(dbPath, fn) {
         }
     }
 }
-const NAMESPACE_PATTERN = /^[A-Za-z0-9._-]{1,128}$/;
 export async function purgeNamespace(options) {
     const { namespace, dbPath: customPath } = options;
-    if (!NAMESPACE_PATTERN.test(namespace)) {
-        return { success: false, deletedCount: 0, remainingEntries: 0, error: `Invalid namespace: ${namespace}` };
+    // #3570: the same validator store, import and export use, so any namespace
+    // that can be written can also be purged (`team:alice` included).
+    const vNs = validateIdentifier(namespace, 'namespace');
+    if (!vNs.valid) {
+        return { success: false, deletedCount: 0, remainingEntries: 0, error: `Invalid namespace: ${vNs.error}` };
     }
     const swarmDir = getMemoryRoot();
     const dbPath = customPath ? path.resolve(customPath) : path.join(swarmDir, 'memory.db');
@@ -3420,7 +3428,12 @@ export async function purgeNamespace(options) {
             if (!fs.existsSync(dbPath)) {
                 return { success: false, deletedCount: 0, remainingEntries: 0, error: 'Database not found' };
             }
-            await ensureSchemaColumns(dbPath);
+            // Recheck at mutation time even when the CLI already read a preview.
+            await releaseOwnNativeHandle(dbPath);
+            if (hasNativeWalSidecars(dbPath)) {
+                return { success: false, deletedCount: 0, remainingEntries: 0, error: await walRefusalError('write') };
+            }
+            await ensureSchemaColumns(dbPath, options);
             const initSqlJs = (await import('sql.js')).default;
             const SQL = await initSqlJs();
             const fileBuffer = readFileMaybeEncrypted(dbPath, null);
@@ -3431,7 +3444,7 @@ export async function purgeNamespace(options) {
             const countResult = db.exec(`SELECT COUNT(*) FROM memory_entries WHERE status = 'active'`);
             const remainingEntries = countResult[0]?.values?.[0]?.[0] || 0;
             const data = db.export();
-            writeFileRestricted(dbPath, Buffer.from(data), { encrypt: true });
+            writeFileRestricted(dbPath, Buffer.from(data), { encrypt: options.encryptWrites ?? true });
             db.close();
             if (deletedCount > 0 && hnswIndex?.entries) {
                 for (const [id, entry] of hnswIndex.entries) {

package/v3/@claude-flow/cli/dist/src/plugins/manager.d.ts

@@ -3,6 +3,7 @@
  * Handles actual plugin installation, persistence, and lifecycle
  * Bridges discovery service with file system persistence
  */
+import { type TrustDecision } from './trust-policy.js';
 export interface InstalledPlugin {
     name: string;
     version: string;
@@ -13,6 +14,40 @@ export interface InstalledPlugin {
     commands?: string[];
     hooks?: string[];
     config?: Record<string, unknown>;
+    /** Declared (or registry-assigned) trust level, recorded at install time. */
+    trustLevel?: string;
+    /** Declared permissions, recorded at install time so they can be enforced. */
+    permissions?: string[];
+    /** How the install was verified. */
+    verification?: 'checksum' | 'npm-integrity' | 'policy' | 'skipped';
+    /** Whether npm lifecycle scripts ran during install (false = `--ignore-scripts`). */
+    scriptsRun?: boolean;
+    /** Hooks/commands the plugin declared but that were not registered, and why. */
+    withheld?: {
+        hooks: string[];
+        commands: string[];
+        reasons: string[];
+    };
+}
+/** Options for {@link PluginManager.installFromLocal} / {@link PluginManager.installFromNpm}. */
+export interface PluginInstallOptions {
+    /** `--verify` (default true). */
+    verify?: boolean;
+    /** `--trust` (default false). */
+    trust?: boolean;
+    /** Registry checksum (`sha256:<hex>`) the downloaded tarball must match. */
+    expectedChecksum?: string;
+    /** Trust level from the registry entry, when the plugin was found there. */
+    registryTrustLevel?: string;
+    /** Permissions from the registry entry, merged with the package's own declaration. */
+    registryPermissions?: string[];
+}
+export interface PluginInstallResult {
+    success: boolean;
+    error?: string;
+    plugin?: InstalledPlugin;
+    decision?: TrustDecision;
+    warnings?: string[];
 }
 export interface InstalledPluginsManifest {
     version: '1.0.0';
@@ -46,19 +81,11 @@ export declare class PluginManager {
     /**
      * Install a plugin from npm
      */
-    installFromNpm(packageName: string, version?: string): Promise<{
-        success: boolean;
-        error?: string;
-        plugin?: InstalledPlugin;
-    }>;
+    installFromNpm(packageName: string, version?: string, opts?: PluginInstallOptions): Promise<PluginInstallResult>;
     /**
      * Install a plugin from a local path
      */
-    installFromLocal(sourcePath: string): Promise<{
-        success: boolean;
-        error?: string;
-        plugin?: InstalledPlugin;
-    }>;
+    installFromLocal(sourcePath: string, opts?: PluginInstallOptions): Promise<PluginInstallResult>;
     /**
      * Uninstall a plugin
      */

package/v3/@claude-flow/cli/dist/src/plugins/manager.js

@@ -4,9 +4,11 @@
  * Bridges discovery service with file system persistence
  */
 import * as fs from 'fs';
+import * as os from 'os';
 import * as path from 'path';
 import { execFile } from 'child_process';
 import { promisify } from 'util';
+import { evaluatePluginTrust, parseSha256Checksum, readDeclaredTrust, sha256Hex, shouldRunInstallScripts, } from './trust-policy.js';
 const execFileAsync = promisify(execFile);
 // On Windows, `npm` is a shell script (no `.exe`) and `npm.cmd` is a batch
 // wrapper. Since Node 18.20.2 / 20.12.2 (CVE-2024-27980) the runtime refuses
@@ -30,6 +32,30 @@ function validatePackageName(spec) {
         throw new Error(`Invalid package name: ${spec}`);
     }
 }
+/**
+ * Apply the #3557 trust policy to a plugin's package.json: record its declared
+ * trust and permissions, and withhold hooks/commands the policy doesn't allow.
+ */
+function applyTrustPolicy(pkg, opts) {
+    const block = (pkg['claude-flow'] ?? {});
+    const commands = Array.isArray(block.commands) ? block.commands : [];
+    const hooks = Array.isArray(block.hooks) ? block.hooks : [];
+    const declared = readDeclaredTrust(pkg);
+    const permissions = [...new Set([...(opts.registryPermissions ?? []), ...declared.permissions])];
+    const trustLevel = opts.registryTrustLevel ?? declared.trustLevel;
+    const decision = evaluatePluginTrust({ trustLevel: declared.trustLevel, permissions }, { verify: opts.verify !== false, trust: opts.trust === true, registryTrustLevel: opts.registryTrustLevel });
+    if (decision.allowed) {
+        return { commands, hooks, trustLevel, permissions, decision };
+    }
+    return {
+        commands: [],
+        hooks: [],
+        trustLevel,
+        permissions,
+        withheld: { hooks, commands, reasons: decision.reasons },
+        decision,
+    };
+}
 // ============================================================================
 // Plugin Manager
 // ============================================================================
@@ -98,11 +124,14 @@ export class PluginManager {
     /**
      * Install a plugin from npm
      */
-    async installFromNpm(packageName, version) {
+    async installFromNpm(packageName, version, opts = {}) {
         if (!this.manifest) {
             await this.initialize();
         }
         const versionSpec = version ? `${packageName}@${version}` : packageName;
+        const verify = opts.verify !== false;
+        const warnings = [];
+        let tmpDir;
         try {
             // Check if already installed
             if (this.manifest.plugins[packageName]) {
@@ -116,23 +145,56 @@ export class PluginManager {
             await this.ensureDirectory(installDir);
             // Validate package name to prevent injection (S-3)
             validatePackageName(versionSpec);
+            // #3557: with --verify, a registry checksum must match the tarball we
+            // install. Pack first, hash that exact file, then install from it, so the
+            // bytes that were checked are the bytes that get installed.
+            let installTarget = versionSpec;
+            let verification = verify ? 'npm-integrity' : 'skipped';
+            const expected = verify ? parseSha256Checksum(opts.expectedChecksum) : null;
+            if (expected) {
+                tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ruflo-plugin-verify-'));
+                const packed = await runNpm(['pack', versionSpec, '--pack-destination', tmpDir, '--json', '--ignore-scripts'], 120000);
+                const info = JSON.parse(packed.stdout);
+                const filename = info[0]?.filename;
+                if (!filename)
+                    throw new Error(`npm pack returned no tarball for ${versionSpec}`);
+                const tarball = path.join(tmpDir, path.basename(filename));
+                const actual = sha256Hex(fs.readFileSync(tarball));
+                if (actual !== expected) {
+                    return {
+                        success: false,
+                        error: `Checksum mismatch for ${versionSpec}: registry expects sha256:${expected}, ` +
+                            `downloaded tarball is sha256:${actual}. Refusing to install (--verify).`,
+                    };
+                }
+                installTarget = tarball;
+                verification = 'checksum';
+            }
+            else if (verify && opts.expectedChecksum) {
+                warnings.push(`Registry checksum "${opts.expectedChecksum}" is not a verifiable sha256 digest; ` +
+                    `relying on npm's own registry integrity check.`);
+            }
             // Use npm to install (array form prevents shell injection)
             console.log(`[PluginManager] Installing ${versionSpec}...`);
-            await runNpm(['install', '--prefix', this.config.pluginsDir, versionSpec], 120000);
+            // #3557 follow-up: lifecycle scripts run before the package's own trust
+            // declaration can be read, so untrusted installs skip them entirely.
+            const scriptsRun = shouldRunInstallScripts(opts);
+            const installArgs = ['install', '--prefix', this.config.pluginsDir, installTarget];
+            if (!scriptsRun) {
+                installArgs.push('--ignore-scripts');
+                warnings.push(`Install scripts were skipped for ${packageName} (--ignore-scripts): it is not registry-vouched and --trust was not given. ` +
+                    `Reinstall with --trust to run them.`);
+            }
+            await runNpm(installArgs, 120000);
             // Get installed version
             const packageJsonPath = path.join(installDir, packageName, 'package.json');
             let installedVersion = version || 'latest';
-            let commands = [];
-            let hooks = [];
+            let pkg = {};
             if (fs.existsSync(packageJsonPath)) {
-                const pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
-                installedVersion = pkg.version;
-                // Check for claude-flow plugin metadata
-                if (pkg['claude-flow']) {
-                    commands = pkg['claude-flow'].commands || [];
-                    hooks = pkg['claude-flow'].hooks || [];
-                }
+                pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+                installedVersion = String(pkg.version ?? installedVersion);
             }
+            const trusted = applyTrustPolicy(pkg, opts);
             // Create plugin entry
             const plugin = {
                 name: packageName,
@@ -141,25 +203,34 @@ export class PluginManager {
                 enabled: true,
                 source: 'npm',
                 path: path.join(installDir, packageName),
-                commands,
-                hooks,
+                commands: trusted.commands,
+                hooks: trusted.hooks,
+                trustLevel: trusted.trustLevel,
+                permissions: trusted.permissions,
+                verification,
+                scriptsRun,
+                ...(trusted.withheld ? { withheld: trusted.withheld } : {}),
             };
             // Save to manifest
             this.manifest.plugins[packageName] = plugin;
             await this.saveManifest();
             console.log(`[PluginManager] Installed ${packageName}@${installedVersion}`);
-            return { success: true, plugin };
+            return { success: true, plugin, decision: trusted.decision, warnings };
         }
         catch (error) {
             const errorMsg = error instanceof Error ? error.message : String(error);
             console.error(`[PluginManager] Failed to install ${packageName}:`, errorMsg);
             return { success: false, error: errorMsg };
         }
+        finally {
+            if (tmpDir)
+                fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
     }
     /**
      * Install a plugin from a local path
      */
-    async installFromLocal(sourcePath) {
+    async installFromLocal(sourcePath, opts = {}) {
         if (!this.manifest) {
             await this.initialize();
         }
@@ -182,6 +253,10 @@ export class PluginManager {
                     error: `Plugin ${packageName} is already installed`,
                 };
             }
+            // #3557: record declared trust/permissions; withhold hooks and commands
+            // the policy doesn't allow without --trust. A local path has no registry
+            // entry to vouch for it, so the plugin's own declaration decides.
+            const trusted = applyTrustPolicy(pkg, { verify: opts.verify, trust: opts.trust });
             // Create plugin entry (link to local path, don't copy)
             const plugin = {
                 name: packageName,
@@ -190,14 +265,20 @@ export class PluginManager {
                 enabled: true,
                 source: 'local',
                 path: absolutePath,
-                commands: pkg['claude-flow']?.commands || [],
-                hooks: pkg['claude-flow']?.hooks || [],
+                commands: trusted.commands,
+                hooks: trusted.hooks,
+                trustLevel: trusted.trustLevel,
+                permissions: trusted.permissions,
+                verification: opts.verify === false ? 'skipped' : 'policy',
+                // A local install links the path; it never runs npm or package scripts.
+                scriptsRun: false,
+                ...(trusted.withheld ? { withheld: trusted.withheld } : {}),
             };
             // Save to manifest
             this.manifest.plugins[packageName] = plugin;
             await this.saveManifest();
             console.log(`[PluginManager] Installed local plugin ${packageName}@${pkg.version}`);
-            return { success: true, plugin };
+            return { success: true, plugin, decision: trusted.decision };
         }
         catch (error) {
             const errorMsg = error instanceof Error ? error.message : String(error);
@@ -345,8 +426,13 @@ export class PluginManager {
             const versionSpec = version ? `${packageName}@${version}` : `${packageName}@latest`;
             // Validate package name to prevent injection (S-3)
             validatePackageName(versionSpec);
-            // Reinstall with new version (array form prevents shell injection)
-            await runNpm(['install', '--prefix', this.config.pluginsDir, versionSpec], 120000);
+            // Reinstall with new version (array form prevents shell injection).
+            // An install recorded with scriptsRun:false stays script-free on upgrade;
+            // legacy entries (no field) keep their pre-#3557 behaviour.
+            const upgradeArgs = ['install', '--prefix', this.config.pluginsDir, versionSpec];
+            if (existing.scriptsRun === false)
+                upgradeArgs.push('--ignore-scripts');
+            await runNpm(upgradeArgs, 120000);
             // Update manifest
             const installDir = path.join(this.config.pluginsDir, 'node_modules');
             const packageJsonPath = path.join(installDir, packageName, 'package.json');

package/v3/@claude-flow/cli/dist/src/plugins/trust-policy.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Plugin install trust policy (#3557).
+ *
+ * `plugins install --verify` used to be parsed and never read, and a plugin's
+ * declared `trustLevel`/`permissions` were neither recorded nor enforced.
+ * These pure helpers decide what an install may register.
+ */
+/**
+ * Permissions a plugin may declare and still have its hooks and commands
+ * registered without `--trust`. Anything else (filesystem, network, shell,
+ * secrets, config, privileged, …) needs an explicit `--trust`.
+ */
+export declare const DEFAULT_PLUGIN_PERMISSIONS: readonly string[];
+/** Trust levels that are withheld unless the user passes `--trust`. */
+export declare const UNTRUSTED_TRUST_LEVELS: readonly string[];
+/** Registry trust levels that the registry itself vouches for. */
+export declare const REGISTRY_VOUCHED_TRUST_LEVELS: readonly string[];
+export interface DeclaredTrust {
+    trustLevel?: string;
+    permissions: string[];
+}
+export interface TrustDecision {
+    /** Hooks and commands may be registered. */
+    allowed: boolean;
+    /** Verification was skipped with `--no-verify`. */
+    verificationSkipped: boolean;
+    /** Why registration was withheld (empty when allowed). */
+    reasons: string[];
+    /** Declared permissions outside {@link DEFAULT_PLUGIN_PERMISSIONS}. */
+    excessPermissions: string[];
+}
+export interface TrustOptions {
+    /** `--verify` (default true). */
+    verify: boolean;
+    /** `--trust` (default false). */
+    trust: boolean;
+    /** Trust level from a registry entry, when the plugin was found there. */
+    registryTrustLevel?: string;
+}
+/**
+ * Read the trust declaration from a plugin's package.json. The `claude-flow`
+ * block wins; top-level fields are accepted as a fallback.
+ */
+export declare function readDeclaredTrust(pkg: Record<string, unknown>): DeclaredTrust;
+/** Decide whether an install may register the plugin's hooks and commands. */
+export declare function evaluatePluginTrust(declared: DeclaredTrust, opts: TrustOptions): TrustDecision;
+/**
+ * Whether npm may run the package's lifecycle scripts (preinstall/install/
+ * postinstall, and those of its dependencies). Scripts execute before the
+ * package's own trust declaration can be read, so only an explicit `--trust`
+ * or a registry-vouched entry allows them; everything else installs with
+ * `--ignore-scripts`.
+ */
+export declare function shouldRunInstallScripts(opts: {
+    trust?: boolean;
+    registryTrustLevel?: string;
+}): boolean;
+/** A registry checksum we can actually verify: `sha256:` + 64 hex chars. */
+export declare function parseSha256Checksum(checksum: unknown): string | null;
+export declare function sha256Hex(data: Buffer): string;
+//# sourceMappingURL=trust-policy.d.ts.map