@machina.ai/cell-cli-core 1.0.13-rc9 → 1.0.21-rc1

package/dist/src/utils/secure-browser-launcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secure-browser-launcher.js","sourceRoot":"","sources":["../../../src/utils/secure-browser-launcher.ts"],"names":[],"mappings":"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"}

package/dist/src/utils/secure-browser-launcher.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export {};

package/dist/src/utils/secure-browser-launcher.test.js

@@ -0,0 +1,149 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { openBrowserSecurely } from './secure-browser-launcher.js';
+// Create mock function using vi.hoisted
+const mockExecFile = vi.hoisted(() => vi.fn());
+// Mock modules
+vi.mock('node:child_process');
+vi.mock('node:util', () => ({
+    promisify: () => mockExecFile,
+}));
+describe('secure-browser-launcher', () => {
+    let originalPlatform;
+    beforeEach(() => {
+        vi.clearAllMocks();
+        mockExecFile.mockResolvedValue({ stdout: '', stderr: '' });
+        originalPlatform = Object.getOwnPropertyDescriptor(process, 'platform');
+    });
+    afterEach(() => {
+        if (originalPlatform) {
+            Object.defineProperty(process, 'platform', originalPlatform);
+        }
+    });
+    function setPlatform(platform) {
+        Object.defineProperty(process, 'platform', {
+            value: platform,
+            configurable: true,
+        });
+    }
+    describe('URL validation', () => {
+        it('should allow valid HTTP URLs', async () => {
+            setPlatform('darwin');
+            await openBrowserSecurely('http://example.com');
+            expect(mockExecFile).toHaveBeenCalledWith('open', ['http://example.com'], expect.any(Object));
+        });
+        it('should allow valid HTTPS URLs', async () => {
+            setPlatform('darwin');
+            await openBrowserSecurely('https://example.com');
+            expect(mockExecFile).toHaveBeenCalledWith('open', ['https://example.com'], expect.any(Object));
+        });
+        it('should reject non-HTTP(S) protocols', async () => {
+            await expect(openBrowserSecurely('file:///etc/passwd')).rejects.toThrow('Unsafe protocol');
+            await expect(openBrowserSecurely('javascript:alert(1)')).rejects.toThrow('Unsafe protocol');
+            await expect(openBrowserSecurely('ftp://example.com')).rejects.toThrow('Unsafe protocol');
+        });
+        it('should reject invalid URLs', async () => {
+            await expect(openBrowserSecurely('not-a-url')).rejects.toThrow('Invalid URL');
+            await expect(openBrowserSecurely('')).rejects.toThrow('Invalid URL');
+        });
+        it('should reject URLs with control characters', async () => {
+            await expect(openBrowserSecurely('http://example.com\nmalicious-command')).rejects.toThrow('invalid characters');
+            await expect(openBrowserSecurely('http://example.com\rmalicious-command')).rejects.toThrow('invalid characters');
+            await expect(openBrowserSecurely('http://example.com\x00')).rejects.toThrow('invalid characters');
+        });
+    });
+    describe('Command injection prevention', () => {
+        it('should prevent PowerShell command injection on Windows', async () => {
+            setPlatform('win32');
+            // The POC from the vulnerability report
+            const maliciousUrl = "http://127.0.0.1:8080/?param=example#$(Invoke-Expression([System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String('Y2FsYy5leGU='))))";
+            await openBrowserSecurely(maliciousUrl);
+            // Verify that execFile was called (not exec) and the URL is passed safely
+            expect(mockExecFile).toHaveBeenCalledWith('powershell.exe', [
+                '-NoProfile',
+                '-NonInteractive',
+                '-WindowStyle',
+                'Hidden',
+                '-Command',
+                `Start-Process '${maliciousUrl.replace(/'/g, "''")}'`,
+            ], expect.any(Object));
+        });
+        it('should handle URLs with special shell characters safely', async () => {
+            setPlatform('darwin');
+            const urlsWithSpecialChars = [
+                'http://example.com/path?param=value&other=$value',
+                'http://example.com/path#fragment;command',
+                'http://example.com/$(whoami)',
+                'http://example.com/`command`',
+                'http://example.com/|pipe',
+                'http://example.com/>redirect',
+            ];
+            for (const url of urlsWithSpecialChars) {
+                await openBrowserSecurely(url);
+                // Verify the URL is passed as an argument, not interpreted by shell
+                expect(mockExecFile).toHaveBeenCalledWith('open', [url], expect.any(Object));
+            }
+        });
+        it('should properly escape single quotes in URLs on Windows', async () => {
+            setPlatform('win32');
+            const urlWithSingleQuotes = "http://example.com/path?name=O'Brien&test='value'";
+            await openBrowserSecurely(urlWithSingleQuotes);
+            // Verify that single quotes are escaped by doubling them
+            expect(mockExecFile).toHaveBeenCalledWith('powershell.exe', [
+                '-NoProfile',
+                '-NonInteractive',
+                '-WindowStyle',
+                'Hidden',
+                '-Command',
+                `Start-Process 'http://example.com/path?name=O''Brien&test=''value'''`,
+            ], expect.any(Object));
+        });
+    });
+    describe('Platform-specific behavior', () => {
+        it('should use correct command on macOS', async () => {
+            setPlatform('darwin');
+            await openBrowserSecurely('https://example.com');
+            expect(mockExecFile).toHaveBeenCalledWith('open', ['https://example.com'], expect.any(Object));
+        });
+        it('should use PowerShell on Windows', async () => {
+            setPlatform('win32');
+            await openBrowserSecurely('https://example.com');
+            expect(mockExecFile).toHaveBeenCalledWith('powershell.exe', expect.arrayContaining([
+                '-Command',
+                `Start-Process 'https://example.com'`,
+            ]), expect.any(Object));
+        });
+        it('should use xdg-open on Linux', async () => {
+            setPlatform('linux');
+            await openBrowserSecurely('https://example.com');
+            expect(mockExecFile).toHaveBeenCalledWith('xdg-open', ['https://example.com'], expect.any(Object));
+        });
+        it('should throw on unsupported platforms', async () => {
+            setPlatform('aix');
+            await expect(openBrowserSecurely('https://example.com')).rejects.toThrow('Unsupported platform');
+        });
+    });
+    describe('Error handling', () => {
+        it('should handle browser launch failures gracefully', async () => {
+            setPlatform('darwin');
+            mockExecFile.mockRejectedValueOnce(new Error('Command not found'));
+            await expect(openBrowserSecurely('https://example.com')).rejects.toThrow('Failed to open browser');
+        });
+        it('should try fallback browsers on Linux', async () => {
+            setPlatform('linux');
+            // First call to xdg-open fails
+            mockExecFile.mockRejectedValueOnce(new Error('Command not found'));
+            // Second call to gnome-open succeeds
+            mockExecFile.mockResolvedValueOnce({ stdout: '', stderr: '' });
+            await openBrowserSecurely('https://example.com');
+            expect(mockExecFile).toHaveBeenCalledTimes(2);
+            expect(mockExecFile).toHaveBeenNthCalledWith(1, 'xdg-open', ['https://example.com'], expect.any(Object));
+            expect(mockExecFile).toHaveBeenNthCalledWith(2, 'gnome-open', ['https://example.com'], expect.any(Object));
+        });
+    });
+});
+//# sourceMappingURL=secure-browser-launcher.test.js.map

