@claude-flow/cli 3.64.0 → 3.65.1

package/dist/src/cost/budget-file.js

@@ -0,0 +1,113 @@
+/**
+ * The shared budget file (ADR-508 §2.1): `.claude-flow/cost/budget.json`,
+ * version 1. `ruflo cost budget set` writes it; the ruflo-mods cost ladder and
+ * `ruflo cost budget export` read it.
+ *
+ * Second copy of plugins/ruflo-mods/hooks/cost/file.ts (the mod may not import
+ * outside its plugin folder). __tests__/cost-budget-file.test.ts runs both over
+ * the same hostile corpus and requires identical answers.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+export const BUDGET_PATH = '.claude-flow/cost/budget.json';
+export const MAX_WINDOWS = 8;
+export const MAX_USD = 1_000_000;
+/** The largest budget file read (a budget is a few hundred bytes). */
+export const MAX_FILE_BYTES = 64 * 1024;
+/** LiteLLM's `budget_duration` grammar (`30s`, `30m`, `30h`, `30d`), with a bounded count. */
+export const PERIOD = /^[1-9][0-9]{0,3}[smhd]$/;
+const MODEL = /^[A-Za-z0-9._:/@-]{1,128}$/;
+const SECONDS = { s: 1, m: 60, h: 3600, d: 86400 };
+export const periodSeconds = (period) => Number(period.slice(0, -1)) * SECONDS[period.slice(-1)];
+/** A budget value validated, or undefined when it breaks any rule (see the mod copy for the list). */
+export function validateBudget(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const o = value;
+    if (o.version !== 1)
+        return undefined;
+    if (!Array.isArray(o.windows) || o.windows.length === 0 || o.windows.length > MAX_WINDOWS)
+        return undefined;
+    const windows = [];
+    const seen = new Set();
+    for (const w of o.windows) {
+        if (!w || typeof w !== 'object' || Array.isArray(w))
+            return undefined;
+        const { usd, period } = w;
+        if (typeof usd !== 'number' || !Number.isFinite(usd) || usd <= 0 || usd > MAX_USD)
+            return undefined;
+        if (typeof period !== 'string' || !PERIOD.test(period) || seen.has(period))
+            return undefined;
+        seen.add(period);
+        windows.push({ usd, period });
+    }
+    if (o.hardStop !== undefined && typeof o.hardStop !== 'boolean')
+        return undefined;
+    if (o.fallbackModel !== undefined && (typeof o.fallbackModel !== 'string' || !MODEL.test(o.fallbackModel)))
+        return undefined;
+    return {
+        version: 1,
+        windows,
+        hardStop: o.hardStop === true,
+        ...(typeof o.fallbackModel === 'string' ? { fallbackModel: o.fallbackModel } : {}),
+    };
+}
+/** The smallest-`usd` window (ties: the shorter period): the one a single session nears first. */
+export function ladderWindow(budget) {
+    return [...budget.windows].sort((a, b) => a.usd - b.usd || periodSeconds(a.period) - periodSeconds(b.period))[0];
+}
+/** Reads and validates the project's budget file. Never throws. */
+export function readBudget(cwd) {
+    const file = path.join(cwd, BUDGET_PATH);
+    let text;
+    try {
+        const stat = fs.statSync(file);
+        if (!stat.isFile())
+            return { kind: 'invalid', reason: `${BUDGET_PATH} is not a file` };
+        if (stat.size > MAX_FILE_BYTES)
+            return { kind: 'invalid', reason: `${BUDGET_PATH} is over ${MAX_FILE_BYTES} bytes` };
+        text = fs.readFileSync(file, 'utf8');
+    }
+    catch (error) {
+        return error?.code === 'ENOENT' ? { kind: 'absent' } : { kind: 'invalid', reason: String(error?.message ?? error) };
+    }
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        return { kind: 'invalid', reason: `${BUDGET_PATH} is not JSON` };
+    }
+    const budget = validateBudget(value);
+    return budget ? { kind: 'ok', budget } : { kind: 'invalid', reason: `${BUDGET_PATH} fails validation (version 1, 1-${MAX_WINDOWS} windows, usd in (0, ${MAX_USD}], period like 24h/7d/30d)` };
+}
+/** A budget from `set` flags (`--daily` 24h, `--weekly` 7d, `--monthly` 30d), or the reason it is not one. */
+export function budgetFromFlags(flags) {
+    const windows = [];
+    for (const [flag, period] of [['daily', '24h'], ['weekly', '7d'], ['monthly', '30d']]) {
+        const raw = flags[flag];
+        if (raw === undefined || raw === false)
+            continue;
+        const usd = typeof raw === 'number' ? raw : typeof raw === 'string' ? Number(raw) : NaN;
+        if (!Number.isFinite(usd) || usd <= 0 || usd > MAX_USD)
+            return { error: `--${flag} must be a USD amount in (0, ${MAX_USD}]` };
+        windows.push({ usd, period });
+    }
+    if (windows.length === 0)
+        return { error: 'give at least one of --daily, --weekly, --monthly' };
+    const value = { version: 1, windows, hardStop: flags.hardStop === true || flags.hardStop === 'true' };
+    if (flags.fallbackModel !== undefined && flags.fallbackModel !== false)
+        value.fallbackModel = String(flags.fallbackModel);
+    const budget = validateBudget(value);
+    return budget ? { budget } : { error: '--fallback-model must be a plain model name (letters, digits, . _ : / @ -; at most 128)' };
+}
+/** Writes the budget file atomically (temp file, rename). Holds no credential. */
+export function writeBudget(cwd, budget) {
+    const file = path.join(cwd, BUDGET_PATH);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.tmp-${process.pid}`;
+    fs.writeFileSync(tmp, `${JSON.stringify(budget, null, 2)}\n`, 'utf8');
+    fs.renameSync(tmp, file);
+    return file;
+}
+//# sourceMappingURL=budget-file.js.map

package/dist/src/cost/litellm.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Budget export to a gateway (ADR-508 §2.2).
+ *
+ * LiteLLM virtual-key budget fields, as docs.litellm.ai documents them
+ * (checked 2026-10-29: /docs/proxy/users and /docs/proxy/budget_fallbacks):
+ *   budget_limits     [{ budget_duration: "24h", max_budget: 10 }, ...]   stacked windows
+ *   model_max_budget  { "<model>": { budget_limit: 0.01, time_period: "1d" } }
+ *   budget_fallbacks  { "<model>": ["<fallback>", ...] }                   LiteLLM >= v1.92.0
+ * Durations use LiteLLM's grammar: "30s", "30m", "30h", "30d".
+ *
+ * meta-llm documents no budget API, so it is refused with a pointer to
+ * ADR-508 rather than guessed at.
+ */
+import { type BudgetFile } from './budget-file.js';
+export declare const ADR_POINTER = "v3/docs/adr/ADR-508-cost-ladder-gateway-budgets.md";
+export declare const GATEWAYS: readonly ["litellm", "meta-llm"];
+export interface LiteLLMKeyBody {
+    budget_limits: {
+        budget_duration: string;
+        max_budget: number;
+    }[];
+    model_max_budget?: Record<string, {
+        budget_limit: number;
+        time_period: string;
+    }>;
+    budget_fallbacks?: Record<string, string[]>;
+}
+/** Why a gateway cannot be exported to, or undefined when it can. */
+export declare function gatewayRefusal(gateway: unknown): string | undefined;
+/**
+ * The LiteLLM `/key/generate` budget fields for a budget. Every window becomes
+ * one `budget_limits` entry. `model_max_budget` (the ladder's window, on the
+ * named model) and `budget_fallbacks` (model → [fallbackModel]) are added only
+ * when `model` is given: the file names no primary model, and ruflo never
+ * invents a gateway model name.
+ */
+export declare function toLiteLLMKeyBody(budget: BudgetFile, model?: string): LiteLLMKeyBody;
+/** The body as YAML (LiteLLM key settings) or as the `/key/generate` JSON body. */
+export declare function formatBody(body: LiteLLMKeyBody, format: 'yaml' | 'json'): string;
+/**
+ * The `/key/generate` URL for a proxy URL, or the reason it is refused:
+ * HTTPS only, except a loopback host (`localhost`, `127.0.0.1`, `[::1]`);
+ * no credentials in the URL; no query or fragment; no path starting with `//`.
+ * The result always keeps the given scheme and host.
+ */
+export declare function keyGenerateUrl(proxy: unknown): {
+    url?: URL;
+    error?: string;
+};
+/** The master key from the environment variable `--key-env` names (never from argv), or why there is none. */
+export declare function keyFromEnv(name: unknown, env?: NodeJS.ProcessEnv): {
+    key?: string;
+    error?: string;
+};
+/** A key shown masked: its first 4 characters and its length. */
+export declare const maskKey: (key: string) => string;
+export interface ApplyResult {
+    ok: boolean;
+    status: number;
+    generatedKey?: string;
+    error?: string;
+}
+/**
+ * POSTs the budget fields to the proxy's `/key/generate`. Only the budget
+ * fields are sent; redirects are refused (one could leave HTTPS or loopback);
+ * 15 s timeout.
+ */
+export declare function applyToLiteLLM(url: URL, masterKey: string, body: LiteLLMKeyBody, fetchImpl?: typeof fetch): Promise<ApplyResult>;
+//# sourceMappingURL=litellm.d.ts.map

package/dist/src/cost/litellm.js

@@ -0,0 +1,135 @@
+/**
+ * Budget export to a gateway (ADR-508 §2.2).
+ *
+ * LiteLLM virtual-key budget fields, as docs.litellm.ai documents them
+ * (checked 2026-10-29: /docs/proxy/users and /docs/proxy/budget_fallbacks):
+ *   budget_limits     [{ budget_duration: "24h", max_budget: 10 }, ...]   stacked windows
+ *   model_max_budget  { "<model>": { budget_limit: 0.01, time_period: "1d" } }
+ *   budget_fallbacks  { "<model>": ["<fallback>", ...] }                   LiteLLM >= v1.92.0
+ * Durations use LiteLLM's grammar: "30s", "30m", "30h", "30d".
+ *
+ * meta-llm documents no budget API, so it is refused with a pointer to
+ * ADR-508 rather than guessed at.
+ */
+import { stringify as stringifyYaml } from 'yaml';
+import { ladderWindow } from './budget-file.js';
+export const ADR_POINTER = 'v3/docs/adr/ADR-508-cost-ladder-gateway-budgets.md';
+export const GATEWAYS = ['litellm', 'meta-llm'];
+const MODEL = /^[A-Za-z0-9._:/@-]{1,128}$/;
+const ENV_NAME = /^[A-Z_][A-Z0-9_]{0,127}$/;
+/** Why a gateway cannot be exported to, or undefined when it can. */
+export function gatewayRefusal(gateway) {
+    if (gateway === 'litellm')
+        return undefined;
+    if (gateway === 'meta-llm') {
+        return `--gateway meta-llm: meta-llm documents no budget API yet, so ruflo does not guess an endpoint. Its allowance tiers stay as they are; see ${ADR_POINTER} §2.2.`;
+    }
+    return `--gateway must be one of: litellm (meta-llm is reserved until it documents a budget API; see ${ADR_POINTER})`;
+}
+/**
+ * The LiteLLM `/key/generate` budget fields for a budget. Every window becomes
+ * one `budget_limits` entry. `model_max_budget` (the ladder's window, on the
+ * named model) and `budget_fallbacks` (model → [fallbackModel]) are added only
+ * when `model` is given: the file names no primary model, and ruflo never
+ * invents a gateway model name.
+ */
+export function toLiteLLMKeyBody(budget, model) {
+    const body = {
+        budget_limits: budget.windows.map((w) => ({ budget_duration: w.period, max_budget: w.usd })),
+    };
+    if (model !== undefined) {
+        if (!MODEL.test(model))
+            throw new Error('--model must be a plain model name (letters, digits, . _ : / @ -; at most 128)');
+        const w = ladderWindow(budget);
+        body.model_max_budget = { [model]: { budget_limit: w.usd, time_period: w.period } };
+        if (budget.fallbackModel)
+            body.budget_fallbacks = { [model]: [budget.fallbackModel] };
+    }
+    return body;
+}
+/** The body as YAML (LiteLLM key settings) or as the `/key/generate` JSON body. */
+export function formatBody(body, format) {
+    return format === 'json' ? `${JSON.stringify(body, null, 2)}\n` : stringifyYaml(body);
+}
+const LOOPBACK = new Set(['localhost', '127.0.0.1', '[::1]', '::1']);
+/**
+ * The `/key/generate` URL for a proxy URL, or the reason it is refused:
+ * HTTPS only, except a loopback host (`localhost`, `127.0.0.1`, `[::1]`);
+ * no credentials in the URL; no query or fragment; no path starting with `//`.
+ * The result always keeps the given scheme and host.
+ */
+export function keyGenerateUrl(proxy) {
+    if (typeof proxy !== 'string' || proxy.trim() === '')
+        return { error: '--apply needs --url <proxy base URL>' };
+    let u;
+    try {
+        u = new URL(proxy);
+    }
+    catch {
+        return { error: `--url is not a URL: ${proxy.slice(0, 200)}` };
+    }
+    if (u.username || u.password)
+        return { error: '--url must not carry credentials; the key comes from --key-env' };
+    if (u.search || u.hash)
+        return { error: '--url must be the proxy base URL, without a query or fragment' };
+    const loopback = LOOPBACK.has(u.hostname);
+    if (u.protocol !== 'https:' && !(u.protocol === 'http:' && loopback)) {
+        return { error: `--apply refuses ${u.protocol}//${u.hostname}: use https, or plain http only to a loopback host (localhost, 127.0.0.1, [::1])` };
+    }
+    // A path starting with "//" ("/\" normalises to it) would read as a protocol-relative
+    // URL if resolved as a string, and move the request, bearer key included, to another host.
+    if (u.pathname.startsWith('//'))
+        return { error: '--url path must not start with "//" or "/\\"' };
+    // The path is set on a copy, never resolved from a string, so it cannot change the
+    // scheme or host; the check below holds that anyway.
+    const out = new URL(u.href);
+    out.pathname = `${u.pathname.endsWith('/') ? u.pathname : `${u.pathname}/`}key/generate`;
+    if (out.protocol !== u.protocol || out.host !== u.host)
+        return { error: `--url would send the key to another host (${out.host}); refused` };
+    return { url: out };
+}
+/** The master key from the environment variable `--key-env` names (never from argv), or why there is none. */
+export function keyFromEnv(name, env = process.env) {
+    if (typeof name !== 'string' || !ENV_NAME.test(name))
+        return { error: '--apply needs --key-env <ENV_VAR_NAME> (upper-case letters, digits, _); the key itself is never taken from the command line' };
+    const key = env[name];
+    if (!key)
+        return { error: `environment variable ${name} is not set or empty` };
+    return { key };
+}
+/** A key shown masked: its first 4 characters and its length. */
+export const maskKey = (key) => (key.length <= 8 ? '********' : `${key.slice(0, 4)}…(${key.length} chars)`);
+/**
+ * POSTs the budget fields to the proxy's `/key/generate`. Only the budget
+ * fields are sent; redirects are refused (one could leave HTTPS or loopback);
+ * 15 s timeout.
+ */
+export async function applyToLiteLLM(url, masterKey, body, fetchImpl = fetch) {
+    let res;
+    try {
+        res = await fetchImpl(url, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', authorization: `Bearer ${masterKey}` },
+            body: JSON.stringify(body),
+            redirect: 'error',
+            signal: AbortSignal.timeout(15_000),
+        });
+    }
+    catch (error) {
+        return { ok: false, status: 0, error: String(error?.message ?? error).slice(0, 300) };
+    }
+    const text = (await res.text().catch(() => '')).slice(0, 64 * 1024);
+    if (!res.ok)
+        return { ok: false, status: res.status, error: text.replace(/\s+/g, ' ').slice(0, 300) };
+    let generatedKey;
+    try {
+        const parsed = JSON.parse(text);
+        if (typeof parsed.key === 'string')
+            generatedKey = parsed.key;
+    }
+    catch {
+        // a 2xx without a JSON body still applied
+    }
+    return { ok: true, status: res.status, generatedKey };
+}
+//# sourceMappingURL=litellm.js.map

