docs: Document remove-labels safe output type (#11425)

Author: Copilot

.changeset/patch-docs-remove-labels-safe-output.md

@@ -90,4 +90,6 @@ Add a **very brief** comment (max 5-10 lines) to the current pull request with:
 
 Use the `add_comment` tool to add a **mystical oracle-themed comment** to the latest discussion (using the `discussion_number` you extracted in step 8) - be creative and use mystical language like "🔮 The ancient spirits stir..."
 
-If all tests pass, add the label `smoke-codex` to the pull request.
+If all tests pass:
+- Use the `add_labels` safe-output tool to add the label `smoke-codex` to the pull request
+- Use the `remove_labels` safe-output tool to remove the label `smoke` from the pull request

.changeset/patch-document-remove-labels-safe-output.md

@@ -104,5 +104,5 @@ strict: true
 3. Use the `add_comment` tool to add a **fun and creative comment** to the latest discussion (using the `discussion_number` you extracted in step 7) - be playful and entertaining in your comment
 
 If all tests pass:
-- Add the label `smoke-copilot` to the pull request
-- Remove the label `smoke` from the pull request
+- Use the `add_labels` safe-output tool to add the label `smoke-copilot` to the pull request
+- Use the `remove_labels` safe-output tool to remove the label `smoke` from the pull request

.changeset/patch-document-remove-labels.md

@@ -47,6 +47,7 @@ The agent requests issue creation; a separate job with `issues: write` creates i
 - [**Add Comment**](#comment-creation-add-comment) (`add-comment`) — Post comments on issues, PRs, or discussions (max: 1)
 - [**Hide Comment**](#hide-comment-hide-comment) (`hide-comment`) — Hide comments on issues, PRs, or discussions (max: 5)
 - [**Add Labels**](#add-labels-add-labels) (`add-labels`) — Add labels to issues or PRs (max: 3)
+- [**Remove Labels**](#remove-labels-remove-labels) (`remove-labels`) — Remove labels from issues or PRs (max: 3)
 - [**Add Reviewer**](#add-reviewer-add-reviewer) (`add-reviewer`) — Add reviewers to pull requests (max: 3)
 - [**Assign Milestone**](#assign-milestone-assign-milestone) (`assign-milestone`) — Assign issues to milestones (max: 1)
 - [**Assign to Agent**](#assign-to-agent-assign-to-agent) (`assign-to-agent`) — Assign Copilot agents to issues or PRs (max: 1)
@@ -211,6 +212,33 @@ safe-outputs:
     target-repo: "owner/repo"    # cross-repository
 ```
 
+### Remove Labels (`remove-labels:`)
+
+Removes labels from issues or PRs. Specify `allowed` to restrict which labels can be removed. If a label is not present on the item, it will be silently skipped.
+
+```yaml wrap
+safe-outputs:
+  remove-labels:
+    allowed: [automated, stale]  # restrict to specific labels (optional)
+    max: 3                       # max operations (default: 3)
+    target: "*"                  # "triggering" (default), "*", or number
+    target-repo: "owner/repo"    # cross-repository
+```
+
+**Target**: `"triggering"` (requires issue/PR event), `"*"` (any issue/PR), or number (specific issue/PR).
+
+When `allowed` is omitted or set to `null`, any labels can be removed. Use `allowed` to restrict removal to specific labels only, providing control over which labels agents can manipulate.
+
+**Example use case**: Label lifecycle management where agents add temporary labels during triage and remove them once processed.
+
+```yaml wrap
+safe-outputs:
+  add-labels:
+    allowed: [needs-triage, automation]
+  remove-labels:
+    allowed: [needs-triage]  # agents can remove triage label after processing
+```
+
 ### Add Reviewer (`add-reviewer:`)
 
 Adds reviewers to pull requests. Specify `reviewers` to restrict to specific GitHub usernames.

.github/workflows/smoke-codex.lock.yml

@@ -361,6 +361,30 @@
       "additionalProperties": false
     }
   },
+  {
+    "name": "remove_labels",
+    "description": "Remove labels from an existing GitHub issue or pull request. Silently skips labels that don't exist on the item. Use this to clean up labels or manage label lifecycles (e.g., removing 'needs-review' after review is complete).",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "labels": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Label names to remove (e.g., ['smoke', 'needs-triage']). Non-existent labels are silently skipped."
+        },
+        "item_number": {
+          "type": "number",
+          "description": "Issue or PR number to remove labels from. This is the numeric ID from the GitHub URL (e.g., 456 in github.com/owner/repo/issues/456). If omitted, removes labels from the item that triggered this workflow."
+        }
+      },
+      "required": [
+        "labels"
+      ],
+      "additionalProperties": false
+    }
+  },
   {
     "name": "add_reviewer",
     "description": "Add reviewers to a GitHub pull request. Reviewers receive notifications and can approve or request changes. Use 'copilot' as a reviewer name to request the Copilot PR review bot.",
@@ -1062,4 +1086,4 @@
       "additionalProperties": false
     }
   }
-]
+]