@lmctl-ai/lmctl 0.2.38 → 0.2.40

package/dist/providers/transports/hold-open.d.ts

@@ -1,120 +0,0 @@
-/**
- * Transport-agnostic "hold stdin open past the turn's result while the session's
- * own dispatched work is still outstanding" mechanism. Extracted verbatim from
- * stream-json.ts (task #68) so every transport — stream-json AND acp — shares
- * ONE copy of this subtle concurrency code instead of re-deriving it.
- *
- * The ALGORITHM lives here once; each transport supplies its own {@link
- * HoldOpenHooks} over its own child/abort/event state. Behavior is identical to
- * the original inline stream-json implementation (its full test suite is the
- * regression proof).
- */
-export type HoldOpenReleaseReason = "cleared" | "max-hold" | "check-error" | "child-exited" | "aborted";
-export interface HoldOpenOptions {
-    /**
-     * True while the session being run still has outstanding dispatched work
-     * that must survive this process. Checked once on the first result event
-     * (fast path: false → close immediately), then every `pollMs` while true.
-     * A thrown/rejected check counts as "no outstanding work" — the check
-     * must never be able to wedge the turn open. A check that never settles
-     * cannot wedge it either: each call races the remaining `maxHoldMs`
-     * budget and the abort signal, so the ceiling is a real hard bound.
-     */
-    hasOutstandingWork: () => Promise<boolean> | boolean;
-    /** Poll interval while work is outstanding. Default 2000ms. */
-    pollMs?: number;
-    /**
-     * Quiescence window required AFTER a hold before the close proceeds: the
-     * check must keep reporting "no outstanding work" for this long. Measured
-     * from the LATER of "the work cleared" and "the child last emitted an event",
-     * and never expires while a turn is mid-flight. Covers the dispatched work's
-     * lease-release → process-exit → completion-notification hand-off, which a
-     * window measured from the lease alone would close stdin in the middle of.
-     * Deliberately applies ONLY after an actual hold. Default 5000ms; 0 disables.
-     */
-    settleMs?: number;
-    /**
-     * Hard ceiling on how long the close may be deferred — last-resort insurance
-     * against a row that stays "live" forever. Callers default this to the
-     * agent_inflight TTL. On expiry the close proceeds (today's behavior), never
-     * a hang. Default 8 hours.
-     */
-    maxHoldMs?: number;
-    /**
-     * Short, bounded window to wait for the FIRST agent_inflight lease to appear
-     * when a background job was launched this turn (see
-     * HoldOpenHooks.wasBackgroundJobLaunched) but no lease has registered yet — a
-     * nested `lmctl chat` has real startup latency before it takes its lease.
-     * Only ever applies before any hold, and only when a background job was
-     * observed; short-circuits the instant the lease appears (zero cost to a
-     * fast-registering dispatch). Distinct from `maxHoldMs`: this bounds ONLY the
-     * first-appearance race, not a held wait. Default 1000ms.
-     */
-    backgroundGraceMs?: number;
-    /** Called once when the close is first deferred (for logging). */
-    onHold?: () => void;
-    /**
-     * Called EXACTLY ONCE per turn once the hold path has finished, including the
-     * fast path (`held: false`, reason `"cleared"`). Callers use it both to log
-     * and to dispose resources the check acquired, so it must not be conditional
-     * on having actually held — decide what is worth logging from `held`/`reason`.
-     */
-    onRelease?: (info: {
-        elapsedMs: number;
-        held: boolean;
-        reason: HoldOpenReleaseReason;
-    }) => void;
-}
-/**
- * Per-transport state the hold loop reads. Each transport wires these to its own
- * abort flag, child-exit flag, turn-in-flight tracking, last-activity timestamp,
- * and stdin-close primitive.
- */
-export interface HoldOpenHooks {
-    /** The turn was aborted (caller signalled). */
-    isAborted: () => boolean;
-    /** The child process has already exited on its own. */
-    hasChildExited: () => boolean;
-    /** A turn is currently mid-flight (events seen since the last result). The
-     * settle window never expires while this is true. */
-    isTurnInFlight: () => boolean;
-    /** Epoch ms of the child's last emitted event/notification. */
-    lastEventAtMs: () => number;
-    /** Close the child's stdin (idempotent / harmless if already gone). */
-    closeStdin: () => void;
-    /** Abort signal, raced inside each never-settling check. */
-    signal?: AbortSignal;
-    /** Provider label for the max-hold errorLog + verbose logs. */
-    label: string;
-    /**
-     * True once a background job (e.g. an ACP `run_in_background` tool call) was
-     * observed launching this turn, and stays true for the rest of the turn. When
-     * true, the first "nothing outstanding" result gets a short grace window for
-     * the nested lease to register instead of the zero-latency fast close. Absent
-     * (stream-json, and any turn with no background launch) ⇒ treated as false ⇒
-     * the fast path is byte-for-byte unchanged.
-     */
-    wasBackgroundJobLaunched?: () => boolean;
-}
-/** Shared with the result-grace-timeout fallback (transports/stream-json.ts)
- * so the two independent uses of `hasOutstandingWork` can't drift apart. */
-export declare const DEFAULT_MAX_HOLD_MS: number;
-/** Sentinel for "the check did not settle within its allotted budget". */
-declare const CHECK_TIMED_OUT: unique symbol;
-/**
- * Await `check` but never longer than `budgetMs`, and never past an abort.
- * Without this a `hasOutstandingWork` that never settles would park the hold
- * loop forever — `maxHoldMs` is only consulted between awaits, so it would not
- * be the hard ceiling it advertises. Exported for the result-grace-timeout
- * fallback (transports/stream-json.ts), which awaits the SAME
- * `hasOutstandingWork` check and needs the identical never-wedge guarantee.
- */
-export declare function settleCheckWithin(check: Promise<boolean> | boolean, budgetMs: number, signal: AbortSignal | undefined): Promise<boolean | typeof CHECK_TIMED_OUT>;
-/**
- * Schedule the turn's stdin close, optionally deferred while the session's own
- * dispatched work is outstanding. Without `hold` this is the exact pre-existing
- * synchronous `closeStdin()` — no promise, no extra tick. Call AT MOST ONCE per
- * turn (callers guard their own first-result transition).
- */
-export declare function scheduleHoldOpenClose(hold: HoldOpenOptions | undefined, hooks: HoldOpenHooks): void;
-export {};

