@aragon-agent/cli 0.6.38 → 0.6.39

package/dist/exec/options.d.ts

@@ -14,7 +14,20 @@
  * half-written event would corrupt every consumer. The caller writes the message
  * to stderr and exits.
  */
+import { type HookTimeoutPolicy } from './hooks/limits.js';
 import type { ExecInputFormat, ExecOutputFormat, ExecPermissionMode } from './events.js';
+/**
+ * What `resolveExecOptions` needs from the resolved config.
+ *
+ * THE ONLY FACT IT NEEDS IS `confirmTools`, and the reason it is a parameter
+ * rather than a second `loadConfig()` call is that this module is PURE by
+ * contract (see the file header): it decides about flags, never about the world.
+ * The default is `false` so every existing caller - and every test that passes one
+ * argument - keeps the exact behaviour it had.
+ */
+export interface ExecOptionsContext {
+    confirmTools?: boolean;
+}
 /** Raw commander output. Every field is whatever the user typed, or absent. */
 export interface RawExecOptions {
     outputFormat?: string;
@@ -32,6 +45,36 @@ export interface RawExecOptions {
     /** The hidden `--timeout` alias of `--max-duration` (P2-1 / D-16). */
     timeout?: string;
     permissionMode?: string;
+    /** `--decision-timeout <ms>`; bridge only. */
+    decisionTimeout?: string;
+    /** `--on-decision-timeout deny|error`; bridge only. */
+    onDecisionTimeout?: string;
+    /** `--caller-tool-timeout <ms>`; bridge only. */
+    callerToolTimeout?: string;
+    /**
+     * Path to the caller's JSON Schema (headless-request-scope-and-typed-result
+     * section 4.1). Not readable from here: this module resolves flags, never the
+     * world, so `exec/index.ts` opens the file and reports `result_schema_unreadable`.
+     */
+    resultSchema?: string;
+    /** `--result-repair-turns 0..2`. Needs `--result-schema`. */
+    resultRepairTurns?: string;
+    /** `--on-result-unsatisfied error|continue`. Needs `--result-schema`. */
+    onResultUnsatisfied?: string;
+    /** `--request-max-turns <n>`; bridge only. */
+    requestMaxTurns?: string;
+    /** `--request-max-duration <ms>`; bridge only. */
+    requestMaxDuration?: string;
+    /** `--threads`. Requires bridge input AND stream-json output. */
+    threads?: boolean;
+    /** `--max-open-threads <n>`; thread mode only. */
+    maxOpenThreads?: string;
+    /** `--thread-concurrency <n>`; thread mode only. */
+    threadConcurrency?: string;
+    /** `--hook-timeout <ms>`; bridge only. */
+    hookTimeout?: string;
+    /** `--on-hook-timeout deny|allow|error`; bridge only. */
+    onHookTimeout?: string;
     allowTool?: string[];
     denyTool?: string[];
     appendSystemPrompt?: string;
@@ -53,8 +96,52 @@ export interface ExecOptions {
     maxTurns?: number;
     maxDurationMs?: number;
     permissionMode: ExecPermissionMode;
+    /**
+     * The three bridge budgets, ALWAYS RESOLVED and only ever used under
+     * `--input-format bridge`. Defaulted here rather than left optional so no
+     * consumer has to repeat `?? 300000` and get a different number than the
+     * `BRIDGE_LIMITS` one.
+     */
+    decisionTimeoutMs: number;
+    onDecisionTimeout: ExecDecisionTimeout;
+    callerToolTimeoutMs: number;
     allowTools: string[];
     denyTools: string[];
+    /**
+     * The structured-result contract for this run (headless-request-scope-and-typed-
+     * result section 4.1). All three are absent unless `--result-schema` was given,
+     * which is what keeps the three output faces byte-identical without it (I-C1).
+     *
+     * `resultRepairTurns` and `onResultUnsatisfied` are RESOLVED HERE rather than left
+     * optional, for the reason the bridge budgets are: a consumer must not repeat
+     * `?? 1` and get a different number than `RESULT_LIMITS` says.
+     */
+    resultSchemaPath?: string;
+    resultRepairTurns?: number;
+    onResultUnsatisfied?: ExecResultUnsatisfiedMode;
+    /**
+     * The per-request budgets. Bridge only, and NEVER defaulted - "no ceiling" is the
+     * honest default for a long-running process, and a default ceiling would silently
+     * cut off a legitimate long request (section 9.7).
+     */
+    requestMaxTurns?: number;
+    requestMaxDurationMs?: number;
+    /**
+     * Thread mode (headless-threads-and-lifecycle-hooks section 4.1).
+     *
+     * `threads` is a BOOLEAN because the mode has no tuning of its own: the two ceilings below
+     * are per-run numbers with defaults that come from `THREAD_LIMITS`, resolved here for the
+     * same reason the bridge budgets are - no consumer may restate a default.
+     */
+    threads: boolean;
+    maxOpenThreads: number;
+    threadConcurrency: number;
+    /**
+     * `--hook-timeout`, ALWAYS RESOLVED and only consulted by a bridge run that registered a
+     * hook. Clamped to 30 s under `--on-hook-timeout allow` (section 2.4.8, review P2-1).
+     */
+    hookTimeoutMs: number;
+    onHookTimeout: HookTimeoutPolicy;
     appendSystemPrompt?: string;
     appendSystemPromptFile?: string;
     quiet: boolean;
@@ -64,7 +151,31 @@ export interface ExecOptions {
      */
     warnings: string[];
 }
-export type ExecUsageCode = 'invalid_output_format' | 'invalid_input_format' | 'invalid_permission_mode' | 'invalid_max_turns' | 'invalid_max_duration' | 'invalid_session_id' | 'unknown_tool' | 'unsupported_in_text_mode' | 'input_format_requires_stream_json' | 'stream_only_flag' | 'session_flag_conflict' | 'print_not_supported';
+export type ExecUsageCode = 'invalid_output_format' | 'invalid_input_format' | 'invalid_permission_mode' | 'invalid_max_turns' | 'invalid_max_duration' | 'invalid_session_id' | 'unknown_tool' | 'unsupported_in_text_mode' | 'input_format_requires_stream_json' | 'stream_only_flag' | 'session_flag_conflict' | 'print_not_supported' | 'bridge_flag_requires_bridge' | 'ask_confirm_conflict' | 'invalid_decision_timeout' | 'invalid_caller_tool_timeout' | 'invalid_on_decision_timeout'
+/**
+ * The structured-result vocabulary (section 4.1). The first five are decided HERE,
+ * from flags alone. The last three come from `exec/result/schema.ts` preflight and
+ * are reported by `exec/index.ts`, which is the module allowed to touch the disk -
+ * one union so a caller switching on the code has one list to read.
+ */
+ | 'result_flag_requires_schema' | 'invalid_result_repair_turns' | 'invalid_on_result_unsatisfied' | 'invalid_request_max_turns' | 'invalid_request_max_duration'
+/**
+ * THE PREFLIGHT VOCABULARY (section 2.3.3 / 4.1), and it is eight members rather
+ * than three on purpose: `exec/result/schema.ts` decides these from the file's
+ * CONTENT, `exec/index.ts` decides `result_schema_unreadable` from the filesystem,
+ * and a caller switching on the code needs ONE list - including the five that only
+ * the parser can produce.
+ */
+ | 'result_schema_unreadable' | 'result_schema_too_large' | 'result_schema_invalid_json' | 'result_schema_not_object' | 'result_schema_too_deep' | 'result_schema_unsupported_ref' | 'result_schema_wrapper_conflict' | 'result_schema_composite_root'
+/**
+ * The thread and hook vocabulary (headless-threads-and-lifecycle-hooks section 4.1).
+ *
+ * SEVEN MEMBERS, and the last two are the ones a caller meets first: a thread flag without
+ * `--threads` and a hook flag without bridge are the same class of mistake as
+ * `--decision-timeout` without a bridge, and this package answers that class with a usage
+ * error rather than a silent no-op.
+ */
+ | 'threads_require_bridge' | 'threads_require_stream_json' | 'threads_flag_conflict' | 'threads_flag_requires_threads' | 'invalid_thread_limit' | 'invalid_hook_timeout' | 'invalid_on_hook_timeout';
 export type ExecOptionsResult = {
     ok: true;
     options: ExecOptions;
@@ -73,4 +184,15 @@ export type ExecOptionsResult = {
     code: ExecUsageCode;
     message: string;
 };
-export declare function resolveExecOptions(raw: RawExecOptions): ExecOptionsResult;
+/** `--on-decision-timeout`. There is deliberately no `allow` member. */
+export type ExecDecisionTimeout = 'deny' | 'error';
+/**
+ * `--on-result-unsatisfied error|continue` (section 2.3.7, rule 3).
+ *
+ * `error` IS THE DEFAULT BECAUSE A SINGLE-CALL EMBEDDER MUST NOT BE TOLD "SUCCESS"
+ * FOR AN ANSWER IT DID NOT GET, and it is also the ONLY value that ends the process.
+ * `continue` keeps the exit code at 0 but never makes `result.isError` false: the two
+ * signals a wrapper branches on must not be able to disagree.
+ */
+export type ExecResultUnsatisfiedMode = 'error' | 'continue';
+export declare function resolveExecOptions(raw: RawExecOptions, context?: ExecOptionsContext): ExecOptionsResult;

package/dist/exec/options.js

@@ -16,9 +16,25 @@
  */
 import { HOST_TOOL_NAMES } from '../tools/index.js';
 import { isValidSessionId } from '../session/store.js';
+import { BRIDGE_LIMITS } from './bridge/limits.js';
+import { RESULT_LIMITS } from './result/limits.js';
+import { REQUEST_LIMITS } from './request/limits.js';
+import { THREAD_LIMITS } from './threads/limits.js';
+import { HOOK_LIMITS } from './hooks/limits.js';
 const OUTPUT_FORMATS = ['text', 'json', 'stream-json'];
-const INPUT_FORMATS = ['text', 'stream-json'];
-const PERMISSION_MODES = ['auto', 'plan', 'strict'];
+const INPUT_FORMATS = ['text', 'stream-json', 'bridge'];
+const PERMISSION_MODES = ['auto', 'plan', 'strict', 'ask'];
+const DECISION_TIMEOUT_MODES = ['deny', 'error'];
+const RESULT_UNSATISFIED_MODES = ['error', 'continue'];
+/**
+ * `--on-hook-timeout deny|allow|error` (section 2.4.8).
+ *
+ * `deny` IS THE DEFAULT AND IT POINTS THE SAFE WAY: an unanswered hook is an unevaluatable
+ * policy, and letting the tool run would silently disable the redactor. `allow` exists
+ * because a purely observational hook that blocks a tool on timeout would be absurd - which
+ * is also why it is the one mode whose timeout is clamped.
+ */
+const ON_HOOK_TIMEOUT_MODES = ['deny', 'allow', 'error'];
 /**
  * Registered nowhere in a headless session, yet real names (P2-2).
  *
@@ -47,6 +63,10 @@ const TEXT_MODE_REFUSED = [
     { flag: '--input-format stream-json', test: (o) => o.inputFormat === 'stream-json' },
     { flag: '--partial-messages', test: (o) => o.partialMessages === true },
     { flag: '--include-thinking', test: (o) => o.includeThinking === true },
+    // Text mode delegates to `runHeadless` VERBATIM, and `runHeadless` has never heard
+    // of `submit_result`: accepting this flag there would promise a contract nothing
+    // honours. Refused for the reason the four above are, not because it is new.
+    { flag: '--result-schema', test: (o) => o.resultSchema !== undefined },
 ];
 function usage(code, message) {
     return { ok: false, code, message };
@@ -71,7 +91,7 @@ function parsePositiveInt(raw) {
     const n = Number.parseInt(raw.trim(), 10);
     return Number.isSafeInteger(n) ? n : null;
 }
-export function resolveExecOptions(raw) {
+export function resolveExecOptions(raw, context = {}) {
     if (raw.print) {
         return usage('print_not_supported', '`aragon exec` is already the headless face; `-p/--print` is not accepted here. ' +
             'Use `aragon exec --output-format text` for the same stdout as `aragon -p`.');
@@ -84,8 +104,12 @@ export function resolveExecOptions(raw) {
     if (!INPUT_FORMATS.includes(inputFormat)) {
         return usage('invalid_input_format', `Unknown --input-format "${inputFormat}". Choose: ${INPUT_FORMATS.join(', ')}.`);
     }
-    if (inputFormat === 'stream-json' && outputFormat !== 'stream-json') {
-        return usage('input_format_requires_stream_json', '--input-format stream-json requires --output-format stream-json.');
+    const genericInputFormat = inputFormat === 'stream-json' || inputFormat === 'bridge';
+    if (genericInputFormat && outputFormat !== 'stream-json') {
+        // ONE RULE, NAMED PER SPELLING. `bridge` needs the per-event writer for `seq`
+        // and for the pre-`init` queue, which is the same structural reason
+        // `stream-json` needs it - so the message quotes the flag actually typed.
+        return usage('input_format_requires_stream_json', `--input-format ${inputFormat} requires --output-format stream-json.`);
     }
     const formatError = checkFormatCompatibility(raw, outputFormat);
     if (formatError)
@@ -94,6 +118,70 @@ export function resolveExecOptions(raw) {
     if (!PERMISSION_MODES.includes(permissionMode)) {
         return usage('invalid_permission_mode', `Unknown --permission-mode "${permissionMode}". Choose: ${PERMISSION_MODES.join(', ')}.`);
     }
+    const bridge = inputFormat === 'bridge';
+    const bridgeFlagError = checkBridgeFlags(raw, bridge);
+    if (bridgeFlagError)
+        return bridgeFlagError;
+    // THE STRUCTURED-RESULT FLAGS, resolved before anything else reads them. Two of the
+    // five are meaningful only WITH `--result-schema`, and "you passed --on-result-
+    // unsatisfied without a schema" is a usage error rather than a silent no-op: a
+    // caller that meant to protect its output must not get a run that quietly cannot.
+    const structured = resolveStructuredResult(raw);
+    if (!structured.ok)
+        return structured.error;
+    const requestBudgets = resolveRequestBudgets(raw);
+    if (!requestBudgets.ok)
+        return requestBudgets.error;
+    // THREADS AND HOOKS, IN THIS ORDER. Hook state is legal WITHOUT threads - "one
+    // conversation with one redactor" is the commonest embedding shape - so the two are
+    // resolved independently and neither implies the other (section 9.9).
+    const policy = resolveHookPolicy(raw);
+    if (!policy.ok)
+        return policy.error;
+    const threads = resolveThreads(raw, bridge, outputFormat);
+    if (!threads.ok)
+        return threads.error;
+    const hooks = resolveHooks(raw, policy.value);
+    if (!hooks.ok)
+        return hooks.error;
+    // THE FOURTH BASELINE NEEDS SOMEWHERE TO ASK. Without bridge there is no
+    // decision channel at all, so `ask` would silently degrade to `auto` - the
+    // worst of the three possible outcomes (run unasked, refuse everything, or say
+    // the invocation is wrong). `exec/options.ts:11-15` settles the choice.
+    if (permissionMode === 'ask' && !bridge) {
+        return usage('bridge_flag_requires_bridge', '--permission-mode ask requires --input-format bridge: there is nobody to answer.');
+    }
+    // TWO APPROVAL LAYERS WOULD ASK TWICE, which a user experiences as "no
+    // approval at all". They cover the same three mutating tools; `skill_create` is
+    // reachable only through the bridge gate, so nothing is left unguarded.
+    if (permissionMode === 'ask' && context.confirmTools === true) {
+        return usage('ask_confirm_conflict', '--permission-mode ask and --confirm both gate the same three tools. Pick one.');
+    }
+    const decisionTimeout = resolveMilliseconds({
+        raw: raw.decisionTimeout,
+        flag: '--decision-timeout',
+        min: 1_000,
+        max: BRIDGE_LIMITS.maxDecisionTimeoutMs,
+        fallback: BRIDGE_LIMITS.defaultDecisionTimeoutMs,
+        code: 'invalid_decision_timeout',
+    });
+    if (!decisionTimeout.ok)
+        return decisionTimeout.error;
+    const callerToolTimeout = resolveMilliseconds({
+        raw: raw.callerToolTimeout,
+        flag: '--caller-tool-timeout',
+        min: 1_000,
+        max: BRIDGE_LIMITS.maxCallerToolTimeoutMs,
+        fallback: BRIDGE_LIMITS.defaultCallerToolTimeoutMs,
+        code: 'invalid_caller_tool_timeout',
+    });
+    if (!callerToolTimeout.ok)
+        return callerToolTimeout.error;
+    const onDecisionTimeout = (raw.onDecisionTimeout ?? 'deny').trim();
+    if (!DECISION_TIMEOUT_MODES.includes(onDecisionTimeout)) {
+        return usage('invalid_on_decision_timeout', `Unknown --on-decision-timeout "${onDecisionTimeout}". ` +
+            `Choose: ${DECISION_TIMEOUT_MODES.join(', ')}.`);
+    }
     const budgets = resolveBudgets(raw);
     if (!budgets.ok)
         return budgets.error;
@@ -106,11 +194,34 @@ export function resolveExecOptions(raw) {
     if (toolError)
         return toolError;
     const warnings = [];
-    for (const name of allowTools) {
+    for (const name of bridge ? [] : allowTools) {
         if (NEVER_REGISTERED_HEADLESS.includes(name)) {
             warnings.push(`--allow-tool ${name}: that tool is never registered in a headless run, so allowing it has no effect.`);
         }
     }
+    // THE THREE INERT-OR-MISLEADING COMBINATIONS (section 4.1, W-1..W-3). All three are
+    // warnings and none changes the exit code: each one describes a run that may still
+    // do exactly what the caller wanted, and refusing it would be overreach.
+    if (structured.resultSchemaPath !== undefined) {
+        if (budgets.maxTurns === 1) {
+            // W-1. One turn CAN be enough (the model may submit on it), so this is not an
+            // error - but the number is almost certainly a mistake.
+            warnings.push('--max-turns 1 with --result-schema: a structured result needs at least 2 turns ' +
+                '(submitting is itself a turn).');
+        }
+        if (requestBudgets.requestMaxTurns === 1) {
+            // W-2. Names the exact shape of the resulting `request_end` (P1-9), so the
+            // "two fields saying two different things" outcome is announced up front
+            // rather than discovered in a log.
+            warnings.push('--request-max-turns 1 with --result-schema: this request will end with ' +
+                "stopReason 'max_turns' and error.code 'result_schema_unsatisfied'.");
+        }
+    }
+    if (structured.resultSchemaPath === undefined && denyTools.includes('submit_result')) {
+        // W-3. `submit_result` is registered ONLY by `--result-schema`, so denying it here
+        // denies a name that will never exist. Same argument as NEVER_REGISTERED_HEADLESS.
+        warnings.push('--deny-tool submit_result: that tool is registered only under --result-schema, so this deny has no effect.');
+    }
     return {
         ok: true,
         options: {
@@ -128,6 +239,27 @@ export function resolveExecOptions(raw) {
             ...(budgets.maxTurns !== undefined ? { maxTurns: budgets.maxTurns } : {}),
             ...(budgets.maxDurationMs !== undefined ? { maxDurationMs: budgets.maxDurationMs } : {}),
             permissionMode: permissionMode,
+            decisionTimeoutMs: decisionTimeout.value,
+            onDecisionTimeout: onDecisionTimeout,
+            callerToolTimeoutMs: callerToolTimeout.value,
+            ...(structured.resultSchemaPath !== undefined
+                ? {
+                    resultSchemaPath: structured.resultSchemaPath,
+                    resultRepairTurns: structured.resultRepairTurns,
+                    onResultUnsatisfied: structured.onResultUnsatisfied,
+                }
+                : {}),
+            ...(requestBudgets.requestMaxTurns !== undefined
+                ? { requestMaxTurns: requestBudgets.requestMaxTurns }
+                : {}),
+            ...(requestBudgets.requestMaxDurationMs !== undefined
+                ? { requestMaxDurationMs: requestBudgets.requestMaxDurationMs }
+                : {}),
+            threads: threads.threads,
+            maxOpenThreads: threads.maxOpenThreads,
+            threadConcurrency: threads.threadConcurrency,
+            hookTimeoutMs: hooks.hookTimeoutMs,
+            onHookTimeout: policy.value,
             allowTools,
             denyTools,
             ...(raw.appendSystemPrompt ? { appendSystemPrompt: raw.appendSystemPrompt } : {}),
@@ -189,6 +321,281 @@ function resolveBudgets(raw) {
         ...(maxDurationMs !== undefined ? { maxDurationMs } : {}),
     };
 }
+/**
+ * A bridge-only flag without `--input-format bridge` is a USAGE ERROR.
+ *
+ * NOT A WARNING, and not a silent no-op: these three flags tune a channel that
+ * does not exist in any other mode, so accepting them would promise a ceiling
+ * that is never consulted. This project's rule for that case is the same one
+ * `checkFormatCompatibility` applies to `--partial-messages` in `json` mode.
+ */
+function checkBridgeFlags(raw, bridge) {
+    if (bridge)
+        return null;
+    const present = [
+        raw.decisionTimeout !== undefined ? '--decision-timeout' : null,
+        raw.onDecisionTimeout !== undefined ? '--on-decision-timeout' : null,
+        raw.callerToolTimeout !== undefined ? '--caller-tool-timeout' : null,
+        // The two REQUEST-LEVEL budgets join the same rule for the same reason: they tune
+        // a per-request channel that does not exist outside bridge mode, and accepting
+        // them elsewhere would promise a ceiling nothing consults.
+        raw.requestMaxTurns !== undefined ? '--request-max-turns' : null,
+        raw.requestMaxDuration !== undefined ? '--request-max-duration' : null,
+        // The two HOOK flags join it too: `hook_register` is a bridge frame, so a timeout for a
+        // hook that can never be registered is the same inert promise.
+        raw.hookTimeout !== undefined ? '--hook-timeout' : null,
+        raw.onHookTimeout !== undefined ? '--on-hook-timeout' : null,
+    ].filter((flag) => flag !== null);
+    if (present.length === 0)
+        return null;
+    const subject = present.join(' and ');
+    const verb = present.length === 1 ? 'requires' : 'require';
+    return usage('bridge_flag_requires_bridge', `${subject} ${verb} --input-format bridge.`);
+}
+/**
+ * Resolve `--result-schema`, `--result-repair-turns` and `--on-result-unsatisfied`.
+ *
+ * THE FILE IS NOT OPENED HERE. Its contents are the world, and this module is the
+ * flag parser: `exec/index.ts` reads it and reports `result_schema_unreadable`, which
+ * is the same split `--prompt-file` already has.
+ */
+function resolveStructuredResult(raw) {
+    const hasSchema = raw.resultSchema !== undefined;
+    if (!hasSchema) {
+        const orphan = [
+            raw.resultRepairTurns !== undefined ? '--result-repair-turns' : null,
+            raw.onResultUnsatisfied !== undefined ? '--on-result-unsatisfied' : null,
+        ].filter((flag) => flag !== null);
+        if (orphan.length > 0) {
+            // A USAGE ERROR, NOT A WARNING: these two exist only to shape an answer that
+            // will never be requested, so "the run ignores you" would be the whole outcome.
+            return {
+                ok: false,
+                error: usage('result_flag_requires_schema', `${orphan.join(' and ')} ${orphan.length === 1 ? 'requires' : 'require'} --result-schema.`),
+            };
+        }
+        return {
+            ok: true,
+            resultRepairTurns: RESULT_LIMITS.defaultRepairTurns,
+            onResultUnsatisfied: 'error',
+        };
+    }
+    let repairTurns = RESULT_LIMITS.defaultRepairTurns;
+    if (raw.resultRepairTurns !== undefined) {
+        const parsed = parsePositiveInt(raw.resultRepairTurns);
+        if (parsed === null || parsed > RESULT_LIMITS.maxRepairTurns) {
+            return {
+                ok: false,
+                error: usage('invalid_result_repair_turns', `--result-repair-turns must be an integer between 0 and ${RESULT_LIMITS.maxRepairTurns}.`),
+            };
+        }
+        repairTurns = parsed;
+    }
+    const mode = (raw.onResultUnsatisfied ?? 'error').trim();
+    if (!RESULT_UNSATISFIED_MODES.includes(mode)) {
+        return {
+            ok: false,
+            error: usage('invalid_on_result_unsatisfied', `Unknown --on-result-unsatisfied "${mode}". Choose: ${RESULT_UNSATISFIED_MODES.join(', ')}.`),
+        };
+    }
+    return {
+        ok: true,
+        resultSchemaPath: raw.resultSchema,
+        resultRepairTurns: repairTurns,
+        onResultUnsatisfied: mode,
+    };
+}
+/** The two per-request ceilings (section 4.1). Bridge-only, checked one level up. */
+function resolveRequestBudgets(raw) {
+    let requestMaxTurns;
+    if (raw.requestMaxTurns !== undefined) {
+        const parsed = parsePositiveInt(raw.requestMaxTurns);
+        if (parsed === null || parsed < 1 || parsed > REQUEST_LIMITS.maxRequestTurns) {
+            return {
+                ok: false,
+                error: usage('invalid_request_max_turns', `--request-max-turns must be an integer between 1 and ${REQUEST_LIMITS.maxRequestTurns}.`),
+            };
+        }
+        requestMaxTurns = parsed;
+    }
+    let requestMaxDurationMs;
+    if (raw.requestMaxDuration !== undefined) {
+        const parsed = parsePositiveInt(raw.requestMaxDuration);
+        if (parsed === null ||
+            parsed < REQUEST_LIMITS.minRequestTimeoutMs ||
+            parsed > REQUEST_LIMITS.maxRequestTimeoutMs) {
+            return {
+                ok: false,
+                error: usage('invalid_request_max_duration', `--request-max-duration must be an integer between ` +
+                    `${REQUEST_LIMITS.minRequestTimeoutMs} and ${REQUEST_LIMITS.maxRequestTimeoutMs} ` +
+                    '(milliseconds).'),
+            };
+        }
+        requestMaxDurationMs = parsed;
+    }
+    return {
+        ok: true,
+        ...(requestMaxTurns !== undefined ? { requestMaxTurns } : {}),
+        ...(requestMaxDurationMs !== undefined ? { requestMaxDurationMs } : {}),
+    };
+}
+/**
+ * Parse a bounded millisecond flag, or fall back to the protocol default.
+ *
+ * BOTH ENDS ARE CHECKED (review P2-5). A lower bound alone would let
+ * `--decision-timeout 999999999` through, and I-6 ("every ceiling has a number")
+ * would then be false for the one ceiling a caller can set - the number would be
+ * a literal in a flag parser rather than a member of `BRIDGE_LIMITS`.
+ */
+function resolveMilliseconds(options) {
+    if (options.raw === undefined)
+        return { ok: true, value: options.fallback };
+    const parsed = parsePositiveInt(options.raw);
+    if (parsed === null || parsed < options.min || parsed > options.max) {
+        return {
+            ok: false,
+            error: usage(options.code, `${options.flag} must be an integer between ${options.min} and ${options.max} ` +
+                '(milliseconds).'),
+        };
+    }
+    return { ok: true, value: parsed };
+}
+/**
+ * `--threads` and its two ceilings (section 4.1).
+ *
+ * THREE CROSS-CHECKS, and each one names BOTH offenders: `--threads` without bridge has no
+ * frame channel, without `stream-json` has no per-event writer (so no `seq` and no
+ * pre-`init` queue), and with `--max-turns` would apply a process-wide turn budget to a
+ * conversation it cannot describe - the honest advice there is `--request-max-turns`.
+ */
+function resolveThreads(raw, bridge, outputFormat) {
+    const maxOpenThreads = resolveThreadLimit({
+        raw: raw.maxOpenThreads,
+        flag: '--max-open-threads',
+        fallback: THREAD_LIMITS.defaultMaxOpenThreads,
+        min: 1,
+        max: THREAD_LIMITS.maxOpenThreads,
+    });
+    if (!maxOpenThreads.ok)
+        return { ok: false, error: maxOpenThreads.error };
+    const threadConcurrency = resolveThreadLimit({
+        raw: raw.threadConcurrency,
+        flag: '--thread-concurrency',
+        fallback: THREAD_LIMITS.defaultConcurrency,
+        min: 1,
+        max: THREAD_LIMITS.maxOpenThreads,
+    });
+    if (!threadConcurrency.ok)
+        return { ok: false, error: threadConcurrency.error };
+    if (threadConcurrency.value > maxOpenThreads.value) {
+        return {
+            ok: false,
+            error: usage('invalid_thread_limit', `--thread-concurrency (${threadConcurrency.value}) cannot exceed --max-open-threads ` +
+                `(${maxOpenThreads.value}): there would be more slots than threads.`),
+        };
+    }
+    const ceilingGiven = raw.maxOpenThreads !== undefined || raw.threadConcurrency !== undefined;
+    if (ceilingGiven && raw.threads !== true) {
+        // A CEILING FOR A MODE THAT IS OFF IS THE SAME INERT PROMISE as a bridge flag without a
+        // bridge, and this package answers that class with a usage error rather than a no-op.
+        return {
+            ok: false,
+            error: usage('threads_flag_requires_threads', `${raw.maxOpenThreads !== undefined ? '--max-open-threads' : '--thread-concurrency'} ` +
+                'only applies with --threads.'),
+        };
+    }
+    if (raw.threads !== true) {
+        return {
+            ok: true,
+            threads: false,
+            maxOpenThreads: maxOpenThreads.value,
+            threadConcurrency: threadConcurrency.value,
+        };
+    }
+    if (!bridge) {
+        return {
+            ok: false,
+            error: usage('threads_require_bridge', '--threads requires --input-format bridge: a thread is opened, prompted and closed ' +
+                'through the frame channel, which no other input format has.'),
+        };
+    }
+    if (outputFormat !== 'stream-json') {
+        return {
+            ok: false,
+            error: usage('threads_require_stream_json', '--threads requires --output-format stream-json: thread events and their `threadId` ' +
+                'need the per-event writer.'),
+        };
+    }
+    if (raw.maxTurns !== undefined) {
+        return {
+            ok: false,
+            error: usage('threads_flag_conflict', '--max-turns cannot be combined with --threads: one process-wide turn budget has no ' +
+                'honest meaning across N conversations. Use --request-max-turns instead.'),
+        };
+    }
+    return {
+        ok: true,
+        threads: true,
+        maxOpenThreads: maxOpenThreads.value,
+        threadConcurrency: threadConcurrency.value,
+    };
+}
+function resolveThreadLimit(options) {
+    if (options.raw === undefined)
+        return { ok: true, value: options.fallback };
+    const parsed = parsePositiveInt(options.raw);
+    if (parsed === null || parsed < options.min || parsed > options.max) {
+        return {
+            ok: false,
+            error: usage('invalid_thread_limit', `${options.flag} must be an integer between ${options.min} and ${options.max}.`),
+        };
+    }
+    return { ok: true, value: parsed };
+}
+/**
+ * `--on-hook-timeout`, alone in its own resolver.
+ *
+ * A HOOK POLICY IS NOT A THREAD CEILING, and the first version of this file parsed it inside
+ * `resolveThreads` because the mode has to be known before the timeout is clamped. That put a
+ * hook rule in a thread function and made `--on-hook-timeout` unreadable to anyone looking for
+ * it under "hooks". The dependency is the other way round: the policy is resolved first and
+ * handed to `resolveHooks`.
+ */
+function resolveHookPolicy(raw) {
+    const mode = (raw.onHookTimeout ?? 'deny').trim();
+    if (!ON_HOOK_TIMEOUT_MODES.includes(mode)) {
+        return {
+            ok: false,
+            error: usage('invalid_on_hook_timeout', `Unknown --on-hook-timeout "${mode}". Choose: ${ON_HOOK_TIMEOUT_MODES.join(', ')}.`),
+        };
+    }
+    return { ok: true, value: mode };
+}
+/**
+ * `--hook-timeout` (section 2.4.8).
+ *
+ * THE `allow` CLAMP IS A RULE, NOT A CONVENIENCE (review P2-1): a tool can be asked twice
+ * (`tool_pre` + `tool_post`) and `ToolExecutor`'s own budget is 120 s, so two round trips
+ * that may each consume the full 60 s could starve a legitimate tool call. Under `deny` and
+ * `error` the ceiling stays at 60 s, because those stop the tool at the deadline instead of
+ * waiting longer.
+ */
+function resolveHooks(raw, proposed) {
+    const max = proposed === 'allow' ? HOOK_LIMITS.allowModeMaxTimeoutMs : HOOK_LIMITS.maxTimeoutMs;
+    if (raw.hookTimeout === undefined) {
+        const fallback = Math.min(HOOK_LIMITS.defaultTimeoutMs, max);
+        return { ok: true, hookTimeoutMs: fallback };
+    }
+    const parsed = parsePositiveInt(raw.hookTimeout);
+    if (parsed === null || parsed < HOOK_LIMITS.minTimeoutMs || parsed > max) {
+        return {
+            ok: false,
+            error: usage('invalid_hook_timeout', `--hook-timeout must be an integer between ${HOOK_LIMITS.minTimeoutMs} and ${max}` +
+                (proposed === 'allow' ? ' under --on-hook-timeout allow.' : '.')),
+        };
+    }
+    return { ok: true, hookTimeoutMs: parsed };
+}
 function checkSessionFlags(raw) {
     if (raw.sessionId !== undefined) {
         const id = raw.sessionId.trim();

package/dist/exec/permission.d.ts

@@ -25,7 +25,15 @@
  * plan mode the point is that the model KNOWS the write exists and is being
  * deferred; for a deny list the point is the opposite (D-4).
  */
-export type PermissionMode = 'auto' | 'plan' | 'strict';
+/**
+ * `ask` is the fourth baseline and it CHANGES NOTHING HERE (headless-host-bridge
+ * section 2.3.2). It filters no tool - an `ask` run registers exactly what an `auto` run
+ * registers - because what it changes is the CALL: `withToolApproval` makes the
+ * mutating tools wait for the caller first. Keeping the filter identical is what
+ * makes `--permission-mode ask --deny-tool bash` mean "not registered, not asked"
+ * rather than "asked and then filtered".
+ */
+export type PermissionMode = 'auto' | 'plan' | 'strict' | 'ask';
 export interface ToolPermission {
     mode: PermissionMode;
     allow: ReadonlySet<string>;

package/dist/exec/permission.js

@@ -82,7 +82,13 @@ export function resolveToolAllowList(registered, mode, allow, deny) {
  * alias of `-p --plan`.
  */
 export function resolvePermission(input) {
-    if (input.mode !== 'strict' && input.allow.length === 0 && input.deny.length === 0) {
+    // `ask` ALWAYS PRODUCES AN OBJECT, even with both lists empty, for the reason
+    // `strict` does: an empty allow list under `ask` is a posture ("ask me about
+    // everything in `CALLER_GATED_TOOLS`"), not the absence of one. It still filters
+    // nothing - `decide()` returns `true` for every name under `ask` apart from the
+    // deny list - so the array it hands back is the array `auto` would have built.
+    const alwaysPresent = input.mode === 'strict' || input.mode === 'ask';
+    if (!alwaysPresent && input.allow.length === 0 && input.deny.length === 0) {
         return undefined;
     }
     const allow = new Set(input.allow);