incur 0.1.5 → 0.1.7

package/README.md

@@ -21,6 +21,7 @@
 - [**Inferred types**](#inferred-types): generic type flow from schemas to `run` callbacks with zero manual annotations
 - [**Global options**](#global-options): `--format`, `--json`, `--verbose`, `--help`, `--version` on every CLI for free
 - [**Light API surface**](#light-api-surface): `Cli.create()`, `.command()`, `.serve()` – that's it
+- [**Middleware**](#middleware): composable before/after hooks with typed dependency injection via `cli.use()`
 
 ## Quickprompt
 
@@ -66,8 +67,8 @@ Cli.create('greet', {
   args: z.object({
     name: z.string().describe('Name to greet'),
   }),
-  run({ args }) {
-    return { message: `hello ${args.name}` }
+  run(c) {
+    return { message: `hello ${c.args.name}` }
   },
 }).serve()
 ```
@@ -124,7 +125,7 @@ Cli.create('my-cli', {
       saveDev: z.boolean().optional().describe('Save as dev dependency'),
     }),
     alias: { saveDev: 'D' },
-    run({ args }) {
+    run(c) {
       return { added: 1, packages: 451 }
     },
   })
@@ -176,8 +177,8 @@ const pr = Cli.create('pr', { description: 'Pull request commands' }).command('l
   options: z.object({
     state: z.enum(['open', 'closed', 'all']).default('open'),
   }),
-  run({ options }) {
-    return { prs: [], state: options.state }
+  run(c) {
+    return { prs: [], state: c.options.state }
   },
 })
 
@@ -264,16 +265,19 @@ Return CTAs from `ok()` or `error()` to suggest next steps. `cta` parameters are
 ```ts
 cli.command('list', {
   args: z.object({ state: z.enum(['open', 'closed']).default('open') }),
-  run({ args, ok }) {
+  run(c) {
     const items = [{ id: 1, title: 'Fix bug' }]
-    return ok({ items }, {
-      cta: {
-        commands: [
-          { command: 'get 1', description: 'View item' },
-          { command: 'list', args: { state: 'closed' }, description: 'View closed' },
-        ],
+    return c.ok(
+      { items },
+      {
+        cta: {
+          commands: [
+            { command: 'get 1', description: 'View item' },
+            { command: 'list', args: { state: 'closed' }, description: 'View closed' },
+          ],
+        },
       },
-    })
+    )
   },
 })
 ```
@@ -296,17 +300,19 @@ A small API means agents can build entire CLIs in a single pass without needing
 import { Cli, z } from 'incur'
 
 // Define sub-command groups
-const db = Cli.create('db', { description: 'Database commands' })
-  .command('migrate', { description: 'Run migrations', run: () => ({ migrated: true }) })
+const db = Cli.create('db', { description: 'Database commands' }).command('migrate', {
+  description: 'Run migrations',
+  run: () => ({ migrated: true }),
+})
 
 // Create the root CLI
 Cli.create('tool', { description: 'A tool' })
   // Register commands
   .command('run', { description: 'Run a task', run: () => ({ ok: true }) })
   // Mount sub-command groups
-  .command(db)    
+  .command(db)
   // Serve the CLI
-  .serve()       
+  .serve()
 ```
 
 ```sh
@@ -364,8 +370,8 @@ cli.command('deploy', {
   options: z.object({ force: z.boolean().optional() }),
   env: z.object({ DEPLOY_TOKEN: z.string() }),
   output: z.object({ url: z.string(), duration: z.number() }),
-  run({ args, options, env }) {
-    return { url: `https://${args.env}.example.com`, duration: 3.2 }
+  run(c) {
+    return { url: `https://${c.args.env}.example.com`, duration: 3.2 }
   },
 })
 ```
@@ -404,10 +410,10 @@ async *run() {
 Use `ok()` or `error()` as the return value to attach CTAs or signal failure:
 
 ```ts
-async *run({ ok }) {
+async *run(c) {
   yield { step: 1 }
   yield { step: 2 }
-  return ok(undefined, { cta: { commands: ['status'] } })
+  return c.ok(undefined, { cta: { commands: ['status'] } })
 }
 ```
 
@@ -420,20 +426,158 @@ cli.command('greet', {
   args: z.object({ name: z.string() }),
   options: z.object({ loud: z.boolean().default(false) }),
   output: z.object({ message: z.string() }),
-  run({ args, options, ok }) {
-    args.name
-    //   ^? (property) name: string
-    options.loud
-    //      ^? (property) loud: boolean
-    return ok({ message: `hello ${args.name}` }, {  
-    //          ^? (property) message: string
-      cta: { commands: ['greet world'] },
-    //                   ^? 'greet' | 'other-cmd'
-    })
+  run(c) {
+    c.args.name
+    //     ^? (property) name: string
+    c.options.loud
+    //        ^? (property) loud: boolean
+    return c.ok(
+      { message: `hello ${c.args.name}` },
+      {
+        //            ^? (property) message: string
+        cta: { commands: ['greet world'] },
+        //                   ^? 'greet' | 'other-cmd'
+      },
+    )
+  },
+})
+```
+
+### Output policy
+
+Control whether output data is displayed to humans. By default, output goes to everyone (`'all'`). Set `outputPolicy: 'agent-only'` to suppress data in TTY mode while still returning it to agents via `--json`, `--format`, or `--verbose`.
+
+```ts
+cli.command('deploy', {
+  outputPolicy: 'agent-only',
+  run() {
+    // Agents get the structured data; humans see nothing (or just CTAs/errors)
+    return { id: 'deploy-123', url: 'https://staging.example.com' }
+  },
+})
+```
+
+Set it on a group or root CLI to inherit across all children:
+
+```ts
+const internal = Cli.create('internal', {
+  description: 'Internal commands',
+  outputPolicy: 'agent-only',
+})
+internal.command('sync', { run: () => ({ synced: true }) }) // inherits agent-only
+internal.command('status', {
+  outputPolicy: 'all', // overrides to show output
+  run: () => ({ ok: true }),
+})
+```
+
+### Agent detection
+
+The `run` context includes an `agent` boolean — `true` when stdout is not a TTY (piped or consumed by an agent), `false` when running in a terminal. Use it to tailor behavior:
+
+```ts
+cli.command('deploy', {
+  args: z.object({ env: z.enum(['staging', 'production']) }),
+  run(c) {
+    if (!c.agent) console.log(`Deploying to ${c.args.env}...`)
+    return { url: `https://${c.args.env}.example.com` }
+  },
+})
+```
+
+### Middleware
+
+Register composable before/after hooks with `cli.use()`. Middleware executes in registration order, onion-style – each calls `await next()` to proceed to the next middleware or the command handler.
+
+```ts
+const cli = Cli.create('deploy-cli', { description: 'Deploy tools' })
+  .use(async (c, next) => {
+    const start = Date.now()
+    await next()
+    console.log(`took ${Date.now() - start}ms`)
+  })
+  .command('deploy', {
+    run() {
+      return { deployed: true }
+    },
+  })
+```
+
+```sh
+$ deploy-cli deploy
+# → deployed: true
+# took 12ms
+```
+
+Per-command middleware runs after root and group middleware, and only for that command:
+
+```ts
+import { Cli, middleware, z } from 'incur'
+
+const cli = Cli.create('my-cli', {
+  description: 'My CLI',
+  vars: z.object({ user: z.custom<User>() }),
+})
+
+const requireAuth = middleware<typeof cli.vars>((c, next) => {
+  if (!c.var.user) throw new Error('must be logged in')
+  return next()
+})
+
+cli.command('deploy', {
+  middleware: [requireAuth],
+  run() {
+    return { deployed: true }
+  },
+})
+```
+
+```sh
+$ my-cli deploy
+# Error: must be logged in
+
+$ my-cli other-cmd
+# per-command middleware does not run
+```
+
+### Variables
+
+Declare a `vars` schema on `create()` to enable typed variables. Middleware sets them with `c.set()`, and both middleware and command handlers read them via `c.var`. Use `.default()` for vars that don't need middleware:
+
+```ts
+type User = { id: string; name: string }
+
+const cli = Cli.create('my-cli', {
+  description: 'My CLI',
+  vars: z.object({
+    user: z.custom<User>(),
+    requestId: z.string(),
+    debug: z.boolean().default(true),
+  }),
+})
+
+cli.use(async (c, next) => {
+  c.set('user', await authenticate())
+  c.set('requestId', crypto.randomUUID())
+  await next()
+})
+
+cli.command('whoami', {
+  run(c) {
+    return { user: c.var.user, requestId: c.var.requestId, debug: c.var.debug }
   },
 })
 ```
 
+```sh
+$ my-cli whoami
+# → user:
+# →   id: u_123
+# →   name: Alice
+# → requestId: 550e8400-e29b-41d4-a716-446655440000
+# → debug: true
+```
+
 ### Global options
 
 Every incur CLI includes these flags automatically:

package/SKILL.md

@@ -339,22 +339,35 @@ incur adapts output based on whether stdout is a TTY:
 | `--help`              | Pretty help text        | Same                 |
 | `--json` / `--format` | Overrides to structured | Same                 |
 
-## Structured Errors
+## Run Context
 
-### `ok()` and `error()` context helpers
+### `agent` boolean
+
+The `run` context includes `agent` — `true` when stdout is not a TTY (piped or consumed by an agent), `false` when running in a terminal:
+
+```ts
+cli.command('deploy', {
+  run(c) {
+    if (!c.agent) console.log('Deploying...')
+    return { status: 'ok' }
+  },
+})
+```
+
+### `ok()` and `error()` helpers
 
 Use the context helpers for explicit result control:
 
 ```ts
-run({ args, ok, error }) {
-  const item = await db.find(args.id)
+run(c) {
+  const item = await db.find(c.args.id)
   if (!item)
     return error({
       code: 'NOT_FOUND',
-      message: `Item ${args.id} not found`,
+      message: `Item ${c.args.id} not found`,
       retryable: false,
     })
-  return ok(item)
+  return c.ok(item)
 }
 ```
 
@@ -363,9 +376,9 @@ run({ args, ok, error }) {
 Suggest next commands to guide agents on success:
 
 ```ts
-run({ args, ok }) {
-  const result = { id: 42, name: args.name }
-  return ok(result, {
+run(c) {
+  const result = { id: 42, name: c.args.name }
+  return c.ok(result, {
     cta: {
       description: 'Suggested commands:',
       commands: [
@@ -380,10 +393,10 @@ run({ args, ok }) {
 Or on errors, to help agents self-correct:
 
 ```ts
-run({ args, error }) {
+run(c) {
   const token = process.env.GH_TOKEN
   if (!token)
-    return error({
+    return c.error({
       code: 'NOT_AUTHENTICATED',
       message: 'GitHub token not found',
       retryable: true,
@@ -554,6 +567,141 @@ cli.command('publish', {
 
 Hints are displayed after examples in help output and included in skill files.
 
+### Output policy
+
+Control whether output data is displayed to humans. `'all'` (default) shows output to everyone. `'agent-only'` suppresses data in human/TTY mode while still returning it via `--json`, `--format`, or `--verbose`.
+
+```ts
+cli.command('deploy', {
+  outputPolicy: 'agent-only',
+  run() {
+    return { id: 'deploy-123', url: 'https://staging.example.com' }
+  },
+})
+```
+
+Set on a group or root CLI to inherit across children. Children can override:
+
+```ts
+const sub = Cli.create('internal', { outputPolicy: 'agent-only' })
+sub.command('sync', { run: () => ({ synced: true }) }) // inherits agent-only
+sub.command('status', { outputPolicy: 'all', run: () => ({}) }) // overrides
+```
+
+## Middleware
+
+Register composable before/after hooks with `cli.use()`. Middleware executes in registration order, onion-style. Each calls `await next()` to proceed.
+
+```ts
+const cli = Cli.create('deploy-cli', { description: 'Deploy tools' })
+  .use(async (c, next) => {
+    const start = Date.now()
+    await next()
+    console.log(`took ${Date.now() - start}ms`)
+  })
+  .command('deploy', {
+    run() {
+      return { deployed: true }
+    },
+  })
+```
+
+```sh
+$ deploy-cli deploy
+# → deployed: true
+# took 12ms
+```
+
+Middleware on a sub-CLI only applies to its commands:
+
+```ts
+const admin = Cli.create('admin', { description: 'Admin commands' })
+  .use(async (c, next) => {
+    if (!isAdmin()) throw new Error('forbidden')
+    await next()
+  })
+  .command('reset', { run: () => ({ reset: true }) })
+
+cli.command(admin) // middleware only runs for `my-cli admin reset`
+```
+
+```sh
+$ my-cli admin reset
+# → reset: true
+
+$ my-cli other-cmd
+# middleware does not run
+```
+
+Per-command middleware runs after root and group middleware, and only for that command:
+
+```ts
+import { Cli, middleware, z } from 'incur'
+
+const cli = Cli.create('my-cli', {
+  description: 'My CLI',
+  vars: z.object({ user: z.custom<{ id: string }>() }),
+})
+
+const requireAuth = middleware<typeof cli.vars>((c, next) => {
+  if (!c.var.user) throw new Error('must be logged in')
+  return next()
+})
+
+cli.command('deploy', {
+  middleware: [requireAuth],
+  run() {
+    return { deployed: true }
+  },
+})
+```
+
+```sh
+$ my-cli deploy
+# Error: must be logged in
+
+$ my-cli other-cmd
+# per-command middleware does not run
+```
+
+### Vars — typed dependency injection
+
+Declare a `vars` schema on `create()` to inject typed variables. Middleware sets them with `c.set()`, handlers read them via `c.var`. Use `.default()` for vars that don't need middleware:
+
+```ts
+const cli = Cli.create('my-cli', {
+  description: 'My CLI',
+  vars: z.object({
+    user: z.custom<{ id: string; name: string }>(),
+    requestId: z.string(),
+    debug: z.boolean().default(false),
+  }),
+})
+
+cli.use(async (c, next) => {
+  c.set('user', await authenticate())
+  c.set('requestId', crypto.randomUUID())
+  await next()
+})
+
+cli.command('whoami', {
+  run(c) {
+    return { user: c.var.user, requestId: c.var.requestId, debug: c.var.debug }
+  },
+})
+```
+
+```sh
+$ my-cli whoami
+# → user:
+# →   id: u_123
+# →   name: Alice
+# → requestId: 550e8400-e29b-41d4-a716-446655440000
+# → debug: false
+```
+
+Middleware does **not** run for built-in commands (`--help`, `--llms`, `--mcp`, `mcp add`, `skills add`).
+
 ## Serving
 
 Call `.serve()` to parse `process.argv` and run:

package/dist/Cli.d.ts

@@ -1,23 +1,25 @@
 import type { z } from 'zod';
 import * as Formatter from './Formatter.js';
+import type { Handler as MiddlewareHandler } from './middleware.js';
+export type { MiddlewareHandler };
 import type { Register } from './Register.js';
 /** A CLI application instance. Also used as a command group when mounted on a parent CLI. */
-export type Cli<commands extends CommandsMap = {}> = {
+export type Cli<commands extends CommandsMap = {}, vars extends z.ZodObject<any> | undefined = undefined> = {
     /** Registers a root command or mounts a sub-CLI as a command group. */
     command: {
         /** Registers a command. Returns the CLI instance for chaining. */
-        <const name extends string, const args extends z.ZodObject<any> | undefined = undefined, const env extends z.ZodObject<any> | undefined = undefined, const options extends z.ZodObject<any> | undefined = undefined, const output extends z.ZodType | undefined = undefined>(name: name, definition: CommandDefinition<args, env, options, output>): Cli<commands & {
+        <const name extends string, const args extends z.ZodObject<any> | undefined = undefined, const env extends z.ZodObject<any> | undefined = undefined, const options extends z.ZodObject<any> | undefined = undefined, const output extends z.ZodType | undefined = undefined>(name: name, definition: CommandDefinition<args, env, options, output, vars>): Cli<commands & {
             [key in name]: {
                 args: InferOutput<args>;
                 options: InferOutput<options>;
             };
-        }>;
+        }, vars>;
         /** Mounts a sub-CLI as a command group. */
-        <const name extends string, const sub extends CommandsMap>(cli: Cli<sub> & {
+        <const name extends string, const sub extends CommandsMap>(cli: Cli<sub, any> & {
             name: name;
         }): Cli<commands & {
             [key in keyof sub & string as `${name} ${key}`]: sub[key];
-        }>;
+        }, vars>;
         /** Mounts a root CLI as a single command. */
         <const name extends string, const args extends z.ZodObject<any> | undefined, const opts extends z.ZodObject<any> | undefined>(cli: Root<args, opts> & {
             name: name;
@@ -26,7 +28,7 @@ export type Cli<commands extends CommandsMap = {}> = {
                 args: InferOutput<args>;
                 options: InferOutput<opts>;
             };
-        }>;
+        }, vars>;
     };
     /** A short description of the CLI. */
     description?: string | undefined;
@@ -34,6 +36,10 @@ export type Cli<commands extends CommandsMap = {}> = {
     name: string;
     /** Parses argv, runs the matched command, and writes the output envelope to stdout. */
     serve(argv?: string[], options?: serve.Options): Promise<void>;
+    /** Registers middleware that runs around every command. */
+    use(handler: MiddlewareHandler<vars>): Cli<commands, vars>;
+    /** The vars schema, if declared. Use `typeof cli.vars` with `Middleware.create` for typed middleware. */
+    vars: vars;
 };
 /** Root CLI — a single command with no subcommands. Carries phantom generics for mounting inference. */
 export type Root<_args extends z.ZodObject<any> | undefined = undefined, _options extends z.ZodObject<any> | undefined = undefined> = Omit<Cli, 'command'>;
@@ -73,18 +79,18 @@ export type Cta<commands extends CommandsMap = Commands> = ([keyof commands] ext
     description?: string | undefined;
 });
 /** Creates a CLI with a root handler. Can still register subcommands which take precedence. */
-export declare function create<const args extends z.ZodObject<any> | undefined = undefined, const env extends z.ZodObject<any> | undefined = undefined, const opts extends z.ZodObject<any> | undefined = undefined, const output extends z.ZodType | undefined = undefined>(name: string, definition: create.Options<args, env, opts, output> & {
+export declare function create<const args extends z.ZodObject<any> | undefined = undefined, const env extends z.ZodObject<any> | undefined = undefined, const opts extends z.ZodObject<any> | undefined = undefined, const output extends z.ZodType | undefined = undefined, const vars extends z.ZodObject<any> | undefined = undefined>(name: string, definition: create.Options<args, env, opts, output, vars> & {
     run: Function;
 }): Cli<{
     [key in typeof name]: {
         args: InferOutput<args>;
         options: InferOutput<opts>;
     };
-}>;
+}, vars>;
 /** Creates a router CLI that registers subcommands. */
-export declare function create<const args extends z.ZodObject<any> | undefined = undefined, const env extends z.ZodObject<any> | undefined = undefined, const opts extends z.ZodObject<any> | undefined = undefined, const output extends z.ZodType | undefined = undefined>(name: string, definition?: create.Options<args, env, opts, output>): Cli;
+export declare function create<const args extends z.ZodObject<any> | undefined = undefined, const env extends z.ZodObject<any> | undefined = undefined, const opts extends z.ZodObject<any> | undefined = undefined, const output extends z.ZodType | undefined = undefined, const vars extends z.ZodObject<any> | undefined = undefined>(name: string, definition?: create.Options<args, env, opts, output, vars>): Cli<{}, vars>;
 /** Creates a CLI with a root handler from a single options object. Can still register subcommands. */
-export declare function create<const args extends z.ZodObject<any> | undefined = undefined, const env extends z.ZodObject<any> | undefined = undefined, const opts extends z.ZodObject<any> | undefined = undefined, const output extends z.ZodType | undefined = undefined>(definition: create.Options<args, env, opts, output> & {
+export declare function create<const args extends z.ZodObject<any> | undefined = undefined, const env extends z.ZodObject<any> | undefined = undefined, const opts extends z.ZodObject<any> | undefined = undefined, const output extends z.ZodType | undefined = undefined, const vars extends z.ZodObject<any> | undefined = undefined>(definition: create.Options<args, env, opts, output, vars> & {
     name: string;
     run: Function;
 }): Cli<{
@@ -92,14 +98,14 @@ export declare function create<const args extends z.ZodObject<any> | undefined =
         args: InferOutput<args>;
         options: InferOutput<opts>;
     };
-}>;
+}, vars>;
 /** Creates a router CLI from a single options object (e.g. package.json). */
-export declare function create<const args extends z.ZodObject<any> | undefined = undefined, const env extends z.ZodObject<any> | undefined = undefined, const opts extends z.ZodObject<any> | undefined = undefined, const output extends z.ZodType | undefined = undefined>(definition: create.Options<args, env, opts, output> & {
+export declare function create<const args extends z.ZodObject<any> | undefined = undefined, const env extends z.ZodObject<any> | undefined = undefined, const opts extends z.ZodObject<any> | undefined = undefined, const output extends z.ZodType | undefined = undefined, const vars extends z.ZodObject<any> | undefined = undefined>(definition: create.Options<args, env, opts, output, vars> & {
     name: string;
-}): Cli;
+}): Cli<{}, vars>;
 export declare namespace create {
     /** Options for creating a CLI. Provide `run` for a leaf CLI, omit it for a router. */
-    type Options<args extends z.ZodObject<any> | undefined = undefined, env extends z.ZodObject<any> | undefined = undefined, options extends z.ZodObject<any> | undefined = undefined, output extends z.ZodType | undefined = undefined> = {
+    type Options<args extends z.ZodObject<any> | undefined = undefined, env extends z.ZodObject<any> | undefined = undefined, options extends z.ZodObject<any> | undefined = undefined, output extends z.ZodType | undefined = undefined, vars extends z.ZodObject<any> | undefined = undefined> = {
         /** Map of option names to single-char aliases. */
         alias?: options extends z.ZodObject<any> ? Partial<Record<keyof z.output<options>, string>> : Record<string, string> | undefined;
         /** Zod schema for positional arguments. */
@@ -116,10 +122,24 @@ export declare namespace create {
         options?: options | undefined;
         /** Zod schema for the return value. */
         output?: output | undefined;
+        /**
+         * Controls when output data is displayed. Inherited by child commands when set on a group or root CLI.
+         *
+         * - `'all'` — displays to both humans and agents.
+         * - `'agent-only'` — suppresses data output in human/TTY mode while still returning it to agents.
+         *
+         * @default 'all'
+         */
+        outputPolicy?: OutputPolicy | undefined;
         /** Alternative usage patterns shown in help output. */
         usage?: Usage<args, options>[] | undefined;
+        /** Zod schema for middleware variables. Keys define variable names, schemas define types and defaults. */
+        vars?: vars | undefined;
         /** The root command handler. When provided, creates a leaf CLI with no subcommands. */
         run?: ((context: {
+            /** Whether the consumer is an agent (stdout is not a TTY). */
+            agent: boolean;
+            /** Positional arguments. */
             args: InferOutput<args>;
             /** Parsed environment variables. */
             env: InferOutput<env>;
@@ -135,6 +155,8 @@ export declare namespace create {
                 cta?: CtaBlock | undefined;
             }) => never;
             options: InferOutput<options>;
+            /** Variables set by middleware. */
+            var: InferVars<vars>;
         }) => InferReturn<output> | Promise<InferReturn<output>> | AsyncGenerator<InferReturn<output>, unknown, unknown>) | undefined;
         /** Options for the built-in `mcp add` command. */
         mcp?: {
@@ -176,14 +198,18 @@ export type CommandsMap = Record<string, {
 }>;
 /** @internal Entry stored in a command map — either a leaf definition or a group. */
 type CommandEntry = CommandDefinition<any, any, any> | InternalGroup;
+/** Controls when output data is displayed. `'all'` displays to both humans and agents. `'agent-only'` suppresses data output in human/TTY mode. */
+export type OutputPolicy = 'agent-only' | 'all';
 /** @internal A command group's internal storage. */
 type InternalGroup = {
     _group: true;
     description?: string | undefined;
+    middlewares?: MiddlewareHandler[] | undefined;
+    outputPolicy?: OutputPolicy | undefined;
     commands: Map<string, CommandEntry>;
 };
 /** @internal Maps CLI instances to their command maps. */
-export declare const toCommands: WeakMap<Cli<{}>, Map<string, CommandEntry>>;
+export declare const toCommands: WeakMap<Cli<{}, undefined>, Map<string, CommandEntry>>;
 /** @internal A CTA block with a description and list of suggested commands. */
 type CtaBlock<commands extends CommandsMap = Commands> = {
     /** Commands to suggest. */
@@ -220,8 +246,10 @@ type Usage<args extends z.ZodObject<any> | undefined, options extends z.ZodObjec
 type InferOutput<schema extends z.ZodObject<any> | undefined> = schema extends z.ZodObject<any> ? z.output<schema> : {};
 /** @internal Inferred return type for a command handler. */
 type InferReturn<output extends z.ZodType | undefined> = output extends z.ZodType ? z.output<output> : unknown;
+/** @internal Inferred vars type from a Zod schema, or `{}` when no schema is provided. */
+type InferVars<vars extends z.ZodObject<any> | undefined> = vars extends z.ZodObject<any> ? z.output<vars> : {};
 /** @internal Defines a command's schema, handler, and metadata. */
-type CommandDefinition<args extends z.ZodObject<any> | undefined = undefined, env extends z.ZodObject<any> | undefined = undefined, options extends z.ZodObject<any> | undefined = undefined, output extends z.ZodType | undefined = undefined> = {
+type CommandDefinition<args extends z.ZodObject<any> | undefined = undefined, env extends z.ZodObject<any> | undefined = undefined, options extends z.ZodObject<any> | undefined = undefined, output extends z.ZodType | undefined = undefined, vars extends z.ZodObject<any> | undefined = undefined> = {
     /** Map of option names to single-char aliases. */
     alias?: options extends z.ZodObject<any> ? Partial<Record<keyof z.output<options>, string>> : Record<string, string> | undefined;
     /** Zod schema for positional arguments. */
@@ -240,10 +268,24 @@ type CommandDefinition<args extends z.ZodObject<any> | undefined = undefined, en
     options?: options | undefined;
     /** Zod schema for the command's return value. */
     output?: output | undefined;
+    /**
+     * Controls when output data is displayed. Inherited by child commands when set on a group.
+     *
+     * - `'all'` — displays to both humans and agents.
+     * - `'agent-only'` — suppresses data output in human/TTY mode while still returning it to agents.
+     *
+     * @default 'all'
+     */
+    outputPolicy?: OutputPolicy | undefined;
+    /** Middleware that runs only for this command, after root and group middleware. */
+    middleware?: MiddlewareHandler<vars>[] | undefined;
     /** Alternative usage patterns shown in help output. */
     usage?: Usage<args, options>[] | undefined;
     /** The command handler. Return a value for single-return, or use `async *run` to stream chunks. */
     run(context: {
+        /** Whether the consumer is an agent (stdout is not a TTY). */
+        agent: boolean;
+        /** Positional arguments. */
         args: InferOutput<args>;
         /** Parsed environment variables. */
         env: InferOutput<env>;
@@ -259,7 +301,8 @@ type CommandDefinition<args extends z.ZodObject<any> | undefined = undefined, en
             cta?: CtaBlock | undefined;
         }) => never;
         options: InferOutput<options>;
+        /** Variables set by middleware. */
+        var: InferVars<vars>;
     }): InferReturn<output> | Promise<InferReturn<output>> | AsyncGenerator<InferReturn<output>, unknown, unknown>;
 };
-export {};
 //# sourceMappingURL=Cli.d.ts.map