package/dist/providers/transports/manager.d.ts

@@ -1,21 +0,0 @@
-/**
- * Transport manager — selects and creates transport handles.
- *
- * Replaces the provider-specific if/else branching in work-cmd.ts
- * with a single unified interface.
- */
-import type { TransportHandle, TransportType, TransportOptions } from "./types.js";
-import type { UserConfig } from "../config/types.js";
-export declare function selectTransport(tool: string): TransportType;
-export declare function transportLabel(type: TransportType, tool: string): string;
-export interface CreateTransportOpts extends TransportOptions {
-    /** User config — needed for one-shot fallback command building */
-    userConfig?: UserConfig;
-    /** Profile override — for one-shot */
-    profile?: string;
-}
-/**
- * Create a transport handle for the given tool.
- * Automatically selects the best transport.
- */
-export declare function createTransport(opts: CreateTransportOpts): TransportHandle;

package/dist/providers/transports/stream-json.d.ts

@@ -1,162 +0,0 @@
-/**
- * Claude Code stream-json transport.
- *
- * Spawns `claude -p --input-format stream-json --output-format stream-json`
- * and communicates via NDJSON on stdin/stdout. The process stays alive for
- * the full conversation — no one-shot timeout.
- *
- * Protocol (reverse-engineered from Claude Agent SDK):
- *   stdin:  {"type":"user","message":{"role":"user","content":"..."}}
- *   stdout: {"type":"system","subtype":"init",...}
- *           {"type":"assistant","message":{...},...}
- *           {"type":"result","subtype":"success","result":"...","session_id":"..."}
- */
-import { type PermissionMode } from "../yolo-contract.js";
-import { type HoldOpenOptions } from "./hold-open.js";
-export type { HoldOpenReleaseReason } from "./hold-open.js";
-export type StreamJsonHoldOpenOptions = HoldOpenOptions;
-import { type StreamJsonResult } from "../parsers/stream-json.js";
-export { aggregateResultEvents, createStreamJsonProcessor, joinResultTurns, supportsStreamJson, } from "../parsers/stream-json.js";
-export type { AggregatedResultEvents, StreamJsonProcessor, StreamJsonResult, } from "../parsers/stream-json.js";
-/**
- * Deferred stdin-close contract (BUG-chat-client-death-interrupts-receiver-
- * live-session, "root cause pinned exactly" section).
- *
- * Closing `child.stdin` on the first `result` event makes `claude -p` exit
- * the moment its visible turn text is done — with zero regard for any
- * `run_in_background` dispatches the session fired during that turn. Those
- * children die with the exiting host process and their completion
- * notifications are never delivered. The durable signal for "this session
- * still has outstanding dispatched work" is an `agent_inflight` row whose
- * SENDER is this session's own identity, held by a live pid — state lmctl
- * already owns.
- *
- * The transport stays DB-free: the caller supplies `hasOutstandingWork` as
- * an opaque callback (queue-delivery builds it from the receiver identity +
- * DAL). When the option is absent, the close is the same synchronous
- * `child.stdin.end()` as before — zero added latency. When present, ONE
- * check runs on the first result event; only if it reports outstanding work
- * does the transport enter a poll loop.
- */
-export interface StreamJsonOptions {
-    sessionId?: string;
-    cwd: string;
-    env?: NodeJS.ProcessEnv;
-    /** Called for each raw NDJSON event from stdout (for logging/debugging) */
-    onEvent?: (event: Record<string, unknown>) => void;
-    /** Called when streaming text arrives (for live output) */
-    onText?: (text: string) => void;
-    /**
-     * Permission mode for this turn.
-     *
-     *   - "yolo" (default) — historical behavior; append the provider's
-     *     permission-bypass flag (`--dangerously-skip-permissions` for
-     *     claude, `--approval-mode yolo` for qwen). Required for
-     *     non-interactive runs; if the provider asks for a permission
-     *     mid-turn lmctl has no UI to forward the request.
-     *   - "plan"            — append the provider's plan-mode flag
-     *     instead (`--permission-mode plan` for claude,
-     *     `--approval-mode plan` for qwen). The provider should refuse
-     *     workspace-modifying tool calls in this mode. Use for research /
-     *     exploration sessions.
-     *
-     * Default is "yolo" so callers that omit the field preserve the
-     * pre-existing argv shape exactly.
-     */
-    permissionMode?: PermissionMode;
-    /** Tool name — determines the binary and permission flags */
-    tool?: string;
-    /**
-     * Override the spawned binary path. When set, this exact path is
-     * spawned instead of looking up `tool` in TOOL_BINARY. Permission
-     * flags are still resolved via `tool`. Used for troubleshooting
-     * with custom Claude Code builds. (Task 63 fix 3.)
-     */
-    binaryPath?: string;
-    /** Abort signal — kills the provider process when aborted */
-    signal?: AbortSignal;
-    /** Provider-specific model name, appended as `--model <name>`. */
-    model?: string;
-    /**
-     * When set, the first-result stdin close is deferred while the caller
-     * reports outstanding dispatched work. See {@link StreamJsonHoldOpenOptions}.
-     */
-    holdOpen?: StreamJsonHoldOpenOptions;
-}
-export declare function formatProviderNoResultError(params: {
-    tool: string;
-    exitCode: number | null;
-    stderr: string;
-}): string;
-/**
- * Send a prompt via the stream-json protocol (Claude Code / Qwen).
- * Returns the final result text when the turn completes.
- */
-export declare function sendPrompt(prompt: string, opts: StreamJsonOptions): Promise<StreamJsonResult>;
-export interface StreamJsonSessionOptions extends StreamJsonOptions {
-    /**
-     * Shutdown cap: how long close() waits for a natural exit after stdin
-     * EOF before escalating to the (internally bounded) terminate ladder.
-     * Also bounds the open-phase wait for the provider's init event.
-     * Default 2000ms (close) / 30000ms (init).
-     */
-    closeTimeoutMs?: number;
-    /**
-     * Override the session-file roots used by the bundle identity check.
-     * Default: the provider's standard projects dir under the user home
-     * (`~/.claude/projects`, `~/.qwen/projects`). Exists for tests and
-     * custom provider homes.
-     */
-    sessionFileRoots?: string[];
-}
-export interface StreamJsonSessionTurnOptions {
-    onText?: (text: string) => void;
-    onEvent?: (event: Record<string, unknown>) => void;
-    /**
-     * Abort THIS turn. stream-json has no verified cancel verb, so
-     * cancellation is TERMINAL for the bundle: the turn rejects with
-     * `Error("Aborted")` and the child gets the same graceful-shutdown
-     * ladder a one-shot abort gets. Later turns fail fast.
-     */
-    signal?: AbortSignal;
-}
-export interface StreamJsonSessionTurnResult {
-    result: string;
-    sessionId: string;
-    durationMs: number;
-    numTurns: number;
-    /** Stall-grace fallback marker (text_done), same convention as
-     *  StreamJsonResult.warnings. */
-    warnings?: string[];
-}
-/**
- * An open stream-json bundle session: one provider process serving many
- * prompts. The lifecycle contract is in src/providers/bundle.ts; the
- * transport-specific decisions:
- *
- *  - Per-turn completion boundary: the turn's `result` event. A fresh
- *    StreamJsonProcessor per turn, so accumulated text/results never leak
- *    across turns; events arriving with no turn in flight update activity
- *    bookkeeping only (never accumulated, never armed timers).
- *  - The stall-grace machinery (text_done / tool_use_silence timers) is
- *    retained and re-armed per turn; a text_done fire resolves the turn
- *    from accumulated text with a warning exactly like the one-shot path
- *    (and ends the process, so the bundle is dead afterwards).
- *  - Identity: the session FILE's header is checked at open (requireResume
- *    parity — no file, no bundle) and re-checked before every sendTurn
- *    (catches an external re-seed mid-bundle); the provider's init event
- *    must agree with the requested session id.
- *  - Cancellation is terminal (no verified cancel verb in stream-json).
- */
-export interface StreamJsonSession {
-    readonly tool: string;
-    readonly sessionId: string;
-    readonly completedTurns: number;
-    sendTurn(prompt: string, opts?: StreamJsonSessionTurnOptions): Promise<StreamJsonSessionTurnResult>;
-    close(): Promise<void>;
-}
-/**
- * Open a persistent stream-json session (`claude`/`qwen`). See
- * {@link StreamJsonSession} for the contract.
- */
-export declare function openStreamJsonSession(opts: StreamJsonSessionOptions): Promise<StreamJsonSession>;

