fix: create_pull_request branch guidance, PR-comment tool selection, and shallow clone fallback

actions/setup/js/create_pull_request.cjs

@@ -895,6 +895,16 @@ gh pr create --title '${title}' --base ${baseBranch} --head ${branchName} --repo
             } else {
               core.info(`Original base commit from patch generation: ${originalBaseCommit}`);
 
+              // In shallow clones (fetch-depth: 1) the base commit may not be locally available.
+              // Attempt to fetch it explicitly before checking whether it exists.
+              try {
+                await exec.exec("git", ["fetch", "origin", originalBaseCommit, "--depth=1"]);
+              } catch (fetchError) {
+                // Non-fatal: the commit may already be available, or the server may not support
+                // fetching individual SHAs (e.g. some GHE configurations). Log for troubleshooting.
+                core.info(`Note: could not fetch base commit ${originalBaseCommit} explicitly (${fetchError instanceof Error ? fetchError.message : String(fetchError)}); will verify local availability next`);
+              }
+
               // Verify the base commit is available in this repo (may not exist cross-repo)
               await exec.exec("git", ["cat-file", "-e", originalBaseCommit]);
               core.info("Original base commit exists locally - proceeding with fallback");

actions/setup/md/pr_context_push_to_pr_branch_guidance.md

@@ -0,0 +1,4 @@
+
+<pr-comment-tool-guidance>
+When triggered by a pull request comment, if you need to push code changes, prefer using `push_to_pull_request_branch` to add commits to the existing pull request branch rather than `create_pull_request` which opens a separate new pull request. Only use `create_pull_request` if the instructions explicitly ask you to create a new, separate pull request.
+</pr-comment-tool-guidance>

actions/setup/md/safe_outputs_create_pull_request.md

@@ -3,7 +3,9 @@
 
 To create a pull request:
 1. Make any file changes directly in the working directory.
-2. If you haven't done so already, create a local branch using an appropriate unique name.
+2. If you haven't done so already, create a new local branch using `git checkout -b <branch-name>` with an appropriate unique name.
 3. Add and commit your changes to the branch. Be careful to add exactly the files you intend, and check there are no extra files left un-added. Verify you haven't deleted or changed any files you didn't intend to.
 4. Do not push your changes. That will be done by the tool.
 5. Create the pull request with the create_pull_request tool from safeoutputs.
+
+**Important**: The `branch` parameter in the create_pull_request tool **must exactly match the name of your current local git branch** — the branch you just committed to. You can verify this with `git branch --show-current`. Never invent or guess a branch name; always use the actual branch name from `git branch --show-current`. If you are on an existing branch (e.g. you checked out a PR branch), use that branch name.

pkg/workflow/prompt_constants.go

@@ -10,6 +10,7 @@ import (
 const (
 	promptsDir                              = constants.GhAwRootDirShell + "/prompts"
 	prContextPromptFile                     = "pr_context_prompt.md"
+	prContextPushToPRBranchGuidanceFile     = "pr_context_push_to_pr_branch_guidance.md"
 	tempFolderPromptFile                    = "temp_folder_prompt.md"
 	playwrightPromptFile                    = "playwright_prompt.md"
 	qmdPromptFile                           = "qmd_prompt.md"

pkg/workflow/unified_prompt_step.go

@@ -272,6 +272,18 @@ func (c *Compiler) collectPromptSections(data *WorkflowData) []PromptSection {
 			ShellCondition: shellCondition,
 			EnvVars:        envVars,
 		})
+
+		// When push_to_pull_request_branch is configured, add guidance to prefer it over
+		// create_pull_request when the workflow was triggered by a PR comment.
+		if data.SafeOutputs != nil && data.SafeOutputs.PushToPullRequestBranch != nil {
+			unifiedPromptLog.Print("Adding push-to-PR-branch tool preference guidance for PR comment context")
+			sections = append(sections, PromptSection{
+				Content:        prContextPushToPRBranchGuidanceFile,
+				IsFile:         true,
+				ShellCondition: shellCondition,
+				EnvVars:        envVars,
+			})
+		}
 	}
 
 	return sections