/** * Argv construction: pure functions turning a descriptor + launch options * into the exact argv a spawner would exec. Ordering rules (positional * prompt before tool grants) and the spawn-boundary refusals live here so * no caller re-derives them. */ import type { AccessValue, HarnessDescriptor, StreamingGranularity } from "../knowledge/descriptor.js"; import type { NativeSettingsSnapshot } from "../knowledge/native-settings.js"; import { type SkillsSelection } from "./skills-selection.js"; import type { ToolMap } from "./tool-vocabulary.js"; export type { RefusalIssue } from "./refusal.js"; export { ArgvRefusalError, buildRefusalMessage, REFUSAL_ISSUES } from "./refusal.js"; /** A prompt carries its own provenance (RFC-02 change 13): a plain string * is an implicit, positional prompt; the object form came from an explicit * flag or file, so a leading dash is the caller's intent, not a flag. */ export type Prompt = string | { readonly text: string; readonly explicit: boolean; }; /** The one accessor for the prompt's text, for builders, the runner, and * redaction alike. */ export declare const promptTextOf: (opts: { readonly prompt: Prompt; }) => string; /** The same prompt with new text: the composed form keeps its provenance. */ export declare const withPromptText: (prompt: Prompt, text: string) => Prompt; export interface DiscoveryOptions { readonly tools?: boolean; readonly instructionFiles?: boolean; readonly extensions?: boolean; readonly skills?: boolean; } export interface TurnOptions { readonly isolation?: "tool-free"; readonly prompt: Prompt; readonly tools?: readonly string[]; readonly excludeTools?: readonly string[]; /** Caller-directed skills allowlist: the resolved picks and the * registry's known names. Rendered per descriptor by * renderSkillsSelection (pi loads each pick with discovery off; claude * and codex turn the complement off); muse refuses. */ readonly skills?: SkillsSelection; readonly model?: string; readonly autonomy?: boolean; readonly effort?: string; readonly sandbox?: string; readonly contextWindow?: number; readonly provider?: string; /** Named-agent selection (map #288): the caller picks among agents the * harness defines natively. claude and antigravity render the native * `--agent `; harnesses without a spec refuse. The name passes * through - an unknown name is the harness's own native error, never an * hcn refusal (no stable machine roster exists to validate against). */ readonly agent?: string; readonly discovery?: DiscoveryOptions; readonly write?: boolean; readonly shell?: boolean; /** Persistent cross-session memory (ratified 2026-08-26). false = the * harness loads no cross-session memory into context (profile default); * true = opt back in. claude renders a spawn env var, codex a feature * flag, pi is vacuously off, muse refuses explicit values (no off * switch exists - memory stays on, reported as divergence). */ readonly memory?: boolean; readonly maxSteps?: number; /** issue #48: replaces the harness's built-in system prompt (opt-in-only, * no profile entry). claude/pi: flag-value (claude pairs the dynamic-section * exclusion); codex: config-kv `instructions` (literal or path); muse: * refuses with hint. */ readonly systemPrompt?: string; /** issue #48: appends to the built-in prompt (claude/pi only). */ readonly appendSystemPrompt?: string; /** RFC 35 (Lucid): extension files the harness loads for this turn. */ readonly extensions?: readonly string[]; /** question mode: which preamble hcn injects (ask/assume/none). * A BEHAVIOR INSTRUCTION, not a turn option. It never renders into any * harness argv; the CLI layer turns it into the prompt preamble and * arms question-block detection. Undefined means the default: "ask". */ readonly questions?: import("./question.js").QuestionMode; /** The merged toolMap (every harness, native plus tier), the one shape * past option resolution (RFC-02 change 8). */ readonly toolMap?: ToolMap; readonly access?: AccessValue; } export interface ResumeOptions extends TurnOptions { readonly sessionId: string; } export type LaunchOptions = TurnOptions; /** Returns the exact text to pipe, or null when it travels in argv. */ export declare function stdinPromptOf(h: HarnessDescriptor, opts: TurnOptions): string | null; export declare const buildLaunchArgv: (h: HarnessDescriptor, opts: LaunchOptions) => string[]; /** Descriptor-derived spawn-env assignments for a turn (claude's memory * disable is an env var, not a flag). Pure data: merge OVER the caller's * env at spawn - an explicit normalized option beats a contradicting raw * variable. Phase matches how the argv was built; env-kind renders * contribute no tokens, so the argv builders ignore them by construction. * The input is Pick because memory is the only * dimension that can render env today - widen deliberately if a second * env-kind option lands. */ export declare const buildTurnEnv: (h: HarnessDescriptor, opts: Pick, phase: "launch" | "resume") => Record; export declare const buildResumeArgv: (h: HarnessDescriptor, opts: ResumeOptions) => string[]; /** What a spawn needs beyond the turn options: the session to resume, if * any, and the raw passthrough tail (ADR 0003). */ export interface SpawnArgvOptions extends TurnOptions { readonly resume?: string; /** Resume the harness's most recent session without naming an id (RFC-06). * Mutually exclusive with `resume`; renderable only when the descriptor's * `resumeLast.headless` is true, else an unsupported-option refusal. */ readonly resumeLast?: true; readonly passthrough?: readonly string[]; /** Internal read result. Execution independently checks the source before using it. */ readonly verifiedNativeSettings?: NativeSettingsSnapshot; } /** Refuse an id-less most-recent turn on a harness with no renderable * most-recent grammar (RFC-06). One owner for the refusal shape: the * resume-last builder and planTurn both raise it from here, so the plan * fires first with the same unsupported-option/resumeLast shape the * builder would raise at spawn time. */ export declare const assertResumeLastRenderable: (h: HarnessDescriptor) => Extract, { readonly headless: true; }>; /** The argv a turn spawns: launch or resume per `resume`, then the * passthrough tail at the descriptor's placement (ADR 0003). The bare * `--` is hcn's own command-line split, never a harness token: every * probed harness parses trailing native flags once the separator is gone, * so it is not rendered. One owner, so the CLI's preview and the runner's * spawn agree by construction (RFC-02 change 10). */ export declare const buildSpawnArgv: (h: HarnessDescriptor, opts: SpawnArgvOptions) => string[]; export interface SessionOptions { readonly sessionId: string; readonly model?: string; /** Effort level, validated against the ladder that applies to the pick * (the model's own ladder where the harness constrains per model, else * the harness-wide one) - the same validation a one-shot turn applies. * No profile entry: a session without --effort runs at the harness's * own default effort, never a pinned one. */ readonly effort?: string; /** Provider selector (pi). A harness with no provider selector refuses, * the same way a one-shot turn does. */ readonly provider?: string; /** Named-agent selection (map #288): rendered at session spawn exactly * as a one-shot launch renders it. A harness with no spec refuses. */ readonly agent?: string; readonly contextWindow?: number; /** True when this argv should resume an existing conversation, false for a * fresh session. Controls which descriptor flag is rendered: resumeFlag * vs idFlag. Only consumers that alias --resume/--session-id set this. */ readonly isResume?: boolean; /** Caller-directed skills allowlist (issue #332), resolved by the CLI * against the registry root before it gets here. Rendered by the same * renderSkillsSelection a one-shot launch uses, so the spelling and the * refusal (a null-skills harness refuses) stay identical across run and * session. A spawn property, not a turn option: the flags ride the one * session spawn, so the allowlist holds for the whole session across * every turn - and on resume too, where the resumed process is re-spawned * with the same narrowing. */ readonly skills?: SkillsSelection; } export declare const buildSessionArgv: (h: HarnessDescriptor, opts: SessionOptions) => string[]; /** The granularity an invocation will actually emit: pins are checked in * order, first fully-satisfied pin wins (every member present with its * pinned value, last occurrence winning like the CLIs themselves); an argv * satisfying no pin gets the floor. */ export declare const streamingGranularityOf: (h: HarnessDescriptor, argv: readonly string[]) => StreamingGranularity; //# sourceMappingURL=argv.d.ts.map