package/dist/providers/transports/types.d.ts

@@ -1,56 +0,0 @@
-/**
- * Shared transport interfaces.
- *
- * All provider transports implement TransportHandle so the caller
- * (work-cmd, serve) doesn't need provider-specific branching.
- */
-export type TransportType = "stream-json" | "codex-app-server" | "acp" | "one-shot";
-export interface TurnResult {
-    text: string;
-    sessionId: string;
-    durationMs: number;
-    stopReason?: string;
-    numTurns?: number;
-}
-export interface TransportOptions {
-    sessionId?: string;
-    cwd: string;
-    env?: NodeJS.ProcessEnv;
-    tool: string;
-    /**
-     * If true, the transport must resume the given sessionId or fail.
-     * If false, a failed resume may fall back to a new session.
-     * Set to true for `--session`, false for `--team` or new sessions.
-     */
-    requireResume?: boolean;
-    /**
-     * Called with each text delta as it arrives from the provider.
-     * Used by the SSE streaming endpoint to push incremental text to the browser.
-     */
-    onDelta?: (text: string) => void;
-    /**
-     * Signal to abort/cancel the turn. When aborted, the transport should
-     * kill the provider process and reject the sendTurn promise.
-     */
-    signal?: AbortSignal;
-    /** Provider-specific model override, when the selected transport supports it. */
-    model?: string;
-    /** Provider-specific effort / variant override, when the selected transport supports it. */
-    effort?: string;
-    /** Teamfile alias, when provider setup needs alias-specific behavior. */
-    alias?: string;
-    /** Provider binary override. */
-    progPath?: string;
-    /**
-     * Permission mode — `"yolo"` (default) or `"plan"`. The transport
-     * substitutes the per-provider argv / JSON-RPC params accordingly.
-     * See `src/providers/yolo-contract.ts`.
-     */
-    permissionMode?: import("../yolo-contract.js").PermissionMode;
-}
-export interface TransportHandle {
-    readonly type: TransportType;
-    readonly tool: string;
-    /** Send a prompt and get the response. Manages the full lifecycle internally. */
-    sendTurn(prompt: string): Promise<TurnResult>;
-}

