effect 4.0.0-beta.103 → 4.0.0-beta.104

package/src/unstable/ai/AiError.ts

@@ -76,7 +76,7 @@ const redactHeaders = (headers: Record<string, string>): Record<string, string>
  * @category errors
  * @since 4.0.0
  */
-export class NetworkError extends Schema.ErrorClass<NetworkError>(
+export class NetworkError extends Schema.Error<NetworkError>(
   "effect/ai/AiError/NetworkError"
 )({
   _tag: Schema.tag("NetworkError"),
@@ -369,7 +369,7 @@ export const HttpContext = Schema.Struct({
  * @category errors
  * @since 4.0.0
  */
-export class RateLimitError extends Schema.ErrorClass<RateLimitError>(
+export class RateLimitError extends Schema.Error<RateLimitError>(
   "effect/ai/AiError/RateLimitError"
 )({
   _tag: Schema.tag("RateLimitError"),
@@ -420,7 +420,7 @@ export class RateLimitError extends Schema.ErrorClass<RateLimitError>(
  * @category errors
  * @since 4.0.0
  */
-export class QuotaExhaustedError extends Schema.ErrorClass<QuotaExhaustedError>(
+export class QuotaExhaustedError extends Schema.Error<QuotaExhaustedError>(
   "effect/ai/AiError/QuotaExhaustedError"
 )({
   _tag: Schema.tag("QuotaExhaustedError"),
@@ -473,7 +473,7 @@ export class QuotaExhaustedError extends Schema.ErrorClass<QuotaExhaustedError>(
  * @category errors
  * @since 4.0.0
  */
-export class AuthenticationError extends Schema.ErrorClass<AuthenticationError>(
+export class AuthenticationError extends Schema.Error<AuthenticationError>(
   "effect/ai/AiError/AuthenticationError"
 )({
   _tag: Schema.tag("AuthenticationError"),
@@ -531,7 +531,7 @@ export class AuthenticationError extends Schema.ErrorClass<AuthenticationError>(
  * @category errors
  * @since 4.0.0
  */
-export class ContentPolicyError extends Schema.ErrorClass<ContentPolicyError>(
+export class ContentPolicyError extends Schema.Error<ContentPolicyError>(
   "effect/ai/AiError/ContentPolicyError"
 )({
   _tag: Schema.tag("ContentPolicyError"),
@@ -584,7 +584,7 @@ export class ContentPolicyError extends Schema.ErrorClass<ContentPolicyError>(
  * @category errors
  * @since 4.0.0
  */
-export class InvalidRequestError extends Schema.ErrorClass<InvalidRequestError>(
+export class InvalidRequestError extends Schema.Error<InvalidRequestError>(
   "effect/ai/AiError/InvalidRequestError"
 )({
   _tag: Schema.tag("InvalidRequestError"),
@@ -641,7 +641,7 @@ export class InvalidRequestError extends Schema.ErrorClass<InvalidRequestError>(
  * @category errors
  * @since 4.0.0
  */
-export class InternalProviderError extends Schema.ErrorClass<InternalProviderError>(
+export class InternalProviderError extends Schema.Error<InternalProviderError>(
   "effect/ai/AiError/InternalProviderError"
 )({
   _tag: Schema.tag("InternalProviderError"),
@@ -692,7 +692,7 @@ export class InternalProviderError extends Schema.ErrorClass<InternalProviderErr
  * @category errors
  * @since 4.0.0
  */
-export class InvalidOutputError extends Schema.ErrorClass<InvalidOutputError>(
+export class InvalidOutputError extends Schema.Error<InvalidOutputError>(
   "effect/ai/AiError/InvalidOutputError"
 )({
   _tag: Schema.tag("InvalidOutputError"),
@@ -769,7 +769,7 @@ export class InvalidOutputError extends Schema.ErrorClass<InvalidOutputError>(
  * @category errors
  * @since 4.0.0
  */
-export class StructuredOutputError extends Schema.ErrorClass<StructuredOutputError>(
+export class StructuredOutputError extends Schema.Error<StructuredOutputError>(
   "effect/ai/AiError/StructuredOutputError"
 )({
   _tag: Schema.tag("StructuredOutputError"),
@@ -848,7 +848,7 @@ export class StructuredOutputError extends Schema.ErrorClass<StructuredOutputErr
  * @category errors
  * @since 4.0.0
  */
-export class UnsupportedSchemaError extends Schema.ErrorClass<UnsupportedSchemaError>(
+export class UnsupportedSchemaError extends Schema.Error<UnsupportedSchemaError>(
   "effect/ai/AiError/UnsupportedSchemaError"
 )({
   _tag: Schema.tag("UnsupportedSchemaError"),
@@ -898,7 +898,7 @@ export class UnsupportedSchemaError extends Schema.ErrorClass<UnsupportedSchemaE
  * @category errors
  * @since 4.0.0
  */
-export class UnknownError extends Schema.ErrorClass<UnknownError>(
+export class UnknownError extends Schema.Error<UnknownError>(
   "effect/ai/AiError/UnknownError"
 )({
   _tag: Schema.tag("UnknownError"),
@@ -955,7 +955,7 @@ export class UnknownError extends Schema.ErrorClass<UnknownError>(
  * @category errors
  * @since 4.0.0
  */
-export class ToolNotFoundError extends Schema.ErrorClass<ToolNotFoundError>(
+export class ToolNotFoundError extends Schema.Error<ToolNotFoundError>(
   "effect/ai/AiError/ToolNotFoundError"
 )({
   _tag: Schema.tag("ToolNotFoundError"),
@@ -1009,7 +1009,7 @@ export class ToolNotFoundError extends Schema.ErrorClass<ToolNotFoundError>(
  * @category errors
  * @since 4.0.0
  */
-export class ToolParameterValidationError extends Schema.ErrorClass<ToolParameterValidationError>(
+export class ToolParameterValidationError extends Schema.Error<ToolParameterValidationError>(
   "effect/ai/AiError/ToolParameterValidationError"
 )({
   _tag: Schema.tag("ToolParameterValidationError"),
@@ -1063,7 +1063,7 @@ export class ToolParameterValidationError extends Schema.ErrorClass<ToolParamete
  * @category errors
  * @since 4.0.0
  */
-export class InvalidToolResultError extends Schema.ErrorClass<InvalidToolResultError>(
+export class InvalidToolResultError extends Schema.Error<InvalidToolResultError>(
   "effect/ai/AiError/InvalidToolResultError"
 )({
   _tag: Schema.tag("InvalidToolResultError"),
@@ -1116,7 +1116,7 @@ export class InvalidToolResultError extends Schema.ErrorClass<InvalidToolResultE
  * @category errors
  * @since 4.0.0
  */
-export class ToolResultEncodingError extends Schema.ErrorClass<ToolResultEncodingError>(
+export class ToolResultEncodingError extends Schema.Error<ToolResultEncodingError>(
   "effect/ai/AiError/ToolResultEncodingError"
 )({
   _tag: Schema.tag("ToolResultEncodingError"),
@@ -1169,7 +1169,7 @@ export class ToolResultEncodingError extends Schema.ErrorClass<ToolResultEncodin
  * @category errors
  * @since 4.0.0
  */
-export class ToolConfigurationError extends Schema.ErrorClass<ToolConfigurationError>(
+export class ToolConfigurationError extends Schema.Error<ToolConfigurationError>(
   "effect/ai/AiError/ToolConfigurationError"
 )({
   _tag: Schema.tag("ToolConfigurationError"),
@@ -1220,7 +1220,7 @@ export class ToolConfigurationError extends Schema.ErrorClass<ToolConfigurationE
  * @category errors
  * @since 4.0.0
  */
-export class ToolkitRequiredError extends Schema.ErrorClass<ToolkitRequiredError>(
+export class ToolkitRequiredError extends Schema.Error<ToolkitRequiredError>(
   "effect/ai/AiError/ToolkitRequiredError"
 )({
   _tag: Schema.tag("ToolkitRequiredError"),
@@ -1273,7 +1273,7 @@ export class ToolkitRequiredError extends Schema.ErrorClass<ToolkitRequiredError
  * @category errors
  * @since 4.0.0
  */
-export class InvalidUserInputError extends Schema.ErrorClass<InvalidUserInputError>(
+export class InvalidUserInputError extends Schema.Error<InvalidUserInputError>(
   "effect/ai/AiError/InvalidUserInputError"
 )({
   _tag: Schema.tag("InvalidUserInputError"),
@@ -1439,7 +1439,7 @@ const TypeId = "~effect/unstable/ai/AiError/AiError" as const
  * @category schemas
  * @since 4.0.0
  */
-export class AiError extends Schema.ErrorClass<AiError>(
+export class AiError extends Schema.Error<AiError>(
   "effect/ai/AiError/AiError"
 )({
   _tag: Schema.tag("AiError"),

package/src/unstable/ai/Chat.ts

@@ -699,7 +699,7 @@ export const fromJson = (data: string): Effect.Effect<
  * @category errors
  * @since 4.0.0
  */
-export class ChatNotFoundError extends Schema.ErrorClass<ChatNotFoundError>(
+export class ChatNotFoundError extends Schema.Error<ChatNotFoundError>(
   "effect/ai/Chat/ChatNotFoundError"
 )({
   _tag: Schema.tag("ChatNotFoundError"),

package/src/unstable/ai/LanguageModel.ts

@@ -2055,7 +2055,8 @@ const executeApprovedToolCalls = <Tools extends Record<string, Tool.Any>>(
       id: approval.toolCallId,
       name: toolCall.name,
       isFailure: terminalResult.isFailure,
-      result: terminalResult.encodedResult
+      result: terminalResult.encodedResult,
+      providerExecuted: false
     })
   })
 
@@ -2075,7 +2076,8 @@ const createDenialResults = (
           id: denial.toolCallId,
           name: denial.toolCall.name,
           isFailure: true,
-          result: { type: "execution-denied", reason: denial.reason }
+          result: { type: "execution-denied", reason: denial.reason },
+          providerExecuted: false
         })
       )
     }

package/src/unstable/ai/McpSchema.ts

@@ -540,7 +540,7 @@ export const PARSE_ERROR_CODE = -32700 as const
  * @category errors
  * @since 4.0.0
  */
-export class ParseError extends Schema.ErrorClass<ParseError>("effect/ai/McpSchema/ParseError")({
+export class ParseError extends Schema.Error<ParseError>("effect/ai/McpSchema/ParseError")({
   ...McpErrorBase.fields,
   _tag: Schema.tag("ParseError"),
   code: Schema.tag(PARSE_ERROR_CODE)
@@ -561,7 +561,7 @@ export class ParseError extends Schema.ErrorClass<ParseError>("effect/ai/McpSche
  * @category errors
  * @since 4.0.0
  */
-export class InvalidRequest extends Schema.ErrorClass<InvalidRequest>("effect/ai/McpSchema/InvalidRequest")({
+export class InvalidRequest extends Schema.Error<InvalidRequest>("effect/ai/McpSchema/InvalidRequest")({
   ...McpErrorBase.fields,
   _tag: Schema.tag("InvalidRequest"),
   code: Schema.tag(INVALID_REQUEST_ERROR_CODE)
@@ -581,7 +581,7 @@ export class InvalidRequest extends Schema.ErrorClass<InvalidRequest>("effect/ai
  * @category errors
  * @since 4.0.0
  */
-export class MethodNotFound extends Schema.ErrorClass<MethodNotFound>("effect/ai/McpSchema/MethodNotFound")({
+export class MethodNotFound extends Schema.Error<MethodNotFound>("effect/ai/McpSchema/MethodNotFound")({
   ...McpErrorBase.fields,
   _tag: Schema.tag("MethodNotFound"),
   code: Schema.tag(METHOD_NOT_FOUND_ERROR_CODE)
@@ -602,7 +602,7 @@ export class MethodNotFound extends Schema.ErrorClass<MethodNotFound>("effect/ai
  * @category errors
  * @since 4.0.0
  */
-export class InvalidParams extends Schema.ErrorClass<InvalidParams>("effect/ai/McpSchema/InvalidParams")({
+export class InvalidParams extends Schema.Error<InvalidParams>("effect/ai/McpSchema/InvalidParams")({
   ...McpErrorBase.fields,
   _tag: Schema.tag("InvalidParams"),
   code: Schema.tag(INVALID_PARAMS_ERROR_CODE)
@@ -624,7 +624,7 @@ export class InvalidParams extends Schema.ErrorClass<InvalidParams>("effect/ai/M
  * @category errors
  * @since 4.0.0
  */
-export class InternalError extends Schema.ErrorClass<InternalError>("effect/ai/McpSchema/InternalError")({
+export class InternalError extends Schema.Error<InternalError>("effect/ai/McpSchema/InternalError")({
   ...McpErrorBase.fields,
   _tag: Schema.tag("InternalError"),
   code: Schema.tag(INTERNAL_ERROR_CODE)
@@ -1562,9 +1562,12 @@ export class CallTool extends Rpc.make("tools/call", {
   payload: {
     ...RequestMeta.fields,
     name: Schema.String,
-    arguments: Schema.Record(
-      Schema.String,
-      Schema.Any
+    arguments: optionalWithDefault(
+      Schema.Record(
+        Schema.String,
+        Schema.Any
+      ),
+      () => ({})
     )
   }
 }) {}
@@ -1851,7 +1854,7 @@ export class CreateMessage extends Rpc.make("sampling/createMessage", {
      * Optional metadata to pass through to the LLM provider. The format of
      * this metadata is provider-specific.
      */
-    metadata: Schema.Any
+    metadata: optional(Schema.Record(Schema.String, Schema.Unknown))
   }
 }) {}
 
@@ -2149,13 +2152,11 @@ export class Elicit extends Rpc.make("elicitation/create", {
  * @category schemas
  * @since 4.0.0
  */
-export class ElicitationDeclined
-  extends Schema.ErrorClass<ElicitationDeclined>("@effect/ai/McpSchema/ElicitationDeclined")({
-    _tag: Schema.tag("ElicitationDeclined"),
-    request: Elicit.payloadSchema,
-    cause: optional(Schema.Defect())
-  })
-{}
+export class ElicitationDeclined extends Schema.Error<ElicitationDeclined>("@effect/ai/McpSchema/ElicitationDeclined")({
+  _tag: Schema.tag("ElicitationDeclined"),
+  request: Elicit.payloadSchema,
+  cause: optional(Schema.Defect())
+}) {}
 
 // =============================================================================
 // McpServerClient

package/src/unstable/ai/McpServer.ts

@@ -1299,7 +1299,7 @@ export const registerToolkit: <Tools extends Record<string, Tool.Any>>(
             new CallToolResult({
               isError: false,
               structuredContent: typeof result.encodedResult === "object" ? result.encodedResult : undefined,
-              content: [{
+              content: result.encodedResult === undefined ? [] : [{
                 type: "text",
                 text: JSON.stringify(result.encodedResult)
               }]

package/src/unstable/ai/Prompt.ts

@@ -631,7 +631,8 @@ export const toolCallPart = (params: PartConstructorParams<ToolCallPart>): ToolC
  *     temperature: 22,
  *     condition: "sunny",
  *     humidity: 65
- *   }
+ *   },
+ *   providerExecuted: false
  * })
  * const result = [toolResultPart.name, toolResultPart.isFailure] // => ["get_weather", false]
  * ```
@@ -656,6 +657,10 @@ export interface ToolResultPart extends BasePart<"tool-result", ToolResultPartOp
    * The result returned by the tool execution.
    */
   readonly result: unknown
+  /**
+   * Whether the tool was executed by the provider (true) or framework (false).
+   */
+  readonly providerExecuted: boolean
 }
 
 /**
@@ -681,6 +686,10 @@ export interface ToolResultPartEncoded extends BasePartEncoded<"tool-result", To
    * The result returned by the tool execution.
    */
   readonly result: unknown
+  /**
+   * Whether the tool was executed by the provider (true) or framework (false).
+   */
+  readonly providerExecuted?: boolean | undefined
 }
 
 /**
@@ -704,6 +713,7 @@ export const ToolResultPart: Schema.Struct<{
   readonly name: Schema.String
   readonly isFailure: Schema.Boolean
   readonly result: Schema.Unknown
+  readonly providerExecuted: Schema.withDecodingDefault<Schema.Boolean>
   readonly "~effect/ai/Prompt/Part": Schema.withDecodingDefaultKey<Schema.Literal<"~effect/ai/Prompt/Part">>
   readonly options: Schema.withDecodingDefault<
     Schema.$Record<
@@ -717,7 +727,8 @@ export const ToolResultPart: Schema.Struct<{
   id: Schema.String,
   name: Schema.String,
   isFailure: Schema.Boolean,
-  result: Schema.Unknown
+  result: Schema.Unknown,
+  providerExecuted: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false)))
 }).annotate({ identifier: "ToolResultPart" })
 
 /**
@@ -1420,7 +1431,8 @@ export const userMessage = (params: MessageConstructorParams<UserMessage>): User
  *         result: {
  *           temperature: 72,
  *           condition: "sunny"
- *         }
+ *         },
+ *         providerExecuted: true
  *       }),
  *       Prompt.makePart("text", {
  *         text: "The weather in San Francisco is currently 72°F and sunny."
@@ -1627,7 +1639,8 @@ export const assistantMessage = (params: MessageConstructorParams<AssistantMessa
  *           { title: "TypeScript Handbook", url: "https://..." },
  *           { title: "Effective TypeScript", url: "https://..." }
  *         ]
- *       }
+ *       },
+ *       providerExecuted: false
  *     })
  *   ]
  * })
@@ -2096,11 +2109,13 @@ export const fromResponseParts = (parts: ReadonlyArray<Response.AnyPart>): Promp
       // Tool Result Parts (skip preliminary results)
       case "tool-result": {
         if (part.preliminary !== true) {
-          toolParts.push(makePart("tool-result", {
+          const target = part.providerExecuted === true ? assistantParts : toolParts
+          target.push(makePart("tool-result", {
             id: part.id,
             name: part.name,
             isFailure: part.isFailure,
-            result: part.encodedResult
+            result: part.encodedResult,
+            providerExecuted: part.providerExecuted ?? false
           }))
         }
         break

package/src/unstable/cli/CliError.ts

@@ -115,7 +115,7 @@ export type CliError =
  * @category errors
  * @since 4.0.0
  */
-export class UnrecognizedOption extends Schema.TaggedErrorClass<UnrecognizedOption>(
+export class UnrecognizedOption extends Schema.TaggedError<UnrecognizedOption>(
   `${TypeId}/UnrecognizedOption`
 )("UnrecognizedOption", {
   option: Schema.String,
@@ -168,7 +168,7 @@ export class UnrecognizedOption extends Schema.TaggedErrorClass<UnrecognizedOpti
  * @category errors
  * @since 4.0.0
  */
-export class DuplicateOption extends Schema.TaggedErrorClass<DuplicateOption>(
+export class DuplicateOption extends Schema.TaggedError<DuplicateOption>(
   `${TypeId}/DuplicateOption`
 )("DuplicateOption", {
   option: Schema.String,
@@ -225,7 +225,7 @@ export class DuplicateOption extends Schema.TaggedErrorClass<DuplicateOption>(
  * @category errors
  * @since 4.0.0
  */
-export class MissingOption extends Schema.TaggedErrorClass<MissingOption>(
+export class MissingOption extends Schema.TaggedError<MissingOption>(
   `${TypeId}/MissingOption`
 )("MissingOption", {
   option: Schema.String
@@ -278,7 +278,7 @@ export class MissingOption extends Schema.TaggedErrorClass<MissingOption>(
  * @category errors
  * @since 4.0.0
  */
-export class MissingArgument extends Schema.TaggedErrorClass<MissingArgument>(
+export class MissingArgument extends Schema.TaggedError<MissingArgument>(
   `${TypeId}/MissingArgument`
 )("MissingArgument", {
   argument: Schema.String
@@ -319,7 +319,7 @@ export class MissingArgument extends Schema.TaggedErrorClass<MissingArgument>(
  * @category errors
  * @since 4.0.0
  */
-export class UnexpectedArgument extends Schema.TaggedErrorClass<UnexpectedArgument>(
+export class UnexpectedArgument extends Schema.TaggedError<UnexpectedArgument>(
   `${TypeId}/UnexpectedArgument`
 )("UnexpectedArgument", {
   arguments: Schema.Array(Schema.String)
@@ -376,7 +376,7 @@ export class UnexpectedArgument extends Schema.TaggedErrorClass<UnexpectedArgume
  * @category errors
  * @since 4.0.0
  */
-export class InvalidValue extends Schema.TaggedErrorClass<InvalidValue>(
+export class InvalidValue extends Schema.TaggedError<InvalidValue>(
   `${TypeId}/InvalidValue`
 )("InvalidValue", {
   option: Schema.String,
@@ -425,7 +425,7 @@ export class InvalidValue extends Schema.TaggedErrorClass<InvalidValue>(
  *   suggestions: ["deploy", "destroy"]
  * })
  *
- * unknownSubcommandError._tag // => "UnknownSubcomand"
+ * unknownSubcommandError._tag // => "UnknownSubcommand"
  * unknownSubcommandError.subcommand // => "deplyo"
  * unknownSubcommandError.parent // => ["myapp"]
  *
@@ -440,15 +440,15 @@ export class InvalidValue extends Schema.TaggedErrorClass<InvalidValue>(
  *   })
  *
  * const parseError = await Effect.runPromise(Effect.flip(parseSubcommand("deplyo")))
- * parseError._tag // => "UnknownSubcomand"
+ * parseError._tag // => "UnknownSubcommand"
  * ```
  *
  * @category errors
  * @since 4.0.0
  */
-export class UnknownSubcommand extends Schema.TaggedErrorClass<UnknownSubcommand>(
+export class UnknownSubcommand extends Schema.TaggedError<UnknownSubcommand>(
   `${TypeId}/UnknownSubcommand`
-)("UnknownSubcomand", {
+)("UnknownSubcommand", {
   subcommand: Schema.String,
   parent: Schema.optional(Schema.Array(Schema.String)),
   suggestions: Schema.Array(Schema.String)
@@ -513,7 +513,7 @@ export class UnknownSubcommand extends Schema.TaggedErrorClass<UnknownSubcommand
  * @category errors
  * @since 4.0.0
  */
-export class UserError extends Schema.TaggedErrorClass<UserError>(
+export class UserError extends Schema.TaggedError<UserError>(
   `${TypeId}/UserError`
 )("UserError", {
   cause: Schema.Defect()
@@ -585,7 +585,7 @@ export type NonShowHelpErrors = typeof NonShowHelpErrors.Type
  * @category errors
  * @since 4.0.0
  */
-export class ShowHelp extends Schema.TaggedErrorClass<ShowHelp>(
+export class ShowHelp extends Schema.TaggedError<ShowHelp>(
   `${TypeId}/ShowHelp`
 )("ShowHelp", {
   commandPath: Schema.Array(Schema.String),

package/src/unstable/cli/Command.ts

@@ -165,11 +165,11 @@ export interface Command<in out Name extends string, in Input, out ContextInput
   readonly annotations: Context.Context<never>
 
   /**
-   * Whether this command is hidden from parent help output, shell
-   * completions, and unknown-subcommand suggestions. Hidden commands still
+   * Whether this command is omitted from parent help output, shell
+   * completions, and unknown-subcommand suggestions. Unlisted commands still
    * parse and execute normally when invoked by exact name.
    */
-  readonly hidden: boolean
+  readonly unlisted: boolean
 }
 
 /**
@@ -352,7 +352,7 @@ export declare namespace Command {
       readonly commands: NonEmptyReadonlyArray<Command.Any>
     }>
     readonly annotations: Context.Context<never>
-    readonly hidden: boolean
+    readonly unlisted: boolean
   }
 
   /**
@@ -1430,6 +1430,7 @@ export const withSubcommands: {
     description: impl.description,
     shortDescription: impl.shortDescription,
     alias: impl.alias,
+    unlisted: impl.unlisted,
     annotations: impl.annotations,
     globalFlags: impl.globalFlags,
     examples: impl.examples,
@@ -1548,6 +1549,7 @@ export const withSharedFlags: {
       description: impl.description,
       shortDescription: impl.shortDescription,
       alias: impl.alias,
+      unlisted: impl.unlisted,
       annotations: impl.annotations,
       globalFlags: impl.globalFlags,
       examples: impl.examples,
@@ -1886,7 +1888,7 @@ export const withAlias: {
 ) => makeCommand({ ...toImpl(self), alias }))
 
 /**
- * Hides a subcommand from parent help output, shell completions, and
+ * Omits a subcommand from parent help output, shell completions, and
  * "did you mean?" suggestions while keeping it fully invocable by exact name.
  *
  * **When to use**
@@ -1894,7 +1896,7 @@ export const withAlias: {
  * Use when experimental or internal subcommands should be accepted but not advertised on
  * the public CLI surface.
  *
- * **Example** (Hiding a subcommand)
+ * **Example** (Unlisting a subcommand)
  *
  * ```ts import.meta.vitest
  * import { Command } from "effect/unstable/cli"
@@ -1902,23 +1904,23 @@ export const withAlias: {
  * // `experimental` still runs when invoked as `mycli experimental`,
  * // but it does not appear under SUBCOMMANDS in `mycli --help`.
  * const experimental = Command.make("experimental").pipe(
- *   Command.withHidden
+ *   Command.unlisted
  * )
  *
  * const root = Command.make("mycli").pipe(
  *   Command.withSubcommands([experimental])
  * )
  *
- * root.subcommands[0].commands[0].hidden // => true
+ * root.subcommands[0].commands[0].unlisted // => true
  * ```
  *
  * @category combinators
  * @since 4.0.0
  */
-export const withHidden = <const Name extends string, Input, E, R, ContextInput>(
+export const unlisted = <const Name extends string, Input, E, R, ContextInput>(
   self: Command<Name, Input, ContextInput, E, R>
 ): Command<Name, Input, ContextInput, E, R> =>
-  makeCommand({ ...toImpl(self), hidden: true }) as Command<Name, Input, ContextInput, E, R>
+  makeCommand({ ...toImpl(self), unlisted: true }) as Command<Name, Input, ContextInput, E, R>
 
 /**
  * Adds a custom annotation to a command.