azdext: extensions cannot customize per-command --output help text or metadata

[JeffreyCA]

Summary

The azd extension framework registers -o/--output as a single SDK-owned persistent flag on the root command (via azdext.NewExtensionRootCommand). This avoids flag collisions with azd's reserved global flags, but leaves a gap: extensions have no way to customize the supported values, default value, or help text of --output on a per-subcommand basis.

Gap

Different subcommands within the same extension typically support different output formats. For example, in azure.ai.agents:

• agent files list and sessions list support json and table (default json)
• agent version only emits json
• Most other commands don't produce structured output at all and just inherit the SDK default default

Because the persistent --output flag is shared across the entire command tree, all subcommands render the same generic help text:

-o, --output string   The output format (default "default")

…regardless of what the subcommand actually accepts, which is misleading to users running <cmd> --help and to consumers of the extension metadata JSON used for IntelliSense. There is also no SDK-side validation, completion, or per-command default for the flag.

Workarounds (redeclaring a local --output flag on each subcommand) collide with the inherited persistent flag and break once azd enforces its reserved-flag set.

Proposed approach

Add a new SDK helper that lets a subcommand declare its allowed values and default for any inherited persistent flag in one place:

azdext.RegisterFlagOptions(listCmd, "output", []string{"json", "table"}, "json")

A single declaration drives:

1. Help text rendered for that subcommand
2. Extension metadata (Flag.ValidValues, Flag.Default)
3. Parse-time validation (rejects unsupported values before RunE runs)
4. Shell completion for the flag on that subcommand
5. Default substitution into the bound ExtensionContext field

Generalizes to any inherited persistent flag via the flag-name argument; not hardcoded to --output.

Related

• azure.ai.agents: adopt NewExtensionRootCommand and remove reserved global flag conflicts #7796 (azure.ai.agents scope update — adopts this approach as part of migrating to NewExtensionRootCommand)