package/dist/providers/types.d.ts

@@ -1,154 +0,0 @@
-export type ProviderName = "claude" | "codex" | "gemini" | "copilot" | "opencode" | "lmplayer" | "qwen" | "agy" | "kimi" | "dsh" | "hermes" | "pi" | "ClaudeMock";
-export interface SessionTokenUsage {
-    inputTokens?: number;
-    cachedInputTokens?: number;
-    cacheWriteInputTokens?: number;
-    outputTokens?: number;
-    reasoningOutputTokens?: number;
-    totalTokens?: number;
-}
-export interface SessionSummary {
-    provider: ProviderName;
-    sessionId: string;
-    slug?: string;
-    cwd: string;
-    createdAt: Date;
-    modifiedAt: Date;
-    model?: string;
-    cliVersion?: string;
-    startCommand?: string;
-    firstUserMessage?: string;
-    lastUserMessage?: string;
-    messageCount: number;
-    filePath: string;
-    filePaths?: string[];
-    totalInputTokens?: number;
-    totalCachedInputTokens?: number;
-    totalCacheWriteInputTokens?: number;
-    totalOutputTokens?: number;
-    totalReasoningOutputTokens?: number;
-    lastInputTokens?: number;
-    lastTokenUsage?: SessionTokenUsage;
-    modelContextWindow?: number;
-}
-export interface SessionDetail extends SessionSummary {
-    /** Native external prompt text, excluding injected context and internal rows.
-     * When present (even empty), authoritative over user-role transcript messages. */
-    userPrompts?: string[];
-    gitBranch?: string;
-    turnStatus?: "in_progress" | "complete" | "aborted";
-    messages: ConversationMessage[];
-}
-export type MessageRole = "user" | "assistant" | "system" | "tool_use" | "tool_result" | "thinking";
-export interface ConversationMessage {
-    role: MessageRole;
-    timestamp: Date;
-    content: string;
-    toolName?: string;
-    toolInput?: string;
-    toolInputData?: Record<string, unknown>;
-    toolCallId?: string;
-    backgroundTaskId?: string;
-    toolDetailedContent?: string;
-    stopReason?: string;
-    model?: string;
-}
-export interface WatchPathInfo {
-    directory: string;
-    filePattern: RegExp;
-}
-export interface WatchTarget {
-    provider: ProviderName;
-    directory: string;
-    recursive: boolean;
-    filePattern?: RegExp;
-}
-export interface SessionProvider {
-    name: ProviderName;
-    discoverSessions(): Promise<SessionSummary[]>;
-    loadSession(sessionId: string): Promise<SessionDetail | null>;
-    resolveSessionPath(sessionId: string): Promise<string | null>;
-    deleteSession(sessionId: string): Promise<boolean>;
-    getWatchPaths?(): WatchPathInfo[];
-}
-export interface DeleteOptions {
-    provider?: ProviderName;
-    force?: boolean;
-    json?: boolean;
-}
-export interface MutationResult {
-    success: boolean;
-    sessionId: string;
-    provider?: ProviderName;
-    filePath: string;
-    error?: string;
-}
-export interface ListOptions {
-    provider?: ProviderName;
-    workspace?: string;
-    limit?: number;
-    from?: string;
-    to?: string;
-    json?: boolean;
-}
-export interface ViewOptions {
-    provider?: ProviderName;
-    detailed?: boolean;
-    noTools?: boolean;
-    noThinking?: boolean;
-    toolDetails?: boolean;
-    json?: boolean;
-}
-export interface ExtractOptions {
-    provider?: ProviderName;
-    detailed?: boolean;
-    last?: number;
-}
-export interface DumpMessage {
-    role: "user" | "assistant";
-    content: string;
-}
-export interface DumpResult {
-    success: boolean;
-    messages: DumpMessage[];
-    error?: string;
-}
-export interface DumpOptions {
-    provider?: ProviderName;
-    format?: "text" | "bundle";
-}
-export type LoadMode = "patch" | "transplant";
-export interface LoadOptions {
-    provider?: ProviderName;
-    force?: boolean;
-    dryRun?: boolean;
-    preserve?: boolean;
-    mode?: LoadMode;
-}
-export interface EditableEntry {
-    role: "user" | "assistant";
-    recordIndex: number;
-    contentPath: string;
-    identityKey: string;
-    content: string;
-}
-export interface SessionBundle {
-    schemaVersion: 2;
-    provider: ProviderName;
-    toolVersion: string;
-    source: {
-        sessionId: string;
-        cwd: string;
-        dumpedAt: string;
-    };
-    raw: {
-        type: "jsonl" | "json";
-        records: string[];
-    };
-    editable: EditableEntry[];
-}
-export interface BundleResult {
-    success: boolean;
-    bundle?: SessionBundle;
-    error?: string;
-}

