When a tool gains a flag the generated package doesn't model, the only escape hatch is CommandLineToolOptions.Arguments, whose entire documentation is "Gets used for providing switches and arguments to the tool" — it says nothing about placement, which is actually "after the subcommand and after all generated options and pass-through positionals" (and, per the separate ordering bug, after -- when a PrependOptionTerminator operand is set). There is no way to inject an argument before the subcommand (global-option position) or between the subcommand and generated options, and the generated records are not partial, so extension means subclassing — a pattern documented nowhere (docs/how-to/custom-commands.md only covers GenericCommandLineToolOptions from scratch).
For v4: either add first-class escape hatches with phase control (e.g. AdditionalArguments accepting a CommandLinePhase, mirroring the internal phase model) or document the subclass-with-attributes pattern plus precise Arguments placement semantics on the property doc-comment and in the how-to guide.
Evidence: src/ModularPipelines/Options/CommandLineToolOptions.cs:22-25, src/ModularPipelines/Context/CommandLineBuilder.cs:59-93, docs/docs/how-to/custom-commands.md:14-23
Raised by the v4 scoping audit round 3 — umbrella #3239.
When a tool gains a flag the generated package doesn't model, the only escape hatch is
CommandLineToolOptions.Arguments, whose entire documentation is "Gets used for providing switches and arguments to the tool" — it says nothing about placement, which is actually "after the subcommand and after all generated options and pass-through positionals" (and, per the separate ordering bug, after--when a PrependOptionTerminator operand is set). There is no way to inject an argument before the subcommand (global-option position) or between the subcommand and generated options, and the generated records are notpartial, so extension means subclassing — a pattern documented nowhere (docs/how-to/custom-commands.mdonly coversGenericCommandLineToolOptionsfrom scratch).For v4: either add first-class escape hatches with phase control (e.g.
AdditionalArgumentsaccepting aCommandLinePhase, mirroring the internal phase model) or document the subclass-with-attributes pattern plus preciseArgumentsplacement semantics on the property doc-comment and in the how-to guide.Evidence:
src/ModularPipelines/Options/CommandLineToolOptions.cs:22-25,src/ModularPipelines/Context/CommandLineBuilder.cs:59-93,docs/docs/how-to/custom-commands.md:14-23Raised by the v4 scoping audit round 3 — umbrella #3239.