package/dist/src/init/executor.d.ts

@@ -3,6 +3,7 @@
  * Main execution logic for V3 initialization
  */
 import type { InitOptions, InitResult } from './types.js';
+import { type RiskySettingsMode } from './settings-risk-scanner.js';
 /**
  * Execute initialization
  */
@@ -29,6 +30,10 @@ export interface UpgradeResult {
      * the upgrade — surfaced so a user can review before trusting it.
      */
     warnings?: string[];
+    /** ADR-509 §2.3 — auto-approve keys found in the existing settings.json. */
+    riskySettings?: string[];
+    /** ADR-509 §2.3 — the upgrade stopped before writing anything because of riskySettings. */
+    stoppedOnRiskySettings?: boolean;
 }
 /**
  * Merge new settings into existing settings.json
@@ -45,13 +50,13 @@ export declare function mergeSettingsForUpgrade(existing: Record<string, unknown
  * @param targetDir - Target directory
  * @param upgradeSettings - If true, merge new settings into existing settings.json
  */
-export declare function executeUpgrade(targetDir: string, upgradeSettings?: boolean): Promise<UpgradeResult>;
+export declare function executeUpgrade(targetDir: string, upgradeSettings?: boolean, riskySettings?: RiskySettingsMode): Promise<UpgradeResult>;
 /**
  * Execute upgrade with --add-missing flag
  * Adds any new skills, agents, and commands that don't exist yet
  * @param targetDir - Target directory
  * @param upgradeSettings - If true, merge new settings into existing settings.json
  */