package/dist/providers/yolo-contract.d.ts

@@ -1,131 +0,0 @@
-/**
- * YOLO contract — every provider transport spawns its CLI in
- * full-auto / permission-bypass mode. Hardcoded; not user-configurable.
- *
- * Why this is non-negotiable: lmctl drives provider sessions
- * non-interactively. If the provider asks for a tool-use permission,
- * there is no human at the prompt and lmctl has no UI for forwarding
- * the request. The session hangs until the per-tool internal timeout
- * fires (could be 30+ minutes), with no recovery path.
- *
- * The opencode06 incident exposed this concretely: opencode was
- * spawned without any permission-bypass flag, sent
- * `session/request_permission` for its first bash tool call, lmctl
- * silently dropped the request, opencode hung for 42+ minutes. See
- * `commit 1cc1766` for the safety-net (reply with -32601) and this
- * module for the upstream fix (force YOLO so the request is never
- * sent in the first place).
- *
- * Users who want permission prompts should use the provider's CLI
- * directly, not through lmctl. That's a deliberate scope boundary.
- *
- * ## Coverage
- *
- * Argv-based providers — flag must appear in the spawn argv:
- *   claude   → --dangerously-skip-permissions       (stream-json transport)
- *   qwen     → --approval-mode yolo                 (stream-json transport)
- *   gemini   → -y                                   (acp transport)
- *   copilot  → --yolo                               (acp transport)
- *   agy      → --dangerously-skip-permissions       (one-shot print transport)
- *   lmplayer → --dangerously-skip-permissions       (one-shot run transport)
- *   opencode → --dangerously-skip-permissions       (acp transport)
- *
- * pi (NOT argv-based): pi has no tool-permission prompts by design —
- * there is no approval UI to hang on, so no bypass flag exists or is
- * needed. Routed through PROTOCOL_LEVEL_YOLO like codex so
- * assertYoloFlagPresent documents the stance at every spawn.
- *
- * Codex (NOT argv-based): the `codex app-server` JSON-RPC speaks YOLO
- * via per-call `thread/start` / `thread/resume` params:
- *   approvalPolicy: "never"
- *   sandbox:        "danger-full-access"
- * These are asserted in `codex-app-server.ts` (see `sendCodexPrompt`),
- * but are NOT covered by `assertYoloFlagPresent` here because the
- * argv carries no flag — codex's YOLO is wire-protocol-level.
- */
-/**
- * Required YOLO flag(s) per argv-based provider. Each entry is a
- * sequence of consecutive argv tokens (e.g. `["--approval-mode",
- * "yolo"]`) that must appear in the spawn args for the contract to
- * hold. Single-token entries (e.g. `["--yolo"]`) just check for the
- * one token's presence.
- *
- * **Note: opencode is NOT here.** Opencode's ACP mode rejects every
- * permission-bypass argv flag (verified empirically — `--dangerously-
- * skip-permissions` is a `run`-subcommand-only flag, not recognized
- * by `opencode acp`). Opencode's YOLO is satisfied via the
- * `permission: "allow"` key in `<cwd>/.opencode/opencode.json`,
- * written by `installOpencodeConfig` (see
- * src/providers/opencode-config.ts). It belongs in the protocol-level
- * set below, same shape as codex.
- */
-export declare const YOLO_FLAGS: Record<string, string[]>;
-/**
- * lmctl-controlled permission mode for a single chat call.
- *
- *   - `"yolo"`  — full-auto / permission-bypass (the historical default;
- *                  what every spawn does without `--permission-mode`).
- *   - `"plan"`  — provider should refuse tool calls that would write
- *                  to the workspace, rather than prompt or auto-approve.
- *
- * Plan mode is for research / exploration sessions where the agent
- * should produce a plan only and never modify the workspace. See
- * `PERMISSION_FLAGS` (below) for the per-provider argv substitution.
- *
- * IMPORTANT (gemini caveat): gemini's `--approval-mode plan` only
- * filters `write_file` by workspace path — an agent can still escape
- * via `run_shell_command` (e.g. `bash -c 'echo > /tmp/x'`). This is
- * a known limitation in gemini-cli; a tighter sandbox for plan mode
- * is tracked as a follow-up. For this layer, plan mode means
- * "ask the provider for plan-mode behavior" — guarantees depend on
- * the provider.
- */
-export type PermissionMode = "plan" | "yolo";
-/**
- * Per-provider argv tokens for the two permission modes, for the
- * providers whose permission selection is argv-based. The `yolo`
- * column mirrors `YOLO_FLAGS` (preserved as the historical default);
- * the `plan` column carries the substitution applied when the CLI
- * receives `--permission-mode plan`.
- *
- * Verified against the actual provider CLIs:
- *
- *   claude :  --dangerously-skip-permissions    vs   --permission-mode plan
- *   qwen   :  --approval-mode yolo              vs   --approval-mode plan
- *   gemini :  -y                                vs   --approval-mode plan
- *
- * Codex and opencode are not here — they are protocol-/config-level
- * (see `PROTOCOL_LEVEL_YOLO`). Codex's plan-mode substitution lives in
- * the `sandbox: "danger-full-access"` → `sandbox: "read-only"` swap in
- * codex-app-server.ts. Opencode plan mode is not yet wired and
- * preserves the yolo (config-file) behavior.
- *
- * Copilot is not here — its CLI lacks a plan-mode flag in `--acp`
- * mode (verified). Copilot in plan mode keeps `--yolo` so it doesn't
- * hang on permission prompts; the limitation is documented in
- * acp.ts.
- */
-export declare const PERMISSION_FLAGS: Record<string, Record<PermissionMode, string[]>>;
-/**
- * Resolve the argv tokens for `provider` under `mode`. Falls back to
- * the yolo token sequence when no plan-mode entry exists, so the
- * assertion in `assertYoloFlagPresent` stays meaningful for providers
- * that do not yet support plan mode.
- */
-export declare function flagsForPermissionMode(provider: string, mode: PermissionMode): string[] | undefined;
-/**
- * Defense-in-depth pre-flight: assert that the YOLO flag for
- * `provider` is present in `args` immediately before `spawn()` is
- * called. Throws `TransportConnectionError` (and emits an
- * unconditional debug-log record) on missing flag — catches the
- * regression class "future refactor accidentally dropped the YOLO
- * flag from the spawn args."
- *
- * Unknown providers (not in `YOLO_FLAGS` or `PROTOCOL_LEVEL_YOLO`)
- * are treated as a hard error — the contract is global; new providers
- * must opt in explicitly.
- *
- * Codex short-circuits with success — its YOLO is in the JSON-RPC
- * params and verified separately at the call site.
- */
-export declare function assertYoloFlagPresent(provider: string, args: readonly string[], mode?: PermissionMode): void;