@retaw106/mmc-oc 0.0.0-stage → 1.2.2

package/src/config/raw-loader.ts

@@ -0,0 +1,435 @@
+import {
+    closeSync,
+    existsSync,
+    linkSync,
+    openSync,
+    readFileSync,
+    realpathSync,
+    renameSync,
+    statSync,
+    unlinkSync,
+    writeFileSync,
+} from "node:fs";
+import { basename, dirname, join } from "node:path";
+
+import { removeJsoncValue, setJsoncValue } from "../shared/jsonc-edit";
+import { parseJsonc } from "../shared/jsonc-parser";
+
+export type ConfigTier = "user" | "project";
+
+export interface FlatConfigDiagnostic {
+    path: string;
+    message: string;
+}
+
+export interface FlatConfigMigration {
+    bytes: Buffer;
+    hasFlatKeys: boolean;
+    diagnostics: FlatConfigDiagnostic[];
+}
+
+export interface RawConfigLoadOptions {
+    configPath: string;
+    tier: ConfigTier;
+    /** Test-only seam for making a competing loader replace the target before this loader re-checks it. */
+    afterTemporaryWrite?: () => void;
+}
+
+export interface RawConfigLoadResult {
+    configPath: string;
+    bytes: Buffer;
+    text: string;
+    warnings: string[];
+    migrated: boolean;
+}
+
+const MODEL_FIELDS = ["model", "fallback_models"] as const;
+const PRE_PER_HARNESS_BACKUP_SUFFIX = ".pre-per-harness.bak";
+let temporaryFileSequence = 0;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function asDocument(text: string): Record<string, unknown> | null {
+    try {
+        // JSON.parse rejects a UTF-8 BOM, while JSONC files commonly retain one.
+        // Remove it only for inspection; every byte-writing path adds it back.
+        const document = parseJsonc<unknown>(text.startsWith("\uFEFF") ? text.slice(1) : text);
+        return isRecord(document) ? document : null;
+    } catch {
+        return null;
+    }
+}
+
+function getAtPath(document: Record<string, unknown>, path: readonly string[]): unknown {
+    let current: unknown = document;
+    for (const part of path) {
+        if (!isRecord(current) || !Object.hasOwn(current, part)) return undefined;
+        current = current[part];
+    }
+    return current;
+}
+
+function stableJson(value: unknown): string {
+    if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+    if (!isRecord(value)) return JSON.stringify(value);
+    return `{${Object.keys(value)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`)
+        .join(",")}}`;
+}
+
+function valuesMatch(left: unknown, right: unknown): boolean {
+    return stableJson(left) === stableJson(right);
+}
+
+function valueForDiagnostic(value: unknown): string {
+    return stableJson(value);
+}
+
+function migrateEntryForHarness(value: unknown, harness: "opencode" | "pi"): unknown {
+    if (Array.isArray(value)) return value.map((entry) => migrateEntryForHarness(entry, harness));
+    if (!isRecord(value) || !Object.hasOwn(value, "model")) return value;
+
+    const entry: Record<string, unknown> = { model: value.model };
+    if (harness === "opencode" && Object.hasOwn(value, "variant")) {
+        entry.variant = value.variant;
+    }
+    if (harness === "pi" && Object.hasOwn(value, "thinking_level")) {
+        entry.thinking_level = value.thinking_level;
+    }
+    return entry;
+}
+
+function migrateFallbackForHarness(value: unknown, harness: "opencode" | "pi"): unknown {
+    if (typeof value === "string") return [value];
+    return migrateEntryForHarness(value, harness);
+}
+
+function canCreateAtPath(document: Record<string, unknown>, path: readonly string[]): boolean {
+    let current: unknown = document;
+    for (const part of path) {
+        if (current === undefined) return true;
+        if (!isRecord(current)) return false;
+        current = current[part];
+    }
+    return current === undefined || isRecord(current);
+}
+
+function flatFieldPath(parts: readonly string[]): string {
+    return parts.join(".");
+}
+
+function updateDocumentForFlatFields(text: string): {
+    text: string;
+    hasFlatKeys: boolean;
+    diagnostics: FlatConfigDiagnostic[];
+    flatPaths: string[];
+} {
+    const hasBom = text.startsWith("\uFEFF");
+    const editableText = hasBom ? text.slice(1) : text;
+    const document = asDocument(text);
+    if (!document) {
+        return { text, hasFlatKeys: false, diagnostics: [], flatPaths: [] };
+    }
+
+    let nextText = editableText;
+    let hasFlatKeys = false;
+    const diagnostics: FlatConfigDiagnostic[] = [];
+    const flatPaths: string[] = [];
+    const sourcePathsToRemove: string[][] = [];
+
+    const addDestination = (
+        sourcePath: string[],
+        destinationPath: string[],
+        destinationValue: unknown,
+    ): void => {
+        const sourceLabel = flatFieldPath(sourcePath);
+        const destinationLabel = flatFieldPath(destinationPath);
+        if (!canCreateAtPath(document, destinationPath.slice(0, -1))) {
+            diagnostics.push({
+                path: sourceLabel,
+                message: `Flat config field "${sourceLabel}" (${valueForDiagnostic(destinationValue)}) conflicts with non-object destination "${destinationLabel}" (${valueForDiagnostic(getAtPath(document, destinationPath.slice(0, -1)))}); kept the destination and ignored the flat field.`,
+            });
+            return;
+        }
+
+        const existing = getAtPath(document, destinationPath);
+        if (existing !== undefined) {
+            if (!valuesMatch(existing, destinationValue)) {
+                diagnostics.push({
+                    path: sourceLabel,
+                    message: `Flat config field "${sourceLabel}" (${valueForDiagnostic(destinationValue)}) conflicts with "${destinationLabel}" (${valueForDiagnostic(existing)}); kept "${destinationLabel}" and ignored the flat field.`,
+                });
+            }
+            return;
+        }
+
+        nextText = setJsoncValue(nextText, destinationPath, destinationValue);
+    };
+
+    const migrateAgentFields = (agentName: "historian"): void => {
+        const agent = document[agentName];
+        if (!isRecord(agent)) return;
+
+        for (const field of MODEL_FIELDS) {
+            if (!Object.hasOwn(agent, field)) continue;
+            const sourcePath = [agentName, field];
+            hasFlatKeys = true;
+            flatPaths.push(flatFieldPath(sourcePath));
+            sourcePathsToRemove.push(sourcePath);
+            const migrateValue =
+                field === "fallback_models" ? migrateFallbackForHarness : migrateEntryForHarness;
+            addDestination(
+                sourcePath,
+                [agentName, "opencode", field],
+                migrateValue(agent[field], "opencode"),
+            );
+            addDestination(sourcePath, [agentName, "pi", field], migrateValue(agent[field], "pi"));
+        }
+
+        if (Object.hasOwn(agent, "variant")) {
+            const sourcePath = [agentName, "variant"];
+            hasFlatKeys = true;
+            flatPaths.push(flatFieldPath(sourcePath));
+            sourcePathsToRemove.push(sourcePath);
+            addDestination(sourcePath, [agentName, "opencode", "variant"], agent.variant);
+        }
+
+        if (Object.hasOwn(agent, "thinking_level")) {
+            const sourcePath = [agentName, "thinking_level"];
+            hasFlatKeys = true;
+            flatPaths.push(flatFieldPath(sourcePath));
+            sourcePathsToRemove.push(sourcePath);
+            addDestination(sourcePath, [agentName, "pi", "thinking_level"], agent.thinking_level);
+        }
+    };
+
+    migrateAgentFields("historian");
+
+    for (const sourcePath of sourcePathsToRemove) {
+        nextText = removeJsoncValue(nextText, sourcePath);
+    }
+
+    return {
+        text: hasBom ? `\uFEFF${nextText}` : nextText,
+        hasFlatKeys,
+        diagnostics,
+        flatPaths,
+    };
+}
+
+/** True when historian fields still use the flat shape. */
+export function hasFlatKeys(input: Buffer | string): boolean {
+    const text = typeof input === "string" ? input : input.toString("utf-8");
+    return updateDocumentForFlatFields(text).hasFlatKeys;
+}
+
+/**
+ * Deterministically maps flat model fields into per-harness blocks while leaving
+ * unrelated JSONC regions untouched. The return type matches the caller's input
+ * representation so callers that operate on file bytes retain BOM and line-ending
+ * details exactly outside the surgical edits.
+ */
+export function migrateFlat(input: string): string;
+export function migrateFlat(input: Buffer): Buffer;
+export function migrateFlat(input: Buffer | string): Buffer | string {
+    const text = typeof input === "string" ? input : input.toString("utf-8");
+    const migrated = updateDocumentForFlatFields(text).text;
+    return typeof input === "string" ? migrated : Buffer.from(migrated, "utf-8");
+}
+
+export function migrateFlatDetailed(input: Buffer | string): FlatConfigMigration {
+    const bytes = typeof input === "string" ? Buffer.from(input, "utf-8") : input;
+    const result = updateDocumentForFlatFields(bytes.toString("utf-8"));
+    return {
+        bytes: Buffer.from(result.text, "utf-8"),
+        hasFlatKeys: result.hasFlatKeys,
+        diagnostics: result.diagnostics,
+    };
+}
+
+function writeExclusiveBackup(backupPath: string, bytes: Buffer, mode: number): void {
+    const temporaryPath = writeTemporaryCandidate(backupPath, bytes, mode);
+    try {
+        try {
+            // A hard link publishes the fully written candidate without replacing a concurrent backup.
+            linkSync(temporaryPath, backupPath);
+            return;
+        } catch (error) {
+            if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+        }
+
+        const existingBytes = readFileSync(backupPath);
+        if (existingBytes.equals(bytes)) return;
+
+        // A prefix may be a partial file left when the former direct-write approach crashed.
+        // Preserve any other content because it may be a complete backup from an earlier run.
+        if (bytes.subarray(0, existingBytes.length).equals(existingBytes)) {
+            renameSync(temporaryPath, backupPath);
+            return;
+        }
+    } finally {
+        try {
+            unlinkSync(temporaryPath);
+        } catch {
+            // The candidate may already be linked or renamed into place; cleanup failure must
+            // not obscure the result of creating or validating the permanent backup.
+        }
+    }
+}
+
+function writeTemporaryCandidate(configPath: string, bytes: Buffer, mode: number): string {
+    const directory = dirname(configPath);
+    const stem = basename(configPath);
+    for (let attempt = 0; attempt < 32; attempt++) {
+        temporaryFileSequence += 1;
+        const path = join(
+            directory,
+            `.${stem}.per-harness-${process.pid}-${temporaryFileSequence}.tmp`,
+        );
+        let descriptor: number | undefined;
+        try {
+            descriptor = openSync(path, "wx", mode);
+            writeFileSync(descriptor, bytes);
+            closeSync(descriptor);
+            return path;
+        } catch (error) {
+            if (descriptor !== undefined) {
+                try {
+                    closeSync(descriptor);
+                } catch {
+                    // The write error below remains the actionable error.
+                }
+            }
+            try {
+                unlinkSync(path);
+            } catch {
+                // A failed cleanup must not hide the original write error.
+            }
+            if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+        }
+    }
+    throw new Error(`Could not allocate a temporary config file beside ${configPath}`);
+}
+
+function migrationWarning(diagnostic: FlatConfigDiagnostic): string {
+    return diagnostic.message;
+}
+
+/**
+ * Reads the raw tier before substitution and schema validation. User files are
+ * rewritten through an exact-byte backup and same-directory atomic replacement;
+ * project files are adapted only in memory. This is the common seam used by both
+ * harness loaders and their doctor paths.
+ */
+export function loadRawConfigFile(options: RawConfigLoadOptions): RawConfigLoadResult | null {
+    if (!existsSync(options.configPath)) return null;
+
+    let observedBytes: Buffer;
+    try {
+        observedBytes = readFileSync(options.configPath);
+    } catch (error) {
+        throw new Error(
+            `failed to read config: ${error instanceof Error ? error.message : String(error)}`,
+        );
+    }
+
+    const initialMigration = migrateFlatDetailed(observedBytes);
+    if (!initialMigration.hasFlatKeys) {
+        return {
+            configPath: options.configPath,
+            bytes: observedBytes,
+            text: observedBytes.toString("utf-8"),
+            warnings: [],
+            migrated: false,
+        };
+    }
+
+    if (options.tier === "project") {
+        return {
+            configPath: options.configPath,
+            bytes: initialMigration.bytes,
+            text: initialMigration.bytes.toString("utf-8"),
+            warnings: [
+                "Adapted flat model config in memory; use historian.opencode/historian.pi instead. Project config files are never rewritten.",
+                ...initialMigration.diagnostics.map(migrationWarning),
+            ],
+            migrated: false,
+        };
+    }
+
+    const backupPath = `${options.configPath}${PRE_PER_HARNESS_BACKUP_SUFFIX}`;
+    for (;;) {
+        const migration = migrateFlatDetailed(observedBytes);
+        if (!migration.hasFlatKeys) {
+            return {
+                configPath: options.configPath,
+                bytes: observedBytes,
+                text: observedBytes.toString("utf-8"),
+                warnings: [],
+                migrated: false,
+            };
+        }
+
+        let temporaryPath: string | undefined;
+        try {
+            // Write through a symlinked config (stow, chezmoi, home-manager keep
+            // it in a dotfiles repo): the temporary file is created next to the
+            // real file and renamed onto it, so the link itself stays a link.
+            const writePath = realpathSync(options.configPath);
+            const mode = options.tier === "user" ? 0o600 : statSync(writePath).mode & 0o777;
+            writeExclusiveBackup(backupPath, observedBytes, mode);
+            temporaryPath = writeTemporaryCandidate(writePath, migration.bytes, mode);
+            options.afterTemporaryWrite?.();
+
+            const currentBytes = readFileSync(options.configPath);
+            if (!hasFlatKeys(currentBytes)) {
+                unlinkSync(temporaryPath);
+                return {
+                    configPath: options.configPath,
+                    bytes: currentBytes,
+                    text: currentBytes.toString("utf-8"),
+                    warnings: [],
+                    migrated: false,
+                };
+            }
+            if (!currentBytes.equals(observedBytes)) {
+                unlinkSync(temporaryPath);
+                observedBytes = currentBytes;
+                continue;
+            }
+
+            renameSync(temporaryPath, writePath);
+            return {
+                configPath: options.configPath,
+                bytes: migration.bytes,
+                text: migration.bytes.toString("utf-8"),
+                warnings: [
+                    "Migrated flat historian model config to per-harness blocks.",
+                    ...migration.diagnostics.map(migrationWarning),
+                ],
+                migrated: true,
+            };
+        } catch (error) {
+            if (temporaryPath) {
+                try {
+                    unlinkSync(temporaryPath);
+                } catch {
+                    // The migration error is more useful than a failed temp cleanup.
+                }
+            }
+            return {
+                configPath: options.configPath,
+                bytes: observedBytes,
+                text: observedBytes.toString("utf-8"),
+                warnings: [
+                    `Could not migrate flat model config: ${error instanceof Error ? error.message : String(error)}. Flat fields were not applied.`,
+                    ...migration.diagnostics.map(migrationWarning),
+                ],
+                migrated: false,
+            };
+        }
+    }
+}

package/src/config/removed-agent-config.ts

@@ -0,0 +1,45 @@
+const REMOVED_AGENT_CONFIG_KEY = "sidekick";
+
+export const REMOVED_AGENT_CONFIG_WARNING = `The "${REMOVED_AGENT_CONFIG_KEY}" configuration was removed and is ignored.`;
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Remove the retired agent block before profile resolution or schema parsing.
+ * The same warning array may be shared across user and project layers so one
+ * load reports the removal once while preserving every unrelated setting.
+ */
+export function stripRemovedAgentConfig(
+    rawConfig: Record<string, unknown>,
+    warnings: string[],
+): Record<string, unknown> {
+    let removed = false;
+    const patched = { ...rawConfig };
+
+    if (Object.hasOwn(patched, REMOVED_AGENT_CONFIG_KEY)) {
+        delete patched[REMOVED_AGENT_CONFIG_KEY];
+        removed = true;
+    }
+
+    if (isPlainObject(patched.profiles)) {
+        const profiles = { ...patched.profiles };
+        let profilesChanged = false;
+        for (const [name, value] of Object.entries(profiles)) {
+            if (!isPlainObject(value) || !Object.hasOwn(value, REMOVED_AGENT_CONFIG_KEY)) continue;
+            const profile = { ...value };
+            delete profile[REMOVED_AGENT_CONFIG_KEY];
+            profiles[name] = profile;
+            profilesChanged = true;
+            removed = true;
+        }
+        if (profilesChanged) patched.profiles = profiles;
+    }
+
+    if (removed && !warnings.includes(REMOVED_AGENT_CONFIG_WARNING)) {
+        warnings.push(REMOVED_AGENT_CONFIG_WARNING);
+    }
+
+    return removed ? patched : rawConfig;
+}

package/src/config/removed-agent-source-fence.test.ts

@@ -0,0 +1,53 @@
+/// <reference types="bun-types" />
+
+import { describe, expect, it } from "bun:test";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+
+const RETIRED_AGENT_NAME = ["side", "kick"].join("");
+const RETIRED_AGENT_PATTERN = new RegExp(RETIRED_AGENT_NAME, "gi");
+const REPO_ROOT = join(__dirname, "..", "..", "..", "..");
+const WARNING_SOURCE = join(
+    REPO_ROOT,
+    "packages",
+    "plugin",
+    "src",
+    "config",
+    "removed-agent-config.ts",
+);
+const SOURCE_ROOTS = [
+    join(REPO_ROOT, "packages", "plugin", "src"),
+    join(REPO_ROOT, "packages", "pi-plugin", "src"),
+];
+const SOURCE_EXTENSIONS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".rs", ".json"]);
+
+function sourceFiles(directory: string, files: string[] = []): string[] {
+    for (const entry of readdirSync(directory)) {
+        if (entry === "node_modules" || entry === "dist") continue;
+        const path = join(directory, entry);
+        const stat = statSync(path);
+        if (stat.isDirectory()) {
+            sourceFiles(path, files);
+            continue;
+        }
+        const extension = entry.slice(entry.lastIndexOf("."));
+        if (stat.isFile() && SOURCE_EXTENSIONS.has(extension)) files.push(path);
+    }
+    return files;
+}
+
+describe("retired agent source fence", () => {
+    it("keeps only the removed-config warning key literal", () => {
+        const offenses: string[] = [];
+        for (const file of SOURCE_ROOTS.flatMap((root) => sourceFiles(root))) {
+            const matches = readFileSync(file, "utf8").match(RETIRED_AGENT_PATTERN) ?? [];
+            const allowed = file === WARNING_SOURCE && matches.length === 1;
+            if (!allowed && matches.length > 0) {
+                offenses.push(`${relative(REPO_ROOT, file)} (${matches.length})`);
+            }
+        }
+
+        expect(offenses).toEqual([]);
+        expect(readFileSync(WARNING_SOURCE, "utf8").match(RETIRED_AGENT_PATTERN)).toHaveLength(1);
+    });
+});

package/src/config/removed-config-keys.test.ts

@@ -0,0 +1,106 @@
+/// <reference types="bun-types" />
+
+// Regression guard: the `auto_drop_tool_age` and `drop_tool_structure` config
+// keys (and their camelCase threads `autoDropToolAge` / `dropToolStructure`)
+// were REMOVED in Phase 2 — routine age-based tool drops were replaced by the
+// tiered target-headroom emergency drop, which always full-drops. No production
+// source in the plugin or Pi packages may reference them; a stray reference
+// would either be dead code or a config the schema now rejects with a warning.
+//
+// This is a static source-text scan so it fails at test-time without runtime
+// mocking. Tests, generated files, and the doctor's deletion routine (which
+// must name the dead keys to strip them) are intentionally excluded.
+
+import { describe, expect, it } from "bun:test";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+const PLUGIN_SRC = join(__dirname, "..");
+const PI_SRC = join(__dirname, "..", "..", "..", "pi-plugin", "src");
+
+const FORBIDDEN = [
+    "auto_drop_tool_age",
+    "drop_tool_structure",
+    "autoDropToolAge",
+    "dropToolStructure",
+    // Nudge redesign removed the rolling/iteration nudge config entirely
+    // (Channel 1/2 replaced them). No schema key, no camelCase thread.
+    "nudge_interval_tokens",
+    "iteration_nudge_threshold",
+    "nudgeIntervalTokens",
+    "iterationNudgeThreshold",
+    // C-① config slimming: retired keys, no camelCase variants.
+    "protected_tags",
+    "retrieval_count_promotion_threshold",
+    "historian.omp",
+];
+
+// Files allowed to mention the dead keys. (Upstream's CLI doctor named them
+// to strip them from existing user configs; the fork has no CLI, so the
+// exception surface is empty and stays empty.)
+const ALLOWED_BASENAMES = new Set<string>([]);
+
+function walkSourceFiles(dir: string, out: string[] = []): string[] {
+    let entries: string[];
+    try {
+        entries = readdirSync(dir);
+    } catch {
+        return out; // package not present in this checkout
+    }
+    for (const entry of entries) {
+        if (entry === "node_modules" || entry === "dist") continue;
+        const full = join(dir, entry);
+        const s = statSync(full);
+        if (s.isDirectory()) {
+            walkSourceFiles(full, out);
+        } else if (
+            s.isFile() &&
+            entry.endsWith(".ts") &&
+            !entry.endsWith(".test.ts") &&
+            !entry.endsWith(".gen.ts") &&
+            !ALLOWED_BASENAMES.has(entry)
+        ) {
+            out.push(full);
+        }
+    }
+    return out;
+}
+
+function scanForForbidden(files: string[]): string[] {
+    const offenders: string[] = [];
+    for (const file of files) {
+        let text: string;
+        try {
+            text = readFileSync(file, "utf-8");
+        } catch {
+            continue; // file absent in this checkout
+        }
+        for (const key of FORBIDDEN) {
+            if (text.includes(key)) offenders.push(`${file}: ${key}`);
+        }
+    }
+    return offenders;
+}
+
+const REPO_ROOT = join(__dirname, "..", "..", "..", "..");
+
+describe("removed Phase 2 config keys", () => {
+    it("no production source references auto_drop_tool_age / drop_tool_structure", () => {
+        const files = [...walkSourceFiles(PLUGIN_SRC), ...walkSourceFiles(PI_SRC)];
+        expect(scanForForbidden(files)).toEqual([]);
+    });
+
+    // The keys also leaked into docs and the generated schema (where they're
+    // silently ignored — the worst kind, since the doc reads as if the knob
+    // still works). Guard those surfaces too so doc/config drift fails CI
+    // alongside source drift. (Upstream also scanned e2e test configs; the
+    // e2e suite is deleted with 01.A.)
+    it("no docs / generated schema references the removed keys", () => {
+        const docFiles = [
+            join(REPO_ROOT, "CONFIGURATION.md"),
+            join(REPO_ROOT, "README.md"),
+            join(REPO_ROOT, "assets", "magic-context.schema.json"),
+        ];
+        expect(scanForForbidden(docFiles)).toEqual([]);
+    });
+});

package/src/config/schema/agent-overrides.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+
+const PermissionValueSchema = z.enum(["ask", "allow", "deny"]);
+
+const PermissionSchema = z
+    .object({
+        edit: PermissionValueSchema.optional(),
+        bash: z
+            .union([PermissionValueSchema, z.record(z.string(), PermissionValueSchema)])
+            .optional(),
+        webfetch: PermissionValueSchema.optional(),
+        doom_loop: PermissionValueSchema.optional(),
+        external_directory: PermissionValueSchema.optional(),
+    })
+    .optional();
+
+export const AgentOverrideConfigSchema = z.object({
+    model: z.string().optional().describe("Primary model ID (e.g. 'claude-sonnet-4-6')"),
+    temperature: z.number().min(0).max(2).optional().describe("Sampling temperature (0-2)"),
+    top_p: z.number().min(0).max(1).optional().describe("Nucleus sampling top_p (0-1)"),
+    prompt: z.string().optional().describe("Additional system prompt text"),
+    tools: z.record(z.string(), z.boolean()).optional().describe("Tool enable/disable overrides"),
+    disable: z.boolean().optional().describe("Disable this agent"),
+    description: z.string().optional().describe("Agent description"),
+    mode: z
+        .enum(["subagent", "primary", "all"])
+        .optional()
+        .describe("Agent mode (subagent, primary, or all)"),
+    color: z
+        .string()
+        .regex(/^#[0-9A-Fa-f]{6}$/)
+        .optional()
+        .describe("Hex color for the agent (e.g. '#a1b2c3')"),
+    maxSteps: z.number().optional().describe("Maximum tool-call steps per invocation"),
+    permission: PermissionSchema.describe("Per-tool permission overrides"),
+    maxTokens: z.number().optional().describe("Maximum output tokens"),
+    variant: z
+        .string()
+        .optional()
+        .describe("OpenCode reasoning variant (e.g. for extended thinking)"),
+    fallback_models: z
+        .union([z.string(), z.array(z.string())])
+        .optional()
+        .describe("Fallback model IDs if primary is unavailable"),
+});