fix(stella-tools): name real forge inputs in gh redirects

[cursor]

What & why

Bugbot reviewed #6545 once and left two medium findings in forge_redirect. Both are fixed here.

gh pr ready was refused with action update with draft, which is not an enum value on pull_request and reads as draft: true. Ready is action update with draft: false. gh pr merge now names action merge and confirm: true as its own field. gh pr checks points at watch_ci with branch set to the pull request's head. That tool has no action.

A wrapper flag that takes a value (sudo -u user, nice -n 10, env -u FOO) was treated as a command word, so the gh after it was not redirected. The parse now consumes that value for the wrapper flags that take one. sudo -n echo gh stays open, because -n on sudo takes no value and echo is the command.

The low finding, an empty body signed twice, is residue in #6553.

Refs #6545
Refs #6553

The witness

• This PR includes a witness test (fails on main, passes here), or
• No witness needed (pure refactor / docs / CI) — because:

every_redirect_names_a_real_tool_input reads the action between backticks and requires it to be in the tool schema's enum. On main the ready refusal puts update with draft in those backticks, which is not an enum value. a_wrapper_flag_value_does_not_hide_the_command requires sudo -u user gh pr create, nice -n 10 gh pr merge, and env -u FOO gh issue comment to redirect. On main is_command_position stops on the flag's value and returns None.

cargo test -p stella-tools --lib forge::redirect — 12 passed.

The gate

• cargo fmt --check (formatted with cargo fmt -p stella-tools)
• cargo clippy -p stella-tools --lib -- -D warnings passed
• cargo test -p stella-tools --lib forge::redirect passed
• Docs updated where behavior/flags changed (the refusal text is the documentation the model reads)
• CLA signed (the bot prompts on your first PR — nothing to do per commit)
• Refs #6545 appears above and as a commit trailer. This PR does not close that issue; it is already merged.

Fix over file

• Extra fixes in this PR: none beyond the two medium review findings — or none
• Filed, with the reason a fix could not ride this PR: the empty-body footer is Signing an empty body twice stacks two footers (residue #6545) #6553. It is a low finding on merged code, outside the two review findings this PR fixes. The docs deploy failure on 331543e is the same ssm:SendCommand AccessDeniedException for gha-deploy-stella that failed the previous main push (run 35527940671). The role policy is outside this repository, so this PR does not change .github/workflows/docs.yml.

Ground-rule check

• No I/O added to stella-core; no new deps without justification below
• No new outbound network calls (Stella never phones home)

Anything reviewers should know?

Bugbot and Sourcery each reviewed #6545 once, so the medium findings are fixed here rather than filed. command -v gh is now left open: -v takes the name and does not run it.

docs guards and main is not known-broken fail on main's account (#6548). #6550 registers SCR-006 in the document manifest and #6552 rewrites its prose. This branch merges main again once they land.

  

Summary by Sourcery

Ensure forge redirects both detect wrapped gh invocations reliably and provide schema-accurate retry instructions.

Bug Fixes:

• Correct forge redirect guidance so refused GitHub CLI commands reference valid tool inputs, including draft, confirmation, and branch parameters.
• Prevent wrapper flags that consume values from hiding executable gh commands from redirect enforcement.

Enhancements:

• Refine command-position parsing for shell assignments, wrappers, flag clusters, and wrapper-specific options while preserving non-executing cases such as command -v gh.
• Distinguish signing write tools from read-only CI monitoring in redirect messages.

Documentation:

• Update refusal guidance to match the schemas and inputs agents should use when retrying redirected commands.

Tests:

• Add regression coverage for wrapper flag values, clustered options, non-executing command forms, and schema-valid redirect guidance.

---

Note

Medium Risk
Changes bash-layer enforcement of which gh invocations are blocked and the guidance agents get on retry; incorrect parsing could either block benign commands or miss wrapped gh writes.

Overview
Fixes forge gh redirects so refusal text matches real tool schemas and wrapped shell spellings cannot skip signing.

Refusal copy now goes through a refusal() helper: each redirect uses a call snippet (e.g. action update plus draft: false for gh pr ready, confirm: true for merge, branch for gh pr checks → watch_ci) and only mentions signing for write tools.

Command-position detection is rewritten to parse forward from the last separator, consuming wrapper flags and their values per wrapper (sudo -u, nice -n, env -u, clusters like -Eu, GNU env -S). That closes the hole where sudo -u user gh … was treated like echo gh … and allowed unsigned forge writes; command -v gh and sudo -n echo gh stay allowed.

Tests add witness coverage that every redirect names a schema-valid action/input and that value-taking wrapper flags still trigger redirects.

^{Reviewed by Cursor Bugbot for commit 5c5fc38. Configure here.}

[sourcery-ai]

Reviewer's Guide

Updates forge_redirect to emit schema-valid tool instructions for GitHub CLI redirects and rewrites command-position detection to recognize real gh invocations behind wrapper flags without misclassifying flag values or non-executing commands.

Flow diagram for schema-valid gh redirect generation

flowchart LR
    Command["gh subcommand"] --> Match["forge_redirect matches verb"]
    Match --> Refusal["refusal uses Redirect.call"]
    Refusal --> Schema["Schema-valid tool input"]
    Schema --> PullRequest["pull_request: action plus draft or confirm"]
    Schema --> WatchCI["watch_ci: branch, no action"]

Loading

Flow diagram for wrapper-aware gh command detection

flowchart TD
    Input["Shell command prefix"] --> Separator["Scan after last separator"]
    Separator --> Assignment["Consume assignments"]
    Assignment --> Wrapper["Recognize wrapper"]
    Wrapper --> Flags["Consume wrapper flags"]
    Flags --> Value{"Flag takes a separate value?"}
    Value -->|Yes| Consume["Consume value"]
    Value -->|No| Next["Continue parsing"]
    Consume --> Next
    Next --> Gh["gh is command position"]
    Next --> NonExec["Non-executing form stays open"]

Loading

File-Level Changes

Change	Details	Files
Correct redirect guidance so each refused GitHub CLI command maps to valid tool-schema inputs.	Replace the overloaded action text with structured call guidance for draft, confirm, and branch fields. Mark read-only watch_ci redirects as unsigned while retaining signing guidance for write tools. Add schema-aware tests covering action enums and special-case fields.	crates/stella-tools/src/forge/redirect.rs
Improve command-position parsing through wrapper flags that consume separate or inline values.	Parse wrapper chains from the command separator, including assignments and --. Consume value-taking flags according to the specific wrapper, including sudo, nice, env, command, exec, and time. Preserve open-command behavior for no-value flags and commands such as sudo -n echo and command -v gh. Add coverage for separated, inline, repeated, and wrapper-specific flag forms.	crates/stella-tools/src/forge/redirect.rs

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_7e697e1c-8954-4a7c-a148-0c991ea4b5a5)

[macanderson]

Adversarial review round 1: env -S regresses a refused spelling, and bundled sudo flags still hide the command.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

[sourcery-ai]

Sorry @macanderson, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 4 days and 20 hours by commenting @sourcery-ai review. Upgrade to get a review now.

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_bd972ff3-218b-4491-ad92-210596880546)

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
🔒 Security Review	✅ Completed 2026-09-23T03:23:28.586460Z	5c5fc38	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.