agent-helpers: expose upstream-pr-prep as a safe-agent-action subcommand

Problem: invoking agent-helpers/upstream-pr-prep.sh directly does not
match the PreToolUse auto-approval hook's regex (which matches only
'safe-agent-action.sh'), so every call prompted the operator for
permission.

Fix: add an 'upstream-pr-prep' case to the wrapper that execs the
helper script with all args passed through. The agent-facing invocation
is now:

  agent-helpers/safe-agent-action.sh upstream-pr-prep --commit X ...

which the auto-approval hook matches on 'safe-agent-action.sh' in the
command string. The wrapper's exec replaces the shell process with the
helper script, so all internal git/make subprocesses run inside the
single Bash tool call — no further prompts.

The helper script at agent-helpers/upstream-pr-prep.sh is unchanged
and still directly executable (operators debugging it will see a
one-time prompt per invocation, which is acceptable for debugging).

Also updates the wrapper's 'help' text and agents.md to document the
new subcommand as the canonical invocation path.

Author: igor

agent-helpers/safe-agent-action.sh

@@ -336,6 +336,25 @@ EOF
         exit 2
         ;;
 
+    # ====================================================================
+    # Upstream PR prep (wrapper dispatch to upstream-pr-prep.sh)
+    # ====================================================================
+    #
+    # Why this exists as a subcommand: the auto-approval PreToolUse hook
+    # matches 'safe-agent-action.sh' in the command string. If the agent
+    # calls upstream-pr-prep.sh directly, the hook doesn't match and the
+    # agent gets prompted on every invocation. Dispatching through this
+    # subcommand means the agent-facing invocation is
+    # 'safe-agent-action.sh upstream-pr-prep ...' which the hook approves
+    # automatically. The helper script itself stays intact and directly
+    # executable for operator debugging.
+
+    upstream-pr-prep)
+        # PURPOSE: Repeatable upstream LinuxCNC PR prep via cherry-pick.
+        # See agent-helpers/upstream-pr-prep.sh --help for full usage.
+        exec "$SCRIPT_DIR/upstream-pr-prep.sh" "$@"
+        ;;
+
     # ====================================================================
     # Process inspection (read-only)
     # ====================================================================
@@ -557,6 +576,15 @@ Branch-per-session workflow:
   session-push          Push current branch to origin. Refuses on main/master.
   session-merge <name>  Prints the merge sequence (does NOT execute).
 
+Upstream PR prep:
+  upstream-pr-prep <args>...
+                        Dispatch to agent-helpers/upstream-pr-prep.sh.
+                        Cherry-picks a fork commit onto a clean branch
+                        based on upstream/master via git worktree, with
+                        dynamic gh-api-user author and strict diff
+                        verification. Mode flags: --build --push --cleanup
+                        --dry-run. Run with --help for full usage.
+
 Process inspection (read-only):
   ps [pattern]          ps aux, optionally filtered
   pgrep <pattern>       pgrep -af

agents.md

@@ -204,18 +204,25 @@ cd src && ./configure --with-realtime=uspace && make clean && make -j$(nproc) &&
 ## Upstream PR prep
 
 When a fix exists on fork `master` and needs to go upstream as a PR
-against `LinuxCNC/linuxcnc`, use the helper script — not raw cherry-pick
-commands:
+against `LinuxCNC/linuxcnc`, use the helper via the wrapper subcommand —
+not raw cherry-pick commands, and not the helper script directly (the
+latter bypasses the PreToolUse auto-approval hook and prompts per call):
 
 ```bash
-agent-helpers/upstream-pr-prep.sh \
+agent-helpers/safe-agent-action.sh upstream-pr-prep \
     --commit <fork-sha> \
     --branch <pr-branch-name> \
     --message /tmp/upstream-commit-msg.txt \
     --worktree /var/tmp/linuxcnc-pr-<branch> \
     [--build] [--push] [--cleanup] [--dry-run]
 ```
 
+The wrapper's `upstream-pr-prep` subcommand is a thin `exec` dispatch to
+`agent-helpers/upstream-pr-prep.sh` — the script stays intact and
+directly executable for operator debugging, but the agent-facing
+invocation should always go through the wrapper so the auto-approval
+hook covers it.
+
 Default (no mode flag) runs prep: `git fetch upstream`, `git worktree add`
 off `upstream/master`, `git cherry-pick --no-commit`, strict diff
 verification, commit with dynamically-resolved GitHub-noreply author