talos-code 0.0.1 → 0.2.0

package/dist/security/mxc-execution-backend.js

@@ -0,0 +1,281 @@
+/*
+ * ⭐⭐⭐ R0 lane S — THE CONTAINER'S ENVIRONMENT IS ONE ALLOWLIST, FOR THE PROBE AND FOR EVERY COMMAND.
+ *
+ * Measured 2026-09-23 on this host (Windows 11 26200.9457, Node 24.18.0, SDK 0.8.0, the policy below):
+ *  · SDK 0.8.0 uses a supplied environment VERBATIM (microsoft/mxc docs/schema.md, 2026-09-21) and serialises it into
+ *    `--config-base64` on the `wxc-exec.exe` command line, which process auditing records (B1 slice 19). So it is an
+ *    allowlist of system paths: never `process.env`, never a denylist of it.
+ *  · Without LOCALAPPDATA every sandboxed process dies before it starts: `CreateProcessW(PROC_THREAD_ATTRIBUTE_SECURITY_
+ *    ENVIRONMENT) failed: WIN32_ERROR(203)` (microsoft/mxc#1130, closed 2026-09-14, "SystemRoot + LOCALAPPDATA").
+ *    Without SystemRoot node, npm and powershell fail; without PATH npm, git, powershell and pwsh are not found
+ *    (microsoft/mxc#1102: no PATH floor). Without APPDATA npm's prefix becomes `<cwd>\${APPDATA}\npm`; without
+ *    USERPROFILE git finds no global configuration. windir, SystemDrive, TEMP, TMP, PATHEXT and ComSpec are not needed
+ *    by those six workloads but are the gate E1 floor (Gemini CLI's win32 list; the container overrides TEMP with its
+ *    own AppContainer folder). NUMBER_OF_PROCESSORS and PROCESSOR_ARCHITECTURE stay from B1 slice 19.
+ *  · A command given NO environment gets the backend default, which is the user's profile block: 56 variables here,
+ *    three of them secret-shaped names from the persistent user environment. So a command always gets this list.
+ * ⛔ A name is added only when a measurement in the real container shows a workload needs it, and only if neither its
+ *   name nor its value can hold a credential.
+ */
+export const MXC_CHILD_ENVIRONMENT_NAMES = Object.freeze(['SystemRoot', 'windir', 'SystemDrive', 'LOCALAPPDATA', 'APPDATA', 'USERPROFILE', 'TEMP', 'TMP', 'PATH', 'PATHEXT', 'ComSpec', 'NUMBER_OF_PROCESSORS', 'PROCESSOR_ARCHITECTURE']);
+function lookup(source, name) {
+    if (source[name] !== undefined)
+        return source[name];
+    const upper = name.toUpperCase();
+    for (const [key, value] of Object.entries(source))
+        if (key.toUpperCase() === upper && value !== undefined)
+            return value;
+    return undefined;
+}
+function systemRootOf(source) { return lookup(source, 'SystemRoot') ?? lookup(source, 'windir') ?? 'C:\\Windows'; }
+/**
+ * The host PATH with the Windows system folders first. ⛔ A relative entry (`.`, `bin`) resolves against whatever the
+ * working directory is — a planting vector — and is dropped, as are empty entries and duplicates (case-insensitive,
+ * trailing separator ignored). Git's `usr/bin` before System32 is what made the SDK's `whoami` print GNU usage.
+ */
+export function systemFirstPath(source = process.env) {
+    const root = systemRootOf(source).replace(/[\\/]+$/u, '');
+    const front = [`${root}\\System32`, root, `${root}\\System32\\Wbem`, `${root}\\System32\\WindowsPowerShell\\v1.0\\`];
+    const seen = new Set();
+    return [...front, ...String(lookup(source, 'PATH') ?? '').split(';')].filter(entry => {
+        if (!entry || !/^(?:[A-Za-z]:[\\/]|\\\\)/u.test(entry))
+            return false;
+        const key = entry.replace(/[\\/]+$/u, '').toLowerCase();
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    }).join(';');
+}
+/** Only the allowlisted names this host defines, PATH always (System32 at least). A fresh object, never `process.env`. */
+export function mxcChildEnvironment(source = process.env) {
+    const environment = {};
+    for (const name of MXC_CHILD_ENVIRONMENT_NAMES) {
+        if (name === 'PATH') {
+            environment.PATH = systemFirstPath(source);
+            continue;
+        }
+        const value = lookup(source, name);
+        if (value !== undefined)
+            environment[name] = value;
+    }
+    return environment;
+}
+/*
+ * R0 lane S, decision 4 (owner, 2026-09-23; gate E2): Win32k is allowed. `allowWindows:false` becomes
+ * `DisallowWin32kSystemCalls`, and measured here node.exe and powershell.exe then exit 0xC0000142
+ * (STATUS_DLL_INIT_FAILED) before their first instruction; Codex keeps `ui.disable:false` because "PowerShell needs
+ * Win32k and desktop handles during DLL startup" (codex-rs/mxc-sandbox policy.rs, 2026-09-22). Clipboard and input
+ * injection stay blocked; filesystem and network grants are unchanged.
+ */
+export const MXC_UI_POLICY = Object.freeze({ allowWindows: true, clipboard: 'none', allowInputInjection: false });
+/*
+ * ⭐⭐ R0 lane S — S4, the SDK's import-time `whoami` (review E-08, gate E5).
+ * `@microsoft/mxc-sdk@0.8.0` `dist/diagnostic.js` runs `execSync('whoami /user /fo csv /nh')` WHEN THE MODULE LOADS,
+ * through cmd, the inherited PATH and the current directory, with stderr inherited. Measured: with Git's `usr/bin`
+ * before System32 every load printed `whoami: extra operand '/user'` on TALOS's stderr; with a `whoami.bat` in the
+ * working directory and NoDefaultCurrentDirectoryInExePath unset (the Windows default) that batch file RAN on the
+ * host. So the SDK is loaded once per process, only when a sandbox is asked for, with PATH System32-first and the
+ * current-directory search off for the length of the import; both are put back exactly afterwards, and only if nobody
+ * else changed them meanwhile.
+ */
+let sdkModule;
+async function importSdkWithSystemSearch() {
+    if (process.platform !== 'win32')
+        return import('@microsoft/mxc-sdk');
+    const FLAG = 'NoDefaultCurrentDirectoryInExePath';
+    const previousPath = process.env.PATH;
+    const previousFlag = process.env[FLAG];
+    const guardedPath = systemFirstPath(process.env);
+    process.env.PATH = guardedPath;
+    process.env[FLAG] = '1';
+    try {
+        return await import('@microsoft/mxc-sdk');
+    }
+    finally {
+        if (process.env.PATH === guardedPath) {
+            if (previousPath === undefined)
+                delete process.env.PATH;
+            else
+                process.env.PATH = previousPath;
+        }
+        if (process.env[FLAG] === '1') {
+            if (previousFlag === undefined)
+                delete process.env[FLAG];
+            else
+                process.env[FLAG] = previousFlag;
+        }
+    }
+}
+export async function loadMxcSdk() {
+    const sdk = await (sdkModule ??= importSdkWithSystemSearch().catch(error => { sdkModule = undefined; throw error; }));
+    return {
+        getPlatformSupport: () => sdk.getPlatformSupport(),
+        createConfigFromPolicy: (policy, containment, name) => sdk.createConfigFromPolicy(policy, containment, name),
+        spawnSandboxFromConfig: (config, options, workingDirectory, environment) => sdk.spawnSandboxFromConfig(config, options, workingDirectory, environment)
+    };
+}
+function quoteWindowsArgument(value) {
+    if (value.length > 0 && !/[\s"]/u.test(value))
+        return value;
+    let quoted = '"';
+    let slashes = 0;
+    for (const character of value) {
+        if (character === '\\') {
+            slashes++;
+            continue;
+        }
+        if (character === '"') {
+            quoted += '\\'.repeat(slashes * 2 + 1) + '"';
+            slashes = 0;
+            continue;
+        }
+        quoted += '\\'.repeat(slashes) + character;
+        slashes = 0;
+    }
+    return quoted + '\\'.repeat(slashes * 2) + '"';
+}
+/** Shared so the probe's sandboxed executor is quoted by the same rule as a brokered command. */
+export function windowsCommandLine(parts) { return parts.map(quoteWindowsArgument).join(' '); }
+/*
+ * ⛔⛔ R0 lane S — cmd.exe does NOT parse MSVCRT quoting. Measured 2026-09-23 on the host, no sandbox involved:
+ *   `windowsCommandLine(['/d','/s','/c','node -e "console.log(1)"'])` gives `/d /s /c "node -e \"console.log(1)\""`,
+ *   cmd strips the outer quotes and hands node `\"console.log(1)\"` — node evaluates a string literal, prints nothing,
+ *   exits 0. Every brokered command with a double quote in it (a `git commit -m "…"`) ran CHANGED. Node's own
+ *   `spawn(cmd,{shell:true})` on Windows builds `<ComSpec> /d /s /c "<command>"` verbatim (lib/child_process.js),
+ *   and with `/s` cmd removes exactly the first and the last quote (`cmd /?`). That is the form used here for the
+ *   brokered shell invocation, and only for it: the request keeps its argv shape.
+ */
+function isCmdInvocation(input) {
+    const { executable, args } = input.request;
+    return /(?:^|[\\/])cmd(?:\.exe)?$/iu.test(executable) && args.length === 4 && args[0] === '/d' && args[1] === '/s' && args[2] === '/c';
+}
+function commandLine(input) {
+    if (isCmdInvocation(input))
+        return `${windowsCommandLine([input.request.executable])} /d /s /c "${input.request.args[3]}"`;
+    return windowsCommandLine([input.request.executable, ...input.request.args]);
+}
+function policyFor(input) {
+    const policy = input.windowsSandboxPolicy;
+    if (!policy)
+        throw new Error('MXC_WINDOWS_SANDBOX_POLICY_REQUIRED');
+    const networkDefault = input.request.network === 'internet-client' ? 'allow' : 'deny';
+    return {
+        version: '0.8.0-alpha',
+        filesystem: { readwritePaths: policy.fsReadWrite, readonlyPaths: policy.fsReadOnly, clearPolicyOnExit: true },
+        network: { egress: { default: networkDefault }, ingress: { default: 'deny', hostLoopback: 'deny' } },
+        ui: { ...MXC_UI_POLICY },
+        ...(input.request.timeoutMs === undefined ? {} : { timeoutMs: input.request.timeoutMs })
+    };
+}
+function collectChild(child, input, maxOutputBytes, applied) {
+    return new Promise((resolve, reject) => {
+        let stdout = Buffer.alloc(0);
+        let stderr = Buffer.alloc(0);
+        let outputBytes = 0;
+        let settled = false;
+        const signal = input.request.signal;
+        const cleanup = () => {
+            if (timer)
+                clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+            child.stdout?.off('data', onStdout);
+            child.stderr?.off('data', onStderr);
+            child.off('error', onError);
+            child.off('close', onClose);
+        };
+        const finishReject = (error) => { if (settled)
+            return; settled = true; cleanup(); try {
+            child.kill();
+        }
+        catch { } reject(error); };
+        const append = (target, chunk) => {
+            const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+            if (outputBytes + buffer.length > maxOutputBytes) {
+                finishReject(new Error('MXC_OUTPUT_LIMIT_EXCEEDED'));
+                return;
+            }
+            outputBytes += buffer.length;
+            if (target === 'stdout')
+                stdout = Buffer.concat([stdout, buffer]);
+            else
+                stderr = Buffer.concat([stderr, buffer]);
+        };
+        const onStdout = (chunk) => append('stdout', chunk);
+        const onStderr = (chunk) => append('stderr', chunk);
+        const onError = (cause) => finishReject(cause);
+        const onClose = (code) => { if (settled)
+            return; settled = true; cleanup(); resolve({ exitCode: code ?? -1, stdout: stdout.toString('utf8'), stderr: stderr.toString('utf8'), applied }); };
+        const onAbort = () => finishReject(new Error('MXC_EXECUTION_CANCELLED'));
+        const timer = input.request.timeoutMs === undefined ? undefined : setTimeout(() => finishReject(new Error('MXC_EXECUTION_TIMEOUT')), input.request.timeoutMs);
+        timer?.unref();
+        child.stdout?.on('data', onStdout);
+        child.stderr?.on('data', onStderr);
+        child.once('error', onError);
+        child.once('close', onClose);
+        if (signal?.aborted)
+            onAbort();
+        else
+            signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+export function createMxcExecutionBackend(options = {}) {
+    const platform = options.platform ?? process.platform;
+    const maxOutputBytes = options.maxOutputBytes ?? 8 * 1024 * 1024;
+    if (!Number.isSafeInteger(maxOutputBytes) || maxOutputBytes < 1)
+        throw new Error('MXC_OUTPUT_LIMIT_INVALID');
+    let sdkPromise;
+    // inspect() runs for both available() and execute(); without this memo every command would spawn a probe tree.
+    let probePromise;
+    const getSdk = () => sdkPromise ??= options.sdk ? Promise.resolve(options.sdk) : (options.sdkLoader ?? loadMxcSdk)();
+    const inspect = async () => {
+        if (platform !== 'win32')
+            return { available: false, reason: 'MXC BaseContainer enforcement requires Windows' };
+        let sdk;
+        try {
+            sdk = await getSdk();
+        }
+        catch (cause) {
+            return { available: false, reason: `MXC SDK failed to load: ${cause instanceof Error ? cause.message : String(cause)}` };
+        }
+        const evidence = sdk.getPlatformSupport();
+        if (!evidence.isSupported)
+            return { available: false, reason: evidence.reason ?? 'MXC is unsupported on this host' };
+        if (!evidence.availableMethods.includes('processcontainer'))
+            return { available: false, reason: 'MXC ProcessContainer is unavailable' };
+        if (evidence.isolationTier !== 'base-container')
+            return { available: false, reason: `MXC isolation tier ${evidence.isolationTier ?? 'unknown'} does not prove Experimental_CreateProcessInSandbox` };
+        if (!options.verifyProcessTreeKillOnClose)
+            return { available: false, reason: 'MXC process-tree kill-on-close has not been verified on this host' };
+        const verify = options.verifyProcessTreeKillOnClose;
+        let probe;
+        try {
+            probe = await (probePromise ??= Promise.resolve(verify(evidence)));
+        }
+        catch (cause) {
+            return { available: false, reason: `MXC process-tree probe failed: ${cause instanceof Error ? cause.message : String(cause)}` };
+        }
+        if (typeof probe !== 'object' || probe === null || typeof probe.verified !== 'boolean' || typeof probe.evidence !== 'object' || probe.evidence === null)
+            return { available: false, reason: 'MXC process-tree probe returned an unrecognized result: the seam is a measurement, not a boolean' };
+        if (!probe.verified)
+            return { available: false, reason: probe.reason ?? 'MXC process-tree kill-on-close probe failed' };
+        return { available: true, probe };
+    };
+    return {
+        name: 'microsoft-mxc-0.8.0', level: 'windows-sandbox', available: inspect,
+        async execute(input) {
+            const availability = await inspect();
+            if (!availability.available)
+                throw Object.assign(new Error(availability.reason), { code: 'MXC_BACKEND_UNAVAILABLE' }); /* R2 (gate E6): code on error.code, printed once */
+            const sdk = await getSdk();
+            const sandboxPolicy = policyFor(input);
+            const identity = input.windowsSandboxPolicy?.identity;
+            const config = sdk.createConfigFromPolicy(sandboxPolicy, 'process', identity);
+            config.process = { ...(config.process ?? { commandLine: '' }), commandLine: commandLine(input), cwd: input.request.cwd };
+            /* ⛔ R0 lane S: never the backend default (the user profile block, secret-shaped names included, measured): the allowlist. */
+            const child = sdk.spawnSandboxFromConfig(config, { usePty: false, experimental: true }, input.request.cwd, input.request.environment ?? mxcChildEnvironment());
+            const applied = { enforcement: 'windows-sandbox', appContainer: true, filesystem: 'bfs', network: input.request.network, processTree: 'job-object-kill-on-close', processTreeEvidence: availability.probe.evidence, sandboxSpecVersion: '0.1.0' };
+            return collectChild(child, input, maxOutputBytes, applied);
+        }
+    };
+}

package/dist/security/permission-engine.js

@@ -0,0 +1,138 @@
+import { randomUUID } from 'node:crypto';
+import path from 'node:path';
+import { compileRuleSet, evaluateRules } from "./evaluate.js";
+import { ruleToPersist, unreadableRulesError } from "./persist.js";
+import { isReadOnlyShellCommand, parseRule, tokenizeCommand } from "./rule-parser.js";
+const FS_EDIT_OPTIONS = {
+    mkdir: new Set(['-p', '-v']), touch: new Set(['-a', '-m', '-c']), rm: new Set(['-r', '-R', '-f', '-rf', '-fr', '-d']), rmdir: new Set(['-p']), cp: new Set(['-r', '-R', '-f', '-n', '-p']), mv: new Set(['-f', '-n']),
+};
+function insideProject(root, candidate) { const rel = path.relative(path.resolve(root), path.resolve(candidate)); return rel === '' || (!rel.startsWith(`..${path.sep}`) && rel !== '..' && !path.isAbsolute(rel)); }
+export function acceptEditsFilesystemCommand(command, projectRoot) {
+    const tokens = tokenizeCommand(command);
+    if (tokens.length < 2)
+        return false;
+    const head = tokens[0];
+    const allowed = FS_EDIT_OPTIONS[head];
+    if (!allowed)
+        return false;
+    const operands = [];
+    let options = true;
+    for (const token of tokens.slice(1)) {
+        if (options && token === '--') {
+            options = false;
+            continue;
+        }
+        if (options && token.startsWith('-')) {
+            if (!allowed.has(token))
+                return false;
+            continue;
+        }
+        options = false;
+        operands.push(token);
+    }
+    if ((head === 'cp' || head === 'mv') ? operands.length < 2 : operands.length < 1)
+        return false;
+    for (const operand of operands) {
+        const abs = path.isAbsolute(operand) ? path.resolve(operand) : path.resolve(projectRoot, operand);
+        if (!insideProject(projectRoot, abs) || abs === path.resolve(projectRoot))
+            return false;
+        const rel = path.relative(projectRoot, abs).split(path.sep);
+        if (rel[0] === '.git' || rel[0] === '.talos-cli')
+            return false;
+    }
+    return true;
+}
+const PROTECTED_PROJECT_ROOTS = new Set(['.git', '.talos-cli', '.github', '.vscode', '.idea', '.husky']);
+function protectedProjectMutation(action, root) {
+    if (!['Write', 'Edit'].includes(action.tool) || !action.resource)
+        return false;
+    const abs = path.isAbsolute(action.resource) ? path.resolve(action.resource) : path.resolve(root, action.resource);
+    if (!insideProject(root, abs))
+        return false;
+    const first = path.relative(path.resolve(root), abs).split(path.sep)[0] ?? '';
+    return PROTECTED_PROJECT_ROOTS.has(first);
+}
+function outsideWrite(action, root) { if (!['Write', 'Edit'].includes(action.tool) || !action.resource)
+    return false; const rel = path.relative(path.resolve(root), path.resolve(root, action.resource)); return rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel); }
+export function createPermissionEngine({ projectRoot, rules, mode, classifier, persistRule }) {
+    if (mode === 'auto' && !classifier)
+        throw new Error('PERMISSION_AUTO_UNAVAILABLE');
+    // B1 slice 21. ⛔ Fail closed and by name: one unreadable entry, in any list, and there is no engine.
+    const { rules: compiled, invalid } = compileRuleSet(rules);
+    if (invalid.length)
+        throw unreadableRulesError(projectRoot, invalid);
+    const pending = new Map();
+    const grants = [];
+    return { async decide(action, context) {
+            if (outsideWrite(action, projectRoot))
+                return { kind: 'deny', code: 'PATH_NOT_ALLOWED', message: 'Operation targets a path outside the project' };
+            let base = evaluateRules(compiled, action, { projectRoot });
+            if (base.effect === 'deny')
+                return { kind: 'deny', code: 'PERMISSION_DENIED', message: base.reason };
+            const m = context.mode;
+            if (m === 'plan' && (['Write', 'Edit', 'Hook', 'Plugin'].includes(action.tool) || (action.tool === 'Bash' && !isReadOnlyShellCommand(action.command ?? ''))))
+                return { kind: 'deny', code: 'PLAN_MODE_READ_ONLY', message: 'Plan mode permits only read-only operations' };
+            if (grants.some(g => JSON.stringify(g) === JSON.stringify(action)))
+                return { kind: 'allow', source: 'session' };
+            if (base.effect === 'allow')
+                return { kind: 'allow', source: base.rule ?? 'rule' };
+            if (m === 'acceptEdits' && base.effect === 'ask' && !base.rule && !protectedProjectMutation(action, projectRoot) && (['Write', 'Edit'].includes(action.tool) || (action.tool === 'Bash' && acceptEditsFilesystemCommand(action.command ?? '', projectRoot))))
+                return { kind: 'allow', source: 'acceptEdits' };
+            if (m === 'bypassPermissions' && base.effect === 'ask' && !base.rule)
+                return { kind: 'allow', source: 'bypassPermissions' };
+            if (m === 'auto' && base.effect === 'ask' && !base.rule && !protectedProjectMutation(action, projectRoot)) {
+                if (!classifier)
+                    throw new Error('PERMISSION_AUTO_UNAVAILABLE');
+                const c = await classifier({ action, projectRoot });
+                if (c === 'allow')
+                    return { kind: 'allow', source: 'auto' };
+                if (c === 'deny')
+                    return { kind: 'deny', code: 'PERMISSION_AUTO_DENIED', message: 'Automatic classifier denied operation' };
+                base = { effect: 'ask', reason: 'automatic classifier requested confirmation' };
+            }
+            if (m === 'dontAsk' || !context.interactive)
+                return { kind: 'deny', code: 'PERMISSION_REQUIRED', message: 'Operation requires approval in non-interactive mode' };
+            const requestId = randomUUID();
+            pending.set(requestId, action);
+            return { kind: 'ask', requestId, action, reason: base.reason, ...(base.rule ? { rule: base.rule } : {}) };
+        }, async resolve(requestId, decision) {
+            const action = pending.get(requestId);
+            if (!action)
+                throw new Error('APPROVAL_NOT_PENDING');
+            pending.delete(requestId);
+            if (decision === 'allow-session')
+                grants.push(action);
+            if ((decision === 'allow-always' || decision === 'deny-always') && persistRule) {
+                const effect = decision === 'allow-always' ? 'allow' : 'deny';
+                // B1 slice 21. A rule the writing path refuses — a compound command, a line break, a rule that would
+                // not match its own request, an allow that narrows nothing — is known before the key is pressed (the
+                // full review previews the same refusal). Nothing is written, and the approval is still answered:
+                // measured at 805c89a0, the refusal threw out of resolve and the runtime's request was never answered.
+                // "Allow always" then answers for this session only, for the identical request, which is what Hermes
+                // does when "always" cannot be honoured; "deny always" denies this request and asks again next time.
+                let rule;
+                try {
+                    rule = parseRule(ruleToPersist(effect, action, projectRoot), effect);
+                }
+                catch {
+                    if (effect === 'allow')
+                        grants.push(action);
+                    return;
+                }
+                await persistRule(effect, action);
+                // ⛔ The rule is obeyed from now on, not from the next start: before this, the engine compiled its rules
+                // once and "allow always" asked again for the identical command in the same session.
+                compiled[effect].push(rule);
+                // ⛔ And the session's rule set shows it. The approval dialog explains each request from the rule set
+                // this engine was built from (`rules`, the same object); without the rule there, measured: after
+                // "allow always" on `npm test`, `npm test && npm publish` asked for segment 2 while the account
+                // said segment 1, and the dialog withheld every row as a "possible race". A frozen set is left alone.
+                try {
+                    const list = rules[effect];
+                    if (Array.isArray(list) && !list.includes(rule.raw))
+                        list.push(rule.raw);
+                }
+                catch { }
+            }
+        } };
+}

package/dist/security/permission-explanation.js

@@ -0,0 +1,54 @@
+import { compileRules, evaluateRules } from "./evaluate.js";
+import { segmentShellCommand } from "./shell-segmentation.js";
+function explanationForDecision(decision, segments, decisiveSegment) {
+    return { effect: decision.effect, reason: decision.reason, ...(decision.rule ? { rule: decision.rule } : {}), precedence: 'deny > ask > allow', decisiveSegment, segments };
+}
+export function explainPermission(rules, action, { projectRoot }) {
+    if (action.tool !== 'Bash')
+        return explanationForDecision(evaluateRules(rules, action, { projectRoot }), [], null);
+    let commandSegments;
+    try {
+        commandSegments = segmentShellCommand(action.command ?? '');
+    }
+    catch {
+        return explanationForDecision({ effect: 'deny', reason: 'unsupported shell composition' }, [], null);
+    }
+    const segments = commandSegments.map(segment => {
+        const decision = evaluateRules(rules, { ...action, command: segment.command }, { projectRoot });
+        return { command: segment.command, operatorBefore: segment.operatorBefore, effect: decision.effect, reason: decision.reason, ...(decision.rule ? { rule: decision.rule } : {}) };
+    });
+    for (const effect of ['deny', 'ask', 'allow']) {
+        const decisiveSegment = segments.findIndex(segment => segment.effect === effect);
+        if (decisiveSegment >= 0) {
+            const decisive = segments[decisiveSegment];
+            return explanationForDecision({ effect: decisive.effect, reason: decisive.reason, ...(decisive.rule ? { rule: decisive.rule } : {}) }, segments, decisiveSegment);
+        }
+    }
+    return explanationForDecision({ effect: 'deny', reason: 'unsupported shell composition' }, segments, null);
+}
+export function simulatePermission({ rules, action, projectRoot }) {
+    const explanation = explainPermission(compileRules(rules), action, { projectRoot });
+    return { effect: explanation.effect, requiresApproval: explanation.effect === 'ask', explanation };
+}
+export function formatPermissionSimulation(simulation) {
+    const explanation = simulation.explanation;
+    const lines = [
+        `Permission dry-run: ${simulation.effect}`,
+        `Precedence: ${explanation.precedence}`,
+    ];
+    if (explanation.decisiveSegment !== null) {
+        const segment = explanation.segments[explanation.decisiveSegment];
+        lines.push(`Decisive: segment ${explanation.decisiveSegment + 1}${segment ? ` · ${segment.command}` : ''} · ${explanation.reason}`);
+    }
+    else
+        lines.push(`Decisive: ${explanation.reason}`);
+    if (explanation.rule)
+        lines.push(`Rule: ${explanation.rule}`);
+    if (explanation.segments.length) {
+        lines.push('Segments:');
+        explanation.segments.forEach((segment, index) => {
+            lines.push(`  ${index + 1}. ${segment.effect} · ${segment.command}${segment.rule ? ` · ${segment.rule}` : ''} · ${segment.reason}`);
+        });
+    }
+    return lines.join('\n') + '\n';
+}

package/dist/security/persist.js

@@ -0,0 +1,179 @@
+import fs from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { projectId, resolveCliPaths } from "../paths.js";
+import { readConfigScope, writeConfigScope } from "../config/load.js";
+import { patternNamesOnlyAVerb, ruleMatchesAction } from "./evaluate.js";
+import { parseRule, ruleProblem } from "./rule-parser.js";
+import { segmentShellCommand } from "./shell-segmentation.js";
+function normalizeResource(resource, root) { const abs = isAbsolute(resource) ? resolve(resource) : resolve(root, resource); const rel = relative(resolve(root), abs); if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel))
+    throw new Error('PATH_NOT_ALLOWED'); return rel.split(sep).join('/'); }
+function spelledRule(a, root) { if (a.tool === 'Bash')
+    return `Bash(${a.command ?? ''})`; if (['Read', 'Write', 'Edit'].includes(a.tool))
+    return `${a.tool}(${normalizeResource(a.resource ?? '', root)})`; if (a.tool === 'Mcp')
+    return `Mcp(${a.serverId ?? ''}:${a.operation ?? '*'})`; if (a.tool === 'TalosService')
+    return `TalosService(${a.resource ?? ''}:${a.operation ?? '*'})`; return `${a.tool}(${a.operation ?? a.resource ?? '*'})`; }
+/*
+ * B1 slice 21 — A RULE IS WRITTEN ONLY IF IT CAN BE READ BACK AND DECIDES THE REQUEST IT WAS WRITTEN FOR.
+ *
+ * Recorded at e5d197e7 and re-measured at 805c89a0: "allow always" on `ls<LF>rm -rf /` wrote `Bash(ls<LF>rm -rf /)`, which the
+ * parser cannot read, and the next start threw; on `git status && npm test; npm publish` it wrote the
+ * whole command, which matches none of the segments the engine judges one at a time.
+ *
+ * ⛔ A compound command is not remembered at all. Measured in the two competitors before deciding:
+ * - Claude Code 2.1.274 (claude.exe) offers one rule per subcommand that still asks, capped at five, each
+ *   the exact subcommand or a prefix ending in ` *` (`git status *`), and labels the row "don't ask again
+ *   for A and B commands" from exactly the rules it writes: shown, but a prefix is broader than the ask.
+ * - Hermes Agent (0.20.0 and main f5d19261) persists the dangerous-pattern CATEGORY ("recursive
+ *   delete"), and its command-text allowlist refuses any command with a shell operator; when "always"
+ *   cannot be honoured it answers "session" instead.
+ * A rule per segment here would allow `rm -rf build` inside any other command, and the approval dialog
+ * previews exactly one rule, so it could not show what was written. Declining is the only form that
+ * neither widens nor hides, and the engine then answers for this session only, as Hermes does.
+ */
+const ALWAYS_ANSWERS = '"allow always" answers for this session only';
+/* R2 (gate E6): the code travels on `error.code`; the message is the English sentence alone, so the failure line prints the
+   code once (review D-06). `codeForError` read the code from a `CODE: ` prefix before; the property keeps it identical. */
+function ruleError(code, message) { return Object.assign(new Error(message), { code }); }
+export function permissionActionToRule(a, root) {
+    if (a.tool === 'Bash') {
+        let segments;
+        try {
+            segments = segmentShellCommand(a.command ?? '');
+        }
+        catch {
+            throw ruleError('RULE_COMMAND_UNSUPPORTED', `this command cannot be split into the segments the engine judges, so no rule is written for it; ${ALWAYS_ANSWERS}`);
+        }
+        if (segments.length > 1)
+            throw ruleError('RULE_COMPOUND_COMMAND', `a command of ${segments.length} segments is not remembered, because a rule for the whole command matches none of its segments and a rule for each segment would allow it inside any other command; ${ALWAYS_ANSWERS}`);
+    }
+    const rule = spelledRule(a, root);
+    let compiled;
+    try {
+        compiled = parseRule(rule, 'allow');
+    }
+    catch {
+        throw ruleError('RULE_UNREADABLE', `the rule for this request ${ruleProblem(rule) ?? 'cannot be parsed'}, so it could not be read back and is not written; ${ALWAYS_ANSWERS}`);
+    }
+    // A verb-only pattern (`cat:*`, `*`) is slice 11's case and keeps slice 11's answer: an allow is refused as
+    // RULE_NOT_NARROWED by the writer, and a deny that covers the verb is the safe direction and is written.
+    if (!(a.tool === 'Bash' && patternNamesOnlyAVerb(compiled.pattern)) && !ruleMatchesAction(compiled, a, root))
+        throw ruleError('RULE_MATCHES_NOTHING', `the rule for this request would not match the request itself, so it is not written; ${ALWAYS_ANSWERS}`);
+    return rule;
+}
+// B1 slice 11. Gemini CLI refuses to *construct* a persistent allow rule for its shell, read, write
+// and search tools unless the rule carries an argument-narrowing pattern — a property of the
+// writing interface, so it binds a hand-written administrator rule too and not only the
+// "don't ask again" button. Measured on this host before the change: this path could produce
+// `Bash(*)`, `Bash(**)` and `Bash(cat:*)`, because the rule is the command text and a command whose
+// own text is `*` or ends in `:*` becomes exactly the blanket form. A deny that covers everything
+// is the safe direction and is still written; only an `allow` that narrows nothing is refused.
+function bashRuleNarrowsNothing(rule) { const m = /^Bash\((.*)\)$/u.exec(rule); if (!m)
+    return false; const pattern = m[1]; return pattern === '' || pattern === '*' || pattern === '**' || /:\*$/u.test(pattern); }
+// B1 slice 21. The rule "always" would write, or the refusal that writes nothing. One function, so the engine answers
+// exactly the refusals the writer makes: before this slice an allow that narrows nothing threw out of the
+// engine's resolve, and the runtime's approval was never answered.
+export function ruleToPersist(effect, action, root) {
+    const rule = permissionActionToRule(action, root);
+    if (effect === 'allow' && bashRuleNarrowsNothing(rule))
+        throw new Error(`RULE_NOT_NARROWED:${rule}`);
+    return rule;
+}
+// ⛔ B1 slice 21. Only the list being changed is written. Measured at 805c89a0: this function wrote all
+// three lists into the project-user file, and a list in a later configuration file REPLACES the list of
+// an earlier one, so one "allow always" on `npm test` wrote `deny: []` and switched off the deny rules of
+// the project's own `.talos-cli/config.json` (`curl evil.example` went from deny to ask).
+export async function persistPermissionRule({ paths, projectRoot, effect, action }) {
+    const rule = ruleToPersist(effect, action, projectRoot);
+    const current = await readConfigScope({ paths, projectRoot, scope: 'project-user' });
+    const list = current.permissions?.[effect] ?? [];
+    if (!Array.isArray(list))
+        throw ruleError('RULE_STORE_INVALID', `"permissions.${effect}" in the project-user configuration is not a list`);
+    // The file keeps whatever other lists it already had; a partial `permissions` object is what the loader
+    // merges over the lower scopes, so the type's three required lists do not describe a patch.
+    await writeConfigScope({ paths, projectRoot, scope: 'project-user', patch: { permissions: { [effect]: [...new Set([...list, rule])] } } });
+}
+/*
+ * B1 slice 21 — A RULE THAT CANNOT BE READ STOPS THE START, BY NAME.
+ *
+ * Measured at 805c89a0, starting the interactive CLI with that rule on disk: Ink printed
+ * `ERROR PERMISSION_RULE_INVALID:Bash(ls` with the rule's own line break splitting the line, then a
+ * stack through parseRule, compileRules, createPermissionEngine and the React reconciler — and nothing
+ * said which file held the rule or what to do about it.
+ * ⛔ Skipping the rule is not the cure: a skipped deny rule silently allows what it denied (Claude Code
+ * 2.1.274 does skip an invalid rule with a warning, deny rules included). The engine refuses to exist.
+ */
+export class PermissionRulesUnreadableError extends Error {
+    code = 'PERMISSION_RULE_INVALID';
+    constructor(message) {
+        super(message);
+        this.name = 'PermissionRulesUnreadableError';
+        // A configuration error is described completely by its message. Its frames point at this constructor,
+        // not at anything a person can fix, and the interactive screen prints every frame it is given.
+        this.stack = `${this.name}: ${message}`;
+    }
+}
+// Highest precedence first: the loader overlays user, then project, then project-user, and a list in a
+// later file replaces the list of an earlier one. So the first file that defines the list is the file the
+// engine's list came from. The layout mirrors `files()` in config/load.ts; a test writes through the real
+// writer into each scope and asserts this names that exact file, so a drift turns red.
+function permissionConfigFiles(projectRoot) {
+    let paths = null;
+    try {
+        paths = resolveCliPaths(process.env, process.platform, homedir());
+    }
+    catch {
+        paths = null;
+    }
+    return [...(paths ? [join(paths.projectOverridesRoot, projectId(projectRoot), 'config.json')] : []), join(projectRoot, '.talos-cli', 'config.json'), ...(paths ? [join(paths.configRoot, 'config.json')] : [])];
+}
+// `undefined` when the file is absent, unreadable or has no `permissions`; `null` when `permissions` is there
+// but is not an object of lists, which replaces every lower file's lists at once.
+function storedPermissions(file) {
+    let value;
+    try {
+        value = JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+    if (!value || typeof value !== 'object' || !Object.hasOwn(value, 'permissions'))
+        return undefined;
+    const permissions = value.permissions;
+    return permissions && typeof permissions === 'object' && !Array.isArray(permissions) ? permissions : null;
+}
+function locate(projectRoot, invalid) {
+    const files = permissionConfigFiles(projectRoot);
+    for (const file of files) {
+        const permissions = storedPermissions(file);
+        if (permissions === null)
+            return invalid.index === null ? { file, whole: true } : { searched: files };
+        if (!permissions || !Object.hasOwn(permissions, invalid.effect))
+            continue;
+        const list = permissions[invalid.effect];
+        const found = invalid.index === null ? JSON.stringify(list) === JSON.stringify(invalid.value) : Array.isArray(list) && JSON.stringify(list[invalid.index]) === JSON.stringify(invalid.value);
+        return found ? { file } : { searched: files };
+    }
+    return { searched: files };
+}
+// JSON spells the rule the way it appears in the file (a line break as the two characters `\n`), and
+// what JSON leaves raw — DEL, C1, line and paragraph separators, bidi controls, invisible characters —
+// becomes a visible `\uXXXX`, so nothing in the message can move a terminal's cursor or hide text.
+const BACKSLASH = String.fromCharCode(92);
+const TERMINAL_UNSAFE = /[\x00-\x1f\x7f-\x9f\p{Zl}\p{Zp}\p{Bidi_Control}\p{Default_Ignorable_Code_Point}]/gu;
+function inert(text) { return text.replace(TERMINAL_UNSAFE, character => { const code = character.codePointAt(0); return code > 0xffff ? `${BACKSLASH}u{${code.toString(16)}}` : `${BACKSLASH}u${code.toString(16).padStart(4, '0')}`; }); }
+function spelled(value) { return JSON.stringify(value) ?? String(value); }
+export function unreadableRulesError(projectRoot, invalid) {
+    const first = invalid[0];
+    const where = locate(projectRoot, first);
+    const found = 'file' in where;
+    const whole = found && where.whole === true;
+    const list = whole ? '"permissions"' : `"permissions.${first.effect}"`;
+    const problem = whole ? 'is not an object holding the allow, ask and deny lists' : first.problem;
+    const subject = first.index === null ? list : `the ${first.effect} rule ${spelled(first.value)} in ${list}`;
+    const place = found ? ` of ${where.file}` : '';
+    const origin = found ? '' : ` It is not in ${where.searched.join(', ')}: these rules were handed to the engine directly.`;
+    const fix = !found ? 'Remove it where these rules come from, then start TALOS again.' : whole ? `Make ${list} in that file an object such as {"allow":[],"ask":[],"deny":[]}, then start TALOS again.` : first.index === null ? `Make ${list} in that file a list of rules, for example [], then start TALOS again.` : `Delete that entry from ${list} in that file, then start TALOS again.`;
+    const more = invalid.length > 1 ? ` ${invalid.length - 1} more permission ${invalid.length === 2 ? 'entry is' : 'entries are'} unreadable too.` : '';
+    return new PermissionRulesUnreadableError(inert(`Permission rules cannot be loaded: ${subject}${place} ${problem}.${origin} No rule is skipped, because a skipped deny rule would allow what it denies. ${fix}${more}`));
+}