@scotthuang/agent-knock-knock 0.13.2 → 0.13.3

package/dist/src/openclaw-plugin-helpers.js

@@ -239,6 +239,43 @@ function parseAkkLifecycleCommand(action, rest) {
         }
         return { action: "list-resumable-threads", terminalId };
     }
+    if (action === "models" || action === "model-options") {
+        const usage = "Usage: /akk models <exact-terminal-id>";
+        const { token: terminalId, rest: extra } = takeRequiredToken(rest, usage);
+        assertExactTerminalId(terminalId, usage);
+        if (extra.trim()) {
+            throw new Error(usage);
+        }
+        return { action: "model-options", terminalId };
+    }
+    if (action === "repair-model-control") {
+        const usage = "Usage: /akk repair-model-control <exact-terminal-id>";
+        const { token: terminalId, rest: extra } = takeRequiredToken(rest, usage);
+        assertExactTerminalId(terminalId, usage);
+        if (extra.trim()) {
+            throw new Error(usage);
+        }
+        return { action: "repair-model-control", terminalId };
+    }
+    if (action === "set-model") {
+        const usage = "Usage: /akk set-model <exact-terminal-id> <advertised-model-id> " +
+            "<advertised-reasoning-effort>";
+        const { token: terminalId, rest: modelInput } = takeRequiredToken(rest, usage);
+        assertExactTerminalId(terminalId, usage);
+        const { token: model, rest: effortInput } = takeRequiredToken(modelInput, usage);
+        const { token: reasoningEffort, rest: extra } = takeRequiredToken(effortInput, usage);
+        if (extra.trim() ||
+            !isAkkModelSemanticIdentifier(model, 160) ||
+            !/^[a-z][a-z0-9_-]{0,63}$/u.test(reasoningEffort)) {
+            throw new Error(usage);
+        }
+        return {
+            action: "set-model",
+            terminalId,
+            model,
+            reasoningEffort
+        };
+    }
     if (action === "new-thread" || action === "clear-thread") {
         const usage = `Usage: /akk ${action} <exact-terminal-id>`;
         const { token: terminalId, rest: extra } = takeRequiredToken(rest, usage);
@@ -378,6 +415,9 @@ export function akkUsageText() {
         "/akk watch <exact-terminal-id>",
         "/akk unwatch <watch-id>",
         "/akk threads <exact-terminal-id>",
+        "/akk models <exact-terminal-id>",
+        "/akk repair-model-control <exact-terminal-id>",
+        "/akk set-model <exact-terminal-id> <advertised-model-id> <advertised-reasoning-effort>",
         "/akk new-thread <exact-terminal-id>",
         "/akk clear-thread <exact-terminal-id>",
         "/akk resume-thread <exact-terminal-id> [uuid|previous|number|@short-id]",
@@ -385,7 +425,10 @@ export function akkUsageText() {
         "/akk status [turn-selector|terminal-watch-id]",
         "/akk respond <turn-selector>: <answer>",
         "/akk approve <turn-selector> [approve_once|reject]",
-        "/akk cancel <turn-selector>"
+        "/akk cancel <turn-selector>",
+        "Model control targets one exact physical pane; Codex rollout attribution and identify-foreground are not prerequisites.",
+        "Repair-model-control is advertised only for an exact stale Codex /model Composer surface or open native picker; it clears no other draft, never presses Enter, and never submits or selects anything.",
+        "Models normally requires an idle, empty, prompt-free UI with no active Turn; for an exactly advertised Codex 0.154 /model residue it may continue that residue into read-only catalog discovery. Successful discovery consumes any residual-entry authority, restores the exact empty UI, and issues a fresh ordinary one-shot set-model offer; set-model accepts only that offer. If the result is uncertain, inspect the pane and do not retry automatically."
     ].join("\n");
 }
 export function formatAkkListCommandResult(result) {
@@ -485,6 +528,500 @@ export function formatAkkListCommandResult(result) {
             : [])
     ].join("\n");
 }
