[docs] Update documentation for features from 2026-05-23

docs/src/content/docs/reference/safe-outputs-pull-requests.md

@@ -415,7 +415,8 @@ The `protected-files` field accepts either a string policy value or an object wi
 
 | Value | Behavior |
 |-------|-----------|
-| `blocked` (default) | Hard-block: the safe output fails with an error |
+| `request_review` (default) | Create the pull request and submit a `REQUEST_CHANGES` review listing the protected files. The agent's work is preserved, and a human reviewer must approve before merge. |
+| `blocked` | Hard-block: the safe output fails with an error |
 | `fallback-to-issue` | Create a review issue with instructions for the human to apply or reject the changes manually |
 | `allowed` | No restriction — all protected file changes are permitted. **Use only when the workflow is explicitly designed to manage these files.** |
 
@@ -425,7 +426,7 @@ The `protected-files` field accepts either a string policy value or an object wi
 safe-outputs:
   create-pull-request:
     protected-files:
-      policy: fallback-to-issue   # same values as string form (default: blocked)
+      policy: fallback-to-issue   # same values as string form (default: request_review)
       exclude:
         - AGENTS.md               # allow the agent to update its own instruction file
         - CHANGELOG.md            # allow the agent to update the changelog
@@ -475,7 +476,7 @@ on:
         type: string
         default: fallback-to-issue
         description: >
-          Protected-file policy: 'blocked', 'fallback-to-issue', or 'allowed'.
+          Protected-file policy: 'request_review', 'blocked', 'fallback-to-issue', or 'allowed'.
       patch-format:
         type: string
         default: bundle

docs/src/content/docs/reference/threat-detection.md

@@ -331,6 +331,10 @@ Reasons:
 
 If the detection process itself fails (e.g., network issues, tool errors), the workflow stops and safe outputs are not applied. This fail-safe approach prevents potentially malicious content from being processed.
 
+**When Detection Returns a Warning:**
+
+A warning is a lower-severity signal than a hard threat: the safe output is allowed to proceed, but human review is required before merge. When `create-pull-request` is the safe output, the handler submits a `REQUEST_CHANGES` pull request review whose body includes the detection reason and a link to the workflow run logs. If a `request_review` protected-files gate also fires in the same run, both signals are composed into a single review body separated by a horizontal rule.
+
 ## Supply Chain Protection (Protected Files)
 
 Beyond AI-powered threat detection, GitHub Agentic Workflows includes a static, rule-based protection layer that guards against **supply chain attacks** — cases where an AI agent could (intentionally or accidentally) modify files that control how software is built, tested, or deployed.
@@ -360,7 +364,8 @@ Configure how each safe output handles protected file changes using the `protect
 
 | Value | Behavior |
 |-------|-----------|
-| `blocked` (default) | Hard-block: the safe output fails with an error message |
+| `request_review` (default) | Create the pull request and submit a `REQUEST_CHANGES` review listing the protected files. A human reviewer must approve before merge. |
+| `blocked` | Hard-block: the safe output fails with an error message |
 | `allowed` | No restriction — all protected file changes are permitted |
 | `fallback-to-issue` | Create a review issue instead of a PR / push, so a human can inspect and apply the changes manually |