package/dist/src/utils/secure-browser-launcher.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secure-browser-launcher.test.js","sourceRoot":"","sources":["../../../src/utils/secure-browser-launcher.test.ts"],"names":[],"mappings":"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"}

package/dist/src/utils/shell-utils.d.ts

@@ -0,0 +1,117 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Config } from '../config/config.js';
+/**
+ * An identifier for the shell type.
+ */
+export type ShellType = 'cmd' | 'powershell' | 'bash';
+/**
+ * Defines the configuration required to execute a command string within a specific shell.
+ */
+export interface ShellConfiguration {
+    /** The path or name of the shell executable (e.g., 'bash', 'cmd.exe'). */
+    executable: string;
+    /**
+     * The arguments required by the shell to execute a subsequent string argument.
+     */
+    argsPrefix: string[];
+    /** An identifier for the shell type. */
+    shell: ShellType;
+}
+/**
+ * Determines the appropriate shell configuration for the current platform.
+ *
+ * This ensures we can execute command strings predictably and securely across platforms
+ * using the `spawn(executable, [...argsPrefix, commandString], { shell: false })` pattern.
+ *
+ * @returns The ShellConfiguration for the current environment.
+ */
+export declare function getShellConfiguration(): ShellConfiguration;
+/**
+ * Export the platform detection constant for use in process management (e.g., killing processes).
+ */
+export declare const isWindows: () => boolean;
+/**
+ * Escapes a string so that it can be safely used as a single argument
+ * in a shell command, preventing command injection.
+ *
+ * @param arg The argument string to escape.
+ * @param shell The type of shell the argument is for.
+ * @returns The shell-escaped string.
+ */
+export declare function escapeShellArg(arg: string, shell: ShellType): string;
+/**
+ * Splits a shell command into a list of individual commands, respecting quotes.
+ * This is used to separate chained commands (e.g., using &&, ||, ;).
+ * @param command The shell command string to parse
+ * @returns An array of individual command strings
+ */
+export declare function splitCommands(command: string): string[];
+/**
+ * Extracts the root command from a given shell command string.
+ * This is used to identify the base command for permission checks.
+ * @param command The shell command string to parse
+ * @returns The root command name, or undefined if it cannot be determined
+ * @example getCommandRoot("ls -la /tmp") returns "ls"
+ * @example getCommandRoot("git status && npm test") returns "git"
+ */
+export declare function getCommandRoot(command: string): string | undefined;
+export declare function getCommandRoots(command: string): string[];
+export declare function stripShellWrapper(command: string): string;
+/**
+ * Detects command substitution patterns in a shell command, following bash quoting rules:
+ * - Single quotes ('): Everything literal, no substitution possible
+ * - Double quotes ("): Command substitution with $() and backticks unless escaped with \
+ * - No quotes: Command substitution with $(), <(), and backticks
+ * @param command The shell command string to check
+ * @returns true if command substitution would be executed by bash
+ */
+export declare function detectCommandSubstitution(command: string): boolean;
+/**
+ * Checks a shell command against security policies and allowlists.
+ *
+ * This function operates in one of two modes depending on the presence of
+ * the `sessionAllowlist` parameter:
+ *
+ * 1.  **"Default Deny" Mode (sessionAllowlist is provided):** This is the
+ *     strictest mode, used for user-defined scripts like custom commands.
+ *     A command is only permitted if it is found on the global `coreTools`
+ *     allowlist OR the provided `sessionAllowlist`. It must not be on the
+ *     global `excludeTools` blocklist.
+ *
+ * 2.  **"Default Allow" Mode (sessionAllowlist is NOT provided):** This mode
+ *     is used for direct tool invocations (e.g., by the model). If a strict
+ *     global `coreTools` allowlist exists, commands must be on it. Otherwise,
+ *     any command is permitted as long as it is not on the `excludeTools`
+ *     blocklist.
+ *
+ * @param command The shell command string to validate.
+ * @param config The application configuration.
+ * @param sessionAllowlist A session-level list of approved commands. Its
+ *   presence activates "Default Deny" mode.
+ * @returns An object detailing which commands are not allowed.
+ */
+export declare function checkCommandPermissions(command: string, config: Config, sessionAllowlist?: Set<string>): {
+    allAllowed: boolean;
+    disallowedCommands: string[];
+    blockReason?: string;
+    isHardDenial?: boolean;
+};
+/**
+ * Determines whether a given shell command is allowed to execute based on
+ * the tool's configuration including allowlists and blocklists.
+ *
+ * This function operates in "default allow" mode. It is a wrapper around
+ * `checkCommandPermissions`.
+ *
+ * @param command The shell command string to validate.
+ * @param config The application configuration.
+ * @returns An object with 'allowed' boolean and optional 'reason' string if not allowed.
+ */
+export declare function isCommandAllowed(command: string, config: Config): {
+    allowed: boolean;
+    reason?: string;
+};

