internal/ghcmd/cmd.go — printError, fullHelp branch (~L306-L313)

Heads-up: I noticed this discrepancy while reviewing and asked Copilot to dig into the case, so @niik please sanity check this one more time before acting on it.

Repro (compare the two):

go run ./cmd/gh xyz
AI_AGENT=foo go run ./cmd/gh xyz

The difference: the first (human) prints the terse Usage: ... Available commands: ..., while the second (agent) prints WriteHelp's full grouped help instead, so the flat Available commands: block is gone rather than just having extra help added to it.

idea: In fullHelp mode we should append the terse usage so agents keep everything a human sees. Right now WriteHelp replaces cmd.UsageString(), so the flat Available commands: block (and the flag list on leaf commands) is dropped for agents on root-level misuse.

Verified behavior:

• gh zzqqxx (root unknown command) reaches printError. Human mode shows the terse Usage: ... Available commands: ...; agent mode shows WriteHelp's grouped rendering instead, so the literal Available commands: block is gone.
• gh pr zzqqxx (nested unknown subcommand) never reaches printError at all - it's handled earlier by nestedSuggestFunc, so it stays terse in both modes.

Heads-up on the "capture cmd.UsageString() first" idea: for real gh commands cmd.UsageString() returns an empty string and writes the usage to IOStreams.ErrOut as a side effect, because gh's SetUsageFunc (root.go:115) writes straight to the captured ErrOut and ignores the buffer Cobra swaps in. Empirically it returns len 0 and leaks ~946 bytes to ErrOut. So capturing it won't capture anything. Instead expose the terse renderer and call it directly.

I also checked the "WriteHelp mutates Cobra state that UsageString reads" theory - it does not; UsageString returns the same thing before and after WriteHelp. So no capture/reorder is needed; we can just append.

Suggested approach (spans two files, so not a single suggestion block):

In pkg/cmd/root/help.go, expose the terse renderer:

// WriteUsage renders the terse usage string for command to w. cmd.UsageString()
// cannot be used for this because gh sets a usage function that writes straight
// to IOStreams.ErrOut, so UsageString returns an empty string and leaks the
// usage onto ErrOut as a side effect.
func WriteUsage(w io.Writer, command *cobra.Command) error {
	return rootUsageFunc(w, command)
}

In internal/ghcmd/cmd.go, append it in the fullHelp branch:

if fullHelp {
	// Render into out rather than calling cmd.Help(), which would send
	// the help text to stdout and split a single failure across two streams.
	root.WriteHelp(out, cs, cmd)
	// Also append the terse usage so agents keep everything a human sees,
	// including the "Available commands" list that WriteHelp replaces with
	// its grouped rendering.
	fmt.Fprintln(out)
	_ = root.WriteUsage(out, cmd)
	fmt.Fprintln(out)
	return
}

Verified output for AI_AGENT=foo gh zzqqxx: full help, then Usage: gh <command> <subcommand> [flags] + Available commands: list appended at the end.

Note: this will change the expected output in the newly added Test_printError full-help cases, so those wantOut values need updating to include the appended usage.

Thanks for flagging this, and for the nudge to sanity check — I dug in properly and had the findings independently verified before acting.

Your mechanism is right on both counts. cmd.UsageString() does return "" for real gh commands: SetUsageFunc (root.go:115) writes straight to the captured ErrOut, so the usage text you see is a side effect and the fmt.Fprintln(out, cmd.UsageString()) contributes only a blank line. Confirmed on gh pr list --badFlag: 972 bytes to stderr, exactly one Usage: line and one --web line, terminated by a lone \n — if the string were actually being returned we'd see it twice. Worth noting the existing human path only works because out and ErrOut are the same stream.

And gh pr zzqqxx does bypass printError entirely, byte-identical in both modes, as you said.

Where I land differently is on the consequence, so let me show the numbers rather than just assert it. Comparing information content rather than the literal string, for gh zzqqxx:

• human: 36 bare command names (429 bytes)
• agent: the same 36 names, each with a description, plus group structure and the 8 help topics (2,837 bytes)

The set difference human-minus-agent is empty. The same holds on leaf commands, which I think is the part worth double-checking against the "(and the flag list on leaf commands) is dropped" note: for gh pr list --badFlag, agent mode contains all 14 flags the human sees, plus --help and --repo, plus the JSON fields and examples. Nothing is dropped in either case — the grouped rendering is a strict superset, not a replacement that loses something.

So appending the terse usage would reprint the same command names and flags in the less informative form: roughly +14% at root, and about +38% on gh pr create --badFlag where it would duplicate the entire FLAGS block. Given the token-cost pressure this epic is tracking, I'd rather not pay that for content already present.

One further reason to avoid WriteUsage specifically: calling rootUsageFunc directly would bypass the alias resolution added in 3a73af2, re-introducing the alias-stub problem for gh <alias> --badFlag that the other review thread caught.

That said, I think you're onto something real with the nested case. Because nestedSuggestFunc handles gh pr zzqqxx before printError, agents get the terse list and no full help there — which is arguably the more valuable gap, since that's a much more common agent mistake than root-level misuse. It's outside this PR's changed path, but I'd be happy to open a follow-up issue for it if you agree.

Happy to be overruled on the append if you still see a case I'm missing.

Thanks for looking deeper, @niik. I agree that this is so hacky already and touching it is a scope creep. Let's leave it as is for now.