/**
 * Discriminated shell type identifier.
 */
export type ShellType = "bash" | "powershell";
/**
 * Options passed to `buildExecCommand`.
 */
export interface BuildCommandOpts {
    /** Unique command invocation ID (for CWD temp-file naming). */
    id: string;
    /** If set, sandbox TMPDIR root. */
    sandboxTmpDir?: string;
    /** Whether sandbox mode is active. */
    useSandbox: boolean;
}
/**
 * Result of `buildExecCommand` — the final command string
 * and the path where the shell will write its post-command CWD.
 */
export interface BuiltCommand {
    /** Fully-wrapped command string ready for spawn. */
    commandString: string;
    /**
     * Temp file path where the shell writes its post-command CWD.
     * Used by the host to track `cd` across invocations.
     * undefined if CWD tracking is not supported / not needed.
     */
    cwdFilePath?: string;
}
/**
 * Runtime-agnostic shell provider.
 *
 * Hosts (Gateway / Desktop / Hub) create a provider once, then
 * use it for every `exec()` call. The tool itself never
 * `spawn()`s — the host does, using args from this provider.
 */
export interface ShellProvider {
    /** Shell type discriminator. */
    readonly type: ShellType;
    /** Absolute path to the shell binary. */
    readonly shellPath: string;
    /**
     * Whether `spawn()` should use `detached: true`.
     * Bash: true (allows job control / cleanup).
     * PowerShell: false (no POSIX process groups on Windows).
     */
    readonly detached: boolean;
    /**
     * Wrap a raw user command into a full shell command string.
     * Handles:
     *   - Environment snapshots / session env sourcing (bash)
     *   - UTF-16LE EncodedCommand wrapping (PowerShell)
     *   - CWD tracking (`pwd -P > file` / `Get-Location | Out-File`)
     *   - stdin redirect for interactive commands (bash)
     */
    buildExecCommand(command: string, opts: BuildCommandOpts): Promise<BuiltCommand>;
    /**
     * Return the argv array for `child_process.spawn()`.
     * E.g. bash → `['-c', commandString]`
     *      PS   → `['-NoProfile', '-NonInteractive', '-Command', cmd]`
     */
    getSpawnArgs(commandString: string): string[];
    /**
     * Return extra environment variables to merge into spawn env.
     * E.g. `{ SHELL: '/bin/bash', GIT_EDITOR: 'true', CLAUDECODE: '1' }`
     */
    getEnvironmentOverrides(command: string): Promise<Record<string, string>>;
}
/**
 * Check if PowerShell tool mode should be enabled.
 * Mirrors cc's `isPowerShellToolEnabled()`.
 *
 * On Windows: enabled when `QLOGICAGENT_USE_POWERSHELL` is truthy.
 * On non-Windows: always false.
 */
export declare function isPowerShellToolEnabled(): boolean;
/**
 * Default shell type for the current platform.
 */
export declare function getDefaultShellType(): ShellType;
/**
 * Generate a short random hex ID for CWD temp file naming.
 * Matches cc's `Math.floor(Math.random() * 0x10000).toString(16)`.
 */
export declare function generateCommandId(): string;