package/dist/src/utils/shell-utils.js

@@ -0,0 +1,376 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import os from 'os';
+import { quote } from 'shell-quote';
+/**
+ * Determines the appropriate shell configuration for the current platform.
+ *
+ * This ensures we can execute command strings predictably and securely across platforms
+ * using the `spawn(executable, [...argsPrefix, commandString], { shell: false })` pattern.
+ *
+ * @returns The ShellConfiguration for the current environment.
+ */
+export function getShellConfiguration() {
+    if (isWindows()) {
+        const comSpec = process.env['ComSpec'] || 'cmd.exe';
+        const executable = comSpec.toLowerCase();
+        if (executable.endsWith('powershell.exe') ||
+            executable.endsWith('pwsh.exe')) {
+            // For PowerShell, the arguments are different.
+            // -NoProfile: Speeds up startup.
+            // -Command: Executes the following command.
+            return {
+                executable: comSpec,
+                argsPrefix: ['-NoProfile', '-Command'],
+                shell: 'powershell',
+            };
+        }
+        // Default to cmd.exe for anything else on Windows.
+        // Flags for CMD:
+        // /d: Skip execution of AutoRun commands.
+        // /s: Modifies the treatment of the command string (important for quoting).
+        // /c: Carries out the command specified by the string and then terminates.
+        return {
+            executable: comSpec,
+            argsPrefix: ['/d', '/s', '/c'],
+            shell: 'cmd',
+        };
+    }
+    // Unix-like systems (Linux, macOS)
+    return { executable: 'bash', argsPrefix: ['-c'], shell: 'bash' };
+}
+/**
+ * Export the platform detection constant for use in process management (e.g., killing processes).
+ */
+export const isWindows = () => os.platform() === 'win32';
+/**
+ * Escapes a string so that it can be safely used as a single argument
+ * in a shell command, preventing command injection.
+ *
+ * @param arg The argument string to escape.
+ * @param shell The type of shell the argument is for.
+ * @returns The shell-escaped string.
+ */
+export function escapeShellArg(arg, shell) {
+    if (!arg) {
+        return '';
+    }
+    switch (shell) {
+        case 'powershell':
+            // For PowerShell, wrap in single quotes and escape internal single quotes by doubling them.
+            return `'${arg.replace(/'/g, "''")}'`;
+        case 'cmd':
+            // Simple Windows escaping for cmd.exe: wrap in double quotes and escape inner double quotes.
+            return `"${arg.replace(/"/g, '""')}"`;
+        case 'bash':
+        default:
+            // POSIX shell escaping using shell-quote.
+            return quote([arg]);
+    }
+}
+/**
+ * Splits a shell command into a list of individual commands, respecting quotes.
+ * This is used to separate chained commands (e.g., using &&, ||, ;).
+ * @param command The shell command string to parse
+ * @returns An array of individual command strings
+ */
+export function splitCommands(command) {
+    const commands = [];
+    let currentCommand = '';
+    let inSingleQuotes = false;
+    let inDoubleQuotes = false;
+    let i = 0;
+    while (i < command.length) {
+        const char = command[i];
+        const nextChar = command[i + 1];
+        if (char === '\\' && i < command.length - 1) {
+            currentCommand += char + command[i + 1];
+            i += 2;
+            continue;
+        }
+        if (char === "'" && !inDoubleQuotes) {
+            inSingleQuotes = !inSingleQuotes;
+        }
+        else if (char === '"' && !inSingleQuotes) {
+            inDoubleQuotes = !inDoubleQuotes;
+        }
+        if (!inSingleQuotes && !inDoubleQuotes) {
+            if ((char === '&' && nextChar === '&') ||
+                (char === '|' && nextChar === '|')) {
+                commands.push(currentCommand.trim());
+                currentCommand = '';
+                i++; // Skip the next character
+            }
+            else if (char === ';' || char === '&' || char === '|') {
+                commands.push(currentCommand.trim());
+                currentCommand = '';
+            }
+            else {
+                currentCommand += char;
+            }
+        }
+        else {
+            currentCommand += char;
+        }
+        i++;
+    }
+    if (currentCommand.trim()) {
+        commands.push(currentCommand.trim());
+    }
+    return commands.filter(Boolean); // Filter out any empty strings
+}
+/**
+ * Extracts the root command from a given shell command string.
+ * This is used to identify the base command for permission checks.
+ * @param command The shell command string to parse
+ * @returns The root command name, or undefined if it cannot be determined
+ * @example getCommandRoot("ls -la /tmp") returns "ls"
+ * @example getCommandRoot("git status && npm test") returns "git"
+ */
+export function getCommandRoot(command) {
+    const trimmedCommand = command.trim();
+    if (!trimmedCommand) {
+        return undefined;
+    }
+    // This regex is designed to find the first "word" of a command,
+    // while respecting quotes. It looks for a sequence of non-whitespace
+    // characters that are not inside quotes.
+    const match = trimmedCommand.match(/^"([^"]+)"|^'([^']+)'|^(\S+)/);
+    if (match) {
+        // The first element in the match array is the full match.
+        // The subsequent elements are the capture groups.
+        // We prefer a captured group because it will be unquoted.
+        const commandRoot = match[1] || match[2] || match[3];
+        if (commandRoot) {
+            // If the command is a path, return the last component.
+            return commandRoot.split(/[\\/]/).pop();
+        }
+    }
+    return undefined;
+}
+export function getCommandRoots(command) {
+    if (!command) {
+        return [];
+    }
+    return splitCommands(command)
+        .map((c) => getCommandRoot(c))
+        .filter((c) => !!c);
+}
+export function stripShellWrapper(command) {
+    const pattern = /^\s*(?:sh|bash|zsh|cmd.exe)\s+(?:\/c|-c)\s+/;
+    const match = command.match(pattern);
+    if (match) {
+        let newCommand = command.substring(match[0].length).trim();
+        if ((newCommand.startsWith('"') && newCommand.endsWith('"')) ||
+            (newCommand.startsWith("'") && newCommand.endsWith("'"))) {
+            newCommand = newCommand.substring(1, newCommand.length - 1);
+        }
+        return newCommand;
+    }
+    return command.trim();
+}
+/**
+ * Detects command substitution patterns in a shell command, following bash quoting rules:
+ * - Single quotes ('): Everything literal, no substitution possible
+ * - Double quotes ("): Command substitution with $() and backticks unless escaped with \
+ * - No quotes: Command substitution with $(), <(), and backticks
+ * @param command The shell command string to check
+ * @returns true if command substitution would be executed by bash
+ */
+export function detectCommandSubstitution(command) {
+    let inSingleQuotes = false;
+    let inDoubleQuotes = false;
+    let inBackticks = false;
+    let i = 0;
+    while (i < command.length) {
+        const char = command[i];
+        const nextChar = command[i + 1];
+        // Handle escaping - only works outside single quotes
+        if (char === '\\' && !inSingleQuotes) {
+            i += 2; // Skip the escaped character
+            continue;
+        }
+        // Handle quote state changes
+        if (char === "'" && !inDoubleQuotes && !inBackticks) {
+            inSingleQuotes = !inSingleQuotes;
+        }
+        else if (char === '"' && !inSingleQuotes && !inBackticks) {
+            inDoubleQuotes = !inDoubleQuotes;
+        }
+        else if (char === '`' && !inSingleQuotes) {
+            // Backticks work outside single quotes (including in double quotes)
+            inBackticks = !inBackticks;
+        }
+        // Check for command substitution patterns that would be executed
+        if (!inSingleQuotes) {
+            // $(...) command substitution - works in double quotes and unquoted
+            if (char === '$' && nextChar === '(') {
+                return true;
+            }
+            // <(...) process substitution - works unquoted only (not in double quotes)
+            if (char === '<' && nextChar === '(' && !inDoubleQuotes && !inBackticks) {
+                return true;
+            }
+            // Backtick command substitution - check for opening backtick
+            // (We track the state above, so this catches the start of backtick substitution)
+            if (char === '`' && !inBackticks) {
+                return true;
+            }
+        }
+        i++;
+    }
+    return false;
+}
+/**
+ * Checks a shell command against security policies and allowlists.
+ *
+ * This function operates in one of two modes depending on the presence of
+ * the `sessionAllowlist` parameter:
+ *
+ * 1.  **"Default Deny" Mode (sessionAllowlist is provided):** This is the
+ *     strictest mode, used for user-defined scripts like custom commands.
+ *     A command is only permitted if it is found on the global `coreTools`
+ *     allowlist OR the provided `sessionAllowlist`. It must not be on the
+ *     global `excludeTools` blocklist.
+ *
+ * 2.  **"Default Allow" Mode (sessionAllowlist is NOT provided):** This mode
+ *     is used for direct tool invocations (e.g., by the model). If a strict
+ *     global `coreTools` allowlist exists, commands must be on it. Otherwise,
+ *     any command is permitted as long as it is not on the `excludeTools`
+ *     blocklist.
+ *
+ * @param command The shell command string to validate.
+ * @param config The application configuration.
+ * @param sessionAllowlist A session-level list of approved commands. Its
+ *   presence activates "Default Deny" mode.
+ * @returns An object detailing which commands are not allowed.
+ */
+export function checkCommandPermissions(command, config, sessionAllowlist) {
+    // Disallow command substitution for security.
+    if (detectCommandSubstitution(command)) {
+        return {
+            allAllowed: false,
+            disallowedCommands: [command],
+            blockReason: 'Command substitution using $(), <(), or >() is not allowed for security reasons',
+            isHardDenial: true,
+        };
+    }
+    const SHELL_TOOL_NAMES = ['run_shell_command', 'ShellTool'];
+    const normalize = (cmd) => cmd.trim().replace(/\s+/g, ' ');
+    const isPrefixedBy = (cmd, prefix) => {
+        if (!cmd.startsWith(prefix)) {
+            return false;
+        }
+        return cmd.length === prefix.length || cmd[prefix.length] === ' ';
+    };
+    const extractCommands = (tools) => tools.flatMap((tool) => {
+        for (const toolName of SHELL_TOOL_NAMES) {
+            if (tool.startsWith(`${toolName}(`) && tool.endsWith(')')) {
+                return [normalize(tool.slice(toolName.length + 1, -1))];
+            }
+        }
+        return [];
+    });
+    const coreTools = config.getCoreTools() || [];
+    const excludeTools = config.getExcludeTools() || [];
+    const commandsToValidate = splitCommands(command).map(normalize);
+    // 1. Blocklist Check (Highest Priority)
+    if (SHELL_TOOL_NAMES.some((name) => excludeTools.includes(name))) {
+        return {
+            allAllowed: false,
+            disallowedCommands: commandsToValidate,
+            blockReason: 'Shell tool is globally disabled in configuration',
+            isHardDenial: true,
+        };
+    }
+    const blockedCommands = extractCommands(excludeTools);
+    for (const cmd of commandsToValidate) {
+        if (blockedCommands.some((blocked) => isPrefixedBy(cmd, blocked))) {
+            return {
+                allAllowed: false,
+                disallowedCommands: [cmd],
+                blockReason: `Command '${cmd}' is blocked by configuration`,
+                isHardDenial: true,
+            };
+        }
+    }
+    const globallyAllowedCommands = extractCommands(coreTools);
+    const isWildcardAllowed = SHELL_TOOL_NAMES.some((name) => coreTools.includes(name));
+    // If there's a global wildcard, all commands are allowed at this point
+    // because they have already passed the blocklist check.
+    if (isWildcardAllowed) {
+        return { allAllowed: true, disallowedCommands: [] };
+    }
+    if (sessionAllowlist) {
+        // "DEFAULT DENY" MODE: A session allowlist is provided.
+        // All commands must be in either the session or global allowlist.
+        const disallowedCommands = [];
+        for (const cmd of commandsToValidate) {
+            const isSessionAllowed = [...sessionAllowlist].some((allowed) => isPrefixedBy(cmd, normalize(allowed)));
+            if (isSessionAllowed)
+                continue;
+            const isGloballyAllowed = globallyAllowedCommands.some((allowed) => isPrefixedBy(cmd, allowed));
+            if (isGloballyAllowed)
+                continue;
+            disallowedCommands.push(cmd);
+        }
+        if (disallowedCommands.length > 0) {
+            return {
+                allAllowed: false,
+                disallowedCommands,
+                blockReason: `Command(s) not on the global or session allowlist. Disallowed commands: ${disallowedCommands
+                    .map((c) => JSON.stringify(c))
+                    .join(', ')}`,
+                isHardDenial: false, // This is a soft denial; confirmation is possible.
+            };
+        }
+    }
+    else {
+        // "DEFAULT ALLOW" MODE: No session allowlist.
+        const hasSpecificAllowedCommands = globallyAllowedCommands.length > 0;
+        if (hasSpecificAllowedCommands) {
+            const disallowedCommands = [];
+            for (const cmd of commandsToValidate) {
+                const isGloballyAllowed = globallyAllowedCommands.some((allowed) => isPrefixedBy(cmd, allowed));
+                if (!isGloballyAllowed) {
+                    disallowedCommands.push(cmd);
+                }
+            }
+            if (disallowedCommands.length > 0) {
+                return {
+                    allAllowed: false,
+                    disallowedCommands,
+                    blockReason: `Command(s) not in the allowed commands list. Disallowed commands: ${disallowedCommands.map((c) => JSON.stringify(c)).join(', ')}`,
+                    isHardDenial: false, // This is a soft denial.
+                };
+            }
+        }
+        // If no specific global allowlist exists, and it passed the blocklist,
+        // the command is allowed by default.
+    }
+    // If all checks for the current mode pass, the command is allowed.
+    return { allAllowed: true, disallowedCommands: [] };
+}
+/**
+ * Determines whether a given shell command is allowed to execute based on
+ * the tool's configuration including allowlists and blocklists.
+ *
+ * This function operates in "default allow" mode. It is a wrapper around
+ * `checkCommandPermissions`.
+ *
+ * @param command The shell command string to validate.
+ * @param config The application configuration.
+ * @returns An object with 'allowed' boolean and optional 'reason' string if not allowed.
+ */
+export function isCommandAllowed(command, config) {
+    // By not providing a sessionAllowlist, we invoke "default allow" behavior.
+    const { allAllowed, blockReason } = checkCommandPermissions(command, config);
+    if (allAllowed) {
+        return { allowed: true };
+    }
+    return { allowed: false, reason: blockReason };
+}
+//# sourceMappingURL=shell-utils.js.map