argsbarg 7.0.3 → 7.0.5

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [7.0.5] - 2026-09-15
+
+### Added
+
+- **Interleaved options between positionals** — options (presence flags and value options) can now be placed anywhere between bounded or optional positional arguments (e.g. `cmd file1 --force file2`), matching varargs tail behavior rather than requiring all options to precede or follow all bounded positionals.
+
+## [7.0.4] - 2026-08-17
+
+### Changed
+
+- **Breaking: leaf-local options only** — options apply on the command node where they are declared (routing groups cannot declare options; program root still may). MCP, OpenAPI, HTTP, and skill wire schemas expose leaf-local options only. `tools/list` is sorted alphabetically by tool name. MCP auto-injects `--yes` for mutating tools; `json`, `yes`, and `verbose` are omitted from MCP/HTTP wire schemas.
+
 ## [7.0.3] - 2026-08-13
 
 ### Fixed
@@ -953,7 +965,9 @@ const cli = { ... } satisfies CliProgram;  // or : CliProgram
 - Migrate schemas: rename every `children` property to **`commands`**; move positional definitions to **`CliPositional`** objects on `positionals` and strip `positional` / `argMin` / `argMax` from flag definitions under `options` (flags only carry `name`, `description`, `kind`, and optional `shortName`).
 - Imports: use `CliPositional` where needed; replace `CliOptionDef` with `CliOption` or `CliPositional` as appropriate.
 