-export declare function executeUpgradeWithMissing(targetDir: string, upgradeSettings?: boolean): Promise<UpgradeResult>;
+export declare function executeUpgradeWithMissing(targetDir: string, upgradeSettings?: boolean, riskySettings?: RiskySettingsMode): Promise<UpgradeResult>;
 export default executeInit;
 //# sourceMappingURL=executor.d.ts.map

package/dist/src/init/executor.js

@@ -19,8 +19,9 @@ import { getInstalledCliVersion, HELPERS_STAMP_FILE } from './helper-refresh.js'
 import { generateClaudeMd } from './claudemd-generator.js';
 import { recordMemoryPackagePath } from './memory-package-resolver.js';
 import { COMMONJS_COMPANION_HELPERS, ensureCommonJsCompanions } from './helper-companions.js';
-import { scanSettingsForRisk, formatRiskFindingsAsWarnings } from './settings-risk-scanner.js';
-import { AUTO_MEMORY_HOOK_TIMEOUT_S, helperHookCommand, helperScopeFor, helperStatusLineCommand, pinToUserHelpers } from './helper-commands.js';
+import { scanSettingsForRisk, formatRiskFindingsAsWarnings, RISKY_SETTINGS_HINT } from './settings-risk-scanner.js';
+import { applyRiskyMode, checkInitTrust, checkRiskySettings } from './risky-settings-gate.js';
+import { AUTO_MEMORY_HOOK_TIMEOUT_S, GIT_ROOT_STATUSLINE_CMD, helperHookCommand, helperScopeFor, helperStatusLineCommand, pinToUserHelpers } from './helper-commands.js';
 /**
  * Skills to copy based on configuration
  */
