From 70e8f8eea0783bb71a7292384f54fc6eff4b514c Mon Sep 17 00:00:00 2001
From: Chris Butler <chrizbo@github.com>
Date: Fri, 1 May 2026 16:16:20 -0700
Subject: [PATCH 1/2] docs: add FAQ entry on agent action constraints

Adds a new entry under the Guardrails section explaining how
agent actions (commenting, PRs, file changes, external calls)
are constrained via read-only defaults, safe outputs, and the
Agent Workflow Firewall.

Source: github/agentic-workflows#528

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 docs/src/content/docs/reference/faq.md | 27 ++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/docs/src/content/docs/reference/faq.md b/docs/src/content/docs/reference/faq.md
index ffb3058c4fa..99d9fb2455e 100644
--- a/docs/src/content/docs/reference/faq.md
+++ b/docs/src/content/docs/reference/faq.md
@@ -212,6 +212,33 @@ When `allowed-github-references` is not configured at all, all references are le
 
 See [Text Sanitization](/gh-aw/reference/safe-outputs/#text-sanitization-allowed-domains-allowed-github-references) for full configuration options.
 
+### How are agent actions constrained — commenting, opening PRs, modifying files, and calling external tools?
+
+gh-aw uses defense-in-depth rather than a single control. Three layers work together:
+
+**1. Read-only agent by default.** The AI agent step has read-only GitHub permissions. It cannot comment, open PRs, or push files unless you explicitly configure [safe outputs](/gh-aw/reference/safe-outputs/).
+
+**2. Safe outputs for all writes.** Commenting, creating PRs, and modifying files all go through safe outputs — separate GitHub Actions jobs with scoped write tokens. The agent produces a structured artifact; a downstream job applies the changes after sanitization (secret redaction, URL filtering, size limits). You declare exactly which operations are permitted:
+
+```yaml wrap
+safe-outputs:
+  add-comment:
+    max: 3
+  create-pull-request:
+    max: 1
+```
+
+**3. Network allowlist for external calls.** The [Agent Workflow Firewall](/gh-aw/reference/sandbox/) blocks all outbound network access by default. You must explicitly allow each domain an agent may reach:
+
+```yaml wrap
+network:
+  allowed:
+    - defaults
+    - "api.example.com"
+```
+
+For sensitive operations, you can layer on a [GitHub Environment protection rule](/gh-aw/reference/faq/#can-i-require-external-human-approval-before-safe-outputs-are-applied) so a designated reviewer must approve before any write jobs run.
+
 ### Tell me more about guardrails
 
 Guardrails are foundational to the design. Agentic workflows implement defense-in-depth through compilation-time validation (schema checks, expression safety, action SHA pinning), runtime isolation (sandboxed containers with network controls), permission separation (read-only defaults with [safe outputs](/gh-aw/reference/safe-outputs/) for writes), tool allowlisting, and output sanitization. See the [Security Architecture](/gh-aw/introduction/architecture/).

From c9910db239034fceba0ee8f01aa35688734fb842 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 1 May 2026 23:22:21 +0000
Subject: [PATCH 2/2] docs(faq): simplify example and add threat detection
 layer

Agent-Logs-Url: https://github.com/github/gh-aw/sessions/7f53e7d5-80a3-41aa-b71a-67cbf89f0077

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
---
 docs/src/content/docs/reference/faq.md | 12 +++++-------
 1 file changed, 5 insertions(+), 7 deletions(-)

diff --git a/docs/src/content/docs/reference/faq.md b/docs/src/content/docs/reference/faq.md
index 99d9fb2455e..15fe38cd3e3 100644
--- a/docs/src/content/docs/reference/faq.md
+++ b/docs/src/content/docs/reference/faq.md
@@ -214,27 +214,25 @@ See [Text Sanitization](/gh-aw/reference/safe-outputs/#text-sanitization-allowed
 
 ### How are agent actions constrained — commenting, opening PRs, modifying files, and calling external tools?
 
-gh-aw uses defense-in-depth rather than a single control. Three layers work together:
+gh-aw uses defense-in-depth rather than a single control. Four layers work together:
 
 **1. Read-only agent by default.** The AI agent step has read-only GitHub permissions. It cannot comment, open PRs, or push files unless you explicitly configure [safe outputs](/gh-aw/reference/safe-outputs/).
 
-**2. Safe outputs for all writes.** Commenting, creating PRs, and modifying files all go through safe outputs — separate GitHub Actions jobs with scoped write tokens. The agent produces a structured artifact; a downstream job applies the changes after sanitization (secret redaction, URL filtering, size limits). You declare exactly which operations are permitted:
+**2. Safe outputs for all writes.** Commenting, creating PRs, and modifying files all go through safe outputs — separate GitHub Actions jobs with scoped write tokens. The agent produces a structured artifact; a downstream job applies the changes after sanitization (secret redaction, URL filtering, size limits). You declare which operations are permitted:
 
 ```yaml wrap
 safe-outputs:
   add-comment:
-    max: 3
-  create-pull-request:
-    max: 1
 ```
 
-**3. Network allowlist for external calls.** The [Agent Workflow Firewall](/gh-aw/reference/sandbox/) blocks all outbound network access by default. You must explicitly allow each domain an agent may reach:
+**3. Threat detection before writes.** [Agentic threat detection](/gh-aw/reference/threat-detection/) runs automatically between the agent job and the safe output jobs. It scans the agent's output for prompt injection attempts, secret leaks, and malicious code patches, blocking the write jobs if a threat is detected.
+
+**4. Network allowlist for external calls.** The [Agent Workflow Firewall](/gh-aw/reference/sandbox/) blocks all outbound network access by default. You must explicitly allow each domain an agent may reach:
 
 ```yaml wrap
 network:
   allowed:
     - defaults
-    - "api.example.com"
 ```
 
 For sensitive operations, you can layer on a [GitHub Environment protection rule](/gh-aw/reference/faq/#can-i-require-external-human-approval-before-safe-outputs-are-applied) so a designated reviewer must approve before any write jobs run.