/**
 * Shell execution tool — the koi's `exec` and `process` tool implementations.
 *
 * Provides sandboxed shell command execution with:
 * - PTY support (for interactive CLIs, terminal UIs, coding kois)
 * - Background process management (start, poll, log, write, send-keys, kill)
 * - Timeout enforcement with configurable kill behavior
 * - Working directory resolution and security policy enforcement
 * - Output streaming with size limits and truncation
 * - Session tracking for long-running processes across heartbeats
 *
 * This is one of the most security-sensitive modules — all commands pass through
 * the security policy layer (deny/allowlist/full) before execution.
 *
 * @module
 */
import type { AgentTool as KoiTool } from "@mariozechner/pi-agent-core";
import type { BashSandboxConfig } from "./bash-tools.shared.js";
import { type ExecAsk, type ExecHost, type ExecSecurity } from "../infra/exec-approvals.js";
export type ExecToolDefaults = {
    host?: ExecHost;
    security?: ExecSecurity;
    ask?: ExecAsk;
    node?: string;
    pathPrepend?: string[];
    safeBins?: string[];
    koiId?: string;
    backgroundMs?: number;
    timeoutSec?: number;
    approvalRunningNoticeMs?: number;
    sandbox?: BashSandboxConfig;
    elevated?: ExecElevatedDefaults;
    allowBackground?: boolean;
    scopeKey?: string;
    sessionKey?: string;
    messageProvider?: string;
    notifyOnExit?: boolean;
    cwd?: string;
};
export type { BashSandboxConfig } from "./bash-tools.shared.js";
export type ExecElevatedDefaults = {
    enabled: boolean;
    allowed: boolean;
    defaultLevel: "on" | "off" | "ask" | "full";
};
export type ExecToolDetails = {
    status: "running";
    sessionId: string;
    pid?: number;
    startedAt: number;
    cwd?: string;
    tail?: string;
} | {
    status: "completed" | "failed";
    exitCode: number | null;
    durationMs: number;
    aggregated: string;
    cwd?: string;
} | {
    status: "approval-pending";
    approvalId: string;
    approvalSlug: string;
    expiresAtMs: number;
    host: ExecHost;
    command: string;
    cwd?: string;
    nodeId?: string;
};
export declare function createExecTool(defaults?: ExecToolDefaults): KoiTool<any, ExecToolDetails>;
export declare const execTool: KoiTool<any, ExecToolDetails>;