@@ -175,6 +176,26 @@ export async function executeInit(options) {
         },
     };
     const targetDir = options.targetDir;
+    // ADR-509 §2.3 — stop before anything is written when the settings.json this
+    // init would merge carries project auto-approve keys (--force overwrites it,
+    // so nothing is carried forward then).
+    // A project-shipped .claude/helpers/<critical helper> that is not ruflo's
+    // signed copy is part of the same gate: init keeps it, and ruflo's hooks run it.
+    if (options.components.settings && !options.force) {
+        const sourceHelpers = findSourceHelpersDir(options.sourceBaseDir);
+        const gate = checkInitTrust(targetDir, options.riskySettings ?? 'stop', sourceHelpers);
+        if (gate) {
+            result.riskySettings = gate.lines;
+            if (gate.stop) {
+                result.success = false;
+                result.stoppedOnRiskySettings = true;
+                result.errors.push(`.claude/settings.json or .claude/helpers carries ${gate.findings.length} item(s) init would carry forward. ${RISKY_SETTINGS_HINT}`);
+                return result;
+            }
+            if (gate.mode === 'drop')
+                replaceUntrustedHelpers(targetDir, gate, sourceHelpers, result);
+        }
+    }
     try {
         // Create directory structure
         await createDirectories(targetDir, options, result);
@@ -369,8 +390,7 @@ export function mergeSettingsForUpgrade(existing, targetDir) {
     // / jetsam / kernel panic. Preserving the user's existing command (the
     // old behavior here) means anyone who installed pre-#2337 and upgraded
     // never gets the fix. Now we detect the broken form and overwrite.
-    const NEW_STATUSLINE_CMD = scope === 'user' ? helperStatusLineCommand('user') :
-        `node -e "var c=require('child_process'),p=require('path'),r;try{r=c.execSync('git rev-parse --show-toplevel',{encoding:'utf8'}).trim()}catch(e){r=process.cwd()}var s=p.join(r,'.claude/helpers/statusline.cjs');process.argv.splice(1,0,s);require(s)"`;
+    const NEW_STATUSLINE_CMD = scope === 'user' ? helperStatusLineCommand('user') : GIT_ROOT_STATUSLINE_CMD;
     // Matches any invocation of `claude-flow hooks statusline` — either via npx
     // (`npx [--prefer-offline] [@]claude-flow[/cli][@<tag>] hooks statusline …`)
     // or as a bare command (`claude-flow hooks statusline …`). Both forms cold-
@@ -479,7 +499,7 @@ export function mergeSettingsForUpgrade(existing, targetDir) {
  * @param targetDir - Target directory
  * @param upgradeSettings - If true, merge new settings into existing settings.json
  */
-export async function executeUpgrade(targetDir, upgradeSettings = false) {
+export async function executeUpgrade(targetDir, upgradeSettings = false, riskySettings = 'stop') {
     const result = {
         success: true,
         updated: [],
@@ -488,6 +508,20 @@ export async function executeUpgrade(targetDir, upgradeSettings = false) {
         errors: [],
         settingsUpdated: [],
     };
+    // ADR-509 §2.3 — `--settings` carries the existing settings.json forward:
+    // stop before anything is written when it holds project auto-approve keys.
+    if (upgradeSettings) {
+        const gate = checkRiskySettings(path.join(targetDir, '.claude', 'settings.json'), riskySettings);
+        if (gate) {
+            result.riskySettings = gate.lines;
+            if (gate.stop) {
+                result.success = false;
+                result.stoppedOnRiskySettings = true;
+                result.errors.push(`.claude/settings.json carries ${gate.findings.length} auto-approve key(s) the upgrade would carry forward. ${RISKY_SETTINGS_HINT}`);
+                return result;
+            }
+        }
+    }
     try {
         // Ensure required directories exist
         const dirs = [
@@ -664,7 +698,7 @@ export async function executeUpgrade(targetDir, upgradeSettings = false) {
             const settingsPath = path.join(targetDir, '.claude', 'settings.json');
             if (fs.existsSync(settingsPath)) {
                 try {
-                    const existingSettings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+                    const existingSettings = applyRiskyMode(JSON.parse(fs.readFileSync(settingsPath, 'utf-8')), riskySettings).settings;
                     const { merged: mergedSettings, warnings: settingsRiskWarnings } = mergeSettingsForUpgrade(existingSettings, targetDir);
                     fs.writeFileSync(settingsPath, JSON.stringify(mergedSettings, null, 2), 'utf-8');
                     result.updated.push('.claude/settings.json');
@@ -706,9 +740,9 @@ export async function executeUpgrade(targetDir, upgradeSettings = false) {
  * @param targetDir - Target directory
  * @param upgradeSettings - If true, merge new settings into existing settings.json
  */
-export async function executeUpgradeWithMissing(targetDir, upgradeSettings = false) {
+export async function executeUpgradeWithMissing(targetDir, upgradeSettings = false, riskySettings = 'stop') {
     // First do the normal upgrade (pass through upgradeSettings)
-    const result = await executeUpgrade(targetDir, upgradeSettings);
+    const result = await executeUpgrade(targetDir, upgradeSettings, riskySettings);
     if (!result.success) {
         return result;
     }
@@ -821,7 +855,8 @@ async function writeSettings(targetDir, options, result) {
     if (fs.existsSync(settingsPath) && !options.force) {
         // Merge hooks/env/permissions into existing settings instead of skipping
         try {
-            const existing = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+            const dropped = applyRiskyMode(JSON.parse(fs.readFileSync(settingsPath, 'utf-8')), options.riskySettings);
+            const existing = dropped.settings;
             // Scan the pre-existing hooks/permissions BEFORE any merge decision
             // below — same untrusted, disk-sourced content mergeSettingsForUpgrade()
             // scans; see settings-risk-scanner.ts for why.
@@ -829,7 +864,8 @@ async function writeSettings(targetDir, options, result) {
             if (riskWarnings.length > 0) {
                 result.warnings = [...(result.warnings ?? []), ...riskWarnings];
             }
-            let merged = false;
+            // ADR-509: --drop-risky-settings removed keys; the file must be rewritten even if nothing else merges.
+            let merged = dropped.dropped > 0;
             // Merge hooks (the critical missing piece — #1484)
             if (generated.hooks && !existing.hooks) {
                 existing.hooks = generated.hooks;
@@ -1205,6 +1241,24 @@ async function copyAgents(targetDir, options, result) {
         }
     }
 }
+/**
+ * ADR-509 --drop-risky-settings: put ruflo's shipped copy in place of each
+ * project helper the gate flagged (or remove it when this ruflo ships none, so
+ * the hook falls back to the user's own helper).
+ */
+function replaceUntrustedHelpers(targetDir, gate, sourceHelpers, result) {
+    for (const f of gate.findings) {
+        if (f.target.kind !== 'helper')
+            continue;
+        const dest = path.join(targetDir, '.claude', 'helpers', f.target.name);
+        const src = sourceHelpers ? path.join(sourceHelpers, f.target.name) : null;
+        fs.rmSync(dest, { force: true, recursive: true });
+        if (src && fs.existsSync(src)) {
+            fs.copyFileSync(src, dest);
+            result.created.files.push(`.claude/helpers/${f.target.name}`);
+        }
+    }
+}
 /**
  * Find source helpers directory.
  * Validates that the directory contains hook-handler.cjs to avoid

package/dist/src/init/helper-commands.d.ts

@@ -17,4 +17,20 @@ export declare function helperStatusLineCommand(scope: HelperScope, windows?: bo
  * commands (other scripts, redirects, chains) are left alone.
  */
 export declare function pinToUserHelpers(command: string, windows?: boolean): string | null;
+/**
+ * ADR-059 statusLine command `init upgrade` writes for a project-level
+ * settings file (the git-root `node -e` form). Exported so the upgrade and the
+ * ADR-509 classifier use one string.
+ */
+export declare const GIT_ROOT_STATUSLINE_CMD = "node -e \"var c=require('child_process'),p=require('path'),r;try{r=c.execSync('git rev-parse --show-toplevel',{encoding:'utf8'}).trim()}catch(e){r=process.cwd()}var s=p.join(r,'.claude/helpers/statusline.cjs');process.argv.splice(1,0,s);require(s)\"";
+/**
+ * ADR-509: whether a settings hook (or statusLine) command is one of ruflo's own
+ * helper launches. Exact string equality against the closed set of commands
+ * ruflo generates or has generated, for each helper, each subcommand it is
+ * launched with, each scope and each platform. No substring or pattern test on
+ * the helper path: a command that merely mentions a helper (in a comment, after
+ * `node -r`, `--import` or a NODE_OPTIONS= prefix, or with code chained on) is
+ * a command ruflo did not write.
+ */
+export declare function isRufloHelperCommand(command: string): boolean;
 //# sourceMappingURL=helper-commands.d.ts.map

package/dist/src/init/helper-commands.js

@@ -170,4 +170,77 @@ export function pinToUserHelpers(command, windows = IS_WINDOWS) {
         return helperStatusLineCommand('user', windows);
     return helperHookCommand(script, args.trim(), 'user', windows);
 }
+/**
+ * ADR-059 statusLine command `init upgrade` writes for a project-level
+ * settings file (the git-root `node -e` form). Exported so the upgrade and the
+ * ADR-509 classifier use one string.
+ */
+export const GIT_ROOT_STATUSLINE_CMD = `node -e "var c=require('child_process'),p=require('path'),r;try{r=c.execSync('git rev-parse --show-toplevel',{encoding:'utf8'}).trim()}catch(e){r=process.cwd()}var s=p.join(r,'.claude/helpers/statusline.cjs');process.argv.splice(1,0,s);require(s)"`;
+/** Subcommands ruflo has written for each helper it launches from a hook. */
+const HELPER_SUBCOMMANDS = {
+    'hook-handler.cjs': [
+        'pre-bash', 'post-bash', 'pre-edit', 'post-edit', 'pre-task', 'post-task', 'pre-command', 'post-command',
+        'route', 'session-restore', 'session-end', 'session-start', 'notify', 'stats', 'status', 'compact-manual', 'compact-auto',
+    ],
+    'auto-memory-hook.mjs': ['import', 'sync', 'status'],
+};
+const GIT_ROOT = "var c=require('child_process'),p=require('path'),r;try{r=c.execSync('git rev-parse --show-toplevel',{encoding:'utf8'}).trim()}catch(e){r=process.cwd()}";
+const GIT_ROOT_ESM = "var c=require('child_process'),p=require('path'),u=require('url'),r;try{r=c.execSync('git rev-parse --show-toplevel',{encoding:'utf8'}).trim()}catch(e){r=process.cwd()}";
+/** Every exact command string ruflo has generated (or generates) to launch `script` with `sub`. */
+function generatedForms(script, sub) {
+    const arg = sub ? ` ${sub}` : '';
+    const win = script.replace(/\//g, '\\');
+    const forms = [
+        ...['project', 'user'].flatMap((scope) => [helperHookCommand(script, sub, scope, false), helperHookCommand(script, sub, scope, true)]),
+        `node ${script}${arg}`,
+        `node "$CLAUDE_PROJECT_DIR/${script}"${arg}`,
+        `sh -c 'exec node "\${CLAUDE_PROJECT_DIR:-.}/${script}"${arg}'`,
+        `cmd /c node %CLAUDE_PROJECT_DIR%/${script}${arg}`,
+        `cmd /c "IF EXIST \"%CLAUDE_PROJECT_DIR%\\${win}\" (node \"%CLAUDE_PROJECT_DIR%\\${win}\"${arg}) ELSE (node \"%USERPROFILE%\\${win}\"${arg})"`,
+    ];
+    if (script.endsWith('.mjs')) {
+        forms.push(`node -e "${GIT_ROOT_ESM}var f=p.join(r,'${script}');process.argv.splice(1,0,f);import(u.pathToFileURL(f).href)"${arg}`, `node -e "${GIT_ROOT_ESM}var f=p.join(r,'${script}');import(u.pathToFileURL(f).href)"${arg}`);
+    }
+    else {
+        forms.push(`node -e "${GIT_ROOT}var s=p.join(r,'${script}');process.argv.splice(1,0,s);require(s)"${arg}`);
+    }
+    return forms;
+}
+let knownCommands;
+/** The closed set of hook and statusLine commands ruflo writes, built once. */
+function rufloCommands() {
+    if (knownCommands)
+        return knownCommands;
+    const set = new Set();
+    for (const [helper, subs] of Object.entries(HELPER_SUBCOMMANDS)) {
+        for (const sub of subs)
+            for (const form of generatedForms(`.claude/helpers/${helper}`, sub))
+                set.add(form);
+    }
+    for (const scope of ['project', 'user'])
+        for (const win of [false, true])
+            set.add(helperStatusLineCommand(scope, win));
+    for (const form of generatedForms(STATUSLINE_SCRIPT, ''))
+        set.add(form);
+    set.add(GIT_ROOT_STATUSLINE_CMD);
+    knownCommands = set;
+    return set;
+}
+// Older ruflo-generated CLI hooks (`npx @claude-flow/cli@latest hooks pre-bash`), which `init upgrade` migrates.
+// Exact shape only: a registry spec with a version or tag (never a bare name a project's node_modules/.bin
+// could answer), one of ruflo's own hook/memory subcommands, and at most ten plain words with no shell
+// syntax (bounded, one alternative: no backtracking blow-up on a crafted settings file).
+const LEGACY_NPX_HOOK = /^npx (?:-y |--yes )?(?:@claude-flow\/cli|claude-flow|ruflo)@(?:latest|alpha|v3alpha|\d+\.\d+\.\d+(?:-[\w.]+)?) (?:hooks (?:pre-bash|post-bash|pre-edit|post-edit|pre-task|post-task|pre-command|post-command|route|session-start|session-end|session-restore|notify|statusline)|memory (?:import|sync|store))(?: [\w.:=-]+){0,10}$/;
+/**
+ * ADR-509: whether a settings hook (or statusLine) command is one of ruflo's own
+ * helper launches. Exact string equality against the closed set of commands
+ * ruflo generates or has generated, for each helper, each subcommand it is
+ * launched with, each scope and each platform. No substring or pattern test on
+ * the helper path: a command that merely mentions a helper (in a comment, after
+ * `node -r`, `--import` or a NODE_OPTIONS= prefix, or with code chained on) is
+ * a command ruflo did not write.
+ */
+export function isRufloHelperCommand(command) {
+    return rufloCommands().has(command) || LEGACY_NPX_HOOK.test(command);
+}
 //# sourceMappingURL=helper-commands.js.map

package/dist/src/init/risky-settings-gate.d.ts

@@ -0,0 +1,39 @@
+import { type AutoApproveFinding, type RiskySettingsMode } from './settings-risk-scanner.js';
+export interface RiskySettingsGate {
+    mode: RiskySettingsMode;
+    findings: AutoApproveFinding[];
+    /** Display lines: location, reason, sanitized snippet. */
+    lines: string[];
+    /** True when init must stop (mode `stop` and at least one finding). */
+    stop: boolean;
+}
+export declare function scanAutoApprove(settings: Record<string, unknown>): AutoApproveFinding[];
+/** Reads a settings file and judges it; null when the file is absent, unreadable or not a JSON object. */
+export declare function checkRiskySettings(settingsPath: string, mode?: RiskySettingsMode): RiskySettingsGate | null;
+/**
+ * ADR-509 §2.3: the helpers ruflo's hooks launch, as the PROJECT ships them.
+ * `init` keeps an existing `.claude/helpers/<name>` unless --force, and the
+ * project-scope hook commands prefer the project's copy, so a repository that
+ * ships its own hook-handler.cjs runs it under an exact ruflo hook command. A
+ * helper is trusted when its bytes are the copy this ruflo ships, or its
+ * SHA-256 is in a helpers manifest signed with ruflo's key (this ruflo's, or
+ * the project's own, which an older signed release left). Anything else is a
+ * finding. A `.LOCKED` helpers dir (deliberate local edits) is skipped, and with
+ * no ground truth at all this fails open. `pubkeyPem` is injectable for tests.
+ */
+export declare function untrustedProjectHelpers(targetDir: string, sourceHelpersDir: string | null, pubkeyPem?: string): AutoApproveFinding[];
+/**
+ * The init gate: the settings file's auto-approve keys plus the project's
+ * untrusted helpers. Null when there is nothing to report.
+ */
+export declare function checkInitTrust(targetDir: string, mode: RiskySettingsMode, sourceHelpersDir: string | null): RiskySettingsGate | null;
+/** `drop`: the settings without the auto-approve keys; otherwise the settings unchanged. */
+export declare function applyRiskyMode(settings: Record<string, unknown>, mode: RiskySettingsMode | undefined): {
+    settings: Record<string, unknown>;
+    dropped: number;
+};
+/** Reads `--keep-risky-settings` / `--drop-risky-settings` (camel or kebab); both at once is an error. */
+export declare function riskyModeFromFlags(flags: Record<string, unknown>): RiskySettingsMode | {
+    error: string;
+};
+//# sourceMappingURL=risky-settings-gate.d.ts.map