introspect: list second-level subcommands in wraptool_discover #51

New issue

Closed

opened 2026-10-08 10:46:58 +02:00 by pti · 0 comments

pti commented

2026-10-08 10:46:58 +02:00

Owner

wraptool_discover lists only a tool's top-level commands, so an agent cannot see second-level ones like fj issue search or fj issue view, and has to guess them when filing a capability request.

Current behaviour

internal/introspect/introspect.go builds Schema.Available from the tool's top-level help only (-h / --help / help, a fixed argv). For fj that yields issue, pr, repo and so on, all with empty descriptions, although fj -h and fj issue -h print descriptions. On 2026-10-08 the subcommand names for three fj issue capability requests had to come from memory and were only confirmed when the operator ran fj issue -h by hand.

Proposal

Go one level deeper: for a top-level command that is itself a command group, run <tool> <command> -h and add its entries to the catalog as command subcommand, cached like the rest of the schema.

The design question

Today wraptool only runs help for the top level and for operator-approved subcommands. Going deeper runs <tool> <command> -h for commands nobody approved (fj auth -h, fj repo -h). Well-behaved CLIs treat -h as help, but a tool that does not could execute the command. Options:

opt-in per tool, along the lines of the existing per-tool catalog argv (git help -a)
only names from the parsed top-level catalog, validated for shape, with a cap on how many get explored
on demand: wraptool_discover takes an optional command to drill into, checked against the catalog

Also

Find out why the descriptions in fj's top-level help are lost (parser format mismatch).

Done when

The design question is settled in a note under design/introspect/, and wraptool_discover reports second-level subcommands for at least fj, with tests on captured fj -h / fj issue -h output in testdata/.

🤖 Generated with Claude Code

`wraptool_discover` lists only a tool's top-level commands, so an agent cannot see second-level ones like `fj issue search` or `fj issue view`, and has to guess them when filing a capability request. ## Current behaviour `internal/introspect/introspect.go` builds `Schema.Available` from the tool's top-level help only (`-h` / `--help` / `help`, a fixed argv). For `fj` that yields `issue`, `pr`, `repo` and so on, all with empty descriptions, although `fj -h` and `fj issue -h` print descriptions. On 2026-10-08 the subcommand names for three `fj issue` capability requests had to come from memory and were only confirmed when the operator ran `fj issue -h` by hand. ## Proposal Go one level deeper: for a top-level command that is itself a command group, run `<tool> <command> -h` and add its entries to the catalog as `command subcommand`, cached like the rest of the schema. ## The design question Today wraptool only runs help for the top level and for operator-approved subcommands. Going deeper runs `<tool> <command> -h` for commands nobody approved (`fj auth -h`, `fj repo -h`). Well-behaved CLIs treat `-h` as help, but a tool that does not could execute the command. Options: - opt-in per tool, along the lines of the existing per-tool catalog argv (`git help -a`) - only names from the parsed top-level catalog, validated for shape, with a cap on how many get explored - on demand: `wraptool_discover` takes an optional command to drill into, checked against the catalog ## Also Find out why the descriptions in `fj`'s top-level help are lost (parser format mismatch). ## Done when The design question is settled in a note under `design/introspect/`, and `wraptool_discover` reports second-level subcommands for at least `fj`, with tests on captured `fj -h` / `fj issue -h` output in `testdata/`. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

pti referenced this issue from a commit

2026-10-19 22:09:33 +02:00

feat(introspect): opt-in second-level subcommand discovery for wraptool_discover

pti referenced this issue from a pull request that will close it,

2026-10-19 22:09:55 +02:00

feat/introspect: opt-in second-level subcommand discovery for wraptool_discover #89

pti closed this issue

2026-10-19 22:10:51 +02:00