@senad-d/branchme 0.3.11 → 0.3.12

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.3.12 - Unreleased
+
+- Added `pull_request_files` (read-only: a PR's first 100 changed files with change type and line counts, plus its labels) and `label_pull_request` (adds 1 to 5 existing repository labels to a PR; GitHub would create an unknown label, so it is refused first). An agent can now choose and set a PR's area label from what it changes.
+- `pull_request_feedback` prints each comment's and review's URL, and review ids, so a follow-up issue can quote and link the exact comment.
+
 ## 0.3.11 - Unreleased
 
 - `land_branch` with `pullRequestNumber` accepts a local source branch that is the merged PR head or one of its ancestors: a branch left behind because the PR received commits pushed from another checkout (for example a merge of the base) holds nothing the PR lacks, and is retired. A local branch with commits the PR head does not contain is still refused, now with its own message and Blocked/Resolve guidance; a PR head that is not available locally counts as not containing it.

package/README.md

@@ -16,7 +16,7 @@
 
 ---
 
-BranchMe is a Pi extension for safe Git repository, branch, and worktree workflow automation. Before each agent run, it appends a bounded, read-only snapshot of the current Git repository to the system prompt. It also adds an informational `/branchme` command and twenty-three agent-callable tools that initialize a repository, refresh state, manage, integrate, and retire local branches, conclude a kept merge, inspect/create/remove linked worktrees, push the current branch, create GitHub pull requests, and read and answer PR feedback.
+BranchMe is a Pi extension for safe Git repository, branch, and worktree workflow automation. Before each agent run, it appends a bounded, read-only snapshot of the current Git repository to the system prompt. It also adds an informational `/branchme` command and twenty-five agent-callable tools that initialize a repository, refresh state, manage, integrate, and retire local branches, conclude a kept merge, inspect/create/remove linked worktrees, push the current branch, create GitHub pull requests, read and answer PR feedback, and list and label a PR's changed files.
 
 <table align="center">
   <tr>
@@ -257,6 +257,8 @@ Commands are informational only. BranchMe actions are performed by agent-callabl
 | `track_branch` | `{ "branchName": string, "remote"?: string, "remoteBranch"?: string }` | Fetch one exact remote branch and create/check out a new local tracking branch. Remote defaults to `origin`; remoteBranch defaults to branchName. Requires a clean idle checkout; verifies HEAD and upstream. |
 | `update_from_base` | `{ "baseBranch": string, "remote"?: string, "keepConflicts"?: boolean }` | Fetch the exact remote base (remote defaults to `origin`) and merge its captured commit into the clean current feature. Uses verified normal-merge policy; a `conflict` is automatically aborted with its paths listed, or with `keepConflicts: true` reported as `conflict_kept` and left in progress (MERGE_HEAD set, conflicted paths unmerged) for `conclude_merge`. Never rebases, pushes, or changes upstream configuration. |
 | `conclude_merge` | `{ "action": "conclude" \| "abort" }` | Finish or abandon the in-progress merge on the current checkout. `conclude` refuses default/custom-sized `<<<<<<<`, `|||||||`, `=======`, or `>>>>>>>` marker lines in unmerged working-tree paths and staged blobs (including CRLF and binary content, naming the paths), stages only the currently unmerged paths, rechecks the candidate index, commits with `git commit --no-edit`, and verifies MERGE_HEAD is gone and HEAD is a two-parent merge of the previous HEAD and MERGE_HEAD; unrelated unstaged changes stay unstaged. `abort` runs `git merge --abort` and verifies the restored HEAD, cleared operation state, and clean tree. Refuses when no merge is in progress. |
+| `pull_request_files` | `{ "number": integer }` | List a pull request's first 100 changed files (path, change type, additions, deletions; the rest counted) and its current labels. Read-only. |
+| `label_pull_request` | `{ "number": integer, "labels": string[] }` | Add 1 to 5 labels that already exist in the repository to a pull request; an unknown label is refused before anything changes, existing labels stay. |
 | `reply_pull_request_feedback` | `{ "number": integer, "body": string, "threadId"?: string, "resolve"?: boolean }` | Answer PR feedback on an open, merged or closed PR of this repository (forks included). With `threadId` (from `pull_request_feedback`) it replies in that review thread after verifying the thread belongs to the PR, and `resolve: true` then resolves it; without `threadId` it posts one conversation comment after confirming the number is a pull request, not an issue. Body is Markdown, at most 4,000 characters. Never edits, deletes, approves, merges, or closes. |
 | `pull_request_feedback` | `{ "number"?: integer, "headBranch"?: string }` | Read what a same-repository PR asks to be fixed in one GraphQL request: unresolved, current review threads with their comments (resolved and outdated threads are counted only), review summaries with a body or requested changes, the latest 50 conversation comments, and the head commit's failing checks with up to 20 failure and warning annotations each (`path:line LEVEL: message`). Threads and conversation comments carry their GraphQL ids, every comment its author and time, and comments by the token's own user are marked `(you)`, so a caller can reply to a thread and tell new comments from its own replies. For up to three failing GitHub Actions jobs it adds the log lines leading to the last `##[error]`. A job log that cannot be read is reported per check. No mutations. |
 | `pull_request_status` | `{ "number"?: integer, "headBranch"?: string }` | Read exact same-repository PR lifecycle and head/base/merge identities. Number and headBranch are mutually exclusive. Without number, returns the most recently updated PR for headBranch or the current branch. Does not certify CI checks or review approvals. |
@@ -566,7 +568,7 @@ npm run check:pack
 printf '/branchme help\n/quit\n' | pi --no-extensions -e .
 ```
 
-Validation covers TypeScript typechecking, formatting checks, automatic context collection and prompt injection, mocked GitHub lookup, isolated real-Git worktree, branch-integration, and leased branch-retirement lifecycle tests, package checks, checkout Pi runtime smoke, and package-content verification. The checkout smoke loads BranchMe through Pi, then uses a temporary verifier command to confirm all twenty-three BranchMe tools are visible through `pi.getAllTools()` with strict schemas and prompt metadata, including `integrate_branch`, `retire_branch`, `conclude_merge`, and targeted `branch_status.ancestry`, with no generic `continue_merge` or `abort_merge` tool. Runtime smoke inspects retirement and landing registration/schema but never executes either cleanup tool. Smoke-test notes are recorded in [`docs/SMOKE_TEST.md`](docs/SMOKE_TEST.md), and TUI/help captures are stored in [`docs/TUI_CAPTURE.md`](docs/TUI_CAPTURE.md).
+Validation covers TypeScript typechecking, formatting checks, automatic context collection and prompt injection, mocked GitHub lookup, isolated real-Git worktree, branch-integration, and leased branch-retirement lifecycle tests, package checks, checkout Pi runtime smoke, and package-content verification. The checkout smoke loads BranchMe through Pi, then uses a temporary verifier command to confirm all twenty-five BranchMe tools are visible through `pi.getAllTools()` with strict schemas and prompt metadata, including `integrate_branch`, `retire_branch`, `conclude_merge`, and targeted `branch_status.ancestry`, with no generic `continue_merge` or `abort_merge` tool. Runtime smoke inspects retirement and landing registration/schema but never executes either cleanup tool. Smoke-test notes are recorded in [`docs/SMOKE_TEST.md`](docs/SMOKE_TEST.md), and TUI/help captures are stored in [`docs/TUI_CAPTURE.md`](docs/TUI_CAPTURE.md).
 
 Refresh TUI captures intentionally with:
 

package/docs/PROJECT_DEFINITION_BRIEF.md

@@ -15,7 +15,7 @@ Originally approved on 2026-06-30. Updated to describe the implemented `0.3.1` p
 - Exported extension function: `branchMeExtension`
 - Repository URL: `https://github.com/senad-d/branchme`
 - One-sentence pitch: Verified Pi tools for Git repository initialization plus current-repository branch, integration, retirement, linked-worktree, push, and GitHub pull request workflows.
-- Tool count: twenty-three strict agent-callable tools.
+- Tool count: twenty-five strict agent-callable tools.
 
 ## 3. Users and use cases
 
@@ -57,6 +57,8 @@ Originally approved on 2026-06-30. Updated to describe the implemented `0.3.1` p
 | Tool | `conclude_merge` | Commit or abort the in-progress kept merge | Refuses remaining markers; stages only formerly unmerged paths; `commit --no-edit`; verified two-parent result or verified abort |
 | Tool | `pull_request_status` | Read exact PR or latest PR for a head | Open/closed/merged state and commit identities; not a CI/review verdict |
 | Tool | `pull_request_feedback` | Read what a PR asks to be fixed | Unresolved review threads, review summaries, conversation comments, failing checks with annotations and Actions log tails; read-only |
+| Tool | `pull_request_files` | List a PR's changed files | Path, change type and line counts of the first 100 changed files, plus current labels; read-only |
+| Tool | `label_pull_request` | Label a PR | Adds 1-5 labels that already exist in the repository; refuses unknown labels; never removes |
 | Tool | `reply_pull_request_feedback` | Answer PR feedback | One reply in a review thread of the PR (optionally resolving it) or one conversation comment; the thread must belong to the PR; never edits, deletes, approves, merges or closes |
 | Tool | `init_repository` | Initialize the exact current directory as a new non-bare Git repository | Optional initial branch; rejects reinitialization/nesting; no path, commit, or project-file controls |
 | Tool | `branch_status` | Refresh bounded current-worktree Git and related-PR context; optionally prove captured local or remote-tracking ancestry | Read-only; targeted ancestry is absent from automatic context |
@@ -97,7 +99,7 @@ Originally approved on 2026-06-30. Updated to describe the implemented `0.3.1` p
   - `src/github.ts`
   - `src/ui/branchme-panel.ts`
 - Module boundaries:
-  - The extension entry point registers the informational command, twenty-three tools, and automatic context hook.
+  - The extension entry point registers the informational command, twenty-five tools, and automatic context hook.
   - `src/git-workflow.ts` and `src/tools/workflow-tools.ts` own verified remote tracking, base updates, and the new PR status registration.
   - The context module owns bounded read-only collection, prompt formatting, targeted ancestry rendering, and the `before_agent_start` hook; automatic context never runs ancestry queries.
   - The command and UI modules own mode-safe informational help/status behavior and never invoke mutations.

package/docs/SMOKE_TEST.md

@@ -23,9 +23,9 @@ pi --no-extensions -e .
 ## Automated smoke behavior
 
 - `npm run smoke:pi` first runs isolated checkout Pi processes from a temporary non-Git working directory: one with `pi --no-extensions -e <package> -e <temporary verifier>` and `/branchmeverify verify`, then one with `pi --no-extensions -e <package>` and `/branchme help`.
-- The temporary command verifier calls `pi.getAllTools()` after BranchMe loads and confirms exactly twenty-three tools—`fetch_remote`, `list_branches`, `track_branch`, `update_from_base`, `conclude_merge`, `pull_request_status`, `pull_request_feedback`, `reply_pull_request_feedback`, `branch_status`, `init_repository`, `change_branch`, `create_branch`, `create_worktree`, `fetch_branch`, `integrate_branch`, `land_branch`, `list_worktrees`, `pull_branch`, `pull_request`, `push_branch`, `rebase_branch`, `remove_worktree`, and `retire_branch`—are each registered exactly once and active with strict schemas, named prompt guidelines, descriptions, and extension source metadata. It also proves `continue_merge` and `abort_merge` are absent.
+- The temporary command verifier calls `pi.getAllTools()` after BranchMe loads and confirms exactly twenty-five tools—`fetch_remote`, `list_branches`, `track_branch`, `update_from_base`, `conclude_merge`, `pull_request_status`, `pull_request_feedback`, `reply_pull_request_feedback`, `pull_request_files`, `label_pull_request`, `branch_status`, `init_repository`, `change_branch`, `create_branch`, `create_worktree`, `fetch_branch`, `integrate_branch`, `land_branch`, `list_worktrees`, `pull_branch`, `pull_request`, `push_branch`, `rebase_branch`, `remove_worktree`, and `retire_branch`—are each registered exactly once and active with strict schemas, named prompt guidelines, descriptions, and extension source metadata. It also proves `continue_merge` and `abort_merge` are absent.
 - Runtime schema inspection verifies that `integrate_branch` has exactly the required `sourceBranch` and `targetBranch` fields and that `retire_branch` has exactly the required `branchName`, `expectedHead`, `targetBranch`, and `force` fields with `additionalProperties: false`. It also verifies that `branch_status` has only an optional top-level `ancestry` object whose required nested `sourceBranch` and `targetBranch` fields reject additional nested or top-level properties.
-- A second temporary verifier registers a deterministic local smoke model, blocks `fetch`, and runs normal prompts through real Pi lifecycle handling. It verifies automatic no-tool Git context in a temporary repository, one real `branch_status` tool refresh after a verifier-created local change, safe credential-free related-PR status with no request, and non-Git startup fallback. It expects all twenty-three tools but forbids `land_branch`, `retire_branch`, `integrate_branch`, `conclude_merge`, and every remote or worktree mutation tool (including `fetch_remote`) from executing.
+- A second temporary verifier registers a deterministic local smoke model, blocks `fetch`, and runs normal prompts through real Pi lifecycle handling. It verifies automatic no-tool Git context in a temporary repository, one real `branch_status` tool refresh after a verifier-created local change, safe credential-free related-PR status with no request, and non-Git startup fallback. It expects all twenty-five tools but forbids `land_branch`, `retire_branch`, `integrate_branch`, `conclude_merge`, and every remote or worktree mutation tool (including `fetch_remote`) from executing.
 - The Pi runtime smoke validates worktree, integration, and retirement tool registration, strict schemas, and prompt contracts only; it never creates or removes a worktree, runs a merge, or retires a branch. Real-Git lifecycle coverage runs under `npm run test` in isolated temporary local repositories with no remote contact.
 - Isolated real-Git integration tests cover `already_integrated`, `fast_forward`, exact two-parent `merge_commit`, and conflict-path capture followed by verified automatic abort/restoration. They also cover target mismatch, dirty control state, rejection of branch-specific target merge options, unrelated histories, ignored-file overwrite protection, preserved repository hooks, and a committed source ref checked out in another dirty linked worktree. The recorded merge argv proves autostash and rerere are disabled, ignored-file protection is enabled, and `--no-verify` is absent.
 - Isolated real-Git retirement tests cover merged and explicitly forced-unmerged local-ref deletion, stale expected-`HEAD` rejection, current and linked-worktree occupancy, dirty unrelated worktrees, non-current targets, and preservation of target refs, remote-tracking refs, worktrees, working-tree files, and `branch.<name>.*` configuration without contacting a remote. Recorded argv proves retirement uses `update-ref --no-deref -d` with the captured expected commit and never uses `git branch -d/-D`, fetch, push, or a remote ref target.

package/docs/STRUCTURE.md

@@ -30,7 +30,7 @@ src/
 
 ## Module boundaries
 
-1. `src/extension.ts` stays small and registers the command, twenty-three tools, and one `before_agent_start` context hook.
+1. `src/extension.ts` stays small and registers the command, twenty-five tools, and one `before_agent_start` context hook.
 2. `src/git-context.ts` owns the shared read-only collector, escaped/bounded formatter, automatic system-prompt append, and the current-state output used by `branch_status`.
 3. `src/commands/branchme-command.ts` parses `/branchme`, `/branchme help`, `--help`, and `-h`; it never performs git or GitHub mutations and avoids raw stdout in JSON mode.
 4. `src/tools/branchme-tools.ts` owns strict TypeBox schemas, prompt metadata, bounded tool content, and safe structured details. `branch_status` delegates to the shared context collector and optional ancestry verifier; `integrate_branch` and `retire_branch` delegate to focused mutation state machines; worktree tools expose explicit inventory and verified handoff operations.

package/docs/TUI_CAPTURE.md

@@ -44,6 +44,8 @@ Commands only show info; BranchMe tools perform actions.
 - `pull_request_status` — inspect a PR by number, or the latest PR for a head branch; not a CI/review verdict.
 - `pull_request_feedback` — read a PR's unresolved review comments and failing checks with log tails.
 - `reply_pull_request_feedback` — reply to a PR review thread (optionally resolving it) or post a PR comment.
+- `pull_request_files` — list a PR's changed files and current labels.
+- `label_pull_request` — add existing repository labels to a PR.
 - `pull_request` — reuses an exact matching open PR without changing its title, body, or draft state.
 - `land_branch` — after host merge, clean up from the primary checkout; use `pullRequestNumber` for squash/rebase evidence.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@senad-d/branchme",
-  "version": "0.3.11",
+  "version": "0.3.12",
   "type": "module",
   "description": "Pi extension for verified Git repository initialization, branch, worktree, integration, retirement, push, and pull request workflows.",
   "license": "MIT",

package/src/commands/branchme-command.ts

@@ -53,6 +53,8 @@ export function getBranchMeHelpText(): string {
     "- `pull_request_status` — inspect a PR by number, or the latest PR for a head branch; not a CI/review verdict.",
     "- `pull_request_feedback` — read a PR's unresolved review comments and failing checks with log tails.",
     "- `reply_pull_request_feedback` — reply to a PR review thread (optionally resolving it) or post a PR comment.",
+    "- `pull_request_files` — list a PR's changed files and current labels.",
+    "- `label_pull_request` — add existing repository labels to a PR.",
     "- `pull_request` — reuses an exact matching open PR without changing its title, body, or draft state.",
     "- `land_branch` — after host merge, clean up from the primary checkout; use `pullRequestNumber` for squash/rebase evidence.",
     "",

package/src/constants.ts

@@ -18,6 +18,8 @@ export const PULL_REQUEST_TOOL_NAME = "pull_request";
 export const PULL_REQUEST_STATUS_TOOL_NAME = "pull_request_status";
 export const PULL_REQUEST_FEEDBACK_TOOL_NAME = "pull_request_feedback";
 export const REPLY_PULL_REQUEST_FEEDBACK_TOOL_NAME = "reply_pull_request_feedback";
+export const PULL_REQUEST_FILES_TOOL_NAME = "pull_request_files";
+export const LABEL_PULL_REQUEST_TOOL_NAME = "label_pull_request";
 export const LIST_WORKTREES_TOOL_NAME = "list_worktrees";
 export const CREATE_WORKTREE_TOOL_NAME = "create_worktree";
 export const REMOVE_WORKTREE_TOOL_NAME = "remove_worktree";
@@ -47,6 +49,8 @@ export const BRANCHME_TOOL_NAMES = [
   PULL_REQUEST_STATUS_TOOL_NAME,
   PULL_REQUEST_FEEDBACK_TOOL_NAME,
   REPLY_PULL_REQUEST_FEEDBACK_TOOL_NAME,
+  PULL_REQUEST_FILES_TOOL_NAME,
+  LABEL_PULL_REQUEST_TOOL_NAME,
   LIST_WORKTREES_TOOL_NAME,
   CREATE_WORKTREE_TOOL_NAME,
   REMOVE_WORKTREE_TOOL_NAME,
@@ -98,5 +102,6 @@ export const PULL_REQUEST_FEEDBACK_BODY_LIMIT_CHARS = 2_000;
 export const PULL_REQUEST_FEEDBACK_LOG_LIMIT_CHARS = 6_000;
 export const PULL_REQUEST_FEEDBACK_SUMMARY_LIMIT_CHARS = 24_000;
 export const PULL_REQUEST_REPLY_BODY_LIMIT_CHARS = 4_000;
+export const PULL_REQUEST_LABEL_LIMIT = 5;
 export const GITHUB_GRAPHQL_TIMEOUT_MS = 15_000;
 export const GITHUB_JOB_LOG_TIMEOUT_MS = 30_000;

package/src/github-feedback.ts

@@ -2,7 +2,7 @@ import {
   GITHUB_API_BASE_URL, GITHUB_GRAPHQL_TIMEOUT_MS, GITHUB_JOB_LOG_TIMEOUT_MS, PULL_REQUEST_FEEDBACK_BODY_LIMIT_CHARS,
   PULL_REQUEST_FEEDBACK_LOG_JOB_LIMIT, PULL_REQUEST_FEEDBACK_LOG_LIMIT_CHARS, PULL_REQUEST_FEEDBACK_LOG_TAIL_BYTES,
   PULL_REQUEST_FEEDBACK_LOG_TAIL_LINES, PULL_REQUEST_FEEDBACK_RESPONSE_LIMIT_BYTES, PULL_REQUEST_FEEDBACK_SUMMARY_LIMIT_CHARS,
-  PULL_REQUEST_REPLY_BODY_LIMIT_CHARS,
+  PULL_REQUEST_LABEL_LIMIT, PULL_REQUEST_REPLY_BODY_LIMIT_CHARS,
 } from "./constants.ts";
 import {
   encodePathSegment, fetchGitHubResponse, gitHubJsonHeaders, isRecord, parseGitHubJson, pullRequestNumberField,
@@ -12,7 +12,8 @@ import {
 import { redactSecrets } from "./redaction.ts";
 import type {
   GitHubRepository, PullRequestFeedbackAnnotation, PullRequestFeedbackCheck, PullRequestFeedbackComment, PullRequestFeedbackDetails,
-  PullRequestFeedbackReview, PullRequestFeedbackThread, PullRequestReplyDetails, PullRequestReplyInput,
+  PullRequestFeedbackReview, PullRequestFeedbackThread, PullRequestFilesDetails, PullRequestLabelDetails,
+  PullRequestReplyDetails, PullRequestReplyInput,
 } from "./types.ts";
 
 // One GraphQL request reads review threads with their resolution state, review summaries, conversation
@@ -255,9 +256,10 @@ function location(path: string, line: number | null): string {
   return line === null ? path : `${path}:${line}`;
 }
 
-// "@alice (you) 2026-10-14T19:50:15Z" — the marker and time decide what is new.
+// "@alice (you) 2026-10-14T19:50:15Z <url>" — the marker and time decide what is new;
+// the URL lets a follow-up issue link the exact comment.
 function byline(comment: PullRequestFeedbackComment): string {
-  return [`@${comment.author}`, comment.byViewer ? "(you)" : "", comment.createdAt].filter(Boolean).join(" ");
+  return [`@${comment.author}`, comment.byViewer ? "(you)" : "", comment.createdAt, comment.url ? `<${comment.url}>` : ""].filter(Boolean).join(" ");
 }
 
 function idTag(kind: string, id: string): string {
@@ -291,7 +293,7 @@ export function formatPullRequestFeedback(details: PullRequestFeedbackDetails):
     `Unresolved review threads: ${details.unresolvedThreads.length} (${details.resolvedThreadCount} resolved and ${details.outdatedThreadCount} outdated not listed${omittedThreads}).`,
     ...details.unresolvedThreads.map(formatThread),
     `Reviews with a body or requested changes: ${details.reviews.length}.`,
-    ...details.reviews.map((review) => `- ${byline(review)} ${review.state}: ${review.body}`),
+    ...details.reviews.map((review) => `- ${idTag("review", review.id)}${byline(review)} ${review.state}: ${review.body}`),
     `Conversation comments: ${details.comments.length}${omittedComments}.`,
     ...details.comments.map((comment) => `- ${idTag("comment", comment.id)}${byline(comment)}: ${comment.body}`),
     `Failing checks: ${details.failingChecks.length}${omittedChecks}.`,
@@ -392,3 +394,84 @@ export function formatPullRequestReply(details: PullRequestReplyDetails): string
   if (details.resolved !== null) resolution = details.resolved ? "; thread resolved" : "; thread NOT resolved";
   return `Replied to thread ${details.threadId} on PR #${details.number}${resolution}: ${details.commentUrl}`;
 }
+
+const PULL_REQUEST_FILES_QUERY = `query($owner: String!, $repo: String!, $number: Int!) {
+  repository(owner: $owner, name: $repo) {
+    pullRequest(number: $number) {
+      number
+      labels(first: 50) { nodes { name } }
+      files(first: 100) { totalCount nodes { path changeType additions deletions } }
+    }
+  }
+}`;
+
+function requirePullRequestNode(payload: Record<string, unknown>, repository: GitHubRepository, number: number): Record<string, unknown> {
+  const pullRequest = isRecord(payload.data) && isRecord(payload.data.repository) ? payload.data.repository.pullRequest : null;
+  if (!isRecord(pullRequest) || pullRequest.number !== number) {
+    throw new Error(`Pull request #${number} was not found in ${repository.owner}/${repository.repo}.`);
+  }
+  return pullRequest;
+}
+
+/** The first 100 changed files of a pull request and its current labels. */
+export async function getPullRequestFiles(repository: GitHubRepository, number: number, token: string, options: PullRequestFetchOptions = {}): Promise<PullRequestFilesDetails> {
+  validateGitHubRepository(repository);
+  pullRequestNumberField(number);
+  const payload = await postGraphQL(PULL_REQUEST_FILES_QUERY, { owner: repository.owner, repo: repository.repo, number }, token, options, "GitHub pull request files");
+  const pullRequest = requirePullRequestNode(payload, repository, number);
+  const files = nodes(pullRequest.files).map((file) => ({
+    path: safeText(file.path, token, 500),
+    change: safeText(file.changeType, token, 20).toLowerCase(),
+    additions: typeof file.additions === "number" ? file.additions : 0,
+    deletions: typeof file.deletions === "number" ? file.deletions : 0,
+  }));
+  return {
+    action: "pull_request_files",
+    repository,
+    number,
+    labels: nodes(pullRequest.labels).map((label) => safeText(label.name, token, 100)).filter(Boolean),
+    files,
+    omitted: Math.max(0, totalCount(pullRequest.files) - files.length),
+  };
+}
+
+export function formatPullRequestFiles(details: PullRequestFilesDetails): string {
+  const omitted = details.omitted > 0 ? `; ${details.omitted} more not listed` : "";
+  return [
+    `PR #${details.number}: ${details.files.length} changed file(s)${omitted}. Labels: ${details.labels.join(", ") || "none"}.`,
+    ...details.files.map((file) => `- ${file.path} (${file.change}, +${file.additions} -${file.deletions})`),
+  ].join("\n");
+}
+
+async function requireExistingLabel(repository: GitHubRepository, label: string, token: string, options: PullRequestFetchOptions): Promise<void> {
+  const url = `${GITHUB_API_BASE_URL}/repos/${encodePathSegment(repository.owner)}/${encodePathSegment(repository.repo)}/labels/${encodePathSegment(label)}`;
+  const response = await fetchGitHubResponse(requireFetchImplementation(options.fetchImpl ?? globalThis.fetch), url, {
+    method: "GET", headers: gitHubJsonHeaders(token), signal: options.signal,
+  }, "GitHub label lookup failed", token);
+  if (response.status === 404) throw new Error(`Label "${label}" does not exist in ${repository.owner}/${repository.repo}; label_pull_request adds existing labels only.`);
+  if (!response.ok) throw new Error(`GitHub label lookup returned HTTP ${response.status}.`);
+}
+
+/** Adds existing repository labels to a pull request; GitHub would create unknown ones, so they are refused first. */
+export async function labelPullRequest(repository: GitHubRepository, number: number, labels: readonly string[], token: string, options: PullRequestFetchOptions = {}): Promise<PullRequestLabelDetails> {
+  validateGitHubRepository(repository);
+  pullRequestNumberField(number);
+  const wanted = [...new Set(labels.map((label) => label.trim()).filter(Boolean))];
+  if (wanted.length === 0 || wanted.length > PULL_REQUEST_LABEL_LIMIT) throw new Error(`labels must name 1 to ${PULL_REQUEST_LABEL_LIMIT} labels.`);
+  const found = await postGraphQL(PULL_REQUEST_EXISTS_QUERY, { owner: repository.owner, repo: repository.repo, number }, token, options, "GitHub pull request");
+  requirePullRequestNode(found, repository, number);
+  await Promise.all(wanted.map((label) => requireExistingLabel(repository, label, token, options)));
+  const url = `${GITHUB_API_BASE_URL}/repos/${encodePathSegment(repository.owner)}/${encodePathSegment(repository.repo)}/issues/${number}/labels`;
+  const response = await fetchGitHubResponse(requireFetchImplementation(options.fetchImpl ?? globalThis.fetch), url, {
+    method: "POST", headers: gitHubJsonHeaders(token), body: JSON.stringify({ labels: wanted }), signal: options.signal,
+  }, "GitHub pull request labeling failed", token);
+  if (!response.ok) throw new Error(`GitHub pull request labeling returned HTTP ${response.status}.`);
+  const text = await readBoundedResponseText(response, options.signal, PULL_REQUEST_FEEDBACK_RESPONSE_LIMIT_BYTES);
+  const payload: unknown = parseGitHubJson(text.text, "GitHub pull request labels response", token);
+  const after = Array.isArray(payload) ? payload.filter(isRecord).map((label) => safeText(label.name, token, 100)).filter(Boolean) : [];
+  return { action: "label_pull_request", repository, number, added: wanted, labels: after };
+}
+
+export function formatPullRequestLabel(details: PullRequestLabelDetails): string {
+  return `Labeled PR #${details.number} with ${details.added.join(", ")}; labels now: ${details.labels.join(", ") || "none"}.`;
+}

package/src/tools/workflow-tools.ts

@@ -3,12 +3,16 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import {
   CONCLUDE_MERGE_TOOL_NAME, GIT_CONTEXT_VALUE_LIMIT_CHARS, PULL_REQUEST_FEEDBACK_TOOL_NAME, PULL_REQUEST_REPLY_BODY_LIMIT_CHARS,
-  PULL_REQUEST_STATUS_TOOL_NAME, REPLY_PULL_REQUEST_FEEDBACK_TOOL_NAME, TRACK_BRANCH_TOOL_NAME, UPDATE_FROM_BASE_TOOL_NAME,
+  LABEL_PULL_REQUEST_TOOL_NAME, PULL_REQUEST_FILES_TOOL_NAME, PULL_REQUEST_LABEL_LIMIT, PULL_REQUEST_STATUS_TOOL_NAME,
+  REPLY_PULL_REQUEST_FEEDBACK_TOOL_NAME, TRACK_BRANCH_TOOL_NAME, UPDATE_FROM_BASE_TOOL_NAME,
 } from "../constants.ts";
 import { getGitRoot, requireCurrentBranch, safeWorktreeValue } from "../git.ts";
 import { concludeMerge, formatConflictPathList } from "../git-integration.ts";
 import { findGitHubPullRequest, getGitHubPullRequest, resolveGitHubRepository, resolveGitHubToken } from "../github.ts";
-import { formatPullRequestFeedback, formatPullRequestReply, getPullRequestFeedback, replyPullRequestFeedback } from "../github-feedback.ts";
+import {
+  formatPullRequestFeedback, formatPullRequestFiles, formatPullRequestLabel, formatPullRequestReply, getPullRequestFeedback,
+  getPullRequestFiles, labelPullRequest, replyPullRequestFeedback,
+} from "../github-feedback.ts";
 import type { ConcludeMergeDetails, PullRequestStatusDetails } from "../types.ts";
 import type { BranchMeToolOptions } from "./branchme-tools.ts";
 import { trackBranch, updateFromBase, type UpdateFromBaseDetails } from "../git-workflow.ts";
@@ -146,6 +150,47 @@ export function registerWorkflowTools(pi: Pick<ExtensionAPI, "registerTool" | "e
       return { content: [{ type: "text", text: formatPullRequestReply(details) }], details };
     },
   });
+  pi.registerTool({
+    name: PULL_REQUEST_FILES_TOOL_NAME,
+    label: "Pull Request Files",
+    description: "pull_request_files lists the changed files of a pull request of this GitHub repository (path, change type, additions, deletions; the first 100, with a count of the rest) and its current labels. No mutations.",
+    promptSnippet: "pull_request_files: list a PR's changed files and current labels",
+    promptGuidelines: [
+      "Use pull_request_files to see which areas of the repository a pull request touches, for example before choosing its labels.",
+      "pull_request_files never reads file contents or diffs, and never changes the pull request.",
+    ],
+    parameters: Type.Object({
+      number: Type.Integer({ minimum: 1, description: "PR number." }),
+    }, { additionalProperties: false }),
+    async execute(_id, params, signal, _update, ctx) {
+      const rootCtx = { cwd: await getGitRoot(pi, ctx, signal) };
+      const repository = await resolveGitHubRepository(pi, rootCtx, signal, options.env);
+      const token = (await resolveGitHubToken(options.env, { cwd: rootCtx.cwd, signal })).token;
+      const details = await getPullRequestFiles(repository, params.number, token, { fetchImpl: options.fetchImpl, signal });
+      return { content: [{ type: "text", text: formatPullRequestFiles(details) }], details };
+    },
+  });
+  pi.registerTool({
+    name: LABEL_PULL_REQUEST_TOOL_NAME,
+    label: "Label Pull Request",
+    description: "label_pull_request adds labels that already exist in this GitHub repository to one of its pull requests (1 to 5 per call). A label that does not exist is refused before anything changes; existing labels on the pull request stay.",
+    promptSnippet: "label_pull_request: add existing repository labels to a PR",
+    promptGuidelines: [
+      "Use label_pull_request only with label names the assignment or the repository's labels name exactly; it never creates, renames or removes labels.",
+      "label_pull_request adds labels and keeps the pull request's existing ones.",
+    ],
+    parameters: Type.Object({
+      number: Type.Integer({ minimum: 1, description: "PR number." }),
+      labels: Type.Array(Type.String({ minLength: 1 }), { minItems: 1, maxItems: PULL_REQUEST_LABEL_LIMIT, description: "Exact names of existing labels." }),
+    }, { additionalProperties: false }),
+    async execute(_id, params, signal, _update, ctx) {
+      const rootCtx = { cwd: await getGitRoot(pi, ctx, signal) };
+      const repository = await resolveGitHubRepository(pi, rootCtx, signal, options.env);
+      const token = (await resolveGitHubToken(options.env, { cwd: rootCtx.cwd, signal })).token;
+      const details = await labelPullRequest(repository, params.number, params.labels, token, { fetchImpl: options.fetchImpl, signal });
+      return { content: [{ type: "text", text: formatPullRequestLabel(details) }], details };
+    },
+  });
   pi.registerTool({
     name: UPDATE_FROM_BASE_TOOL_NAME,
     label: "Update From Base",

package/src/types.ts

@@ -660,6 +660,24 @@ export interface PullRequestFeedbackDetails {
   omitted: { threads: number; comments: number; checks: number };
 }
 
+export interface PullRequestFilesDetails {
+  action: "pull_request_files";
+  repository: GitHubRepository;
+  number: number;
+  labels: string[];
+  files: { path: string; change: string; additions: number; deletions: number }[];
+  omitted: number;
+}
+
+export interface PullRequestLabelDetails {
+  action: "label_pull_request";
+  repository: GitHubRepository;
+  number: number;
+  added: string[];
+  /** Every label on the pull request after the call. */
+  labels: string[];
+}
+
 export interface PullRequestReplyInput {
   number: number;
   body: string;