A wrapped command can declare a subcommand group - #433
Merged
Conversation
wrapped.rs:381's Verb had name, lead, flags, positionals, tail, and stdin but no children, so a two-level grammar was undeclarable: git worktree list could only be one flat verb string, and every subcommand-group program (docker, kubectl, git itself) was out of reach for the allowlist that is 0.17.0's headline feature. Verb gains a recursive verbs: Vec<Verb> and a .verb() builder mirroring WrappedCommand::verb(). A verb with children is a node: it selects among them and is never itself callable. Calling one bare (git worktree) now refuses at plan_call, exit 2, naming its own children before anything spawns. An unknown or missing leaf under a node names that node's own children, never the top level's or a sibling node's — the property nesting exists to give an agent, since a leaked top-level set would actively misdirect the next attempt. Call.verb_index: Option<usize> — a flat index into declaration.verbs — became Call.verb_path: Vec<usize>, a chain of indices walked one level at a time (empty selects the root). select_verb's return type grew to match; a new descend() helper keeps consuming words for as long as the matched verb has children, reusing the exact opaque-word and dash-prefix handling select_verb already had at the top level, so the same "the parser describes nothing" rule now applies at every depth rather than just the first word. scope_of_path() replaces scope_of() everywhere a Call's resolved verb needs a label, so an error or a spawn label reads "git worktree list", not "git list". lead concatenates down the path in path order (verb_chain() in render.rs walks the whole chain, not just the leaf); flags, positionals, tail, and stdin stay leaf-only, refused at build() on a node with the property and the fix named. The root verb may not declare children either — nesting under root would make a path index ambiguous between declaration.verbs and root.verbs, so it is refused rather than half-supported. verb_schema() and every_verb_is_json() both walk to leaves now, so a node's schema carries its own children as nested ToolSchemas and typed substitution still turns on only when every leaf a tool can run declares json_output(). Every existing wrapped-command test still passes unmodified: 75 in tools/wrapped/tests.rs, 94 in wrapped_command_parse_tests.rs, 32 in wrapped_command_exec_tests.rs. New coverage adds a git-worktree fixture with a sibling top-level verb (so a node-scoped refusal has a real name to leak, if it still could), a three-level fixture, six build()-time refusal tests for the node restrictions, two schema- recursion tests, and two end-to-end exec tests spawning a real child through a nested path. docs/wrapped_command.md gains a "Nested verbs" section between the cargo and TOML examples, with the git-worktree declaration and its three refusals quoted verbatim from the new tests, plus updates to the Parsing, Rendering, build()-refusal, and Testing sections.
tobert
force-pushed
the
feat/wrapped-nested-verbs
branch
from
September 2, 2026 12:38
2754f44 to
7ded300
Compare
Merged
tobert
added a commit
that referenced
this pull request
Sep 2, 2026
Version bump and changelog stamp for v0.17.1, a patch release covering six PRs merged since v0.17.0: help/kaish-tools nested-subcommand recursion (#430), the wrapped-command allow_external_commands framing correction (#431), a changelog correction plus a new zero-padded date/time migration note (#432), nested verb groups for wrapped commands (#433), mount-point ancestor navigation when a backend also covers `/` (#435), and VfsRouter-shared path canonicalization closing a containment leak in `readlink -f`/`realpath` (#434). This bump also carries two documentation fixes surfaced by the release-gate review below rather than opening a separate PR for text-only changes: `docs/EMBEDDING.md` claimed `realpath` passes `allow_missing_final: true` and rechecks existence, when it actually passes `false` directly; and the canonicalize changelog entry overstated the default implementation as containment-checked, when containment is a property of `LocalFs`'s and `VfsRouter`'s overrides, not the shared default. Reviewed with kaibo (`consult`, cast `deepseek`) against the full `v0.17.0..HEAD` diff. Verdict: no undocumented semver breaks — the two new `canonicalize` trait methods are defaulted and every changed public type is either `#[non_exhaustive]` or privately fielded, so the patch framing holds. Two smaller findings from that review are real but scoped as code changes rather than release-blocking text, so they're queued as follow-up work rather than folded into this bump: a wrapped-command node can silently accept a no-op `json_output` declaration instead of being refused, and the new `canonicalize` default's symlink-hop cap has thin test coverage. Gates: `cargo test --all` (2231 passed), `cargo clippy --all --all-targets -- -D warnings` (clean), `cargo insta test --check` (no pending snapshots).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
git worktree listwas undeclarable.Verbcarried flags and positionals but no child verbs, so a wrapped command could declareworktreeand neverlistunder it. A subcommand group is the ordinary shape of a real program —docker,kubectl,gh, and git itself — and wrapped commands are 0.17.0's headline feature.Verb::verb()declares a child, the same builder the top level uses:A verb with children is a node. A node selects among its children and never runs itself:
The allowed set in a node-scoped refusal names that node's own children, never the top level's. That is the property nesting exists to give an agent: the next word to try is drawn from the set it actually chose into. A test asserts the top-level verbs are absent from a node-scoped message, which is the assertion that discriminates.
leadandomit_nameare meaningful at every level and concatenate down the path.flags,positionals,tail, andstdinbelong to the leaf that runs, and a node declaring one is refused atbuild()rather than ignored. A flag on a node is ambiguous against its leaves' flags; the restriction can relax later, but a wrong binding cannot be un-shipped. The root verb may not take children either — it is the nameless verb, so it would have no word to select with.Call.verb_indexbecame a path. All 201 existing wrapped-command tests pass unmodified.Gates:
clippy -D warnings,cargo test --all(6533 passed, 0 failed),insta --check,no-default-features, rustdoc-D warnings.