effect 4.0.4 → 4.0.5

package/src/ai/LanguageModel.ts

@@ -893,6 +893,13 @@ export const make: (params: {
     Effect.map(Option.getOrElse(() => defaultIdGenerator))
   )
 
+  const contentDecoderFor = makeResponseDecoder((toolkit, deferred) =>
+    Schema.decodeEffect(Schema.mutable(Schema.Array(withUndeclaredToolCalls(Response.Part(toolkit), deferred))))
+  )
+  const streamDecoderFor = makeResponseDecoder((toolkit, deferred) =>
+    Schema.decodeEffect(Schema.NonEmptyArray(withUndeclaredToolCalls(Response.StreamPart(toolkit), deferred)))
+  )
+
   const generateText = <
     Options extends NoExcessProperties<GenerateTextOptions<any>, Options>,
     Tools extends Record<string, Tool.Any> = {}
@@ -1132,10 +1139,8 @@ export const make: (params: {
     }
 
     // Check for pending approvals that need resolution
-    const { approved, denied } = collectToolApprovals(
-      providerOptions.prompt.content,
-      { excludeResolved: true }
-    )
+    const { approved: allResolved, denied: allDenied, pendingApproved: approved, pendingDenied: denied } =
+      collectToolApprovals(providerOptions.prompt.content)
     const hasPendingApprovals = approved.length > 0 || denied.length > 0
 
     // If there is no toolkit, the generated content can be returned immediately
@@ -1245,17 +1250,12 @@ export const make: (params: {
 
     // Strip all resolved approval artifacts (both current and from previous
     // rounds) in a single pass before sending to the provider.
-    {
-      const { approved: allResolved, denied: allDenied } = collectToolApprovals(
-        providerOptions.prompt.content
+    if (allResolved.length > 0 || allDenied.length > 0) {
+      providerOptions.prompt = stripResolvedApprovals(
+        providerOptions.prompt,
+        allResolved,
+        allDenied
       )
-      if (allResolved.length > 0 || allDenied.length > 0) {
-        providerOptions.prompt = stripResolvedApprovals(
-          providerOptions.prompt,
-          allResolved,
-          allDenied
-        )
-      }
     }
 
     const tools = typeof toolChoice === "object" && "oneOf" in toolChoice
@@ -1272,20 +1272,17 @@ export const make: (params: {
       }
     }
 
-    const ResponseSchema = Schema.mutable(Schema.Array(withUndeclaredToolCalls(
-      Response.Part(
-        options.disableToolCallResolution === true && !deferToolCallValidation
-          ? makeToolkitWithEncodedParameters(toolkit)
-          : makeToolkitWithOpaqueParameters(toolkit)
-      ),
+    const decodeContent = contentDecoderFor(
+      toolkit,
+      options.disableToolCallResolution === true && !deferToolCallValidation,
       deferToolCallValidation
-    )))
+    )
 
     // If tool call resolution is disabled, return the response without
     // resolving the tool calls that were generated
     if (options.disableToolCallResolution === true) {
       const rawContent = yield* generateWithNonIncrementalFallback()
-      const content = yield* Schema.decodeEffect(ResponseSchema)(rawContent)
+      const content = yield* decodeContent(rawContent)
       if (deferToolCallValidation) {
         yield* validateProviderExecutedToolCalls(makeToolkitWithEncodedParameters(toolkit), rawContent)
       }
@@ -1301,7 +1298,7 @@ export const make: (params: {
     const rawContent = yield* generateWithNonIncrementalFallback()
 
     // Validate before running tool handlers.
-    const content = yield* Schema.decodeEffect(ResponseSchema)(rawContent)
+    const content = yield* decodeContent(rawContent)
     yield* validateProviderExecutedToolCalls(toolkit, rawContent)
 
     // Resolve the generated tool calls. When the finish reason indicates an
@@ -1407,9 +1404,9 @@ export const make: (params: {
     }
 
     // Check for pending approvals that need resolution
-    const { approved: pendingApproved, denied: pendingDenied } = collectToolApprovals(providerOptions.prompt.content, {
-      excludeResolved: true
-    })
+    const { approved: allResolved, denied: allDenied, pendingApproved, pendingDenied } = collectToolApprovals(
+      providerOptions.prompt.content
+    )
     const hasPendingApprovals = pendingApproved.length > 0 || pendingDenied.length > 0
 
     // If there is no toolkit, return immediately
@@ -1564,9 +1561,6 @@ export const make: (params: {
 
     // Strip all resolved approval artifacts (both current and from previous
     // rounds) in a single pass before sending to the provider.
-    const { approved: allResolved, denied: allDenied } = collectToolApprovals(
-      providerOptions.prompt.content
-    )
     if (allResolved.length > 0 || allDenied.length > 0) {
       providerOptions.prompt = stripResolvedApprovals(
         providerOptions.prompt,
@@ -1589,15 +1583,11 @@ export const make: (params: {
       }
     }
 
-    const ResponseSchema = Schema.NonEmptyArray(withUndeclaredToolCalls(
-      Response.StreamPart(
-        options.disableToolCallResolution === true && !deferToolCallValidation
-          ? makeToolkitWithEncodedParameters(toolkit)
-          : makeToolkitWithOpaqueParameters(toolkit)
-      ),
+    const decodeParts = streamDecoderFor(
+      toolkit,
+      options.disableToolCallResolution === true && !deferToolCallValidation,
       deferToolCallValidation
-    ))
-    const decodeParts = Schema.decodeEffect(ResponseSchema)
+    )
 
     // If tool call resolution is disabled, return the response without
     // resolving the tool calls that were generated
@@ -1638,8 +1628,7 @@ export const make: (params: {
     const deferredFinishParts: Array<Response.StreamPart<Tools>> = []
 
     // Emit pre-resolved tool results so Chat.streamText persists them to
-    // history. This ensures collectToolApprovals({ excludeResolved }) can
-    // find the corresponding tool-results on future rounds.
+    // history, where collectToolApprovals finds them on future rounds.
     if (preResolvedStreamParts.length > 0) {
       yield* Queue.offerAll(queue, preResolvedStreamParts)
     }
@@ -2072,16 +2061,13 @@ interface ApprovalResult {
   readonly toolCall?: Prompt.ToolCallPart | undefined
 }
 
-interface CollectToolApprovalsOptions {
-  readonly excludeResolved?: boolean
-}
-
 const collectToolApprovals = (
-  messages: ReadonlyArray<Prompt.Message>,
-  options?: CollectToolApprovalsOptions
+  messages: ReadonlyArray<Prompt.Message>
 ): {
   readonly approved: Array<ApprovalResult>
   readonly denied: Array<ApprovalResult>
+  readonly pendingApproved: Array<ApprovalResult>
+  readonly pendingDenied: Array<ApprovalResult>
 } => {
   const requests = new Map<
     string,
@@ -2124,15 +2110,12 @@ const collectToolApprovals = (
 
   const approved: Array<ApprovalResult> = []
   const denied: Array<ApprovalResult> = []
+  const pendingApproved: Array<ApprovalResult> = []
+  const pendingDenied: Array<ApprovalResult> = []
 
   for (const response of responses) {
     const request = requests.get(response.approvalId)
     if (Predicate.isNotUndefined(request)) {
-      // Skip if already resolved
-      if (options?.excludeResolved && toolResultIds.has(request.toolCallId)) {
-        continue
-      }
-
       const result: ApprovalResult = {
         ...response,
         toolCallId: request.toolCallId,
@@ -2141,13 +2124,15 @@ const collectToolApprovals = (
 
       if (response.approved) {
         approved.push(result)
+        if (!toolResultIds.has(request.toolCallId)) pendingApproved.push(result)
       } else {
         denied.push(result)
+        if (!toolResultIds.has(request.toolCallId)) pendingDenied.push(result)
       }
     }
   }
 
-  return { approved, denied }
+  return { approved, denied, pendingApproved, pendingDenied }
 }
 
 /**
@@ -2476,6 +2461,27 @@ const resolveToolCalls = <Tools extends Record<string, Tool.Any>>(
 // Utilities
 // =============================================================================
 
+// Cache one decoder per model and response kind, keyed by validation mode
+// and tool names and schema identities in insertion order.
+const makeResponseDecoder = <Decode>(make: (toolkit: Toolkit.Any, deferred: boolean) => Decode) => {
+  let cached: { readonly key: ReadonlyArray<unknown>; readonly decode: Decode } | undefined
+  return (toolkit: Toolkit.WithHandler<any>, encoded: boolean, deferred: boolean): Decode => {
+    const key: Array<unknown> = [encoded, deferred]
+    for (const tool of Object.values(toolkit.tools as Record<string, Tool.Any>)) {
+      key.push(tool.name, tool.parametersSchema, tool.successSchema, tool.failureSchema)
+    }
+    if (cached !== undefined && cached.key.length === key.length && cached.key.every((part, i) => part === key[i])) {
+      return cached.decode
+    }
+    const decode = make(
+      encoded ? makeToolkitWithEncodedParameters(toolkit) : makeToolkitWithOpaqueParameters(toolkit),
+      deferred
+    )
+    cached = { key, decode }
+    return decode
+  }
+}
+
 // Stable parameter-mode copies let Response reuse each tool's part schemas.
 const parameterModeTools = new WeakMap<Tool.Any, { encoded?: Tool.Any; opaque?: Tool.Any }>()
 

package/src/ai/McpServer.ts

@@ -2277,12 +2277,6 @@ export type ResourceCompletions<Schemas extends ReadonlyArray<Schema.Constraint>
 /**
  * Registers an MCP resource or resource template from an Effect program.
  *
- * **When to use**
- *
- * Use when you are already inside an Effect program with an `McpServer`
- * service and need to add a concrete resource or URI-template resource
- * directly.
- *
  * @see {@link resource} for the layer-based resource registration wrapper
  *
  * @stability unstable
@@ -2293,12 +2287,6 @@ export const registerResource: {
   /**
    * Registers an MCP resource or resource template from an Effect program.
    *
-   * **When to use**
-   *
-   * Use when you are already inside an Effect program with an `McpServer`
-   * service and need to add a concrete resource or URI-template resource
-   * directly.
-   *
    * @see {@link resource} for the layer-based resource registration wrapper
    *
    * @stability unstable
@@ -2324,12 +2312,6 @@ export const registerResource: {
   /**
    * Registers an MCP resource or resource template from an Effect program.
    *
-   * **When to use**
-   *
-   * Use when you are already inside an Effect program with an `McpServer`
-   * service and need to add a concrete resource or URI-template resource
-   * directly.
-   *
    * @see {@link resource} for the layer-based resource registration wrapper
    *
    * @stability unstable
@@ -2360,9 +2342,7 @@ export const registerResource: {
       | Schemas[number]["DecodingServices"]
       | Schemas[number]["EncodingServices"]
       | R
-      | (Completions[keyof Completions] extends (input: string) => infer Ret ?
-        Ret extends Effect.Effect<infer _A, infer _E, infer _R> ? _R : never
-        : never),
+      | CompletionServices<Completions>,
       McpRequestContext
     >
     | McpServer
@@ -2491,10 +2471,6 @@ export const registerResource: {
 /**
  * Creates a layer that registers an MCP resource or resource template.
  *
- * **When to use**
- *
- * Use to compose resource registration into an MCP server layer.
- *
  * @see {@link registerResource} for the Effect-level resource registration API
  *
  * @stability unstable
@@ -2505,10 +2481,6 @@ export const resource: {
   /**
    * Creates a layer that registers an MCP resource or resource template.
    *
-   * **When to use**
-   *
-   * Use to compose resource registration into an MCP server layer.
-   *
    * @see {@link registerResource} for the Effect-level resource registration API
    *
    * @stability unstable
@@ -2533,10 +2505,6 @@ export const resource: {
   /**
    * Creates a layer that registers an MCP resource or resource template.
    *
-   * **When to use**
-   *
-   * Use to compose resource registration into an MCP server layer.
-   *
    * @see {@link registerResource} for the Effect-level resource registration API
    *
    * @stability unstable
@@ -2563,10 +2531,10 @@ export const resource: {
     never,
     never,
     Exclude<
+      | Schemas[number]["DecodingServices"]
+      | Schemas[number]["EncodingServices"]
       | R
-      | (Completions[keyof Completions] extends (input: string) => infer Ret ?
-        Ret extends Effect.Effect<infer _A, infer _E, infer _R> ? _R : never
-        : never),
+      | CompletionServices<Completions>,
       McpRequestContext
     >
   >
@@ -2586,16 +2554,10 @@ export const resource: {
 /**
  * Registers an MCP prompt from an Effect program.
  *
- * **When to use**
- *
- * Use when you are already inside an Effect program with an `McpServer`
- * service and need to add a prompt handler directly.
- *
  * **Details**
  *
- * Parameters are decoded with the supplied schema, completion handlers encode
- * per-parameter suggestions, and string prompt content is converted into a user
- * text message.
+ * Decodes parameters and encodes completion suggestions using their schemas.
+ * String content becomes a user text message.
  *
  * @see {@link prompt} for the layer-based prompt registration wrapper
  *
@@ -2630,6 +2592,7 @@ export const registerPrompt = <
   never,
   | Exclude<
     | Schema.Struct.DecodingServices<Params>
+    | Params[Extract<keyof Completions, keyof Params>]["EncodingServices"]
     | R
     | CompletionServices<Completions>,
     McpRequestContext
@@ -2665,7 +2628,13 @@ export const registerPrompt = <
     const registry = yield* McpServer
     const services = omitRequestServices(
       yield* Effect.context<
-        Exclude<R | Schema.Struct.DecodingServices<Params>, McpRequestContext>
+        Exclude<
+          | R
+          | Schema.Struct.DecodingServices<Params>
+          | Params[Extract<keyof Completions, keyof Params>]["EncodingServices"]
+          | CompletionServices<Completions>,
+          McpRequestContext
+        >
       >()
     )
     const completions: Record<
@@ -2731,16 +2700,6 @@ export const registerPrompt = <
 /**
  * Creates a layer that registers an MCP prompt.
  *
- * **When to use**
- *
- * Use to compose prompt registration into an MCP server layer.
- *
- * **Details**
- *
- * Parameters are decoded with the supplied schema, completion handlers encode
- * per-parameter suggestions, and string prompt content is converted into a user
- * text message.
- *
  * @see {@link registerPrompt} for the Effect-level prompt registration API
  *
  * @stability unstable
@@ -2774,6 +2733,7 @@ export const prompt = <
   never,
   Exclude<
     | Schema.Struct.DecodingServices<Params>
+    | Params[Extract<keyof Completions, keyof Params>]["EncodingServices"]
     | R
     | CompletionServices<Completions>,
     McpRequestContext

package/src/cli/Completions.ts

@@ -48,6 +48,11 @@ export interface FlagDescriptor {
   readonly aliases: ReadonlyArray<string>
   readonly description: string | undefined
   readonly type: FlagType
+  /**
+   * Whether the flag's value is optional. Its value can only be attached with
+   * `=` (`--name=value`), never given as the next word.
+   */
+  readonly optionalValue?: boolean | undefined
 }
 
 /**

package/src/cli/Flag.ts

@@ -611,6 +611,107 @@ export const withDescription: {
   <A>(self: Flag<A>, description: string): Flag<A>
 } = dual(2, <A>(self: Flag<A>, description: string) => Param.withDescription(self, description))
 
+/**
+ * Lets a flag be given without a value, in which case `value` is used.
+ *
+ * **Details**
+ *
+ * Follows GNU-style optional values, like `--color[=WHEN]`. An explicit value
+ * must be attached with `=` (`--watch=until-done` or `-w=until-done`). A bare
+ * `--watch` is parsed as `--watch=<value>`, so `value` is validated like any
+ * other input. The flag never consumes the next token, so in `--watch build`,
+ * `build` stays a positional argument or subcommand. The flag is still
+ * required unless it is made optional or given a default.
+ *
+ * **Example** (Flag with an optional value)
+ *
+ * ```ts import.meta.vitest
+ * import { Flag } from "effect/cli"
+ *
+ * const watch = Flag.Literals("watch", ["first-failure", "until-done"]).pipe(
+ *   Flag.withOptionalValue("first-failure"),
+ *   Flag.optional
+ * )
+ * // --watch             => Option.some("first-failure")
+ * // --watch=until-done  => Option.some("until-done")
+ * // (absent)            => Option.none()
+ * // In help: --watch [=choice]
+ * watch.kind // => "flag"
+ * ```
+ *
+ * @stability unstable
+ * @category combinators
+ * @since 4.1.0
+ */
+export const withOptionalValue: {
+  /**
+   * Lets a flag be given without a value, in which case `value` is used.
+   *
+   * **Details**
+   *
+   * Follows GNU-style optional values, like `--color[=WHEN]`. An explicit value
+   * must be attached with `=` (`--watch=until-done` or `-w=until-done`). A bare
+   * `--watch` is parsed as `--watch=<value>`, so `value` is validated like any
+   * other input. The flag never consumes the next token, so in `--watch build`,
+   * `build` stays a positional argument or subcommand. The flag is still
+   * required unless it is made optional or given a default.
+   *
+   * **Example** (Flag with an optional value)
+   *
+   * ```ts import.meta.vitest
+   * import { Flag } from "effect/cli"
+   *
+   * const watch = Flag.Literals("watch", ["first-failure", "until-done"]).pipe(
+   *   Flag.withOptionalValue("first-failure"),
+   *   Flag.optional
+   * )
+   * // --watch             => Option.some("first-failure")
+   * // --watch=until-done  => Option.some("until-done")
+   * // (absent)            => Option.none()
+   * // In help: --watch [=choice]
+   * watch.kind // => "flag"
+   * ```
+   *
+   * @stability unstable
+   * @category combinators
+   * @since 4.1.0
+   */
+  (value: string): <A>(self: Flag<A>) => Flag<A>
+  /**
+   * Lets a flag be given without a value, in which case `value` is used.
+   *
+   * **Details**
+   *
+   * Follows GNU-style optional values, like `--color[=WHEN]`. An explicit value
+   * must be attached with `=` (`--watch=until-done` or `-w=until-done`). A bare
+   * `--watch` is parsed as `--watch=<value>`, so `value` is validated like any
+   * other input. The flag never consumes the next token, so in `--watch build`,
+   * `build` stays a positional argument or subcommand. The flag is still
+   * required unless it is made optional or given a default.
+   *
+   * **Example** (Flag with an optional value)
+   *
+   * ```ts import.meta.vitest
+   * import { Flag } from "effect/cli"
+   *
+   * const watch = Flag.Literals("watch", ["first-failure", "until-done"]).pipe(
+   *   Flag.withOptionalValue("first-failure"),
+   *   Flag.optional
+   * )
+   * // --watch             => Option.some("first-failure")
+   * // --watch=until-done  => Option.some("until-done")
+   * // (absent)            => Option.none()
+   * // In help: --watch [=choice]
+   * watch.kind // => "flag"
+   * ```
+   *
+   * @stability unstable
+   * @category combinators
+   * @since 4.1.0
+   */
+  <A>(self: Flag<A>, value: string): Flag<A>
+} = dual(2, <A>(self: Flag<A>, value: string) => Param.withOptionalValue(self, value))
+
 // -------------------------------------------------------------------------------------
 // metadata
 // -------------------------------------------------------------------------------------

package/src/cli/Param.ts

@@ -213,6 +213,10 @@ export interface Single<Kind extends ParamKind, out A> extends Param<Kind, A> {
   readonly primitiveType: Primitive.Primitive<A>
   readonly typeName?: string | undefined
   readonly hidden: boolean
+  /**
+   * Raw value used for a bare flag. See `withOptionalValue`.
+   */
+  readonly optionalValue?: string | undefined
 }
 
 /**
@@ -362,6 +366,7 @@ export const makeSingle = <const Kind extends ParamKind, A>(params: {
   readonly description?: Option.Option<string> | undefined
   readonly aliases?: ReadonlyArray<string> | undefined
   readonly hidden?: boolean | undefined
+  readonly optionalValue?: string | undefined
 }): Single<Kind, A> => {
   const parse: Parse<A> = (args) =>
     params.kind === argumentKind
@@ -2664,6 +2669,97 @@ export const withMetavar: {
       typeName: metavar
     })))
 
+/**
+ * Lets a flag be given without a value, in which case `value` is used.
+ *
+ * **Details**
+ *
+ * Follows GNU-style optional values. An explicit value must be attached with
+ * `=` (`--watch=until-done`), and a bare `--watch` is parsed as
+ * `--watch=<value>`. The flag never consumes the next token. It is still
+ * required unless it is made optional or given a default.
+ *
+ * **Example** (Flag with an optional value)
+ *
+ * ```ts import.meta.vitest
+ * import { Param } from "effect/cli"
+ *
+ * const watch = Param.String(Param.flagKind, "watch").pipe(
+ *   Param.withOptionalValue("first-failure"),
+ *   Param.optional
+ * )
+ * watch.kind // => "flag"
+ * ```
+ *
+ * @stability unstable
+ * @category combinators
+ * @since 4.1.0
+ */
+export const withOptionalValue: {
+  /**
+   * Lets a flag be given without a value, in which case `value` is used.
+   *
+   * **Details**
+   *
+   * Follows GNU-style optional values. An explicit value must be attached with
+   * `=` (`--watch=until-done`), and a bare `--watch` is parsed as
+   * `--watch=<value>`. The flag never consumes the next token. It is still
+   * required unless it is made optional or given a default.
+   *
+   * **Example** (Flag with an optional value)
+   *
+   * ```ts import.meta.vitest
+   * import { Param } from "effect/cli"
+   *
+   * const watch = Param.String(Param.flagKind, "watch").pipe(
+   *   Param.withOptionalValue("first-failure"),
+   *   Param.optional
+   * )
+   * watch.kind // => "flag"
+   * ```
+   *
+   * @stability unstable
+   * @category combinators
+   * @since 4.1.0
+   */
+  (value: string): <A>(self: Param<typeof flagKind, A>) => Param<typeof flagKind, A>
+  /**
+   * Lets a flag be given without a value, in which case `value` is used.
+   *
+   * **Details**
+   *
+   * Follows GNU-style optional values. An explicit value must be attached with
+   * `=` (`--watch=until-done`), and a bare `--watch` is parsed as
+   * `--watch=<value>`. The flag never consumes the next token. It is still
+   * required unless it is made optional or given a default.
+   *
+   * **Example** (Flag with an optional value)
+   *
+   * ```ts import.meta.vitest
+   * import { Param } from "effect/cli"
+   *
+   * const watch = Param.String(Param.flagKind, "watch").pipe(
+   *   Param.withOptionalValue("first-failure"),
+   *   Param.optional
+   * )
+   * watch.kind // => "flag"
+   * ```
+   *
+   * @stability unstable
+   * @category combinators
+   * @since 4.1.0
+   */
+  <A>(self: Param<typeof flagKind, A>, value: string): Param<typeof flagKind, A>
+} = dual(2, <A>(
+  self: Param<typeof flagKind, A>,
+  value: string
+) =>
+  transformSingle(self, (single) =>
+    makeSingle({
+      ...single,
+      optionalValue: value
+    })))
+
 /**
  * Validates parsed values against a Schema, providing detailed error messages.
  *

package/src/cli/internal/command.ts

@@ -242,10 +242,11 @@ export const toFlagDoc = (
   metadata: ReturnType<typeof Param.getParamMetadata>
 ): FlagDoc => {
   const formattedAliases = single.aliases.map((alias) => alias.length === 1 ? `-${alias}` : `--${alias}`)
+  const type = single.typeName ?? Primitive.getTypeName(single.primitiveType)
   return {
     name: single.name,
     aliases: formattedAliases,
-    type: single.typeName ?? Primitive.getTypeName(single.primitiveType),
+    type: single.optionalValue === undefined ? type : `[=${type}]`,
     description: appendChoiceKeys(single.description, Primitive.getChoiceKeys(single.primitiveType)),
     required: single.primitiveType._tag !== "Boolean" && !metadata.isOptional
   }

package/src/cli/internal/completions/bash.ts

@@ -7,6 +7,7 @@
  * @internal
  */
 import type * as Completions from "../../Completions.ts"
+import { takesSeparateValue } from "./descriptor.ts"
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -164,7 +165,7 @@ const generateFunction = (
   lines.push(``)
 
   // Build flag-value dispatch
-  const flagsWithValues = descriptor.flags.filter((f) => f.type._tag !== "Boolean")
+  const flagsWithValues = descriptor.flags.filter(takesSeparateValue)
   if (flagsWithValues.length > 0) {
     lines.push(`  # Flag value completions`)
     lines.push(`  case "$prev" in`)
@@ -196,7 +197,7 @@ const generateFunction = (
     lines.push(`    fi`)
     lines.push(`    case "\${words[i]}" in`)
     for (const flag of descriptor.flags) {
-      if (flag.type._tag === "Boolean") continue
+      if (!takesSeparateValue(flag)) continue
       const forms = flagNamesForWordlist(flag)
       lines.push(`      ${forms.join("|")}) _skip_next=1 ;;`)
       lines.push(`      ${forms.map((form) => `${form}=*`).join("|")}) ;;`)
@@ -248,7 +249,7 @@ const generateFunction = (
     lines.push(`      --) _end_of_options=1 ;;`)
     for (const flag of descriptor.flags) {
       const forms = flagNamesForWordlist(flag)
-      if (flag.type._tag === "Boolean") {
+      if (!takesSeparateValue(flag)) {
         lines.push(`      ${forms.join("|")}) ;;`)
       } else {
         lines.push(`      ${forms.join("|")}) _skip_next=1 ;;`)

package/src/cli/internal/completions/descriptor.ts

@@ -95,7 +95,8 @@ export const fromCommand = (
         name: single.name,
         aliases: single.aliases,
         description: Option.getOrUndefined(single.description),
-        type: toFlagType(single as Param.Single<"flag", unknown>)
+        type: toFlagType(single as Param.Single<"flag", unknown>),
+        optionalValue: single.optionalValue !== undefined
       })
     }
   }
@@ -139,3 +140,11 @@ export const fromCommand = (
     subcommands
   }
 }
+
+/**
+ * Whether the flag reads its value from the next word.
+ *
+ * @internal
+ */
+export const takesSeparateValue = (flag: Completions.FlagDescriptor): boolean =>
+  flag.type._tag !== "Boolean" && flag.optionalValue !== true