Summary

Once cli/azd/extensions/azure.ai.agents/go.mod is bumped past the version that includes #7312 (currently pinned to github.com/azure/azure-dev/cli/azd v1.23.14), azd ai agent ... fails to start because the extension declares flags that collide with azd's reserved global flag registry:

ERROR: extension defines flags that conflict with reserved azd global flags:
  - command "":               --debug, --no-prompt
  - command "init":           --environment
  - command "show":           --output/-o
  - command "files list":     --output
  - command "files stat":     --output/-o
  - command "sessions create|list|show": --output/-o
Reserved flags: environment, cwd, debug, no-prompt, output, help, docs, trace-log-file, trace-log-url

Root cause

The extension builds its root with a bare cobra.Command{} and manually wires --debug / --no-prompt, instead of using azdext.NewExtensionRootCommand() which already provides every SDK-managed global plus an *ExtensionContext (OutputFormat, Environment, Debug, NoPrompt, Cwd). Several subcommands then redundantly redeclare --output/-o, and init declares its own --environment (which the host pre-parser would hijack anyway).

Proposed changes (extension only)

1. Switch internal/cmd/root.go to azdext.NewExtensionRootCommand(); drop the manual --debug/--no-prompt registrations and the AZD_NO_PROMPT fallback in PersistentPreRunE (the SDK handles both). Thread the returned *ExtensionContext to subcommands.
2. Remove the per-subcommand --output/-o registrations in show.go:101, files.go:452 (files list), files.go:754 (files stat), and sessions*.go (create|list|show). Read extCtx.OutputFormat instead. The accepted values (json, table) are already standard azd Format constants from cli/azd/pkg/output/formatter.go. Preserve current per-command default-format behavior by mapping the SDK default "default" → "json" per command, and consider rejecting unknown values explicitly (today they silently fall through to JSON).
3. Rename or remove init --environment (init.go:518) — either rename to --env-name/--target-env, or drop it and use extCtx.Environment.
4. Update tests in files_test.go, show_test.go, session_test.go that read --output from cobra flags to read from extCtx.OutputFormat.
5. Bump go.mod to the post-Add reserved global flags registry for extensions #7312 cli/azd version once the above is done.

Validation

cd cli/azd/extensions/azure.ai.agents
go build ./... && go test ./...
azd x build
azd ai agent --help
azd ai agent show -o json
azd ai agent files list

Related

• Add reserved global flags registry for extensions #7312 — reserved global flags registry
• Fix env var leak when running extension commands with -e flag #7035 / azd <extension> -e <env> leaks default environment variables into extension process #7034 — extension flag-parsing fixes
• cli/azd/docs/extensions/extensions-style-guide.md
• cli/azd/docs/design/extension-flag-architecture.md

Out of scope

• Changing the reserved-flag set itself. Keeping --output reserved is intentional — the SDK already provides it at the extension root.
• Other first-party extensions (file separately if affected).