omniagent 0.1.13 → 0.1.16

package/dist/cli.js

@@ -3,7 +3,7 @@ import { constants, realpathSync, existsSync, readFileSync } from "node:fs";
 import { pathToFileURL, fileURLToPath } from "node:url";
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
-import { stat, rm, readdir, access, readFile, mkdir, writeFile, rename } from "node:fs/promises";
+import { stat, rm, readdir, access, readFile, mkdir, writeFile, rename, mkdtemp } from "node:fs/promises";
 import path from "node:path";
 import { createHash, randomUUID } from "node:crypto";
 import os from "node:os";
@@ -11,6 +11,9 @@ import { Minimatch } from "minimatch";
 import { createInterface } from "node:readline/promises";
 import { TextDecoder } from "node:util";
 import { spawn } from "node:child_process";
+import Ajv from "ajv";
+import Ajv2019 from "ajv/dist/2019.js";
+import Ajv2020 from "ajv/dist/2020.js";
 async function pathExists$2(candidate) {
   try {
     await stat(candidate);
@@ -475,14 +478,14 @@ const ALLOWED_TOP_LEVEL_KEYS = /* @__PURE__ */ new Set([
 ]);
 const ALLOWED_CATEGORY_KEYS = new Set(PROFILE_CATEGORIES);
 const ALLOWED_TARGET_SETTING_KEYS = /* @__PURE__ */ new Set(["enabled"]);
-function isPlainObject$1(value) {
+function isPlainObject$2(value) {
   return !!value && typeof value === "object" && !Array.isArray(value);
 }
 function pushError(errors, path2, message) {
   errors.push({ path: path2, message });
 }
 function validatePatternMap(value, pathPrefix, errors) {
-  if (!isPlainObject$1(value)) {
+  if (!isPlainObject$2(value)) {
     pushError(errors, pathPrefix, "must be an object.");
     return;
   }
@@ -507,7 +510,7 @@ function validatePatternMap(value, pathPrefix, errors) {
   }
 }
 function validateTargets(value, errors) {
-  if (!isPlainObject$1(value)) {
+  if (!isPlainObject$2(value)) {
     pushError(errors, "targets", "must be an object.");
     return;
   }
@@ -516,7 +519,7 @@ function validateTargets(value, errors) {
       pushError(errors, "targets", `target keys must be non-empty strings (got "${targetName}").`);
       continue;
     }
-    if (!isPlainObject$1(setting)) {
+    if (!isPlainObject$2(setting)) {
       pushError(errors, `targets.${targetName}`, "must be an object.");
       continue;
     }
@@ -532,7 +535,7 @@ function validateTargets(value, errors) {
 }
 function validateProfile(value) {
   const errors = [];
-  if (!isPlainObject$1(value)) {
+  if (!isPlainObject$2(value)) {
     return {
       valid: false,
       errors: [{ path: "", message: "profile must be a JSON object." }]
@@ -578,7 +581,7 @@ function validateProfile(value) {
   };
 }
 function validateVariables(value, errors) {
-  if (!isPlainObject$1(value)) {
+  if (!isPlainObject$2(value)) {
     pushError(errors, "variables", "must be an object of string values.");
     return;
   }
@@ -1272,6 +1275,74 @@ function resolveEffectiveTargets(options) {
   const skipSet = new Set(overrideSkip.map((target) => normalizeTargetName(target)));
   return dedupeTargets(base.filter((target) => !skipSet.has(normalizeTargetName(target))));
 }
+const agyTarget = {
+  id: "agy",
+  displayName: "Antigravity CLI",
+  aliases: ["gemini"],
+  cli: {
+    modes: {
+      interactive: { command: "agy" },
+      oneShot: { command: "agy" }
+    },
+    // agy requires the prompt as -p's argument; the shim always passes the
+    // (possibly stdin-derived) prompt inline, so piped stdin works.
+    prompt: { type: "flag", flag: ["-p"] },
+    flags: {
+      approval: {
+        values: {
+          prompt: [],
+          "auto-edit": null,
+          yolo: ["--dangerously-skip-permissions"]
+        }
+      },
+      sandbox: {
+        values: {
+          "workspace-write": ["--sandbox"],
+          off: []
+        }
+      },
+      output: {
+        byMode: {
+          "one-shot": {
+            text: [],
+            json: null,
+            "stream-json": null
+          }
+        }
+      },
+      // Model names are display strings, e.g. "Gemini 3.5 Flash (Low)"; list via `agy models`.
+      model: { flag: ["--model"] },
+      structuredOutputFallback: {
+        extraction: { type: "text" }
+      }
+    }
+  },
+  outputs: {
+    skills: "{repoRoot}/.agents/skills/{itemName}",
+    subagents: {
+      path: "{repoRoot}/.agents/skills/{itemName}",
+      fallback: { mode: "convert", targetType: "skills" }
+    },
+    commands: {
+      fallback: { mode: "convert", targetType: "skills" }
+    },
+    instructions: {
+      filename: "AGENTS.md",
+      group: "agents"
+    }
+  },
+  usage: {
+    windows: ["weekly"],
+    launch: {
+      command: "agy",
+      timeoutMs: 7e4
+    },
+    extract: async (context) => {
+      const { extractAgyUsage } = await import("./agy-DlbWeyP_.js");
+      return extractAgyUsage(context);
+    }
+  }
+};
 const claudeTarget = {
   id: "claude",
   displayName: "Claude Code",
@@ -1298,7 +1369,13 @@ const claudeTarget = {
           }
         }
       },
-      model: { flag: ["--model"] }
+      model: { flag: ["--model"] },
+      structuredOutput: {
+        delivery: "inline",
+        flag: ["--json-schema"],
+        companionArgs: ["--output-format", "json"],
+        extraction: { type: "json-envelope", field: "structured_output" }
+      }
     }
   },
   outputs: {
@@ -1322,7 +1399,7 @@ const claudeTarget = {
       timeoutMs: 6e4
     },
     extract: async (context) => {
-      const { extractClaudeUsage } = await import("./claude-DWeyS4fP.js");
+      const { extractClaudeUsage } = await import("./claude-CcxRb8OW.js");
       return extractClaudeUsage(context);
     }
   }
@@ -1368,7 +1445,12 @@ const codexTarget = {
         }
       },
       model: { flag: ["-m"] },
-      web: { on: ["--search"], off: ["--disable", "web_search_request"] }
+      web: { on: ["--search"], off: ["--disable", "web_search_request"] },
+      structuredOutput: {
+        delivery: "file",
+        flag: ["--output-schema"],
+        extraction: { type: "last-message-file", flag: ["--output-last-message"] }
+      }
     }
   },
   outputs: {
@@ -1402,7 +1484,7 @@ const codexTarget = {
       timeoutMs: 6e4
     },
     extract: async (context) => {
-      const { extractCodexUsage } = await import("./codex-0b2YLh_8.js");
+      const { extractCodexUsage } = await import("./codex-DhlBosXm.js");
       return extractCodexUsage(context);
     }
   }
@@ -1500,7 +1582,11 @@ const copilotTarget = {
           }
         }
       },
-      model: { flag: ["--model"] }
+      model: { flag: ["--model"] },
+      structuredOutputFallback: {
+        args: ["--silent"],
+        extraction: { type: "text" }
+      }
     }
   },
   outputs: {
@@ -1547,74 +1633,10 @@ const copilotTarget = {
     }
   }
 };
-const geminiTarget = {
-  id: "gemini",
-  displayName: "Gemini CLI",
-  cli: {
-    modes: {
-      interactive: { command: "gemini" },
-      oneShot: { command: "gemini" }
-    },
-    prompt: { type: "flag", flag: ["-p"] },
-    flags: {
-      approval: {
-        values: {
-          prompt: ["--approval-mode", "default"],
-          "auto-edit": ["--approval-mode", "auto_edit"],
-          yolo: ["--yolo"]
-        }
-      },
-      sandbox: {
-        values: {
-          "workspace-write": ["--sandbox"],
-          off: []
-        }
-      },
-      output: {
-        byMode: {
-          "one-shot": {
-            text: [],
-            json: ["--output-format", "json"],
-            "stream-json": ["--output-format", "stream-json"]
-          }
-        }
-      },
-      model: { flag: ["--model"] },
-      web: { on: [], off: null }
-    }
-  },
-  outputs: {
-    skills: "{repoRoot}/.gemini/skills/{itemName}",
-    subagents: {
-      path: "{repoRoot}/.gemini/skills/{itemName}",
-      fallback: { mode: "convert", targetType: "skills" }
-    },
-    commands: {
-      projectPath: "{repoRoot}/.gemini/commands/{itemName}.toml",
-      userPath: "{homeDir}/.gemini/commands/{itemName}.toml"
-    },
-    instructions: {
-      filename: "GEMINI.md"
-    }
-  },
-  usage: {
-    windows: ["model"],
-    launch: {
-      command: "gemini",
-      // /model inspection does not need a model override; Gemini requires session-scoped trust.
-      args: ["--skip-trust"],
-      timeoutMs: 7e4
-    },
-    extract: async (context) => {
-      const { extractGeminiUsage } = await import("./gemini-BVRg6OMO.js");
-      return extractGeminiUsage(context);
-    }
-  }
-};
 const BUILTIN_TARGETS = [
   codexTarget,
   claudeTarget,
-  geminiTarget,
+  agyTarget,
   copilotTarget
 ];
 Object.freeze(BUILTIN_TARGETS.map((target) => target.id));
@@ -2386,7 +2408,7 @@ const COMMON_PLACEHOLDERS = /* @__PURE__ */ new Set([
   "itemName"
 ]);
 const COMMAND_PLACEHOLDERS = /* @__PURE__ */ new Set([...COMMON_PLACEHOLDERS, "commandLocation"]);
-function isPlainObject(value) {
+function isPlainObject$1(value) {
   return !!value && typeof value === "object" && !Array.isArray(value);
 }
 function normalizeString(value) {
@@ -2415,7 +2437,7 @@ function validateStringArray(value, label, errors, options = {}) {
   }
 }
 function validateFlagMapValues(value, label, allowedValues, errors) {
-  if (!isPlainObject(value)) {
+  if (!isPlainObject$1(value)) {
     errors.push(`${label} must be an object.`);
     return;
   }
@@ -2431,7 +2453,7 @@ function validateFlagMapValues(value, label, allowedValues, errors) {
   }
 }
 function validateFlagMap(value, label, allowedValues, errors) {
-  if (!isPlainObject(value)) {
+  if (!isPlainObject$1(value)) {
     errors.push(`${label} must be an object.`);
     return;
   }
@@ -2439,7 +2461,7 @@ function validateFlagMap(value, label, allowedValues, errors) {
     validateFlagMapValues(value.values, `${label}.values`, allowedValues, errors);
   }
   if (value.byMode !== void 0) {
-    if (!isPlainObject(value.byMode)) {
+    if (!isPlainObject$1(value.byMode)) {
       errors.push(`${label}.byMode must be an object.`);
     } else {
       for (const [mode, entries] of Object.entries(value.byMode)) {
@@ -2452,8 +2474,64 @@ function validateFlagMap(value, label, allowedValues, errors) {
     }
   }
 }
+function validateStructuredOutputSpec(value, label, errors) {
+  if (!isPlainObject$1(value)) {
+    errors.push(`${label} must be an object.`);
+    return;
+  }
+  if (value.delivery !== "inline" && value.delivery !== "file") {
+    errors.push(`${label}.delivery must be "inline" or "file".`);
+  }
+  validateStringArray(value.flag, `${label}.flag`, errors);
+  if (value.companionArgs !== void 0) {
+    validateStringArray(value.companionArgs, `${label}.companionArgs`, errors, {
+      allowEmpty: true
+    });
+  }
+  if (!isPlainObject$1(value.extraction)) {
+    errors.push(`${label}.extraction must be an object.`);
+    return;
+  }
+  if (value.extraction.type === "json-envelope") {
+    if (normalizeString(value.extraction.field) === null) {
+      errors.push(`${label}.extraction.field must be a non-empty string.`);
+    }
+    return;
+  }
+  if (value.extraction.type === "last-message-file") {
+    validateStringArray(value.extraction.flag, `${label}.extraction.flag`, errors);
+    return;
+  }
+  errors.push(`${label}.extraction.type must be "json-envelope" or "last-message-file".`);
+}
+function validateStructuredOutputFallbackSpec(value, label, errors) {
+  if (!isPlainObject$1(value)) {
+    errors.push(`${label} must be an object.`);
+    return;
+  }
+  if (value.args !== void 0) {
+    validateStringArray(value.args, `${label}.args`, errors, { allowEmpty: true });
+  }
+  if (value.extraction === void 0) {
+    return;
+  }
+  if (!isPlainObject$1(value.extraction)) {
+    errors.push(`${label}.extraction must be an object.`);
+    return;
+  }
+  if (value.extraction.type === "text") {
+    return;
+  }
+  if (value.extraction.type === "json-envelope") {
+    if (normalizeString(value.extraction.field) === null) {
+      errors.push(`${label}.extraction.field must be a non-empty string.`);
+    }
+    return;
+  }
+  errors.push(`${label}.extraction.type must be "text" or "json-envelope".`);
+}
 function validateModeCommand(value, label, errors) {
-  if (!isPlainObject(value)) {
+  if (!isPlainObject$1(value)) {
     errors.push(`${label} must be an object.`);
     return;
   }
@@ -2466,7 +2544,7 @@ function validateModeCommand(value, label, errors) {
   }
 }
 function validatePromptSpec(value, label, errors) {
-  if (!isPlainObject(value)) {
+  if (!isPlainObject$1(value)) {
     errors.push(`${label} must be an object.`);
     return;
   }
@@ -2486,11 +2564,11 @@ function validateCliDefinition(cli, label, errors) {
   if (!cli) {
     return;
   }
-  if (!isPlainObject(cli)) {
+  if (!isPlainObject$1(cli)) {
     errors.push(`${label} must be an object.`);
     return;
   }
-  if (!isPlainObject(cli.modes)) {
+  if (!isPlainObject$1(cli.modes)) {
     errors.push(`${label}.modes is required.`);
     return;
   }
@@ -2500,7 +2578,7 @@ function validateCliDefinition(cli, label, errors) {
     validatePromptSpec(cli.prompt, `${label}.prompt`, errors);
   }
   if (cli.flags !== void 0) {
-    if (!isPlainObject(cli.flags)) {
+    if (!isPlainObject$1(cli.flags)) {
       errors.push(`${label}.flags must be an object.`);
     } else {
       if (cli.flags.approval !== void 0) {
@@ -2513,7 +2591,7 @@ function validateCliDefinition(cli, label, errors) {
         validateFlagMap(cli.flags.output, `${label}.flags.output`, OUTPUT_FORMATS, errors);
       }
       if (cli.flags.model !== void 0) {
-        if (!isPlainObject(cli.flags.model)) {
+        if (!isPlainObject$1(cli.flags.model)) {
           errors.push(`${label}.flags.model must be an object.`);
         } else {
           validateStringArray(cli.flags.model.flag, `${label}.flags.model.flag`, errors);
@@ -2527,8 +2605,22 @@ function validateCliDefinition(cli, label, errors) {
           }
         }
       }
+      if (cli.flags.structuredOutput !== void 0) {
+        validateStructuredOutputSpec(
+          cli.flags.structuredOutput,
+          `${label}.flags.structuredOutput`,
+          errors
+        );
+      }
+      if (cli.flags.structuredOutputFallback !== void 0) {
+        validateStructuredOutputFallbackSpec(
+          cli.flags.structuredOutputFallback,
+          `${label}.flags.structuredOutputFallback`,
+          errors
+        );
+      }
       if (cli.flags.web !== void 0) {
-        if (!isPlainObject(cli.flags.web)) {
+        if (!isPlainObject$1(cli.flags.web)) {
           errors.push(`${label}.flags.web must be an object.`);
         } else {
           if (cli.flags.web.on !== void 0 && cli.flags.web.on !== null) {
@@ -2554,7 +2646,7 @@ function validateCliDefinition(cli, label, errors) {
     }
   }
   if (cli.passthrough !== void 0) {
-    if (!isPlainObject(cli.passthrough)) {
+    if (!isPlainObject$1(cli.passthrough)) {
       errors.push(`${label}.passthrough must be an object.`);
     } else if (cli.passthrough.position !== void 0 && cli.passthrough.position !== "after" && cli.passthrough.position !== "before-prompt") {
       errors.push(`${label}.passthrough.position must be "after" or "before-prompt".`);
@@ -2568,13 +2660,13 @@ function validateUsageDefinition(usage, label, errors) {
   if (usage === void 0) {
     return;
   }
-  if (!isPlainObject(usage)) {
+  if (!isPlainObject$1(usage)) {
     errors.push(`${label} must be an object.`);
     return;
   }
   validateStringArray(usage.windows, `${label}.windows`, errors);
   if (usage.launch !== void 0) {
-    if (!isPlainObject(usage.launch)) {
+    if (!isPlainObject$1(usage.launch)) {
       errors.push(`${label}.launch must be an object.`);
     } else {
       if (usage.launch.command !== void 0 && normalizeString(usage.launch.command) === null) {
@@ -2632,7 +2724,7 @@ function validateOutputDefinition(output, label, errors) {
     validateTemplate(output, label, COMMON_PLACEHOLDERS, errors);
     return;
   }
-  if (!isPlainObject(output)) {
+  if (!isPlainObject$1(output)) {
     errors.push(`${label} must be a string or an object.`);
     return;
   }
@@ -2647,7 +2739,7 @@ function validateCommandOutputDefinition(output, label, errors) {
     validateTemplate(output, label, COMMAND_PLACEHOLDERS, errors);
     return;
   }
-  if (!isPlainObject(output)) {
+  if (!isPlainObject$1(output)) {
     errors.push(`${label} must be a string or an object.`);
     return;
   }
@@ -2671,7 +2763,7 @@ function validateInstructionOutputDefinition(output, label, errors) {
     validateTemplate(output, label, COMMON_PLACEHOLDERS, errors);
     return;
   }
-  if (!isPlainObject(output)) {
+  if (!isPlainObject$1(output)) {
     errors.push(`${label} must be a string or an object.`);
     return;
   }
@@ -2684,7 +2776,7 @@ function validateOutputs(outputs, label, errors) {
   if (!outputs) {
     return;
   }
-  if (!isPlainObject(outputs)) {
+  if (!isPlainObject$1(outputs)) {
     errors.push(`${label} must be an object.`);
     return;
   }
@@ -2702,7 +2794,7 @@ function validateTargetConfig(options) {
   if (config === null) {
     return { valid: true, errors, config: null };
   }
-  if (!isPlainObject(config)) {
+  if (!isPlainObject$1(config)) {
     return {
       valid: false,
       errors: ["Config must export an object."],
@@ -2717,9 +2809,11 @@ function validateTargetConfig(options) {
   }
   const builtInIds = new Set(options.builtIns.map((target) => normalizeLower(target.id)));
   const builtInAliasSet = /* @__PURE__ */ new Set();
+  const builtInAliasToId = /* @__PURE__ */ new Map();
   for (const target of options.builtIns) {
     for (const alias of target.aliases ?? []) {
       builtInAliasSet.add(normalizeLower(alias));
+      builtInAliasToId.set(normalizeLower(alias), normalizeLower(target.id));
     }
   }
   const seenIds = /* @__PURE__ */ new Set();
@@ -2736,7 +2830,8 @@ function validateTargetConfig(options) {
           errors.push("disableTargets entries must be non-empty strings.");
           continue;
         }
-        const key = normalizeLower(normalized);
+        const rawKey = normalizeLower(normalized);
+        const key = builtInAliasToId.get(rawKey) ?? rawKey;
         if (!builtInIds.has(key)) {
           errors.push(`disableTargets includes unknown built-in: ${normalized}.`);
           continue;
@@ -2755,7 +2850,7 @@ function validateTargetConfig(options) {
     } else {
       for (const [index, entry2] of config.targets.entries()) {
         const label = `targets[${index}]`;
-        if (!isPlainObject(entry2)) {
+        if (!isPlainObject$1(entry2)) {
           errors.push(`${label} must be an object.`);
           continue;
         }
@@ -2770,6 +2865,14 @@ function validateTargetConfig(options) {
         } else {
           seenIds.add(idKey);
         }
+        const aliasOwner = builtInAliasToId.get(idKey);
+        if (aliasOwner) {
+          errors.push(
+            `${label}.id collides with built-in alias (${id}) of target ${aliasOwner}. Pick a distinct id.`
+          );
+        } else if (seenAliases.has(idKey)) {
+          errors.push(`${label}.id collides with existing alias (${id}).`);
+        }
         if (entry2.displayName !== void 0 && normalizeString(entry2.displayName) === null) {
           errors.push(`${label}.displayName must be a non-empty string when provided.`);
         }
@@ -2779,7 +2882,8 @@ function validateTargetConfig(options) {
         }
         if (inherits) {
           const inheritKey = normalizeLower(inherits);
-          if (!builtInIds.has(inheritKey)) {
+          const canonicalInherit = builtInAliasToId.get(inheritKey) ?? inheritKey;
+          if (!builtInIds.has(canonicalInherit)) {
             errors.push(`${label}.inherits references unknown built-in: ${inherits}.`);
           }
         }
@@ -2818,7 +2922,8 @@ function validateTargetConfig(options) {
                 errors.push(`${label}.aliases collides with existing target id (${aliasValue}).`);
                 continue;
               }
-              if (seenAliases.has(aliasKey) || builtInAliasSet.has(aliasKey)) {
+              const collidesWithOtherBuiltInAlias = builtInAliasSet.has(aliasKey) && builtInAliasToId.get(aliasKey) !== idKey;
+              if (seenAliases.has(aliasKey) || collidesWithOtherBuiltInAlias) {
                 errors.push(`${label}.aliases collides with existing alias (${aliasValue}).`);
                 continue;
               }
@@ -2835,7 +2940,8 @@ function validateTargetConfig(options) {
   }
   if (config.disableTargets && Array.isArray(config.disableTargets)) {
     for (const targetId of config.disableTargets) {
-      const normalized = normalizeLower(targetId);
+      const rawKey = normalizeLower(targetId);
+      const normalized = builtInAliasToId.get(rawKey) ?? rawKey;
       if (customBuiltInIds.has(normalized)) {
         errors.push(`disableTargets cannot include overridden/inherited target (${targetId}).`);
       }
@@ -2890,7 +2996,7 @@ function mergeOutputs(base, override) {
 }
 function resolveInheritTarget(builtIns, inherits) {
   const key = normalizeKey$2(inherits);
-  const found = builtIns.find((target) => normalizeKey$2(target.id) === key);
+  const found = builtIns.find((target) => normalizeKey$2(target.id) === key) ?? builtIns.find((target) => (target.aliases ?? []).some((alias) => normalizeKey$2(alias) === key));
   return found ?? null;
 }
 function resolveTargets(options) {
@@ -2899,12 +3005,18 @@ function resolveTargets(options) {
   for (const target of builtIns) {
     builtInMap.set(normalizeKey$2(target.id), target);
   }
+  const builtInAliasToId = /* @__PURE__ */ new Map();
+  for (const target of builtIns) {
+    for (const alias of target.aliases ?? []) {
+      builtInAliasToId.set(normalizeKey$2(alias), normalizeKey$2(target.id));
+    }
+  }
   const disabledTargets = [];
   const disableSet = /* @__PURE__ */ new Set();
   if (options.config?.disableTargets) {
     for (const entry2 of options.config.disableTargets) {
-      const key = normalizeKey$2(entry2);
-      disableSet.add(key);
+      const rawKey = normalizeKey$2(entry2);
+      disableSet.add(builtInAliasToId.get(rawKey) ?? rawKey);
       disabledTargets.push(entry2);
     }
   }
@@ -2938,7 +3050,9 @@ function resolveTargets(options) {
       resolvedTargets.push({
         id: customTarget.id,
         displayName: customTarget.displayName ?? inherited?.displayName ?? customTarget.id,
-        aliases: customTarget.aliases ?? inherited?.aliases ?? [],
+        // Aliases follow the overridden built-in's identity, not the inherited
+        // definition — inheriting them would move the alias between targets.
+        aliases: customTarget.aliases ?? builtIn.aliases ?? [],
         outputs: mergedOutputs,
         cli: cloneCli(customTarget.cli ?? inherited?.cli),
         usage: cloneUsage(customTarget.usage ?? inherited?.usage),
@@ -2951,7 +3065,7 @@ function resolveTargets(options) {
       resolvedTargets.push({
         id: customTarget.id,
         displayName: customTarget.displayName ?? customTarget.id,
-        aliases: customTarget.aliases ?? [],
+        aliases: customTarget.aliases ?? builtIn.aliases ?? [],
         outputs: cloneOutputs(customTarget.outputs),
         cli: cloneCli(customTarget.cli),
         usage: cloneUsage(customTarget.usage),
@@ -2972,7 +3086,9 @@ function resolveTargets(options) {
     resolvedTargets.push({
       id: target.id,
       displayName: target.displayName ?? inherited?.displayName ?? target.id,
-      aliases: target.aliases ?? inherited?.aliases ?? [],
+      // Aliases name a specific target, so a new custom target never inherits
+      // them — otherwise it would shadow the built-in's alias in aliasToId.
+      aliases: target.aliases ?? [],
       outputs: mergedOutputs,
       cli: cloneCli(target.cli ?? inherited?.cli),
       usage: cloneUsage(target.usage ?? inherited?.usage),
@@ -3144,7 +3260,7 @@ Profile files must be valid JSON. This commented version is just a guide:
 
   "targets": {
     "claude": { "enabled": true }, // includes Claude; overrides an earlier profile setting it false
-    "gemini": { "enabled": false } // skips Gemini for this profile
+    "agy": { "enabled": false } // skips Antigravity for this profile
   },
 
   "enable": { // names/globs to include; also opts in items marked enabled:false
@@ -3578,6 +3694,18 @@ function processTemplating(content, options) {
   const validSet = new Set(normalizedValid);
   const context = { sourcePath: options.sourcePath, validAgents: normalizedValid };
   const target = options.target ? options.target.toLowerCase() : null;
+  const targetKeys = target ? /* @__PURE__ */ new Set([target, ...(options.targetAliases ?? []).map((alias) => alias.toLowerCase())]) : null;
+  const intersects = (set) => {
+    if (!targetKeys) {
+      return false;
+    }
+    for (const key of targetKeys) {
+      if (set.has(key)) {
+        return true;
+      }
+    }
+    return false;
+  };
   let output = "";
   let index = 0;
   while (index < content.length) {
@@ -3608,7 +3736,7 @@ function processTemplating(content, options) {
       );
     }
     const { include, exclude } = parseSelectorList(selectorRaw, validSet, context);
-    const shouldInclude = target === null ? false : include.size > 0 ? include.has(target) && !exclude.has(target) : !exclude.has(target);
+    const shouldInclude = target === null ? false : include.size > 0 ? intersects(include) && !intersects(exclude) : !intersects(exclude);
     let cursor = contentStart;
     let blockOutput = "";
     while (cursor < content.length) {
@@ -3658,6 +3786,7 @@ function validateAgentTemplating(options) {
 function applyAgentTemplating(options) {
   return processTemplating(options.content, {
     target: options.target,
+    targetAliases: options.targetAliases,
     validAgents: options.validAgents,
     sourcePath: options.sourcePath
   });
@@ -4030,6 +4159,7 @@ const DEFAULT_SKIP_DIRS = /* @__PURE__ */ new Set([
   ".git",
   "node_modules",
   "dist",
+  ".agents",
   ".claude",
   ".codex",
   ".gemini",
@@ -5167,6 +5297,7 @@ async function copySkillDirectory(options) {
     const templated = applyAgentTemplating({
       content: withScripts,
       target: options.targetId,
+      targetAliases: options.targetAliases,
       validAgents: options.validAgents,
       sourcePath: winner.sourcePath
     });
@@ -5186,6 +5317,7 @@ const defaultSkillWriter = {
       source: item.directoryPath,
       destination: options.outputPath,
       targetId: options.context.targetId,
+      targetAliases: options.context.targetAliases,
       validAgents: options.context.validAgents,
       skillFileName: item.skillFileName,
       outputFileName: item.outputFileName,
@@ -5211,6 +5343,7 @@ const defaultSubagentWriter = {
     const templated = applyAgentTemplating({
       content: withScripts,
       target: options.context.targetId,
+      targetAliases: options.context.targetAliases,
       validAgents: options.context.validAgents,
       sourcePath: item.sourcePath
     });
@@ -5552,6 +5685,7 @@ async function syncInstructions(request) {
       const content = applyAgentTemplating({
         content: withScripts,
         target: targetName,
+        targetAliases: selection.target.aliases,
         validAgents: request.validAgents,
         sourcePath: template.sourcePath
       });
@@ -5753,6 +5887,7 @@ async function syncInstructions(request) {
           agentsDir: agentsRoot,
           homeDir,
           targetId: candidate.targetName,
+          targetAliases: selectionById.get(candidate.targetName)?.target.aliases,
           outputType: "instructions",
           validAgents: request.validAgents
         });
@@ -5805,6 +5940,7 @@ async function syncInstructions(request) {
           agentsDir: agentsRoot,
           homeDir,
           targetId: candidate.targetName,
+          targetAliases: selectionById.get(candidate.targetName)?.target.aliases,
           outputType: "instructions",
           validAgents: request.validAgents,
           templateScriptRuntime
@@ -6301,6 +6437,7 @@ async function syncSkills(request) {
           agentsDir: agentsDirPath,
           homeDir,
           targetId: target.id,
+          targetAliases: target.aliases,
           outputType: "skills",
           validAgents: request.validAgents
         });
@@ -6361,6 +6498,7 @@ async function syncSkills(request) {
           agentsDir: agentsDirPath,
           homeDir,
           targetId: target.id,
+          targetAliases: target.aliases,
           outputType: "skills",
           validAgents: request.validAgents,
           templateScriptRuntime
@@ -6698,7 +6836,7 @@ function buildInvalidTargetWarnings$1(commands) {
   }
   return warnings;
 }
-async function applyTemplatingToCommand(command, targetName, validAgents, runtime) {
+async function applyTemplatingToCommand(command, targetName, validAgents, runtime, targetAliases) {
   const withScripts = runtime ? await evaluateTemplateScripts({
     templatePath: command.sourcePath,
     content: command.rawContents,
@@ -6707,6 +6845,7 @@ async function applyTemplatingToCommand(command, targetName, validAgents, runtim
   const templatedContents = applyAgentTemplating({
     content: withScripts,
     target: targetName,
+    targetAliases,
     validAgents,
     sourcePath: command.sourcePath
   });
@@ -6974,7 +7113,8 @@ async function syncSlashCommands(request) {
         command,
         target.id,
         validAgents,
-        templateScriptRuntime
+        templateScriptRuntime,
+        target.aliases
       );
       const writer = resolveWriter(commandDef.writer, writerRegistry);
       const converter = resolveConverter(commandDef.converter, converterRegistry);
@@ -7050,6 +7190,7 @@ async function syncSlashCommands(request) {
           agentsDir: agentsDirPath,
           homeDir,
           targetId: target.id,
+          targetAliases: target.aliases,
           outputType: "commands",
           commandLocation: selected.location,
           validAgents
@@ -7111,6 +7252,7 @@ async function syncSlashCommands(request) {
             agentsDir: agentsDirPath,
             homeDir,
             targetId: target.id,
+            targetAliases: target.aliases,
             outputType: "commands",
             commandLocation: selected.location,
             validAgents,
@@ -8027,6 +8169,7 @@ async function syncSubagents(request) {
           agentsDir: agentsDirPath,
           homeDir,
           targetId: target.id,
+          targetAliases: target.aliases,
           outputType: "subagents",
           validAgents
         });
@@ -8087,6 +8230,7 @@ async function syncSubagents(request) {
           agentsDir: agentsDirPath,
           homeDir,
           targetId: target.id,
+          targetAliases: target.aliases,
           outputType: "subagents",
           validAgents,
           templateScriptRuntime
@@ -8474,7 +8618,9 @@ async function checkTargetAvailability(target) {
     checks
   };
 }
-const DEFAULT_SUPPORTED_TARGETS = BUILTIN_TARGETS.map((target) => target.id).join(", ");
+const DEFAULT_SUPPORTED_TARGETS = BUILTIN_TARGETS.map(
+  (target) => target.aliases?.length ? `${target.id} (alias: ${target.aliases.join(", ")})` : target.id
+).join(", ");
 const LOCAL_CATEGORIES = ["skills", "commands", "agents", "instructions"];
 const LOCAL_CATEGORY_SET = new Set(LOCAL_CATEGORIES);
 const utf8Decoder = new TextDecoder("utf-8", { fatal: true });
@@ -10377,6 +10523,7 @@ function makeUsageLimit(options) {
     modelLabel: options.modelLabel,
     percentUsed: options.percentUsed,
     percentRemaining: options.percentRemaining,
+    remainingText: emptyToNull(options.remainingText) ?? void 0,
     resetAt: parseResetAt(resetText, {
       now: options.now,
       sourceTimeZone: options.resetSourceTimeZone ?? "local"
@@ -10554,6 +10701,13 @@ function emptyToNull(value) {
 function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
+class UsageExtractionError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "UsageExtractionError";
+  }
+}
 const USAGE_BAR_WIDTH = 12;
 const ANSI = {
   reset: "\x1B[0m",
@@ -10588,6 +10742,12 @@ class UsageExtractionTimeoutError extends Error {
     this.timeoutMs = timeoutMs;
   }
 }
+class UsageCommandInterruptedError extends Error {
+  constructor() {
+    super("Usage cancelled.");
+    this.name = "UsageCommandInterruptedError";
+  }
+}
 function normalizeOptionalWindow(value) {
   if (value == null) {
     return null;
@@ -10658,6 +10818,68 @@ function uniqueNormalizedWindows(values) {
   }
   return result;
 }
+class UsageConfirmationPrompter {
+  rl = null;
+  queue = Promise.resolve();
+  closed = false;
+  interrupt;
+  constructor(interrupt) {
+    this.interrupt = interrupt;
+  }
+  confirm = (request, signal) => {
+    const confirmation = this.queue.then(() => this.ask(request, signal));
+    this.queue = confirmation.then(
+      () => void 0,
+      () => void 0
+    );
+    return confirmation;
+  };
+  close() {
+    this.closed = true;
+    this.rl?.close();
+    this.rl = null;
+  }
+  async ask(request, signal) {
+    if (this.closed) {
+      throw new Error("Usage confirmation is no longer available.");
+    }
+    if (signal.aborted) {
+      throw signal.reason instanceof Error ? signal.reason : new Error("Usage confirmation was cancelled.");
+    }
+    const scope = request.managed ? "managed usage directory" : "project directory";
+    const question = `${request.displayName} needs to trust this ${scope}:
+${request.path}
+
+Allow this? [y/N] `;
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    this.rl = rl;
+    const handleInterrupt = () => this.interrupt();
+    rl.once("SIGINT", handleInterrupt);
+    try {
+      while (true) {
+        const answer = (await rl.question(question, { signal })).trim().toLowerCase();
+        if (!answer || answer === "n" || answer === "no") {
+          return false;
+        }
+        if (answer === "y" || answer === "yes") {
+          return true;
+        }
+        console.error("Please enter yes or no.");
+      }
+    } catch (error) {
+      if (signal.aborted && signal.reason instanceof Error) {
+        throw signal.reason;
+      }
+      throw error;
+    } finally {
+      rl.removeListener("SIGINT", handleInterrupt);
+      rl.close();
+      if (this.rl === rl) {
+        this.rl = null;
+      }
+    }
+  }
+}
 function formatUsageTargetLabel(targets) {
   return buildSupportedTargetLabel(targets);
 }
@@ -10668,6 +10890,13 @@ function formatSupportedUsageTargetsMessage(targets) {
 function getUsageCommand(target) {
   return target.usage?.launch?.command;
 }
+function supportsUsageConfirmation(target) {
+  if (target.id.trim().toLowerCase() === "agy") {
+    return true;
+  }
+  const builtInAgyExtractor = BUILTIN_TARGETS.find((candidate) => candidate.id === "agy")?.usage?.extract;
+  return builtInAgyExtractor != null && target.usage?.extract === builtInAgyExtractor;
+}
 async function checkUsageCommandAvailability(target) {
   const command = getUsageCommand(target)?.trim();
   if (!command) {
@@ -10725,6 +10954,7 @@ function validateCodexCommand(candidate) {
 }
 function buildContext(options) {
   const windows = uniqueNormalizedWindows(options.target.usage?.windows ?? []);
+  const confirm = options.confirm;
   const launch = {
     ...options.target.usage?.launch ?? {},
     timeoutMs: options.timeoutMs
@@ -10741,6 +10971,7 @@ function buildContext(options) {
     homeDir: options.homeDir,
     launch,
     signal: options.signal,
+    confirm: confirm == null ? void 0 : (request) => confirm(request, options.signal),
     debug: {
       enabled: options.debug,
       includeRawOutput: options.debug,
@@ -10754,7 +10985,11 @@ function filterTargetResult(target, result, selectedWindow) {
     window: normalizeUsageWindow(limit.window)
   }));
   const filteredLimits = selectedWindow == null ? normalizedLimits : normalizedLimits.filter((limit) => limit.window === selectedWindow);
-  const notes = selectedWindow != null && filteredLimits.length === 0 ? [`${target.displayName} reported no usage rows for window "${selectedWindow}".`] : [];
+  const resultNotes = result.notes ?? [];
+  const notes = selectedWindow != null && filteredLimits.length === 0 ? [
+    ...resultNotes,
+    `${target.displayName} reported no usage rows for window "${selectedWindow}".`
+  ] : resultNotes;
   return {
     result: {
       targetId: result.targetId,
@@ -10789,10 +11024,14 @@ async function extractUsageForTarget(options) {
         debug: []
       };
     }
-    const result = await withUsageTimeout((signal) => {
-      const context = buildContext({ ...options, signal });
-      return extractor(context);
-    }, options.timeoutMs);
+    const result = await withUsageTimeout(
+      (signal) => {
+        const context = buildContext({ ...options, signal });
+        return extractor(context);
+      },
+      options.timeoutMs,
+      options.commandSignal
+    );
     const filtered = filterTargetResult(options.target, result, options.selectedWindow);
     return {
       status: "success",
@@ -10804,7 +11043,7 @@ async function extractUsageForTarget(options) {
     };
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    const code = isUsageTimeoutError(error) ? "usage_extraction_timeout" : "usage_extraction_failed";
+    const code = isUsageTimeoutError(error) ? "usage_extraction_timeout" : getUsageExtractionErrorCode(error);
     return {
       status: "error",
       target: options.target,
@@ -10813,6 +11052,21 @@ async function extractUsageForTarget(options) {
     };
   }
 }
+function getUsageExtractionErrorCode(error) {
+  if (error instanceof UsageExtractionError) {
+    return error.code;
+  }
+  if (error && typeof error === "object") {
+    const code = error.code;
+    if (typeof code === "string") {
+      const normalized = code.trim();
+      if (/^[a-z][a-z0-9_]*$/.test(normalized)) {
+        return normalized;
+      }
+    }
+  }
+  return "usage_extraction_failed";
+}
 function isUsageTimeoutError(error) {
   if (error instanceof UsageExtractionTimeoutError) {
     return true;
@@ -10836,18 +11090,25 @@ function isDebugArtifact(value) {
   const artifact = value;
   return (artifact.type === "raw-output" || artifact.type === "screen-snapshot") && typeof artifact.label === "string";
 }
-function withUsageTimeout(run, timeoutMs) {
+function withUsageTimeout(run, timeoutMs, commandSignal) {
   return new Promise((resolve, reject) => {
     const controller = new AbortController();
     let settled = false;
     let timeoutFired = false;
-    let timeout;
+    let timeout = null;
+    let removeCommandAbortListener = null;
+    const cleanup = () => {
+      if (timeout != null) {
+        clearTimeout(timeout);
+      }
+      removeCommandAbortListener?.();
+    };
     const settleResolve = (value) => {
       if (settled) {
         return;
       }
       settled = true;
-      clearTimeout(timeout);
+      cleanup();
       resolve(value);
     };
     const settleReject = (error) => {
@@ -10855,7 +11116,7 @@ function withUsageTimeout(run, timeoutMs) {
         return;
       }
       settled = true;
-      clearTimeout(timeout);
+      cleanup();
       reject(error);
     };
     timeout = setTimeout(() => {
@@ -10866,6 +11127,19 @@ function withUsageTimeout(run, timeoutMs) {
         settleReject(error);
       });
     }, timeoutMs);
+    if (commandSignal) {
+      const abortFromCommand = () => {
+        const reason = commandSignal.reason instanceof Error ? commandSignal.reason : new UsageCommandInterruptedError();
+        controller.abort(reason);
+        settleReject(reason);
+      };
+      if (commandSignal.aborted) {
+        abortFromCommand();
+        return;
+      }
+      commandSignal.addEventListener("abort", abortFromCommand, { once: true });
+      removeCommandAbortListener = () => commandSignal.removeEventListener("abort", abortFromCommand);
+    }
     let promise;
     try {
       promise = run(controller.signal);
@@ -11142,6 +11416,9 @@ function leftCellText(row) {
   if (row.status === "error") {
     return "-";
   }
+  if (row.limit.percentRemaining == null && row.limit.remainingText) {
+    return row.limit.remainingText;
+  }
   return percentText(row.limit.percentRemaining);
 }
 function resetCellText(row) {
@@ -11481,9 +11758,17 @@ async function runUsageCommand(argv) {
     }
   }
   const now = /* @__PURE__ */ new Date();
-  const outcomes = await Promise.all(
-    selectedTargets.map(
-      (target) => extractUsageForTarget({
+  const commandController = new AbortController();
+  const confirmationPrompter = !jsonOutput && Boolean(process.stdin.isTTY) && Boolean(process.stderr.isTTY) ? new UsageConfirmationPrompter(() => {
+    if (!commandController.signal.aborted) {
+      commandController.abort(new UsageCommandInterruptedError());
+    }
+  }) : null;
+  let outcomes;
+  try {
+    let confirmationTargetChain = Promise.resolve();
+    const outcomePromises = selectedTargets.map((target) => {
+      const extract = () => extractUsageForTarget({
         target,
         repoRoot,
         agentsDir,
@@ -11492,10 +11777,29 @@ async function runUsageCommand(argv) {
         timeoutMs: resolveTargetTimeoutMs(target, cliTimeoutMs),
         debug: debugOutput,
         now,
-        command: resolvedUsageCommands.get(target.id)
-      })
-    )
-  );
+        command: resolvedUsageCommands.get(target.id),
+        confirm: supportsUsageConfirmation(target) ? confirmationPrompter?.confirm : void 0,
+        commandSignal: commandController.signal
+      });
+      if (confirmationPrompter == null || !supportsUsageConfirmation(target)) {
+        return extract();
+      }
+      const outcome = confirmationTargetChain.then(extract);
+      confirmationTargetChain = outcome.then(
+        () => void 0,
+        () => void 0
+      );
+      return outcome;
+    });
+    outcomes = await Promise.all(outcomePromises);
+  } finally {
+    confirmationPrompter?.close();
+  }
+  if (commandController.signal.reason instanceof UsageCommandInterruptedError) {
+    console.error(commandController.signal.reason.message);
+    process.exit(130);
+    return null;
+  }
   const targets = [];
   const errors = [];
   const notes = [];
@@ -11581,7 +11885,7 @@ const usageCommand = {
     type: "boolean",
     describe: "Print JSON and include extractor debug artifacts when available."
   }).epilog(
-    "Usage extraction may launch agent TUIs and may incur cost if an agent reads repo context on startup. omniagent uses cheap/minimal launch settings where possible."
+    "Usage extraction may launch agent TUIs and may incur cost if an agent reads repo context on startup. Interactive runs may ask before forwarding directory trust; JSON, debug, and non-interactive runs never prompt."
   ),
   handler: async (argv) => {
     await runUsageCommand(argv);
@@ -11708,6 +12012,9 @@ function translateInvocation(invocation, cli, options = {}) {
       args.push(...mapped);
     }
   }
+  if (invocation.structuredOutput) {
+    args.push(...invocation.structuredOutput.args);
+  }
   if (mode === "one-shot" && base.args?.includes("exec")) {
     const searchIndex = args.indexOf("--search");
     if (searchIndex > -1) {
@@ -11765,9 +12072,344 @@ function buildAgentArgs(invocation) {
     warnings: translated.warnings
   };
 }
+const PREVIOUS_OUTPUT_LIMIT = 4e3;
+const RESPONSE_RULES = "Respond with only the JSON value - no explanations, no markdown code fences, no additional text.";
+function schemaBlock(schemaJson) {
+  return `Your entire response must be a single JSON value that conforms to this JSON Schema:
+${schemaJson}`;
+}
+function truncate(text, limit) {
+  if (text.length <= limit) {
+    return text;
+  }
+  return `${text.slice(0, limit)}
+[truncated]`;
+}
+function buildFallbackPrompt(prompt, schemaJson) {
+  const base = prompt.trim().length > 0 ? `${prompt}
+
+` : "";
+  return `${base}${schemaBlock(schemaJson)}
+
+${RESPONSE_RULES}`;
+}
+function buildRetryPrompt(prompt, schemaJson, previousOutput, errors) {
+  const base = prompt.trim().length > 0 ? `${prompt}
+
+` : "";
+  const previous = previousOutput.trim().length > 0 ? truncate(previousOutput.trim(), PREVIOUS_OUTPUT_LIMIT) : "(empty response)";
+  const errorLines = errors.map((error) => `- ${error}`).join("\n");
+  return [
+    `${base}${schemaBlock(schemaJson)}`,
+    `Your previous response failed validation.
+
+Previous response:
+${previous}`,
+    `Validation errors:
+${errorLines}`,
+    `Respond again with only the corrected JSON value. ${RESPONSE_RULES}`
+  ].join("\n\n");
+}
+function tryParse(text) {
+  try {
+    return { ok: true, value: JSON.parse(text) };
+  } catch {
+    return null;
+  }
+}
+function extractJsonPayload(text) {
+  const trimmed = text.trim();
+  if (trimmed.length === 0) {
+    return { ok: false, error: "the response was empty" };
+  }
+  const whole = tryParse(trimmed);
+  if (whole) {
+    return whole;
+  }
+  const fenced = trimmed.match(/```(?:json)?\s*\n?([\s\S]*?)```/);
+  if (fenced?.[1]) {
+    const parsed = tryParse(fenced[1].trim());
+    if (parsed) {
+      return parsed;
+    }
+  }
+  for (const [open, close] of [
+    ["{", "}"],
+    ["[", "]"]
+  ]) {
+    const start = trimmed.indexOf(open);
+    const end = trimmed.lastIndexOf(close);
+    if (start !== -1 && end > start) {
+      const parsed = tryParse(trimmed.slice(start, end + 1));
+      if (parsed) {
+        return parsed;
+      }
+    }
+  }
+  return { ok: false, error: "the response did not contain parseable JSON" };
+}
+function withPipedStdout(stdio) {
+  if (Array.isArray(stdio)) {
+    return [stdio[0] ?? "inherit", "pipe", stdio[2] ?? "inherit"];
+  }
+  return [stdio, "pipe", stdio];
+}
+function mapExitCode(code) {
+  if (code === 0) {
+    return { exitCode: 0, reason: "success" };
+  }
+  if (code === 2) {
+    return { exitCode: 2, reason: "invalid-usage" };
+  }
+  if (code === 3) {
+    return { exitCode: 3, reason: "blocked" };
+  }
+  return { exitCode: 1, reason: "execution-error" };
+}
+async function finalizeStructuredOutput(options) {
+  const { plan, agentId, code, captured, stdout, stderr } = options;
+  if (code !== 0) {
+    if (plan.capture.type === "json-envelope" && captured.length > 0) {
+      stderr.write(captured);
+    }
+    return mapExitCode(code);
+  }
+  if (plan.capture.type === "json-envelope") {
+    let envelope;
+    try {
+      envelope = JSON.parse(captured);
+    } catch {
+      envelope = void 0;
+    }
+    if (typeof envelope !== "object" || envelope === null || Array.isArray(envelope)) {
+      stderr.write(captured);
+      stderr.write(`Error: ${agentId} did not return a JSON envelope.
+`);
+      return { exitCode: 1, reason: "execution-error" };
+    }
+    const record = envelope;
+    if (record.is_error === true) {
+      stderr.write(captured);
+      stderr.write(`Error: ${agentId} reported an error result.
+`);
+      return { exitCode: 1, reason: "execution-error" };
+    }
+    const payload = record[plan.capture.field];
+    if (payload === void 0 || payload === null) {
+      stderr.write(captured);
+      stderr.write(`Error: ${agentId} response is missing ${plan.capture.field}.
+`);
+      return { exitCode: 1, reason: "execution-error" };
+    }
+    stdout.write(`${JSON.stringify(payload)}
+`);
+    return { exitCode: 0, reason: "success" };
+  }
+  if (plan.capture.type === "fallback") {
+    return { exitCode: 1, reason: "execution-error" };
+  }
+  let contents;
+  try {
+    contents = await readFile(plan.capture.path, "utf8");
+  } catch {
+    contents = "";
+  }
+  const trimmed = contents.trim();
+  if (!trimmed) {
+    stderr.write(`Error: ${agentId} did not produce a structured output message.
+`);
+    return { exitCode: 1, reason: "execution-error" };
+  }
+  stdout.write(`${trimmed}
+`);
+  return { exitCode: 0, reason: "success" };
+}
+function runCapturedAttempt(params) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const settle = (value) => {
+      if (!settled) {
+        settled = true;
+        resolve(value);
+      }
+    };
+    const child = params.spawn(params.command, params.args, { stdio: params.stdio });
+    const chunks = [];
+    const childStdout = child.stdout;
+    if (childStdout) {
+      childStdout.on("data", (chunk) => {
+        chunks.push(Buffer.from(chunk));
+      });
+    }
+    child.on("error", (error) => {
+      params.stderr.write(`Error: ${error.message}
+`);
+      settle({ kind: "spawn-error" });
+    });
+    child.on("close", (code) => {
+      if (!childStdout) {
+        params.stderr.write(`Error: ${params.agentId} stdout was not captured.
+`);
+        settle({ kind: "spawn-error" });
+        return;
+      }
+      settle({ kind: "closed", code, captured: Buffer.concat(chunks).toString("utf8") });
+    });
+  });
+}
+function extractEnvelopeText(params) {
+  const { captured, field, agentId, stderr } = params;
+  let envelope;
+  try {
+    envelope = JSON.parse(captured);
+  } catch {
+    envelope = void 0;
+  }
+  if (typeof envelope !== "object" || envelope === null || Array.isArray(envelope)) {
+    if (captured.length > 0) {
+      stderr.write(captured);
+    }
+    stderr.write(`Error: ${agentId} did not return a JSON envelope.
+`);
+    return { ok: false };
+  }
+  const record = envelope;
+  if (record.error !== void 0 && record.error !== null) {
+    stderr.write(captured);
+    stderr.write(`Error: ${agentId} reported an error result.
+`);
+    return { ok: false };
+  }
+  const payload = record[field];
+  if (payload === void 0 || payload === null) {
+    stderr.write(captured);
+    stderr.write(`Error: ${agentId} response is missing ${field}.
+`);
+    return { ok: false };
+  }
+  return { ok: true, text: typeof payload === "string" ? payload : JSON.stringify(payload) };
+}
+async function runFallbackAttempts(params) {
+  const { invocation, plan, capture, options, stdout, stderr } = params;
+  const agentId = invocation.agent.id;
+  const spawn$1 = options.spawn ?? spawn;
+  const stdio = withPipedStdout(options.stdio ?? "inherit");
+  const originalPrompt = invocation.prompt ?? "";
+  const validate = plan.validate ?? (() => ({ valid: true, errors: [] }));
+  let feedback = null;
+  for (let attempt = 1; attempt <= capture.maxAttempts; attempt += 1) {
+    const attemptPrompt = feedback ? buildRetryPrompt(originalPrompt, plan.schemaJson, feedback.output, feedback.errors) : buildFallbackPrompt(originalPrompt, plan.schemaJson);
+    const built = buildAgentArgs({ ...invocation, prompt: attemptPrompt });
+    if (attempt === 1) {
+      if (options.traceTranslate) {
+        const trace = {
+          agent: agentId,
+          mode: invocation.mode,
+          command: built.command,
+          args: built.args,
+          shimArgs: built.shimArgs,
+          passthroughArgs: built.passthroughArgs,
+          warnings: built.warnings,
+          requests: invocation.requests,
+          structuredOutput: { capture: capture.type, maxAttempts: capture.maxAttempts }
+        };
+        stderr.write(`OA_TRANSLATION=${JSON.stringify(trace)}
+`);
+      }
+      for (const warning of built.warnings) {
+        stderr.write(`${warning}
+`);
+      }
+      for (const notice of plan.notices ?? []) {
+        stderr.write(`${notice}
+`);
+      }
+    }
+    const attemptResult = await runCapturedAttempt({
+      spawn: spawn$1,
+      command: built.command,
+      args: built.args,
+      stdio,
+      agentId,
+      stderr
+    });
+    if (attemptResult.kind === "spawn-error") {
+      return { exitCode: 1, reason: "execution-error" };
+    }
+    if (attemptResult.code !== 0) {
+      if (attemptResult.captured.length > 0) {
+        stderr.write(attemptResult.captured);
+      }
+      return mapExitCode(attemptResult.code);
+    }
+    let responseText = attemptResult.captured;
+    if (capture.extraction.type === "json-envelope") {
+      const outcome = extractEnvelopeText({
+        captured: attemptResult.captured,
+        field: capture.extraction.field,
+        agentId,
+        stderr
+      });
+      if (!outcome.ok) {
+        return { exitCode: 1, reason: "execution-error" };
+      }
+      responseText = outcome.text;
+    }
+    const extracted = extractJsonPayload(responseText);
+    if (extracted.ok) {
+      const result = validate(extracted.value);
+      if (result.valid) {
+        stdout.write(`${JSON.stringify(extracted.value)}
+`);
+        return { exitCode: 0, reason: "success" };
+      }
+      feedback = { output: responseText, errors: result.errors };
+    } else {
+      feedback = { output: responseText, errors: [extracted.error] };
+    }
+    if (attempt < capture.maxAttempts) {
+      stderr.write(
+        `Attempt ${attempt} failed schema validation; retrying (${attempt + 1}/${capture.maxAttempts}).
+`
+      );
+      for (const error of feedback.errors) {
+        stderr.write(`- ${error}
+`);
+      }
+    }
+  }
+  if (feedback) {
+    const lastOutput = feedback.output.trim();
+    if (lastOutput.length > 0) {
+      stderr.write(`${lastOutput}
+`);
+    }
+    for (const error of feedback.errors) {
+      stderr.write(`- ${error}
+`);
+    }
+  }
+  stderr.write(
+    `Error: ${agentId} response failed schema validation after ${capture.maxAttempts} attempts.
+`
+  );
+  return { exitCode: 1, reason: "execution-error" };
+}
 async function executeInvocation(invocation, options = {}) {
-  const { command, args, warnings, shimArgs, passthroughArgs } = buildAgentArgs(invocation);
   const stderr = options.stderr ?? process.stderr;
+  const stdout = options.stdout ?? process.stdout;
+  const plan = invocation.structuredOutput;
+  if (plan && plan.capture.type === "fallback") {
+    return runFallbackAttempts({
+      invocation,
+      plan,
+      capture: plan.capture,
+      options,
+      stdout,
+      stderr
+    });
+  }
+  const { command, args, warnings, shimArgs, passthroughArgs } = buildAgentArgs(invocation);
   if (options.traceTranslate) {
     const trace = {
       agent: invocation.agent.id,
@@ -11777,17 +12419,23 @@ async function executeInvocation(invocation, options = {}) {
       shimArgs,
       passthroughArgs,
       warnings,
-      requests: invocation.requests
+      requests: invocation.requests,
+      ...plan ? { structuredOutput: { capture: plan.capture.type } } : {}
     };
     stderr.write(`OA_TRANSLATION=${JSON.stringify(trace)}
 `);
   }
   for (const warning of warnings) {
     stderr.write(`${warning}
+`);
+  }
+  for (const notice of plan?.notices ?? []) {
+    stderr.write(`${notice}
 `);
   }
   const spawn$1 = options.spawn ?? spawn;
-  const stdio = options.stdio ?? "inherit";
+  const baseStdio = options.stdio ?? "inherit";
+  const stdio = plan ? withPipedStdout(baseStdio) : baseStdio;
   return await new Promise((resolve) => {
     const child = spawn$1(command, args, { stdio });
     child.on("error", (error) => {
@@ -11795,20 +12443,40 @@ async function executeInvocation(invocation, options = {}) {
 `);
       resolve({ exitCode: 1, reason: "execution-error" });
     });
-    child.on("exit", (code) => {
-      if (code === 0) {
-        resolve({ exitCode: 0, reason: "success" });
-        return;
-      }
-      if (code === 2) {
-        resolve({ exitCode: 2, reason: "invalid-usage" });
-        return;
+    if (!plan) {
+      child.on("exit", (code) => {
+        resolve(mapExitCode(code));
+      });
+      return;
+    }
+    const chunks = [];
+    const childStdout = child.stdout;
+    if (childStdout) {
+      if (plan.capture.type === "json-envelope") {
+        childStdout.on("data", (chunk) => {
+          chunks.push(Buffer.from(chunk));
+        });
+      } else {
+        childStdout.on("data", (chunk) => {
+          stderr.write(chunk);
+        });
       }
-      if (code === 3) {
-        resolve({ exitCode: 3, reason: "blocked" });
+    }
+    child.on("close", (code) => {
+      if (!childStdout) {
+        stderr.write(`Error: ${invocation.agent.id} stdout was not captured.
+`);
+        resolve({ exitCode: 1, reason: "execution-error" });
         return;
       }
-      resolve({ exitCode: 1, reason: "execution-error" });
+      void finalizeStructuredOutput({
+        plan,
+        agentId: invocation.agent.id,
+        code,
+        captured: Buffer.concat(chunks).toString("utf8"),
+        stdout,
+        stderr
+      }).then(resolve);
     });
   });
 }
@@ -11846,6 +12514,16 @@ function readFlagValue(args, index, label) {
   }
   return [value, index + 1];
 }
+function parseRetriesValue(value) {
+  const normalized = normalizeValue(value, "--output-schema-retries");
+  const parsed = Number(normalized);
+  if (!Number.isInteger(parsed) || parsed < 0 || parsed > 10) {
+    throw new InvalidUsageError(
+      "Invalid value for --output-schema-retries. Provide an integer between 0 and 10."
+    );
+  }
+  return parsed;
+}
 function parseBooleanValue(label, value) {
   const normalized = normalizeValue(value, label).toLowerCase();
   if (["on", "true", "1"].includes(normalized)) {
@@ -11874,6 +12552,9 @@ function parseShimFlags(argv) {
   let webExplicit = false;
   let agent = null;
   let agentExplicit = false;
+  let outputSchema = null;
+  let outputSchemaExplicit = false;
+  let outputSchemaRetries = null;
   let traceTranslate = false;
   let help = false;
   let version = false;
@@ -12011,6 +12692,28 @@ function parseShimFlags(argv) {
       agentExplicit = true;
       continue;
     }
+    if (arg === "--output-schema-retries") {
+      const [value, nextIndex] = readFlagValue(preArgs, index, "--output-schema-retries");
+      outputSchemaRetries = parseRetriesValue(value);
+      index = nextIndex;
+      continue;
+    }
+    if (arg.startsWith("--output-schema-retries=")) {
+      outputSchemaRetries = parseRetriesValue(arg.slice("--output-schema-retries=".length));
+      continue;
+    }
+    if (arg === "--output-schema") {
+      const [value, nextIndex] = readFlagValue(preArgs, index, "--output-schema");
+      outputSchema = normalizeValue(value, "--output-schema");
+      outputSchemaExplicit = true;
+      index = nextIndex;
+      continue;
+    }
+    if (arg.startsWith("--output-schema=")) {
+      outputSchema = normalizeValue(arg.slice("--output-schema=".length), "--output-schema");
+      outputSchemaExplicit = true;
+      continue;
+    }
     if (arg === "--trace-translate") {
       traceTranslate = true;
       continue;
@@ -12029,6 +12732,14 @@ function parseShimFlags(argv) {
   if (outputSelections.length > 0) {
     output = outputSelections[outputSelections.length - 1];
   }
+  if (outputSchema !== null && outputExplicit) {
+    throw new InvalidUsageError(
+      "--output-schema cannot be combined with --output, --json, or --stream-json."
+    );
+  }
+  if (outputSchemaRetries !== null && outputSchema === null) {
+    throw new InvalidUsageError("--output-schema-retries requires --output-schema.");
+  }
   if (approval === "yolo" && !sandboxExplicit) {
     sandbox = "off";
   }
@@ -12047,6 +12758,9 @@ function parseShimFlags(argv) {
     webExplicit,
     agent,
     agentExplicit,
+    outputSchema,
+    outputSchemaExplicit,
+    outputSchemaRetries,
     traceTranslate,
     help,
     version,
@@ -12145,6 +12859,157 @@ async function resolveAgentSelection(flags, repoRoot, agentsDir) {
   }
   return { resolution: { selection, targetId: resolvedId }, targetMap };
 }
+const AJV_OPTIONS = { allErrors: true, strict: false, validateFormats: false };
+const instances = /* @__PURE__ */ new Map();
+function resolveDialect(schema) {
+  const declared = typeof schema.$schema === "string" ? schema.$schema : "";
+  if (declared.includes("2020-12")) {
+    return "2020-12";
+  }
+  if (declared.includes("2019-09")) {
+    return "2019-09";
+  }
+  return "draft-07";
+}
+function ajvForDialect(dialect) {
+  let instance = instances.get(dialect);
+  if (!instance) {
+    instance = dialect === "2020-12" ? new Ajv2020(AJV_OPTIONS) : dialect === "2019-09" ? new Ajv2019(AJV_OPTIONS) : new Ajv(AJV_OPTIONS);
+    instances.set(dialect, instance);
+  }
+  return instance;
+}
+function compileSchemaValidator(schemaJson) {
+  let compiled;
+  try {
+    const schema = JSON.parse(schemaJson);
+    compiled = ajvForDialect(resolveDialect(schema)).compile(schema);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new InvalidUsageError(`Invalid value for --output-schema: ${message}.`);
+  }
+  return (data) => {
+    const valid = compiled(data) === true;
+    const errors = (compiled.errors ?? []).map(
+      (error) => `${error.instancePath || "/"}: ${error.message ?? "is invalid"}`
+    );
+    return { valid, errors };
+  };
+}
+const SCHEMA_LABEL = "--output-schema";
+const DEFAULT_SCHEMA_RETRIES = 2;
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseSchemaJson(text, sourceLabel) {
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new InvalidUsageError(`Invalid value for ${SCHEMA_LABEL}: ${sourceLabel}.`);
+  }
+  if (!isPlainObject(parsed)) {
+    throw new InvalidUsageError(`Invalid value for ${SCHEMA_LABEL}: schema must be a JSON object.`);
+  }
+  return JSON.stringify(parsed);
+}
+async function resolveOutputSchema(raw) {
+  const trimmed = raw.trim();
+  if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+    return parseSchemaJson(trimmed, "schema is not valid JSON");
+  }
+  let contents;
+  try {
+    contents = await readFile(trimmed, "utf8");
+  } catch {
+    throw new InvalidUsageError(
+      `Invalid value for ${SCHEMA_LABEL}: cannot read schema file ${trimmed}.`
+    );
+  }
+  return parseSchemaJson(contents, `schema file ${trimmed} is not valid JSON`);
+}
+async function planStructuredOutput(options) {
+  const { rawSchema, mode, agentId, spec } = options;
+  if (rawSchema === null) {
+    return null;
+  }
+  if (mode !== "one-shot") {
+    throw new InvalidUsageError(
+      `${SCHEMA_LABEL} requires one-shot mode; provide -p/--prompt or pipe stdin.`
+    );
+  }
+  if (!spec) {
+    return planFallback(options);
+  }
+  const notices = [];
+  if (options.retries !== null && options.retries !== void 0) {
+    notices.push(
+      `Warning: ${agentId} uses native ${SCHEMA_LABEL} support; ignoring ${SCHEMA_LABEL}-retries.`
+    );
+  }
+  const schemaJson = await resolveOutputSchema(rawSchema);
+  const needsTempDir = spec.delivery === "file" || spec.extraction.type === "last-message-file";
+  const tempPaths = [];
+  let tempDirPath = null;
+  if (needsTempDir) {
+    tempDirPath = await mkdtemp(path.join(options.tempDir ?? os.tmpdir(), "omniagent-schema-"));
+    tempPaths.push(tempDirPath);
+  }
+  let deliveryValue = schemaJson;
+  if (spec.delivery === "file" && tempDirPath) {
+    deliveryValue = path.join(tempDirPath, "schema.json");
+    await writeFile(deliveryValue, schemaJson, "utf8");
+  }
+  const args = [...spec.flag, deliveryValue, ...spec.companionArgs ?? []];
+  let capture;
+  if (spec.extraction.type === "json-envelope") {
+    capture = { type: "json-envelope", field: spec.extraction.field };
+  } else {
+    const lastMessagePath = path.join(tempDirPath ?? os.tmpdir(), "last-message.txt");
+    args.push(...spec.extraction.flag, lastMessagePath);
+    capture = { type: "last-message-file", path: lastMessagePath };
+  }
+  return { schemaJson, args, capture, tempPaths, notices };
+}
+async function planFallback(options) {
+  const { rawSchema, agentId, fallbackSpec } = options;
+  if (rawSchema === null) {
+    return null;
+  }
+  if (options.promptDeliverable === false) {
+    throw new InvalidUsageError(
+      `${agentId} cannot use the ${SCHEMA_LABEL} fallback: target defines no prompt flag.`
+    );
+  }
+  const schemaJson = await resolveOutputSchema(rawSchema);
+  const validate = compileSchemaValidator(schemaJson);
+  const maxAttempts = (options.retries ?? DEFAULT_SCHEMA_RETRIES) + 1;
+  return {
+    schemaJson,
+    args: [...fallbackSpec?.args ?? []],
+    capture: {
+      type: "fallback",
+      extraction: fallbackSpec?.extraction ?? { type: "text" },
+      maxAttempts
+    },
+    tempPaths: [],
+    validate,
+    notices: [
+      `Notice: ${agentId} lacks native ${SCHEMA_LABEL} support; using prompt-based fallback with client-side validation.`
+    ]
+  };
+}
+async function cleanupStructuredOutput(plan) {
+  if (!plan) {
+    return;
+  }
+  for (const tempPath of plan.tempPaths) {
+    try {
+      await rm(tempPath, { recursive: true, force: true });
+    } catch {
+    }
+  }
+}
 function normalizeKey(value) {
   return value.trim().toLowerCase();
 }
@@ -12165,6 +13030,16 @@ async function resolveInvocationFromFlags(options) {
   const agent = resolution.selection;
   const session = buildSession(flags);
   const requests = buildRequests(flags);
+  const structuredOutput = await planStructuredOutput({
+    rawSchema: flags.outputSchema,
+    mode,
+    agentId: agent.id,
+    spec: target.cli?.flags?.structuredOutput,
+    fallbackSpec: target.cli?.flags?.structuredOutputFallback,
+    retries: flags.outputSchemaRetries,
+    promptDeliverable: Boolean(target.cli?.prompt),
+    tempDir: options.tempDir
+  });
   return {
     mode,
     prompt,
@@ -12176,7 +13051,8 @@ async function resolveInvocationFromFlags(options) {
     passthrough: {
       hasDelimiter: flags.hasDelimiter,
       args: flags.passthroughArgs
-    }
+    },
+    structuredOutput
   };
 }
 async function readStreamText(stream) {
@@ -12195,6 +13071,7 @@ async function runShim(argv, runtime = {}) {
   const stdin = runtime.stdin ?? process.stdin;
   const repoRoot = runtime.repoRoot ?? await findRepoRoot(process.cwd()) ?? process.cwd();
   const stdinIsTTY = runtime.stdinIsTTY ?? stdin.isTTY ?? false;
+  let invocation = null;
   try {
     const flags = parseShimFlags(argv);
     let stdinText = runtime.stdinText ?? null;
@@ -12210,16 +13087,18 @@ async function runShim(argv, runtime = {}) {
       }
     }
     const stdio = !stdinIsTTY && flags.promptExplicit ? ["ignore", "inherit", "inherit"] : "inherit";
-    const invocation = await resolveInvocationFromFlags({
+    invocation = await resolveInvocationFromFlags({
       flags,
       stdinIsTTY,
       stdinText,
       repoRoot,
-      agentsDir: runtime.agentsDir
+      agentsDir: runtime.agentsDir,
+      tempDir: runtime.tempDir
     });
     const result = await executeInvocation(invocation, {
       spawn: runtime.spawn,
       stderr,
+      stdout: runtime.stdout,
       stdio,
       traceTranslate: flags.traceTranslate
     });
@@ -12234,6 +13113,8 @@ async function runShim(argv, runtime = {}) {
     stderr.write(`Error: ${message}
 `);
     return exitCodeFor("execution-error");
+  } finally {
+    await cleanupStructuredOutput(invocation?.structuredOutput);
   }
 }
 function resolveVersion() {
@@ -12260,11 +13141,13 @@ const VERSION = resolveVersion();
 const KNOWN_COMMANDS = /* @__PURE__ */ new Set(["hello", "greet", "echo", "sync", "dev", "profiles", "usage"]);
 const SHIM_CAPABILITIES = [
   "Capabilities by agent:",
-  "  codex: approval, sandbox, output, model, web",
-  "  claude: approval, output, model",
-  "  gemini: approval, sandbox, output, model, web",
-  "  copilot: approval, model",
-  "Unsupported shared flags for a selected agent emit a warning and are ignored."
+  "  codex: approval, sandbox, output, model, web, output-schema",
+  "  claude: approval, output, model, output-schema",
+  "  agy: approval, sandbox, model, output-schema (fallback) (alias: gemini)",
+  "  copilot: approval, model, output-schema (fallback)",
+  "Unsupported shared flags for a selected agent emit a warning and are ignored.",
+  "--output-schema is one-shot only; agents without native support use a prompt-based",
+  "fallback with client-side validation and retries (--output-schema-retries, default 2)."
 ].join("\n");
 function formatError(message, args) {
   if (message.startsWith("Unknown command:")) {
@@ -12345,6 +13228,12 @@ function runCli(argv = process.argv, options = {}) {
     }).option("agent", {
       type: "string",
       describe: "Select the agent (built-in id or configured alias)."
+    }).option("output-schema", {
+      type: "string",
+      describe: "JSON schema file path or inline JSON; emit the final response as schema-conforming JSON (one-shot only)."
+    }).option("output-schema-retries", {
+      type: "number",
+      describe: "Max retries when a prompt-based --output-schema fallback response fails validation (0-10, default 2)."
     }).option("trace-translate", {
       type: "boolean",
       describe: "Emit a JSON line to stderr with the translated agent command/args."
@@ -12367,11 +13256,12 @@ if (!entry) {
   }
 }
 export {
+  UsageExtractionError as U,
   compactLines as a,
-  parsePercentRemaining as b,
+  parsePercentUsed as b,
   cleanControlOutput as c,
   parseResetText as d,
   makeUsageLimit as m,
-  parsePercentUsed as p,
+  parsePercentRemaining as p,
   runCli
 };