/**
 * Pseudo-terminal (PTY) shell runner (T1741 · epic T11456 · SG-TOOLS).
 *
 * The `terminal` toolset's execution backend. Runs a command under a PTY when
 * the OPTIONAL `node-pty` native dependency is loadable, otherwise transparently
 * degrades to a plain `child_process.spawn` (the {@link defaultShellExecutor}
 * path) so the tool ALWAYS works without a heavy native dep. `node-pty` is
 * loaded lazily via dynamic `import()` inside the runner — NEVER at module
 * import — so this file is import-time side-effect-free (and adds no startup
 * cost / hard dependency).
 *
 * The child runs under the SCRUBBED, explicitly-constructed environment from
 * {@link scrubSubprocessEnv} (same security posture as the non-PTY path): the
 * daemon's secrets are never inherited and a Pi-controlled loader hook / PATH
 * can never reach the spawned process. This runner is invoked ONLY from the
 * guard chokepoint ({@link ./guard.js}), so the command denylist applies before
 * any process is spawned — there is no raw bypass.
 *
 * @epic T11456
 * @task T1741
 * @see ./guard.js — the deny-first chokepoint that wraps this runner
 */
import type { RunShellInput, RunShellResult } from '@cleocode/contracts/tools/agent-tools';
/**
 * Run a command under a PTY when possible, else a non-PTY spawn.
 *
 * - `spawn` mode → always {@link runSpawn}.
 * - `pty` / `auto` mode → attempt {@link loadNodePty}; on success {@link runWithPty},
 *   otherwise degrade to {@link runSpawn} with `ptyFellBack: true`.
 *
 * The actual process is always launched under the scrubbed subprocess env. This
 * function performs NO policy decision of its own — it is the executor the guard
 * chokepoint ({@link ./guard.js}) invokes AFTER its denylist check passes.
 *
 * @param input - {@link RunShellInput}.
 * @returns The {@link RunShellResult}.
 *
 * @example
 * ```ts
 * const res = await runPty({ command: 'echo', args: ['hi'], mode: 'auto' });
 * // res.mode === 'pty' when node-pty is installed, else 'spawn' (ptyFellBack: true)
 * ```
 */
export declare function runPty(input: RunShellInput): Promise<RunShellResult>;
//# sourceMappingURL=pty.d.ts.map