+/**
+ * Keep every structured controller-Host List result below its model-output
+ * budget without weakening the private action-authority path.
+ *
+ * The CLI remains the complete operator/debug contract.  The controller receives a
+ * terminal-first projection: current resource identities and state, action
+ * names, and only the dynamic semantic inputs needed to invoke those actions.
+ * Static explanations live in the bundled agent-knock-knock skill.
+ */
+export function compactAkkListModelProjection(value) {
+    const result = recordValue(value) ?? {};
+    const actionContracts = recordValue(result.action_contracts);
+    const diagnostics = compactAkkListDiagnostics(result);
+    const recovery = compactAkkListControlState(result.recovery);
+    return {
+        projection: {
+            schema: "agent-knock-knock/host-list-compact",
+            version: 1,
+            skill: "agent-knock-knock",
+            ...(finiteNumber(actionContracts?.version) !== undefined
+                ? { action_contract_version: finiteNumber(actionContracts?.version) }
+                : {})
+        },
+        terminals: arrayValue(result.terminals).map(compactAkkListTerminal),
+        terminal_watches: arrayValue(result.terminal_watches)
+            .map(compactAkkListWatch),
+        unavailable_managed_turns: arrayValue(result.unavailable_managed_turns)
+            .map((turn) => compactAkkListTurn(turn, true)),
+        ...(recovery ? { recovery } : {}),
+        ...(Object.keys(diagnostics).length > 0 ? { diagnostics } : {})
+    };
+}
+function compactAkkListTerminal(terminal) {
+    const output = compactAkkListScalars(terminal, [
+        "id",
+        "short_ref",
+        "source",
+        "agent",
+        "agent_version",
+        "pid",
+        "cwd",
+        "process_state",
+        "screen_state",
+        "activity_state",
+        "durable_activity_state",
+        "native_identity_state",
+        "native_agent_session_id",
+        "management_state",
+        "handoff_state",
+        "confidence"
+    ]);
+    const workspace = nonEmptyString(terminal.workspace);
+    if (workspace && workspace !== nonEmptyString(terminal.cwd)) {
+        output.workspace = workspace;
+    }
+    const command = nonEmptyString(terminal.command);
+    if (command)
+        output.command = truncateText(command, 160);
+    compactAkkListNested(output, "terminal_control", terminal.terminal_control, ["kind", "target"]);
+    compactAkkListNested(output, "approval_state", terminal.approval_state, [
+        "scanned", "blocked", "approvable", "state", "kind", "decision_mode"
+    ]);
+    const features = compactAkkListFeatures(terminal);
+    if (Object.keys(features).length > 0)
+        output.features = features;
+    const managed = compactAkkListManaged(terminal.managed);
+    if (managed)
+        output.managed = managed;
+    const managementConflict = compactAkkListControlState(terminal.management_conflict);
+    if (managementConflict)
+        output.management_conflict = managementConflict;
+    const managementUnavailable = recordValue(terminal.management_unavailable);
+    if (managementUnavailable)
+        output.management_unavailable = true;
+    const handoffDecision = compactAkkListHandoffDecision(terminal.handoff_decision);
+    if (handoffDecision)
+        output.handoff_decision = handoffDecision;
+    const blockingTurns = arrayValue(terminal.blocking_turns)
+        .map(compactAkkListBlockingTurn);
+    if (blockingTurns.length > 0)
+        output.blocking_turns = blockingTurns;
+    const managedRecord = recordValue(terminal.managed);
+    const currentTurn = recordValue(managedRecord?.current_turn);
+    Object.assign(output, compactAkkListActions(terminal.available_actions, {
+        terminal_id: terminal.id,
+        conversation_id: terminal.id,
+        session_id: managedRecord?.session_id,
+        turn_id: currentTurn?.turn_id ?? currentTurn?.conversation_id ??
+            currentTurn?.id
+    }));
+    addAkkListWarningFlags(output, terminal);
+    return output;
+}
+function compactAkkListFeatures(terminal) {
+    const output = {};
+    const lifecycle = recordValue(terminal.native_thread_lifecycle);
+    const inspection = recordValue(terminal.native_inspection);
+    const modelControl = recordValue(terminal.model_control);
+    if (typeof lifecycle?.status === "string") {
+        output.native_threads = lifecycle.status;
+    }
+    if (typeof inspection?.status === "string") {
+        output.native_inspection = inspection.status;
+    }
+    if (typeof modelControl?.status === "string") {
+        const model = compactAkkListScalars(modelControl, ["status", "scope"]);
+        output.model_control = Object.keys(model).length === 1
+            ? model.status
+            : model;
+    }
+    return output;
+}
+function compactAkkListManaged(value) {
+    const managed = recordValue(value);
+    if (!managed)
+        return undefined;
+    const output = compactAkkListScalars(managed, [
+        "session_id",
+        "session_short_ref",
+        "native_thread_id",
+        "binding_status",
+        "turn_count",
+        "hidden_turn_count",
+        "session_count"
+    ]);
+    const currentTurn = recordValue(managed.current_turn);
+    const recentTurn = recordValue(managed.recent_turn);
+    output.current_turn = currentTurn ? compactAkkListTurn(currentTurn) : null;
+    output.recent_turn = recentTurn ? compactAkkListTurn(recentTurn) : null;
+    const history = arrayValue(managed.history)
+        .map((turn) => compactAkkListTurn(turn));
+    if (history.length > 0)
+        output.history = history;
+    return output;
+}
+function compactAkkListTurn(turn, standalone = false) {
+    const output = compactAkkListScalars(turn, [
+        "short_ref",
+        "status",
+        "lifecycle_state",
+        "session_id",
+        "turn_id",
+        "updated_at",
+        "response_rounds_used"
+    ]);
+    const turnId = nonEmptyString(turn.turn_id ?? turn.conversation_id ?? turn.id);
+    if (turnId)
+        output.turn_id = turnId;
+    if (standalone) {
+        Object.assign(output, compactAkkListScalars(turn, [
+            "source", "agent", "workspace", "created_at"
+        ]));
+    }
+    compactAkkListNested(output, "approval_state", turn.approval_state, [
+        "scanned", "blocked", "approvable", "state", "kind", "decision_mode"
+    ]);
+    const interaction = compactAkkListInteraction(turn.interaction_state);
+    if (interaction)
+        output.interaction_state = interaction;
+    const terminalAvailability = compactAkkListControlState(turn.terminal_availability);
+    if (terminalAvailability) {
+        output.terminal_availability = terminalAvailability;
+    }
+    else if (typeof turn.terminal_availability === "string" ||
+        typeof turn.terminal_availability === "boolean") {
+        output.terminal_availability = turn.terminal_availability;
+    }
+    Object.assign(output, compactAkkListActions(turn.available_actions, {
+        session_id: turn.session_id,
+        turn_id: turnId,
+        conversation_id: turnId
+    }));
+    addAkkListWarningFlags(output, turn);
+    return output;
+}
+function compactAkkListWatch(watch) {
+    const output = compactAkkListScalars(watch, [
+        "watch_id",
+        "short_ref",
+        "source",
+        "watch_mode",
+        "confidence",
+        "interaction_policy",
+        "agent",
+        "terminal_id",
+        "native_thread_id",
+        "workspace",
+        "status",
+        "activity_state",
+        "created_at",
+        "deadline_at",
+        "updated_at",
+        "last_activity_at"
+    ]);
+    compactAkkListNested(output, "capabilities", watch.capabilities, [
+        "interaction_notify", "interaction_respond"
+    ]);
+    compactAkkListNested(output, "callback", watch.callback, [
+        "pending", "delivered", "failed", "superseded", "last_error_code"
+    ]);
+    const interaction = compactAkkListInteraction(watch.interaction_state);
+    if (interaction)
+        output.interaction_state = interaction;
+    const settlement = recordValue(watch.settlement);
+    if (settlement) {
+        const compactSettlement = compactAkkListScalars(settlement, [
+            "kind", "observed_at", "reason_code", "completion_id",
+            "completion_timestamp"
+        ]);
+        if (Object.keys(compactSettlement).length > 0) {
+            output.settlement = compactSettlement;
+        }
+    }
+    Object.assign(output, compactAkkListActions(watch.available_actions, {
+        terminal_id: watch.terminal_id,
+        watch_id: watch.watch_id
+    }));
+    addAkkListWarningFlags(output, watch);
+    return output;
+}
+function compactAkkListInteraction(value) {
+    const interaction = recordValue(value);
+    if (!interaction)
+        return undefined;
+    const output = compactAkkListScalars(interaction, [
+        "state", "response_kind", "current_step", "total_steps",
+        "response_authority"
+    ]);
+    compactAkkListNested(output, "capabilities", interaction.capabilities, [
+        "respond", "single_select", "multi_select", "free_text", "confirm"
+    ]);
+    return Object.keys(output).length > 0 ? output : undefined;
+}
+function compactAkkListActions(value, parentIds = {}) {
+    const actions = recordValue(value);
+    if (!actions)
+        return {};
+    const availableActions = {};
+    const actionInputs = {};
+    for (const [name, actionValue] of Object.entries(actions)) {
+        const action = recordValue(actionValue);
+        if (!action)
+            continue;
+        availableActions[name] = true;
+        const input = compactAkkListActionInput(name, action, parentIds);
+        if (Object.keys(input).length > 0)
+            actionInputs[name] = input;
+    }
+    return {
+        ...(Object.keys(availableActions).length > 0
+            ? { available_actions: availableActions }
+            : {}),
+        ...(Object.keys(actionInputs).length > 0
+            ? { action_inputs: actionInputs }
+            : {})
+    };
+}
+function compactAkkListActionInput(name, action, parentIds = {}) {
+    const output = {};
+    const tool = nonEmptyString(action.tool);
+    const expectedTool = name === "retry_submission"
+        ? "agent_knock_knock_send"
+        : `agent_knock_knock_${name}`;
+    if (tool && tool !== expectedTool)
+        output.tool = tool;
+    const args = compactAkkListActionArguments(action.arguments, name, parentIds);
+    if (Object.keys(args).length > 0)
+        output.arguments = args;
+    const missingRequired = stringArrayValue(action.missing_required)
+        .filter((field) => !isAkkModelFacingPrivateAuthorityField(field));
+    if (missingRequired.length > 0) {
+        output.missing_required = missingRequired;
+    }
+    for (const key of ["scope", "decision_mode"]) {
+        const item = action[key];
+        if (typeof item === "string" ||
+            typeof item === "boolean" ||
+            typeof item === "number")
+            output[key] = item;
+    }
+    for (const key of ["decisions", "choices"]) {
+        const values = stringArrayValue(action[key]);
+        if (values.length > 0)
+            output[key] = values;
+    }
+    return output;
+}
+function compactAkkListActionArguments(value, actionName, parentIds) {
+    const args = recordValue(value);
+    if (!args)
+        return {};
+    const output = {};
+    for (const [key, item] of Object.entries(args)) {
+        if (isAkkModelFacingPrivateAuthorityField(key) ||
+            ["request", "text", "body", "description", "instruction", "use"]
+                .includes(key))
+            continue;
+        const compact = compactAkkListSemanticValue(item, 0);
+        if (compact !== undefined)
+            output[key] = compact;
+    }
+    const selector = nonEmptyString(output.selector);
+    if (actionName === "send" &&
+        selector &&
+        /^terminal:v[0-9]+:\S+$/u.test(selector)) {
+        delete output.selector;
+        output.terminal_id = selector;
+    }
+    const conversationId = nonEmptyString(output.conversation_id);
+    if (actionName === "approve" &&
+        conversationId &&
+        /^terminal:v[0-9]+:\S+$/u.test(conversationId)) {
+        delete output.conversation_id;
+        output.terminal_id = conversationId;
+    }
+    for (const key of [
+        "terminal_id", "session_id", "turn_id", "conversation_id", "watch_id"
+    ]) {
+        if (output[key] !== undefined && output[key] === parentIds[key]) {
+            delete output[key];
+        }
+    }
+    return output;
+}
+function compactAkkListSemanticValue(value, depth) {
+    if (value === null ||
+        typeof value === "string" ||
+        typeof value === "boolean" ||
+        (typeof value === "number" && Number.isFinite(value)))
+        return value;
+    if (depth >= 3)
+        return undefined;
+    if (Array.isArray(value)) {
+        return value.slice(0, 32).flatMap((item) => {
+            const compact = compactAkkListSemanticValue(item, depth + 1);
+            return compact === undefined ? [] : [compact];
+        });
+    }
+    const record = recordValue(value);
+    if (!record)
+        return undefined;
+    const output = {};
+    for (const [key, item] of Object.entries(record)) {
+        if (isAkkModelFacingPrivateAuthorityField(key))
+            continue;
+        const compact = compactAkkListSemanticValue(item, depth + 1);
+        if (compact !== undefined)
+            output[key] = compact;
+    }
+    return output;
+}
+function compactAkkListHandoffDecision(value) {
+    const decision = recordValue(value);
+    if (!decision)
+        return undefined;
+    const output = compactAkkListScalars(decision, [
+        "kind", "source_session_id", "source_turn_id"
+    ]);
+    const choices = recordValue(decision.choices);
+    if (choices) {
+        const compactChoices = {};
+        for (const [name, choiceValue] of Object.entries(choices)) {
+            const choice = recordValue(choiceValue);
+            if (!choice)
+                continue;
+            const action = compactAkkListNamedAction(choice.action);
+            compactChoices[name] = action ? { action } : true;
+        }
+        if (Object.keys(compactChoices).length > 0)
+            output.choices = compactChoices;
+    }
+    return Object.keys(output).length > 0 ? output : undefined;
+}
+function compactAkkListBlockingTurn(value) {
+    const output = compactAkkListScalars(value, [
+        "session_id", "turn_id", "status"
+    ]);
+    const recoveryAction = compactAkkListNamedAction(value.recovery_action);
+    if (recoveryAction)
+        output.recovery_action = recoveryAction;
+    return output;
+}
+function compactAkkListNamedAction(value) {
+    const action = recordValue(value);
+    if (!action)
+        return undefined;
+    const tool = nonEmptyString(action.tool);
+    const name = tool?.replace(/^agent_knock_knock_/u, "") ?? "action";
+    const input = compactAkkListActionInput(name, action);
+    return {
+        name,
+        ...(Object.keys(input).length > 0 ? input : {})
+    };
+}
+function compactAkkListControlState(value) {
+    const record = recordValue(value);
+    if (!record)
+        return undefined;
+    const output = {};
+    for (const [key, item] of Object.entries(record)) {
+        if (isAkkModelFacingPrivateAuthorityField(key) ||
+            /(?:reason|recovery|instruction|description|evidence|path)$/iu.test(key))
+            continue;
+        const keep = /(?:^|_)(?:id|state|status|kind|mode|scope|code|count|owner)$/u
+            .test(key) || typeof item === "boolean" || typeof item === "number";
+        if (!keep)
+            continue;
+        const compact = compactAkkListSemanticValue(item, 0);
+        if (compact !== undefined)
+            output[key] = compact;
+    }
+    return Object.keys(output).length > 0 ? output : undefined;
+}
+function compactAkkListDiagnostics(result) {
+    const output = {};
+    compactAkkListNested(output, "store", result.store, [
+        "status", "readable", "writable", "upgradeable", "format_version",
+        "writer_protocol"
+    ]);
+    const reconciliation = recordValue(result.reconciliation);
+    if (reconciliation) {
+        const compact = compactAkkListDiagnosticRecord(reconciliation);
+        if (Object.keys(compact).length > 0)
+            output.reconciliation = compact;
+    }
+    const scan = recordValue(result.terminal_scan);
+    if (scan) {
+        const compact = compactAkkListDiagnosticRecord(scan);
+        if (Array.isArray(scan.agents)) {
+            compact.agents = scan.agents.filter((item) => typeof item === "string");
+        }
+        if (scan.diagnostics !== undefined)
+            compact.provider_diagnostics = true;
+        if (Object.keys(compact).length > 0)
+            output.terminal_scan = compact;
+    }
+    return output;
+}
+function compactAkkListDiagnosticRecord(value) {
+    const output = {};
+    for (const [key, item] of Object.entries(value)) {
+        if (key === "reason" ||
+            key === "diagnostics" ||
+            /(?:^|_)(?:path|dir)$/u.test(key))
+            continue;
+        if (typeof item === "boolean" ||
+            (typeof item === "number" && Number.isFinite(item)) ||
+            (typeof item === "string" && key !== "error"))
+            output[key] = item;
+        if (key === "error" && typeof item === "string") {
+            output.error = truncateText(item, 300);
+        }
+        if (Array.isArray(item) && key === "errors") {
+            output.error_count = item.length;
+        }
+    }
+    if (nonEmptyString(value.reason) &&
+        !["ok", "healthy", "compatible", "disabled"]
+            .includes(nonEmptyString(value.status) ?? "")) {
+        output.message = truncateText(value.reason, 300);
+    }
+    return output;
+}
+function compactAkkListScalars(value, keys) {
+    const output = {};
+    for (const key of keys) {
+        const item = value[key];
+        if (item === null ||
+            typeof item === "string" ||
+            typeof item === "boolean" ||
+            (typeof item === "number" && Number.isFinite(item)))
+            output[key] = item;
+    }
+    return output;
+}
+function compactAkkListNested(output, key, value, keys) {
+    const record = recordValue(value);
+    if (!record)
+        return;
+    const compact = compactAkkListScalars(record, keys);
+    if (Object.keys(compact).length > 0)
+        output[key] = compact;
+}
+function addAkkListWarningFlags(output, value) {
+    const compatibilityWarnings = [
+        nonEmptyString(value.compatibility_warning),
+        ...stringArrayValue(value.compatibility_warnings)
+    ].filter((item) => Boolean(item));
+    if (compatibilityWarnings.length > 0)
+        output.compatibility_warning = true;
+    const warnings = stringArrayValue(value.warnings);
+    if (warnings.length > 0)
+        output.warning_count = warnings.length;
+}
 export function formatAkkWatchCommandResult(result) {
     const watch = terminalWatchRecord(result);
     return [
@@ -720,6 +1257,108 @@ export function formatAkkThreadsCommandResult(result) {
         "Listing or switching native threads does not create an AKK Turn."
     ].join("\n");
 }
+export function formatAkkModelOptionsCommandResult(result) {
+    const terminalId = nonEmptyString(result.terminal_id) ?? "unknown";
+    const scope = nonEmptyString(result.scope) ?? "unknown";
+    const current = recordValue(result.current) ?? {};
+    const models = arrayValue(result.models);
+    const modelLines = models.slice(0, 50).map((entry) => {
+        const id = nonEmptyString(entry.id) ?? "unknown";
+        const label = nonEmptyString(entry.label);
+        const efforts = stringArrayValue(entry.reasoning_efforts);
+        return `- ${id}${label && label !== id ? ` (${label})` : ""}` +
+            `${efforts.length > 0 ? ` | reasoning: ${efforts.join(", ")}` : ""}`;
+    });
+    return [
+        `AKK model options (${models.length} models):`,
+        `terminal: ${terminalId}`,
+        `agent: ${nonEmptyString(result.agent) ?? "unknown"}`,
+        `scope: ${scope}`,
+        `current model: ${nonEmptyString(current.model) ?? "unknown"}`,
+        `current reasoning: ${nonEmptyString(current.reasoning_effort) ?? "unobserved"}`,
+        ...compatibilityWarningLines(result),
+        ...(modelLines.length > 0 ? ["models:", ...modelLines] : ["models: none"]),
+        scope === "current_and_new_sessions"
+            ? "Codex applies this selection to the current session and persists the selected model and ordinary efforts (including max) for new sessions; ultra applies only now and uses a native non-ultra future fallback."
+            : "Claude Code applies this selection only to the current session; new-session defaults are unchanged.",
+        `next: /akk set-model ${terminalId} <advertised-model-id> <advertised-reasoning-effort>`,
+        "This successful catalog result has restored an exact empty Composer and carries a fresh ordinary private offer for one set-model attempt in the current controller. Residual-entry authority was consumed by model-options and is never reusable by set-model. A Codex rollout and identify-foreground are not prerequisites. Refresh /akk models after any terminal change or failed attempt."
+    ].join("\n");
+}
+export function formatAkkSetModelCommandResult(result) {
+    const outcome = nonEmptyString(result.outcome) ?? "uncertain";
+    const requested = recordValue(result.requested) ?? {};
+    const effective = recordValue(result.effective) ?? {};
+    const newSessionDefaults = recordValue(result.new_session_defaults) ?? {};
+    const uncertain = outcome === "uncertain" || result.do_not_retry === true;
+    const defaultsChanged = typeof result.defaults_changed === "boolean"
+        ? result.defaults_changed ? "yes" : "no"
+        : "unknown";
+    const requestedUltra = requested.reasoning_effort === "ultra";
+    return [
+        outcome === "changed"
+            ? "AKK changed and verified the coding-agent model."
+            : outcome === "already_effective"
+                ? "AKK verified that the requested model was already effective."
+                : "AKK could not prove the complete model-change postcondition.",
+        `terminal: ${nonEmptyString(result.terminal_id) ?? "unknown"}`,
+        `scope: ${nonEmptyString(result.scope) ?? "unknown"}`,
+        `requested model: ${nonEmptyString(requested.model) ?? "unknown"}`,
+        `requested reasoning: ${nonEmptyString(requested.reasoning_effort) ?? "unchanged/default"}`,
+        `effective model: ${nonEmptyString(effective.model) ?? "unproven"}`,
+        `effective reasoning: ${nonEmptyString(effective.reasoning_effort) ?? "unproven"}`,
+        `new-session default changed: ${defaultsChanged}`,
+        ...(nonEmptyString(newSessionDefaults.model)
+            ? [`new-session default model: ${nonEmptyString(newSessionDefaults.model)}`]
+            : []),
+        ...(nonEmptyString(newSessionDefaults.reasoning_effort)
+            ? [`new-session default reasoning: ${nonEmptyString(newSessionDefaults.reasoning_effort)}`]
+            : requestedUltra && result.scope === "current_and_new_sessions" && outcome === "changed"
+                ? ["new-session default reasoning: native non-ultra fallback (exact value is not exposed by this Codex TUI)"]
+                : []),
+        ...compatibilityWarningLines(result),
+        ...(nonEmptyString(result.reason)
+            ? [
+                `reason: ${sanitizeAkkModelFacingDiagnosticText(nonEmptyString(result.reason) ?? "")}`
+            ]
+            : []),
+        uncertain
+            ? "Next: do not retry automatically; inspect the shared pane, then refresh /akk models before any deliberate new attempt."
+            : "No task, approval, questionnaire response, or AKK Turn was created."
+    ].join("\n");
+}
+export function formatAkkRepairModelControlCommandResult(result) {
+    const outcome = nonEmptyString(result.outcome) ?? "uncertain";
+    const repaired = outcome === "repaired";
+    const uncertain = outcome === "uncertain" || result.do_not_retry === true;
+    return [
+        repaired
+            ? "AKK cleared and verified the exact stale Codex /model surface."
+            : "AKK could not prove the model-control repair postcondition.",
+        `terminal: ${nonEmptyString(result.terminal_id) ?? "unknown"}`,
+        `composer postcondition: ${nonEmptyString(result.composer_postcondition) ?? "unproven"}`,
+        `terminal input attempted: ${result.terminal_input_attempted === true ? "yes" : "no"}`,
+        ...compatibilityWarningLines(result),
+        ...(nonEmptyString(result.reason)
+            ? [
+                `reason: ${sanitizeAkkModelFacingDiagnosticText(nonEmptyString(result.reason) ?? "")}`
+            ]
+            : []),
+        uncertain
+            ? "Next: do not retry automatically; inspect the shared pane and refresh /akk list."
+            : "Next: refresh /akk list, then run /akk models before any deliberate set-model attempt.",
+        "This repair never submits a task, chooses a model, approves a prompt, or creates an AKK Turn."
+    ].join("\n");
+}
+export function isAkkRepairModelControlSuccess(result) {
+    const record = recordValue(result);
+    return record?.outcome === "repaired" || record?.outcome === "already_empty";
+}
+export function isAkkSetModelSuccess(result) {
+    const record = recordValue(result);
+    return record?.outcome === "changed" ||
+        record?.outcome === "already_effective";
+}
 export function formatAkkThreadTransitionCommandResult(result) {
     if (!isAkkThreadTransitionSuccess(result)) {
         const status = nonEmptyString(result.status) ?? "unknown";
@@ -805,6 +1444,34 @@ export function buildAkkCommandCliArgs(command, config, context = {}) {
                 "--terminal",
                 command.terminalId
             ], ["--store-dir", storeDir], ["--codex-home", codexHome], ["--selection-scope", nonEmptyString(context.selectionScope)]);
+        case "model-options":
+            return withOptionalArgs([
+                "model-options",
+                "--terminal",
+                command.terminalId,
+                "--expected-binding-token",
+                requiredExpectedBindingToken(context.expectedBindingToken)
+            ], ["--store-dir", storeDir], ["--codex-home", codexHome]);
+        case "repair-model-control":
+            return withOptionalArgs([
+                "repair-model-control",
+                "--terminal",
+                command.terminalId,
+                "--expected-binding-token",
+                requiredExpectedBindingToken(context.expectedBindingToken)
+            ], ["--store-dir", storeDir], ["--codex-home", codexHome]);
+        case "set-model":
+            return withOptionalArgs([
+                "set-model",
+                "--terminal",
+                command.terminalId,
+                "--expected-binding-token",
+                requiredExpectedBindingToken(context.expectedBindingToken),
+                "--expected-catalog-fingerprint",
+                requiredExpectedCatalogFingerprint(context.expectedCatalogFingerprint),
+                "--model",
+                command.model
+            ], ["--reasoning-effort", command.reasoningEffort], ["--store-dir", storeDir], ["--codex-home", codexHome]);
         case "new-thread":
             return withOptionalArgs([
                 "new-thread",
@@ -944,6 +1611,10 @@ function assertExactTerminalId(value, usage) {
         throw new Error(`${usage}; use the exact terminal_id returned by /akk list`);
     }
 }
+function isAkkModelSemanticIdentifier(value, maxLength) {
+    return value.length <= maxLength &&
+        /^[A-Za-z0-9][A-Za-z0-9._:/+\-]*$/u.test(value);
+}
 function isExactNativeThreadId(value) {
     return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu.test(value);
 }
@@ -980,6 +1651,13 @@ function requiredCandidateToken(value) {
     }
     return token;
 }
+function requiredExpectedCatalogFingerprint(value) {
+    const fingerprint = nonEmptyString(value);
+    if (!fingerprint) {
+        throw new Error("expected catalog fingerprint is required; refresh model options before switching the model");
+    }
+    return fingerprint;
+}
 function requiredSelectionScope(value) {
     const scope = nonEmptyString(value);
     if (!scope) {
@@ -1126,7 +1804,9 @@ function formatAvailableActions(label, resource) {
         "list_resumable_threads",
         "new_thread",
         "resume_thread",
-        "native_inspect"
+        "native_inspect",
+        "model_options",
+        "repair_model_control"
     ]);
     const names = Object.keys(actions)
         .filter((name) => displayedActions.has(name))