-[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v7.0.3...HEAD
+[Unreleased]: https://github.com/bdombro/bun-argsbarg/compare/v7.0.5...HEAD
+[7.0.5]: https://github.com/bdombro/bun-argsbarg/releases/tag/v7.0.5
+[7.0.4]: https://github.com/bdombro/bun-argsbarg/releases/tag/v7.0.4
 [7.0.3]: https://github.com/bdombro/bun-argsbarg/releases/tag/v7.0.3
 [7.0.2]: https://github.com/bdombro/bun-argsbarg/releases/tag/v7.0.2
 [7.0.1]: https://github.com/bdombro/bun-argsbarg/releases/tag/v7.0.1

package/docs/cli-program.md

@@ -107,6 +107,7 @@ Use root **`notes`** for cross-cutting hints shown in help (install commands, do
 
 Descriptions and schemas are copied into MCP tools, HTTP OpenAPI, and generated skills — optimize for smaller, clearer agent payloads:
 
+- **Declare options on the leaf command** that uses them — routing groups cannot declare options (program root may). Wire schemas (MCP, OpenAPI, skills) expose leaf-local options only.
 - Prefer **`kind: "json"`** leaves with schemagen `inputSchema` for complex tool bodies (one nested object beats many flat flags).
 - Keep **`description`** strings short and action-oriented; put examples in **`notes`**, not duplicated in every option.
 - Use **`hidden: true`** or **`mcpTool.enabled: false`** for debug/internal commands.

package/docs/mcp.md

@@ -169,7 +169,7 @@ Set **`outputSchema` on the leaf** (not under `mcpTool`) — see [cli-program.md
 
 Each tool’s `inputSchema` is a JSON Schema object built from your CLI definition:
 
-- **Options** — parent-scoped flags are included (e.g. `stat`’s `--json` appears on `stat_owner_lookup`). Presence options are `boolean`; string, number, and **enum** options match their `CliOptionKind` (`Enum` uses JSON Schema `enum`). Required options are listed in `required`.
+- **Options** — leaf-local flags only (declare on the command that uses them). Presence options are `boolean`; string, number, and **enum** options match their `CliOptionKind` (`Enum` uses JSON Schema `enum`). Required options are listed in `required`. `json`, `yes`, and `verbose` are omitted from MCP wire schemas (the framework handles them on invoke; mutating tools auto-receive `--yes`).
 - **Positionals** — one property per `CliPositional` on the leaf. Single-slot positionals are `string`; varargs tails (`argMax: 0`) are `string[]`. Required positionals are listed in `required`. **Varargs must be a JSON array** — comma-separated strings are not accepted (use `format: comma-list` on an option when a single flag should accept `"a,b"` or `["a","b"]`).
 
 Arguments are a **flat JSON object** keyed by option and positional names (same names as in your schema, including hyphenated option names like `"user-name"`).

package/examples/nested.ts

@@ -8,20 +8,13 @@ It demonstrates how the schema scales beyond one command.
 */
 
 import pkg from "../package.json" with { type: "json" };
-import { Cli, CliFallbackMode, CliOptionKind, type CliProgram } from "../src/index";
+import { Cli, CliFallbackMode, CliOptionKind, type CliProgram, wantsExplicitJson } from "../src/index";
 
 const program = {
   commands: [
     {
       key: "stat",
       description: "File metadata.",
-      options: [
-        {
-          name: "json",
-          description: "Emit handler output as JSON.",
-          kind: CliOptionKind.Presence,
-        },
-      ],
       commands: [
         {
           key: "owner",
@@ -31,6 +24,11 @@ const program = {
               key: "lookup",
               description: "Resolve owner info.",
               options: [
+                {
+                  name: "json",
+                  description: "Emit handler output as JSON.",
+                  kind: CliOptionKind.Presence,
+                },
                 {
                   name: "user-name",
                   description: "User to look up.",
@@ -52,7 +50,7 @@ const program = {
                   console.error("Missing path.");
                   process.exit(1);
                 }
-                if (ctx.hasFlag("json")) {
+                if (wantsExplicitJson(ctx, ctx.hasFlag("json"))) {
                   const payload = { user, path };
                   if (ctx.invocation === "cli") {
                     console.log(JSON.stringify(payload));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "7.0.3",
+  "version": "7.0.5",
   "main": "./src/index.ts",
   "module": "./src/index.ts",
   "dependencies": {

package/src/core/parse.test.ts

@@ -370,8 +370,186 @@ test("trailing options after bounded positionals", () => {
   expect(pr.opts.verbose).toBe("1");
 });
 
-/** Tests that trailing options include parent-scoped flags. */
-test("trailing options include parent-scoped flags", () => {
+/** Tests that options can be interleaved between bounded positionals. */
+test("options interleaved between bounded positionals", () => {
+  const root = testProgram({
+    key: "app",
+    description: "",
+    commands: [
+      {
+        key: "copy",
+        description: "copy",
+        options: [
+          {
+            name: "force",
+            description: "",
+            kind: CliOptionKind.Presence,
+            shortName: "f",
+          },
+          {
+            name: "mode",
+            description: "",
+            kind: CliOptionKind.String,
+          },
+        ],
+        positionals: [
+          {
+            name: "src",
+            description: "",
+            kind: CliOptionKind.String,
+          },
+          {
+            name: "dest",
+            description: "",
+            kind: CliOptionKind.String,
+          },
+        ],
+        handler: () => {},
+      },
+    ],
+  });
+  cliValidateProgram(root);
+
+  // Presence flag interleaved between positionals
+  const prPresence = postParseValidate(root, parse(root, ["copy", "file1", "--force", "file2"]));
+  expect(prPresence.kind).toBe(ParseKind.Ok);
+  expect(prPresence.args).toEqual(["file1", "file2"]);
+  expect(prPresence.opts.force).toBe("1");
+
+  // String option with value interleaved between positionals
+  const prString = postParseValidate(root, parse(root, ["copy", "file1", "--mode", "fast", "file2"]));
+  expect(prString.kind).toBe(ParseKind.Ok);
+  expect(prString.args).toEqual(["file1", "file2"]);
+  expect(prString.opts.mode).toBe("fast");
+
+  // Multiple flags interleaved between positionals
+  const prMulti = postParseValidate(root, parse(root, ["copy", "file1", "--mode", "fast", "-f", "file2"]));
+  expect(prMulti.kind).toBe(ParseKind.Ok);
+  expect(prMulti.args).toEqual(["file1", "file2"]);
+  expect(prMulti.opts.mode).toBe("fast");
+  expect(prMulti.opts.force).toBe("1");
+
+  // Unknown option interleaved between positionals returns error
+  const prUnknown = postParseValidate(root, parse(root, ["copy", "file1", "--unknown", "file2"]));
+  expect(prUnknown.kind).toBe(ParseKind.Error);
+  expect(prUnknown.errorMsg).toContain("Unknown option: --unknown");
+
+  // Interleaved help request triggers contextual help
+  const prHelp = parse(root, ["copy", "file1", "-h"]);
+  expect(prHelp.kind).toBe(ParseKind.Help);
+  expect(prHelp.helpPath).toEqual(["copy"]);
+
+  // Double dash between positionals disables option consumption
+  const prDoubleDash = postParseValidate(root, parse(root, ["copy", "file1", "--", "--force"]));
+  expect(prDoubleDash.kind).toBe(ParseKind.Ok);
+  expect(prDoubleDash.args).toEqual(["file1", "--force"]);
+  expect(prDoubleDash.opts.force).toBeUndefined();
+});
+
+/** Tests that options can be interleaved with optional positionals. */
+test("options interleaved with optional positionals", () => {
+  const root = testProgram({
+    key: "app",
+    description: "",
+    commands: [
+      {
+        key: "deploy",
+        description: "deploy",
+        options: [
+          {
+            name: "force",
+            description: "",
+            kind: CliOptionKind.Presence,
+          },
+        ],
+        positionals: [
+          {
+            name: "env",
+            description: "",
+            kind: CliOptionKind.String,
+            argMin: 0,
+            argMax: 1,
+          },
+          {
+            name: "target",
+            description: "",
+            kind: CliOptionKind.String,
+            argMin: 0,
+            argMax: 1,
+          },
+        ],
+        handler: () => {},
+      },
+    ],
+  });
+  cliValidateProgram(root);
+
+  // Interleaved between two optional positionals
+  const prBoth = postParseValidate(root, parse(root, ["deploy", "prod", "--force", "us-east"]));
+  expect(prBoth.kind).toBe(ParseKind.Ok);
+  expect(prBoth.args).toEqual(["prod", "us-east"]);
+  expect(prBoth.opts.force).toBe("1");
+
+  // Option after first optional positional when second is omitted
+  const prOne = postParseValidate(root, parse(root, ["deploy", "prod", "--force"]));
+  expect(prOne.kind).toBe(ParseKind.Ok);
+  expect(prOne.args).toEqual(["prod"]);
+  expect(prOne.opts.force).toBe("1");
+
+  // Option before optional positionals when all are omitted
+  const prNone = postParseValidate(root, parse(root, ["deploy", "--force"]));
+  expect(prNone.kind).toBe(ParseKind.Ok);
+  expect(prNone.args).toEqual([]);
+  expect(prNone.opts.force).toBe("1");
+});
+
+/** Tests that options can be interleaved between bounded positional and varargs tail. */
+test("options interleaved between bounded positional and varargs tail", () => {
+  const root = testProgram({
+    key: "app",
+    description: "",
+    commands: [
+      {
+        key: "upload",
+        description: "upload",
+        options: [
+          {
+            name: "json",
+            description: "",
+            kind: CliOptionKind.Presence,
+          },
+        ],
+        positionals: [
+          {
+            name: "target",
+            description: "",
+            kind: CliOptionKind.String,
+            argMin: 1,
+            argMax: 1,
+          },
+          {
+            name: "files",
+            description: "",
+            kind: CliOptionKind.String,
+            argMin: 1,
+            argMax: 0,
+          },
+        ],
+        handler: () => {},
+      },
+    ],
+  });
+  cliValidateProgram(root);
+
+  // Flag between target and files does not get captured as first file
+  const pr = postParseValidate(root, parse(root, ["upload", "s3", "--json", "a.txt", "b.txt"]));
+  expect(pr.kind).toBe(ParseKind.Ok);
+  expect(pr.args).toEqual(["s3", "a.txt", "b.txt"]);
+  expect(pr.opts.json).toBe("1");
+});
+
+/** Tests that options on routing groups are rejected at schema validation. */
+test("rejects options on routing groups", () => {
   const root = testProgram({
     key: "app",
     description: "",
@@ -386,11 +564,38 @@ test("trailing options include parent-scoped flags", () => {
             kind: CliOptionKind.Presence,
           },
         ],
+        commands: [
+          {
+            key: "leaf",
+            description: "leaf",
+            handler: () => {},
+          },
+        ],
+      },
+    ],
+  });
+  expect(() => cliValidateProgram(root)).toThrow(/routing group/);
+});
+
+/** Tests that leaf flags are only accepted on the leaf command segment. */
+test("leaf flags are only accepted on the leaf command segment", () => {
+  const root = testProgram({
+    key: "app",
+    description: "",
+    commands: [
+      {
+        key: "group",
+        description: "group",
         commands: [
           {
             key: "leaf",
             description: "leaf",
             options: [
+              {
+                name: "json",
+                description: "",
+                kind: CliOptionKind.Presence,
+              },
               {
                 name: "user",
                 description: "",
@@ -412,12 +617,12 @@ test("trailing options include parent-scoped flags", () => {
     ],
   });
   cliValidateProgram(root);
-  const pr = postParseValidate(root, parse(root, ["group", "leaf", "-u", "alice", "./file", "--json"]));
-  expect(pr.kind).toBe(ParseKind.Ok);
-  expect(pr.path).toEqual(["group", "leaf"]);
-  expect(pr.args).toEqual(["./file"]);
-  expect(pr.opts.user).toBe("alice");
-  expect(pr.opts.json).toBe("1");
+  const ok = postParseValidate(root, parse(root, ["group", "leaf", "-u", "alice", "./file", "--json"]));
+  expect(ok.kind).toBe(ParseKind.Ok);
+  expect(ok.opts.json).toBe("1");
+
+  const bad = parse(root, ["group", "--json", "leaf", "-u", "alice", "./file"]);
+  expect(bad.kind).toBe(ParseKind.Error);
 });
 
 /** Varargs tail parses trailing options. */

package/src/core/parse.ts

@@ -244,15 +244,38 @@ function consumeOptions(
 
 // ── Positional Collection ─────────────────────────────────────────────────────
 
-/** Merges option defs from the program root along the routed command path. */
-export function collectOptionDefs(root: CliNode, path: string[]): CliOption[] {
+/** Resolves the command node at the end of a routed path. */
+function resolveNodeAtPath(root: CliNode, path: string[]): CliNode | undefined {
+  if (path.length === 0) {
+    return root;
+  }
+  let node: CliNode = root;
+  for (const seg of path) {
+    if (!isCliRouter(node)) {
+      return undefined;
+    }
+    const ch = findChild(node.commands, seg);
+    if (!ch) {
+      return undefined;
+    }
+    node = ch;
+  }
+  return node;
+}
+
+/** Options declared on each command node along the path (root + each segment). Used for post-parse validation. */
+export function collectPathOptionDefs(root: CliNode, path: string[]): CliOption[] {
   const defs = [...(root.options ?? [])];
   let node: CliNode = root;
 
   for (const seg of path) {
-    if (!isCliRouter(node)) break;
+    if (!isCliRouter(node)) {
+      break;
+    }
     const ch = findChild(node.commands, seg);
-    if (!ch) break;
+    if (!ch) {
+      break;
+    }
     defs.push(...(ch.options ?? []));
     node = ch;
   }
@@ -260,6 +283,15 @@ export function collectOptionDefs(root: CliNode, path: string[]): CliOption[] {
   return defs;
 }
 
+/** Options declared on the leaf command at path (wire schemas and MCP/HTTP tool args). */
+export function collectOptionDefs(root: CliNode, path: string[]): CliOption[] {
+  const node = resolveNodeAtPath(root, path);
+  if (!node || !isCliLeaf(node)) {
+    return [];
+  }
+  return [...(node.options ?? [])];
+}
+
 /** Fills `args` for a json leaf from `startIdx` (0 or 1 JSON string positional). */
 function finishJsonLeaf(
   _node: CliLeaf,
@@ -319,9 +351,47 @@ function finishLeaf(
   const args: string[] = [];
   let forcePositionals = forcePositionalsIn;
 
+  /**
+   * Consumes any pending options, `--`, or help flags at the current argv index.
+   * Sets `forcePositionals = true` when `--` is encountered.
+   * Returns a help or error ParseResult if parsing halts, or null to continue positional consumption.
+   */
+  function consumePendingOptions(): ParseResult | null {
+    while (!forcePositionals && idx < argv.length) {
+      const tok = argv[idx];
+      if (tok === "--") {
+        forcePositionals = true;
+        idx += 1;
+        break;
+      }
+      if (isHelpTok(tok)) {
+        return helpResult(path, true, pathParams);
+      }
+      if (tok.startsWith("-")) {
+        const rep = consumeOptions(optionDefs, false, argv, idx, opts);
+        if (rep.report.err) {
+          return errorResult(rep.report.err, path, [], pathParams);
+        }
+        if (rep.report.sawDoubleDash) {
+          forcePositionals = true;
+        }
+        if (rep.nextIndex > idx) {
+          idx = rep.nextIndex;
+          continue;
+        }
+        return errorResult(`Unexpected option token: ${tok}`, path, [], pathParams);
+      }
+      break;
+    }
+    return null;
+  }
+
   for (const p of node.positionals ?? []) {
     const { argMin = 1, argMax = 1 } = p;
     if (argMax === 1) {
+      const pendingErr = consumePendingOptions();
+      if (pendingErr) return pendingErr;
+
       if (argMin >= 1) {
         if (idx >= argv.length) {
           return errorResult(`Missing positional argument: ${p.name}`, path, [], pathParams);
@@ -329,13 +399,8 @@ function finishLeaf(
         args.push(argv[idx]);
         idx += 1;
       } else if (idx < argv.length) {
-        const tok = argv[idx];
-        if (argMin < 1 && tok.startsWith("-")) {
-          // Optional slot: leave `-` tokens for trailing option parsing.
-        } else {
-          args.push(tok);
-          idx += 1;
-        }
+        args.push(argv[idx]);
+        idx += 1;
       }
       continue;
     }
@@ -343,40 +408,20 @@ function finishLeaf(
     let count = 0;
     if (argMax === 0) {
       while (idx < argv.length) {
-        const tok = argv[idx];
+        const pendingErr = consumePendingOptions();
+        if (pendingErr) return pendingErr;
+        if (idx >= argv.length) break;
 
-        if (!forcePositionals && tok === "--") {
-          forcePositionals = true;
-          idx++;
-          continue;
-        }
-
-        if (!forcePositionals && isHelpTok(tok)) {
-          return helpResult(path, true, pathParams);
-        }
-
-        if (!forcePositionals && tok.startsWith("-")) {
-          // MUST be false — lenient mode swallows unknown flags as positionals silently
-          const tailRep = consumeOptions(optionDefs, false, argv, idx, opts);
-          if (tailRep.report.err) {
-            return errorResult(tailRep.report.err, path, [], pathParams);
-          }
-          if (tailRep.report.sawDoubleDash) {
-            forcePositionals = true;
-          }
-          if (tailRep.nextIndex > idx) {
-            idx = tailRep.nextIndex;
-            continue;
-          }
-          return errorResult(`Unexpected option token: ${tok}`, path, [], pathParams);
-        }
-
-        args.push(tok);
-        idx++;
-        count++;
+        args.push(argv[idx]);
+        idx += 1;
+        count += 1;
       }
     } else {
       while (count < argMax && idx < argv.length) {
+        const pendingErr = consumePendingOptions();
+        if (pendingErr) return pendingErr;
+        if (idx >= argv.length) break;
+
         args.push(argv[idx]);
         idx += 1;
         count += 1;
@@ -387,24 +432,11 @@ function finishLeaf(
     }
   }
 
-  if (idx < argv.length) {
-    if (forcePositionals) {
-      return errorResult("Unexpected extra arguments", path, [], pathParams);
-    }
+  const trailingErr = consumePendingOptions();
+  if (trailingErr) return trailingErr;
 
-    if (isHelpTok(argv[idx])) {
-      return helpResult(path, true, pathParams);
-    }
-
-    const tailRep = consumeOptions(optionDefs, false, argv, idx, opts);
-    if (tailRep.report.err) {
-      return errorResult(tailRep.report.err, path, [], pathParams);
-    }
-    idx = tailRep.nextIndex;
-
-    if (idx < argv.length) {
-      return errorResult("Unexpected extra arguments", path, [], pathParams);
-    }
+  if (idx < argv.length) {
+    return errorResult("Unexpected extra arguments", path, [], pathParams);
   }
 
   return {
@@ -618,7 +650,7 @@ export function parse(root: CliNode, argv: string[]): ParseResult {
     }
 
     if (!forcePositionals) {
-      const orep = consumeOptions(collectOptionDefs(root, path), false, argv, i, opts);
+      const orep = consumeOptions(current.options ?? [], false, argv, i, opts);
       if (orep.report.err) {
         return errorResult(orep.report.err, path);
       }
@@ -650,7 +682,7 @@ export function parse(root: CliNode, argv: string[]): ParseResult {
       if (!isCliLeaf(current)) {
         return helpResult(path, false, pathParams);
       }
-      return finishLeaf(current, i, argv, path, opts, collectOptionDefs(root, path), forcePositionals, pathParams);
+      return finishLeaf(current, i, argv, path, opts, current.options ?? [], forcePositionals, pathParams);
     }
 
     const tok = argv[i];
@@ -695,32 +727,19 @@ export function parse(root: CliNode, argv: string[]): ParseResult {
     if (!isCliLeaf(current)) {
       return helpResult(path, false, pathParams);
     }
-    return finishLeaf(current, i, argv, path, opts, collectOptionDefs(root, path), forcePositionals, pathParams);
+    return finishLeaf(current, i, argv, path, opts, current.options ?? [], forcePositionals, pathParams);
   }
 }
 
 // ── Post-Parse Validation ─────────────────────────────────────────────────────
 
 /**
- * Validates option keys and numeric values for an Ok parse, merging in-scope options along `pr.path`.
+ * Validates option keys and numeric values for an Ok parse along `pr.path`.
  */
 export function postParseValidate(root: CliNode, pr: ParseResult): ParseResult {
   if (pr.kind !== ParseKind.Ok) return pr;
 
-  const defs = [...(root.options ?? [])];
-  let node: CliNode = root;
-
-  for (const seg of pr.path) {
-    if (!isCliRouter(node)) {
-      return errorResult("Internal path error", pr.path);
-    }
-    const ch = findChild(node.commands, seg);
-    if (!ch) {
-      return errorResult("Internal path error", pr.path);
-    }
-    defs.push(...(ch.options ?? []));
-    node = ch;
-  }
+  const defs = collectPathOptionDefs(root, pr.path);
 
   const opts = { ...pr.opts };
   for (const d of defs) {

package/src/core/validate.ts

@@ -328,6 +328,11 @@ function walkNode(node: CliNode, program: CliProgram, isRoot: boolean): void {
   }
 
   if (isCliRouter(node)) {
+    if (!isRoot && (node.options ?? []).length > 0) {
+      throw new CliSchemaValidationError(
+        `Options on routing group '${node.key}' are not supported — declare options on leaf commands`,
+      );
+    }
     const seenNames = new Set<string>();
     let paramRouterCount = 0;
     for (const child of node.commands) {
@@ -367,9 +372,13 @@ function walkNode(node: CliNode, program: CliProgram, isRoot: boolean): void {
     }
   }
 
-  const positionals = isCliLeaf(node) ? (node.positionals ?? []) : [];
-  validateOptions(node.key, node.options ?? []);
-  validatePositionals(node.key, positionals);
+  if (isCliRouter(node) && !isRoot) {
+    validatePositionals(node.key, []);
+  } else {
+    const positionals = isCliLeaf(node) ? (node.positionals ?? []) : [];
+    validateOptions(node.key, node.options ?? []);
+    validatePositionals(node.key, positionals);
+  }
 }
 
 function validateOptions(scopeKey: string, options: import("./types.ts").CliOption[]): void {

package/src/docs/http-guide.ts

@@ -1,16 +1,16 @@
 import { defaultConfigEntryTitle } from "../config/entry.ts";
 import { displayAppConfigPath } from "../config/file.ts";
-import { collectOptionDefs } from "../core/parse.ts";
 import { CliOptionKind, type CliProgram } from "../core/types.ts";
 import { httpUserPathGlob, resolveHttpPathPrefix } from "../http/paths.ts";
 import { collectHttpRoutes } from "../http/routes.ts";
 import { resolveHttpListenAddress } from "../http/server.ts";
+import { leafWireOptions } from "../mcp/tools.ts";
 
 /** Formats one HTTP route for the auto-generated HTTP guide. */
 function formatRouteLine(root: CliProgram, route: ReturnType<typeof collectHttpRoutes>[number]): string {
   const cliPath = route.commandPath.join(" ");
   let line = `- \`${route.method} ${route.openApiPath}\` (CLI: \`${root.key} ${cliPath}\`) — ${route.leaf.description}`;
-  const opts = collectOptionDefs(root, route.commandPath);
+  const opts = leafWireOptions(route.leaf);
   const flags = opts.filter((o) => o.kind === CliOptionKind.Presence).map((o) => `--${o.name}`);
   if (flags.length > 0) {
     line += ` (flags: ${flags.join(", ")})`;

package/src/docs/mcp-guide.ts

@@ -2,9 +2,8 @@ import { defaultConfigEntryTitle } from "../config/entry.ts";
 import { displayAppConfigPath } from "../config/file.ts";
 import { expectedMcpEntry } from "../configure/artifacts/mcp-config.ts";
 import { resolveClaudeDesktopMcpPath, userHome } from "../configure/artifacts/paths.ts";
-import { collectOptionDefs } from "../core/parse.ts";
 import { CliOptionKind, type CliProgram } from "../core/types.ts";
-import { collectMcpTools, type McpToolDef, mcpServerId, resolveMcpSchemaUri } from "../mcp/tools.ts";
+import { collectMcpTools, leafWireOptions, type McpToolDef, mcpServerId, resolveMcpSchemaUri } from "../mcp/tools.ts";
 import { resolveCapabilities } from "../runtime/capabilities.ts";
 import { resolveDocsTopicResourceUri } from "./mcp-resources.ts";
 import { docsEnabled, docsUserTopicKeys, resolveDocsConfig } from "./resolve.ts";
@@ -52,7 +51,7 @@ function appendManualClientSetup(
 function formatToolLine(root: CliProgram, tool: McpToolDef): string {
   const cliPath = tool.path.length > 0 ? `${root.key} ${tool.path.join(" ")}` : root.key;
   let line = `- \`${cliPath}\` — ${tool.description}`;
-  const opts = collectOptionDefs(root, tool.path);
+  const opts = leafWireOptions(tool.leaf);
   const flags = opts.filter((o) => o.kind === CliOptionKind.Presence).map((o) => `--${o.name}`);
   if (flags.length > 0) {
     line += ` (flags: ${flags.join(", ")})`;

package/src/http/openapi.ts

@@ -2,9 +2,9 @@
 Hand-built OpenAPI 3.1 document from exposed HTTP REST routes.
 */
 
-import { collectOptionDefs } from "../core/parse.ts";
 import type { CliHttpMethod, CliNode, CliProgram } from "../core/types.ts";
 import { CliOptionKind, isCliLeaf, isJsonLeaf } from "../core/types.ts";
+import { leafWireOptions } from "../mcp/tools.ts";
 import { collectHttpRoutes, defaultSuccessStatus } from "./routes.ts";
 import { dereferenceJsonSchema } from "./schema-deref.ts";
 
@@ -35,7 +35,7 @@ function errorResponseEntry(program: CliProgram, description: string): Record<st
 }
 
 function buildInputSchema(
-  program: CliProgram,
+  _program: CliProgram,
   route: ReturnType<typeof collectHttpRoutes>[number],
 ): Record<string, unknown> {
   const leaf = route.leaf;
@@ -48,8 +48,7 @@ function buildInputSchema(
     properties[p] = { type: "string" };
     required.push(p);
   }
-  const argv = route.commandPath.filter((k) => !k.startsWith(":"));
-  for (const opt of collectOptionDefs(program, argv)) {
+  for (const opt of leafWireOptions(leaf)) {
     if (opt.kind === CliOptionKind.Json) {
       continue;
     }
@@ -244,10 +243,7 @@ export function generateOpenApi(program: CliProgram): Record<string, unknown> {
     if (method === "get" || method === "delete") {
       op.parameters = [
         ...((op.parameters as unknown[]) ?? []),
-        ...collectOptionDefs(
-          program,
-          route.commandPath.filter((k) => !k.startsWith(":")),
-        ).map((opt) => ({
+        ...leafWireOptions(route.leaf).map((opt) => ({
           name: opt.name,
           in: "query",
           required: opt.required ?? false,

package/src/http/routes.ts

@@ -2,7 +2,6 @@
 HTTP REST route collection and request matching from the CLI command tree.
 */
 
-import { collectOptionDefs } from "../core/parse.ts";
 import {
   type CliHttpMethod,
   type CliLeaf,
@@ -12,7 +11,7 @@ import {
   isJsonLeaf,
   CliOptionKind as OptKind,
 } from "../core/types.ts";
-import { formatMcpOptionValue } from "../mcp/tools.ts";
+import { formatMcpOptionValue, leafHasYesOption, leafWireOptions } from "../mcp/tools.ts";
 import { isHttpDisabled, isHttpHidden } from "../runtime/exposure.ts";
 import { buildHttpUserPath, httpUserPathRegexPrefix, resolveHttpPathPrefix } from "./paths.ts";
 
@@ -232,7 +231,7 @@ export function matchHttpRoute(program: CliProgram, method: string, pathname: st
 
 /** Builds argv from an HTTP route match, query string, and optional JSON body. */
 export function httpRequestToArgv(
-  program: CliProgram,
+  _program: CliProgram,
   route: HttpRouteDef,
   pathParams: Record<string, string>,
   query: Record<string, string>,
@@ -268,7 +267,7 @@ export function httpRequestToArgv(
     }
   }
 
-  for (const opt of collectOptionDefs(program, argv)) {
+  for (const opt of leafWireOptions(leaf)) {
     if (opt.kind === OptKind.Json) {
       continue;
     }
@@ -289,6 +288,10 @@ export function httpRequestToArgv(
     argv.push(`--${opt.name}`, formatted);
   }
 
+  if (leafHasYesOption(leaf) && !argv.includes("--yes")) {
+    argv.push("--yes");
+  }
+
   for (const p of leaf.positionals ?? []) {
     const val = merged[p.name] ?? pathParams[p.name];
     const { argMin = 1, argMax = 1 } = p;

package/src/mcp/hidden-mcpb.test.ts

@@ -95,7 +95,7 @@ describe("hidden commands and options", () => {
 
   test("MCP tools omit hidden commands", () => {
     const tools = collectMcpTools(hiddenFixture);
-    expect(tools.map((t) => t.name)).toEqual(["public", "flags"]);
+    expect(tools.map((t) => t.name)).toEqual(["flags", "public"]);
   });
 });
 

package/src/mcp/tools.ts

@@ -3,7 +3,6 @@ This module maps CliProgram leaf nodes to MCP tool definitions and converts
 flat JSON tool arguments into argv for Cli.invoke.
 */
 
-import { collectOptionDefs } from "../core/parse.ts";
 import { cliSchemaJson } from "../core/schema.ts";
 import {
   type CliLeaf,
@@ -23,6 +22,9 @@ import { isMcpHidden, visibleOptions } from "../runtime/exposure.ts";
 
 const DURATION_PATTERN = "^\\d+[hdms]?$";
 
+/** Presence flags omitted from MCP wire schemas (handled by the framework on invoke). */
+const MCP_WIRE_OMIT_PRESENCE = new Set(["json", "yes", "verbose"]);
+
 /** Default URI pattern for the CLI schema MCP resource (`<mcpId>://schema`). */
 export function defaultMcpSchemaUri(mcpId: string): string {
   return `${mcpId}://schema`;
@@ -70,6 +72,18 @@ export function mcpToolName(root: CliProgram, path: string[]): string {
   return path.map(sanitizeToolSegment).join("_");
 }
 
+/** Leaf options exposed on MCP/HTTP wire schemas (omits framework-handled presence flags). */
+export function leafWireOptions(leaf: CliLeaf): CliOption[] {
+  return visibleOptions(leaf.options).filter(
+    (opt) => !(opt.kind === CliOptionKind.Presence && MCP_WIRE_OMIT_PRESENCE.has(opt.name)),
+  );
+}
+
+/** True when the leaf declares a `yes` presence option (auto-injected on MCP invoke). */
+export function leafHasYesOption(leaf: CliLeaf): boolean {
+  return visibleOptions(leaf.options).some((opt) => opt.name === "yes" && opt.kind === CliOptionKind.Presence);
+}
+
 /** JSON Schema property for one option. */
 function optionProperty(opt: CliOption): Record<string, unknown> {
   const base: Record<string, unknown> = { description: opt.description };
@@ -140,7 +154,7 @@ function positionalProperty(p: CliPositional): Record<string, unknown> {
 }
 
 /** Builds inputSchema for a leaf command. */
-function buildInputSchema(root: CliProgram, path: string[], leaf: CliLeaf): Record<string, unknown> {
+function buildInputSchema(leaf: CliLeaf): Record<string, unknown> {
   if (isJsonLeaf(leaf) && leaf.inputSchema !== undefined) {
     return leaf.inputSchema;
   }
@@ -148,7 +162,7 @@ function buildInputSchema(root: CliProgram, path: string[], leaf: CliLeaf): Reco
   const properties: Record<string, unknown> = {};
   const required: string[] = [];
 
-  for (const opt of visibleOptions(collectOptionDefs(root, path))) {
+  for (const opt of leafWireOptions(leaf)) {
     properties[opt.name] = optionProperty(opt);
     if (opt.required) {
       required.push(opt.name);
@@ -237,7 +251,7 @@ export function collectMcpTools(root: CliProgram): McpToolDef[] {
         description: resolveToolDescription(root, path, cmd),
         path,
         leaf: cmd,
-        inputSchema: cmd.inputSchema ?? buildInputSchema(root, path, cmd),
+        inputSchema: cmd.inputSchema ?? buildInputSchema(cmd),
         ...(outputSchema === undefined ? {} : { outputSchema }),
       });
       return;
@@ -255,7 +269,7 @@ export function collectMcpTools(root: CliProgram): McpToolDef[] {
     }
   }
 
-  return out;
+  return out.sort((a, b) => a.name.localeCompare(b.name));
 }
 
 /** Resolves MCP server name and version for initialize. */
@@ -276,7 +290,7 @@ export function resolveMcpSchemaUri(root: CliProgram): string {
 
 /** Converts flat MCP tool arguments to argv for Cli.invoke. */
 export function mcpToolCallToArgv(
-  root: CliProgram,
+  _root: CliProgram,
   tool: McpToolDef,
   args: Record<string, unknown>,
 ): string[] | { error: string } {
@@ -286,7 +300,7 @@ export function mcpToolCallToArgv(
 
   const argv = [...tool.path];
 
-  for (const opt of collectOptionDefs(root, tool.path)) {
+  for (const opt of leafWireOptions(tool.leaf)) {
     if (opt.kind === CliOptionKind.Json) {
       continue;
     }
@@ -307,6 +321,10 @@ export function mcpToolCallToArgv(
     argv.push(`--${opt.name}`, formatted);
   }
 
+  if (leafHasYesOption(tool.leaf) && !argv.includes("--yes")) {
+    argv.push("--yes");
+  }
+
   for (const p of tool.leaf.positionals ?? []) {
     const val = args[p.name];
     const { argMin = 1, argMax = 1 } = p;

package/src/skill/generate.ts

@@ -3,11 +3,11 @@ This module generates Agent Skills content (SKILL.md + reference.md) from a CLI
 */
 
 import { defaultConfigEntryTitle } from "../config/entry.ts";
-import { collectOptionDefs } from "../core/parse.ts";
 import { CliOptionKind, type CliProgram } from "../core/types.ts";
 import { generateCliGuide } from "../docs/cli-guide.ts";
 import {
   collectMcpTools,
+  leafWireOptions,
   type McpToolDef,
   mcpServerId,
   resolveMcpSchemaUri,
@@ -69,7 +69,7 @@ function commandCatalogPath(root: CliProgram, tool: McpToolDef): string {
 function formatCommandEntry(root: CliProgram, tool: McpToolDef): string {
   const cliPath = commandCatalogPath(root, tool);
   let line = `- **\`${cliPath}\`** — ${tool.leaf.description}`;
-  const opts = collectOptionDefs(root, tool.path);
+  const opts = leafWireOptions(tool.leaf);
   const flags = opts.filter((o) => o.kind === CliOptionKind.Presence).map((o) => `--${o.name}`);
   if (flags.length > 0) {
     line += ` (flags: ${flags.join(", ")})`;

package/src/test/fixtures.ts

@@ -14,13 +14,6 @@ export const nestedMcpFixture = testProgram({
     {
       key: "stat",
       description: "File metadata.",
-      options: [
-        {
-          name: "json",
-          description: "Emit handler output as JSON.",
-          kind: CliOptionKind.Presence,
-        },
-      ],
       commands: [
         {
           key: "owner",

package/src/test/integration/http.test.ts

@@ -9,7 +9,14 @@ import { cliValidateProgram } from "../../core/validate.ts";
 import { generateOpenApi } from "../../http/openapi.ts";
 import { API_CORS_HEADERS } from "../../http/result.ts";
 import { handleApiRequest } from "../../http/server.ts";
-import { Cli, CliContext, type CliContext as CliContextType, CliOptionKind, cliErrWithHelp } from "../../index.ts";
+import {
+  Cli,
+  CliContext,
+  type CliContext as CliContextType,
+  CliOptionKind,
+  cliErrWithHelp,
+  wantsExplicitJson,
+} from "../../index.ts";
 import { LogEmitter } from "../../log/emitter.ts";
 import { createServerRuntime } from "../../server/context.ts";
 import { resolveHttpServeConfig } from "../../server/overrides.ts";
@@ -24,13 +31,6 @@ function nestedApiFixture() {
       {
         key: "stat",
         description: "File metadata.",
-        options: [
-          {
-            name: "json",
-            description: "Emit handler output as JSON.",
-            kind: CliOptionKind.Presence,
-          },
-        ],
         commands: [
           {
             key: "owner",
@@ -40,6 +40,11 @@ function nestedApiFixture() {
                 key: "lookup",
                 description: "Resolve owner info.",
                 options: [
+                  {
+                    name: "json",
+                    description: "Emit handler output as JSON.",
+                    kind: CliOptionKind.Presence,
+                  },
                   {
                     name: "user-name",
                     description: "User to look up.",
@@ -57,7 +62,7 @@ function nestedApiFixture() {
                 handler: (ctx: CliContextType) => {
                   const user = ctx.stringOpt("user-name") ?? "unknown";
                   const path = ctx.positional("path") ?? "";
-                  if (ctx.hasFlag("json")) {
+                  if (wantsExplicitJson(ctx, ctx.hasFlag("json"))) {
                     return { user, path };
                   }
                   return `lookup user=${user} path=${path}`;
@@ -318,7 +323,7 @@ describe("HTTP API routes", () => {
     expect(await res.json()).toEqual({ user: "alice", path: readme });
   });
 
-  test("POST /api/... returns raw text body with 201", async () => {
+  test("POST /api/... returns JSON body by default with 201", async () => {
     const readme = join(import.meta.dir, "..", "..", "..", "README.md");
     const res = await apiRequest(
       program,
@@ -329,8 +334,8 @@ describe("HTTP API routes", () => {
       }),
     );
     expect(res.status).toBe(201);
-    const text = await res.text();
-    expect(text).toContain("lookup user=alice");
+    expect(res.headers.get("content-type")).toContain("application/json");
+    expect(await res.json()).toEqual({ user: "alice", path: readme });
   });
 
   test("POST /tools returns 404 (legacy path removed)", async () => {

package/src/test/integration/mcp.test.ts

@@ -153,11 +153,12 @@ test("outputSchema must be a JSON Schema object", () => {
   expect(() => cliValidateProgram(root)).toThrow(/outputSchema must be a JSON Schema object/);
 });
 
-test("collectMcpTools merges parent options into inputSchema", () => {
+test("collectMcpTools uses leaf-local options in inputSchema", () => {
   const tools = collectMcpTools(nestedMcpFixture);
   const lookup = tools.find((t) => t.name === "stat_owner_lookup")!;
   const schema = lookup.inputSchema as { properties: Record<string, unknown>; required?: string[] };
-  expect(schema.properties.json).toBeDefined();
+  expect(schema.properties.json).toBeUndefined();
+  expect(schema.properties["user-name"]).toBeDefined();
   expect(schema.required).toContain("path");
 });
 
@@ -202,9 +203,8 @@ test("mcpToolCallToArgv builds nested lookup argv", () => {
   const argv = mcpToolCallToArgv(nestedMcpFixture, lookup, {
     "user-name": "alice",
     path: "./x",
-    json: true,
   });
-  expect(argv).toEqual(["stat", "owner", "lookup", "--json", "--user-name", "alice", "./x"]);
+  expect(argv).toEqual(["stat", "owner", "lookup", "--user-name", "alice", "./x"]);
 });
 
 test("mcpToolCallToArgv expands varargs positionals", () => {
@@ -386,10 +386,10 @@ test("MCP tools/call runs stat_owner_lookup", async () => {
     },
   ]);
   const res = responses.get(4) as {
-    result: { content: { text: string }[]; structuredContent?: { content: string }; isError: boolean };
+    result: { content: { text: string }[]; structuredContent?: { user: string; path: string }; isError: boolean };
   };
   expect(res.result.isError).toBe(false);
-  expect(res.result.structuredContent?.content).toContain("lookup user=test");
+  expect(res.result.structuredContent).toEqual({ user: "test", path: readme });
 });
 
 /** MCP tools/call returns structuredContent for JSON stdout. */