feat(compile): default executor to System.AccessToken and add always-on Azure CLI (#873)

* feat(compile): default executor to System.AccessToken and add always-on Azure CLI

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* refactor(compile): detect az at pipeline time so missing azure-cli no longer crashes 1ES

Reviewer-requested fix: static AWF bind-mounts for /opt/az and /usr/bin/az
would break `docker run` on runners without azure-cli pre-installed (notably
some 1ES self-hosted pools), failing the pipeline before the agent ever
started.

Replace the static mounts with a runtime detection prepare step that sets
the ADO pipeline variable AW_AZ_MOUNTS via `##vso[task.setvariable]` when
both /usr/bin/az and /opt/az exist on the host, or emits a `task.logissue`
warning and leaves the variable unset otherwise.

The AWF invocation in the compiled YAML now includes a single
`$(AW_AZ_MOUNTS) \` line in the --mount chain. ADO interpolates the variable
at step start: present -> the two --mount args appear; absent -> the line
collapses to whitespace. No new trait method is added; only the existing
`prepare_steps` hook is used.

- AzureCliExtension: required_awf_mounts() now returns []; prepare_steps()
  emits the detection bash step
- generate_awf_mounts: appends `$(AW_AZ_MOUNTS) \` when AzureCli is present
- Tests: rewrite static-mount assertions to assert the detection step + the
  pipeline variable injection, plus a regression guard that no static az
  mount is emitted
- Docs: docs/network.md and docs/tools.md updated with the runtime-detection
  design and operator implications

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix(compile): graceful-degradation bug + cleanup per PR review

Address two findings from the Rust PR Reviewer bot on PR #873.

1. CRITICAL — AW_AZ_MOUNTS undefined when az is missing:

The runtime-detection step in AzureCliExtension only set the
AW_AZ_MOUNTS pipeline variable in the detected branch. In the
missing-az branch the variable was left undefined. ADO leaves an
undefined $(VAR) as the LITERAL STRING "$(VAR)" in subsequent bash
steps (it does NOT expand to empty). Bash sees $(AW_AZ_MOUNTS),
interprets it as a $(...) command substitution, tries to execute
a program named AW_AZ_MOUNTS, gets exit 127, and the AWF
invocation step dies under `set -e` — the exact 1ES failure mode
the refactor set out to prevent.

Fix: always emit `##vso[task.setvariable variable=AW_AZ_MOUNTS]`,
with an empty value in the missing branch. ADO then expands
$(AW_AZ_MOUNTS) to nothing and the trailing `\` line becomes a
harmless continuation no-op.

Regression guards (both lock this in):
  - azure_cli.rs::test_azure_cli_prepare_steps_defines_aw_az_mounts_in_else_branch
    counts `setvariable` occurrences (must be 2) and asserts the
    else block contains an empty-value setvariable line.
  - compiler_tests.rs::test_default_pipeline_mounts_az_and_allows_azure_hosts
    asserts the same 2× count on the compiled lock.yml.

2. Cleanup — delete WRITE_REQUIRING_SAFE_OUTPUTS:

The const was retained with #[allow(dead_code)] after the
removal of `validate_write_permissions`, but its only consumers
left were the two tests that exercised the const itself. Each
`*Result` type already carries `REQUIRES_WRITE: bool` for any
caller (compiler, audit, runtime) that needs the same info.
Deleting the const removes a dead-code annotation and one
otherwise-purposeless list to maintain when adding new tools.

Test cleanup: removed `test_write_requiring_subset_of_all_known`
(purely exercised the deleted const) and rewrote
`test_all_known_completeness` to use a HashSet-based duplicate
check on ALL_KNOWN_SAFE_OUTPUTS plus the ALWAYS_ON/NON_MCP
disjointness check (preserves the meaningful invariants).

Validation:
  - cargo build: clean
  - cargo test: 1748 unit + 119 compiler + all integration pass
  - cargo clippy --all-targets --all-features -- -D warnings: clean
  - tests/safe-outputs/azure-cli.lock.yml regenerated (+1 line)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* feat(compile): inject conditional Azure CLI advisory into the agent prompt

When the always-on AzureCli extension detects azure-cli on the host
(AW_AZ_MOUNTS non-empty), append an Azure CLI advisory section to
the agent prompt so the agent knows az is on PATH inside the
sandbox, what it's good for, and the auth model. Skip the append
when az is missing so the agent never tries to call az on a runner
that doesn't have it.

Design
======

AzureCliExtension::prepare_steps() now returns TWO YAML steps:

  1. Detection (existing) — sets AW_AZ_MOUNTS to the two --mount
     args or empty string.
  2. NEW: "Append Azure CLI prompt" — a single-quoted heredoc that
     cats an Azure CLI advisory into /tmp/awf-tools/agent-prompt.md,
     gated by `condition: ne(variables['AW_AZ_MOUNTS'], '')`.

The CompilerExtension trait API is unchanged. wrap_prompt_append
is unchanged. The single call site in common.rs:2311 is unchanged.
prompt_supplement() on AzureCli stays None. The conditional
injection is entirely self-contained inside the extension's own
prepare_steps Vec.

Why not extend the trait. The existing prompt_supplement() hook
doesn't carry a step-level condition. Adding one would require a
new trait method, a new wrap_prompt_append signature, an enum-macro
arm update, and a call-site change in common.rs — disproportionate
for a 15-line advisory that only one extension wants gated.

Advisory content
================

The advisory assumes az IS available (no "may be" hedging — the
step only runs when it is) and covers:

  - az devops family — autoauthed via $AZURE_DEVOPS_EXT_PAT when
    permissions: read: is declared
  - Azure Resource Manager — separate identity required, not
    provisioned by ado-aw
  - Microsoft Graph — same caveat as ARM
  - Fallback — file a missing-tool safe output naming azure-cli

Heredoc terminator is SINGLE-QUOTED ('AZURE_CLI_PROMPT_EOF') so
$AZURE_DEVOPS_EXT_PAT and similar literals are appended verbatim
rather than being shell-expanded to the runner's PAT value. Locked
in by test_azure_cli_prompt_append_uses_single_quoted_heredoc.

Tests
=====

Five new unit tests in src/compile/extensions/azure_cli.rs:
  - test_azure_cli_prompt_append_step_is_conditional
  - test_azure_cli_prompt_append_step_targets_agent_prompt_file
  - test_azure_cli_prompt_append_step_has_advisory_anchors
  - test_azure_cli_prompt_append_uses_single_quoted_heredoc
  - test_azure_cli_prompt_append_displayname_matches_lint_list

Existing test_azure_cli_prepare_steps_detects_az_before_setting_var
updated for the new vec length (2 instead of 1).

Integration test test_default_pipeline_mounts_az_and_allows_azure_hosts
extended to assert the displayName, the condition expression in the
same step (proximity check), and the advisory anchor strings.

tests/bash_lint_tests.rs REQUIRED_STEP_DISPLAY_NAMES gains "Append
Azure CLI prompt" so shellcheck exercises the new heredoc.

tests/safe-outputs/azure-cli.lock.yml regenerated.

Docs
====

docs/network.md and docs/tools.md "Always-on Azure CLI" sections
gain a paragraph describing the conditional advisory injection. The
same edits also correct a small carryover inaccuracy from commit
7fe562f: the previous text said "leaves AW_AZ_MOUNTS unset" — the
graceful-degradation fix actually sets it to the empty string. Now
documented correctly with the rationale.

Validation
==========

  - cargo build: clean
  - cargo test: 1753 unit + 119 compiler + all integration pass
  - cargo clippy --all-targets --all-features -- -D warnings: clean

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix(compile): silence shellcheck SC2046 on $(AW_AZ_MOUNTS) macro

The new `$(AW_AZ_MOUNTS)` line in the AWF invocation chain is an
ADO macro substituted before bash sees it, not a bash command
substitution. shellcheck cannot distinguish the two and flagged
every compiled fixture with SC2046 ("Quote this to prevent word
splitting"), turning Build & Test red.

Word splitting of the expanded value into separate `--mount` tokens
is intentional and required (the pipeline variable expands to
`--mount /opt/az:/opt/az:ro --mount /usr/bin/az:/usr/bin/az:ro` or
to the empty string). Quoting would produce a single malformed
token. Disable SC2046 with an inline directive on the `sudo -E`
line in all four base templates (base, 1es-base, job-base,
stage-base) so the directive applies to the multi-line awf
invocation as a unit.

Regenerated tests/safe-outputs/azure-cli.lock.yml; verified
bash_lint_tests passes locally with shellcheck 0.11.0.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: jamesadevine

.gitattributes

@@ -2,6 +2,7 @@
 # BEGIN ado-aw managed (do not edit)
 tests/safe-outputs/add-build-tag.lock.yml linguist-generated=true merge=ours text eol=lf
 tests/safe-outputs/add-pr-comment.lock.yml linguist-generated=true merge=ours text eol=lf
+tests/safe-outputs/azure-cli.lock.yml linguist-generated=true merge=ours text eol=lf
 tests/safe-outputs/comment-on-work-item.lock.yml linguist-generated=true merge=ours text eol=lf
 tests/safe-outputs/create-branch.lock.yml linguist-generated=true merge=ours text eol=lf
 tests/safe-outputs/create-git-tag.lock.yml linguist-generated=true merge=ours text eol=lf

docs/ado-aw-debug.md

@@ -112,7 +112,7 @@ Stage 3 authenticates against GitHub using the
 
 ```yaml
 env:
-  SYSTEM_ACCESSTOKEN: $(SC_WRITE_TOKEN)                  # if write permissions: are set
+  SYSTEM_ACCESSTOKEN: $(System.AccessToken)              # default executor token (or $(SC_WRITE_TOKEN) if permissions.write is set)
   ADO_AW_DEBUG_GITHUB_TOKEN: $(ADO_AW_DEBUG_GITHUB_TOKEN) # only when ado-aw-debug.create-issue is set
 ```
 

docs/front-matter.md

@@ -144,7 +144,10 @@ network:                       # optional network policy (standalone target only
     - "evil.example.com"
 permissions:                   # optional ADO access token configuration
   read: my-read-arm-connection   # ARM service connection for read-only ADO access (Stage 1 agent)
-  write: my-write-arm-connection # ARM service connection for write ADO access (Stage 3 executor only)
+  write: my-write-arm-connection # OPTIONAL ARM SC for Stage 3 executor writes.
+                                 # Default: executor uses $(System.AccessToken).
+                                 # Set this only for cross-org writes or
+                                 # named-identity attribution.
 parameters:                    # optional ADO runtime parameters (surfaced in UI when queuing a run)
   - name: clearMemory
     displayName: "Clear agent memory"

docs/network.md

@@ -47,6 +47,81 @@ The following domains are always allowed. Most are defined in `CORE_ALLOWED_HOST
 | `rt.services.visualstudio.com` | Visual Studio runtime telemetry |
 | `config.edge.skype.com` | Configuration |
 | `host.docker.internal` | MCP Gateway (MCPG) on host — added by the standalone compiler, not part of `CORE_ALLOWED_HOSTS` |
+| `aka.ms` | Microsoft link shortener (used by `az` subcommand metadata) — contributed by the always-on Azure CLI extension |
+
+## Always-on Azure CLI (`az`)
+
+Every compiled pipeline adds the Azure auth and management hosts listed
+above (`login.microsoftonline.com`, `login.windows.net`,
+`management.azure.com`, `graph.microsoft.com`, `aka.ms`) to the AWF
+allowlist and emits a small *Detect Azure CLI on host* prepare step
+that runs early in the Agent job. This mirrors gh-aw's "assume `gh` is
+on the runner" model: agents can call `az` from their bash tool
+without opting in — *when the runner has it*.
+
+### Runtime detection and graceful degradation
+
+Because `azure-cli` is not universally pre-installed on every ADO
+runner image (notably some 1ES self-hosted pools), the compiler does
+**not** declare static AWF bind-mounts for `/opt/az` and `/usr/bin/az`.
+Static mounts would cause `docker run` to fail with "bind source path
+does not exist" on runners without `az`, breaking the pipeline before
+the agent ever started.
+
+Instead, the prepare step does the detection itself at pipeline time:
+
+* If both `/usr/bin/az` (the launcher shim) and `/opt/az` (the Python
+  venv that `az` actually runs in) exist on the host, the step sets
+  the ADO pipeline variable
+  `AW_AZ_MOUNTS=--mount /opt/az:/opt/az:ro --mount /usr/bin/az:/usr/bin/az:ro`
+  via `##vso[task.setvariable]`.
+* If either is missing, the step emits a
+  `##vso[task.logissue type=warning]` explaining `az` won't be
+  available inside the agent sandbox and sets `AW_AZ_MOUNTS` to the
+  *empty string* (also via `##vso[task.setvariable]` — leaving the
+  variable undefined would make ADO render the literal `$(AW_AZ_MOUNTS)`
+  in the AWF bash step, where bash would interpret it as a `$(...)`
+  command substitution and kill the step under `set -e`).
+
+The AWF invocation in the compiled YAML then includes a literal
+`$(AW_AZ_MOUNTS) \` line on its own in the `--mount` chain.
+At step start, ADO interpolates that pipeline variable into the bash
+script: when az is present the two `--mount` args appear; when it's
+absent the line collapses to empty whitespace + the `\` continuation,
+which is a no-op.
+
+### Agent prompt advisory (conditional)
+
+When (and only when) `AW_AZ_MOUNTS` is non-empty, a follow-up
+*Append Azure CLI prompt* step appends an Azure CLI advisory section
+to `/tmp/awf-tools/agent-prompt.md`. The agent reads the prompt on
+startup and learns that `az` is on PATH, what it's good for
+(`az devops` autoauthed via `$AZURE_DEVOPS_EXT_PAT`, ARM and Graph
+requiring separate auth), and the fallback path (`missing-tool`
+safe output naming `azure-cli`).
+
+The step is gated by `condition: ne(variables['AW_AZ_MOUNTS'], '')`,
+which reuses the same pipeline variable the detection step writes.
+On runners where `az` is missing, the advisory step is skipped
+entirely — the agent never sees Azure CLI guidance and never tries
+to call `az`, avoiding the "told to use `az`, fails with command
+not found" failure mode.
+
+### Operator implications
+
+- **Microsoft-hosted `ubuntu-latest`**: `az` is detected, mounted, and
+  available inside the agent sandbox. Nothing to do.
+- **1ES self-hosted runners *with* azure-cli baked in**: same as above.
+- **1ES self-hosted runners *without* azure-cli**: the pipeline runs
+  successfully, but agents that invoke `az` get the standard
+  `command not found` inside the sandbox. The warning emitted by the
+  prepare step is visible in the ADO log as a yellow-flagged issue on
+  the build summary; treat it as a signal to either ignore (if no
+  agent on that runner needs `az`) or to install `azure-cli` on the
+  runner image.
+
+See [`docs/tools.md`](tools.md#built-in-clis) for the agent-facing
+contract (auth scope, available subcommands).
 
 ## Adding Additional Hosts
 
@@ -108,46 +183,83 @@ network:
 
 ## Permissions (ADO Access Tokens)
 
-ADO does not support fine-grained permissions — there are two access levels: blanket read and blanket write. Tokens are minted from ARM service connections; `System.AccessToken` is never used for agent or executor operations.
+ADO does not support fine-grained permissions — there are two access levels:
+blanket read and blanket write. The executor (Stage 3) always has a
+write-capable token; what changes is its *source* and *attribution*:
 
-**Exception:** The trigger filter gate step (Setup job) uses `System.AccessToken`
-for two purposes: (1) self-cancelling the build when filters don't match
-(`PATCH` to `_apis/build/builds/{id}`), and (2) fetching PR metadata for
-Tier 2 filters (labels, draft status, changed files). This runs in the
-Setup job before the agent starts, outside the AWF sandbox. The pipeline
-must have "Allow scripts to access the OAuth token" enabled for this to
-work. This is a deliberate scoped exception — the token is not passed to
-the agent or executor.
+| Source                              | When                                          | Identity                                        |
+| ----------------------------------- | --------------------------------------------- | ----------------------------------------------- |
+| `$(System.AccessToken)` *(default)* | No `permissions.write` configured             | `Project Collection Build Service (org)`        |
+| `$(SC_WRITE_TOKEN)` *(opt-in)*      | `permissions.write: <arm-service-connection>` | The federated identity behind the ARM SC        |
+
+The agent (Stage 1) never receives the executor's token. Stage separation —
+not token type — is the trust boundary.
+
+**`System.AccessToken` exceptions.** Two other steps also map
+`System.AccessToken`:
+
+1. **Setup-job trigger filter gate** — self-cancels the build when filters
+   don't match (`PATCH _apis/build/builds/{id}`) and fetches PR metadata for
+   Tier 2 filters (labels, draft status, changed files). Runs before the
+   agent, outside the AWF sandbox.
+2. **Stage 3 executor** — when no ARM write SC is configured (the default),
+   the executor's `SYSTEM_ACCESSTOKEN` env var is sourced from
+   `$(System.AccessToken)`.
+
+Both require the pipeline setting "Allow scripts to access the OAuth token"
+to be enabled (the ADO default).
+
+`System.AccessToken` is scoped by the pipeline's
+**"Limit job authorization scope to current project"** toggle. With this on
+(strongly recommended), writes are limited to the pipeline's host project.
+Operators can scope further per-pipeline by editing the build definition's
+*Run-time settings*.
 
 ```yaml
 permissions:
   read: my-read-arm-connection    # Stage 1 agent — read-only ADO access
-  write: my-write-arm-connection  # Stage 3 executor — write access for safe-outputs
+  # write: my-write-arm-connection  # Optional — see below
 ```
 
-### Security Model
+### When to set `permissions.write`
 
-- **`permissions.read`**: Mints a read-only ADO-scoped token given to the agent inside the AWF sandbox (Stage 1). The agent can query ADO APIs but cannot write.
-- **`permissions.write`**: Mints a write-capable ADO-scoped token used **only** by the executor in Stage 3 (`SafeOutputs` job). This token is never exposed to the agent.
-- **Both omitted**: No ADO tokens are passed anywhere. The agent has no ADO API access.
+The default (`$(System.AccessToken)`) is sufficient for the vast majority of
+agents. Set `permissions.write` only when you need:
 
-### Compile-Time Validation
+1. **Cross-org or cross-project writes** — `System.AccessToken` is scoped to
+   the host project. Targeting work items or repos in a different ADO
+   project / organization requires an ARM SC with broader scope.
+2. **Named-identity attribution** — `System.AccessToken` writes are
+   attributed to the `Project Collection Build Service` identity. An ARM SC
+   attributes writes to its underlying federated identity (e.g.
+   `safe-output-bot@contoso.com`), useful when audit logs or work-item
+   notifications need a specific actor.
 
-If write-requiring safe-outputs (`create-pull-request`, `create-work-item`) are configured but `permissions.write` is missing, compilation fails with a clear error message.
+### Security Model
+
+- **`permissions.read`**: Mints a read-only ADO-scoped token given to the
+  agent inside the AWF sandbox (Stage 1). The agent can query ADO APIs but
+  cannot write.
+- **`permissions.write` (optional)**: Mints a write-capable ADO-scoped token
+  used **only** by the executor in Stage 3 (`SafeOutputs` job). Overrides
+  the default `$(System.AccessToken)` for write operations. Never exposed
+  to the agent.
+- **Both omitted**: The agent has no ADO API access. The executor still has
+  a write-capable token via `$(System.AccessToken)`, scoped by the
+  pipeline's job-authorization settings.
 
 ### Examples
 
 ```yaml
-# Agent can read ADO, safe-outputs can write
+# Default: agent can read ADO, executor writes via $(System.AccessToken).
 permissions:
   read: my-read-sc
-  write: my-write-sc
 
-# Agent can read ADO, no write safe-outputs needed
+# Cross-org / named-identity attribution — executor writes via ARM SC.
 permissions:
   read: my-read-sc
-
-# Agent has no ADO access, but safe-outputs can create PRs/work items
-permissions:
   write: my-write-sc
+
+# Agent has no ADO read access; executor still writes via $(System.AccessToken).
+# (Empty front matter — no `permissions:` key at all.)
 ```

docs/safe-outputs.md

@@ -37,6 +37,18 @@ safe-outputs:
 
 Safe output configurations are passed to Stage 3 execution and used when processing safe outputs.
 
+### Executor authentication
+
+All write-bearing safe outputs (e.g. `create-pull-request`,
+`create-work-item`, `add-pr-comment`, `upload-build-attachment`) run in the
+Stage 3 `SafeOutputs` job and authenticate to Azure DevOps using
+`SYSTEM_ACCESSTOKEN`. By default this is `$(System.AccessToken)` — the
+pipeline's built-in OAuth token running as the *Project Collection Build
+Service* identity. Set `permissions.write` to override this with an
+ARM-minted token, e.g. for cross-org writes or named-identity attribution.
+See [`docs/network.md`](network.md) and
+[`docs/template-markers.md`](template-markers.md) for details.
+
 ## Available Safe Output Tools
 
 ### comment-on-work-item
@@ -604,7 +616,7 @@ multiple uploads.
 **Notes:**
 - Single-file only; directory uploads are not supported.
 - When `build_id` is omitted and `allowed-build-ids` is configured, the allow-list check is skipped — the current build is implicitly trusted.
-- Requires `BUILD_CONTAINERID`, `BUILD_BUILDID`, and `SYSTEM_TEAMPROJECTID` (all set automatically inside an Azure DevOps pipeline job) and `vso.build_execute` scope on the executor's token (the existing write service connection provides this).
+- Requires `BUILD_CONTAINERID`, `BUILD_BUILDID`, and `SYSTEM_TEAMPROJECTID` (all set automatically inside an Azure DevOps pipeline job) and `vso.build_execute` scope on the executor's token (granted to `$(System.AccessToken)` by default, and to the ARM-minted token when `permissions.write` is set).
 
 ### cache-memory (moved to `tools:`)
 Memory is now configured as a first-class tool under `tools: cache-memory:` instead of `safe-outputs: memory:`. See the [Cache Memory section](./tools.md#cache-memory-cache-memory) in `docs/tools.md` for details.

docs/template-markers.md

@@ -532,23 +532,24 @@ If `permissions.read` is not configured, this marker is replaced with an empty s
 
 ## {{ acquire_write_token }}
 
-Generates an `AzureCLI@2` step that acquires a write-capable ADO-scoped access token from the ARM service connection specified in `permissions.write`. This token is used only by the executor in Stage 3 (`SafeOutputs` job) and is never exposed to the agent.
+Generates an `AzureCLI@2` step that acquires a write-capable ADO-scoped access token from the ARM service connection specified in `permissions.write`. When present, this token is used by the executor in Stage 3 (`SafeOutputs` job) instead of the default `$(System.AccessToken)`, and is never exposed to the agent.
 
 The step:
 - Uses the ARM service connection from `permissions.write`
 - Calls `az account get-access-token` with the ADO resource ID
 - Stores the token in a secret pipeline variable `SC_WRITE_TOKEN`
 
-If `permissions.write` is not configured, this marker is replaced with an empty string.
+If `permissions.write` is not configured (the default), this marker is replaced with an empty string and the executor uses `$(System.AccessToken)` instead — see `{{ executor_ado_env }}` below.
 
 ## {{ executor_ado_env }}
 
-Generates the complete `env:` block (including the `env:` key) for the Stage 3 executor step. The block contains zero, one, or two lines depending on which features are configured:
+Generates the complete `env:` block (including the `env:` key) for the Stage 3 executor step. The block always contains at least `SYSTEM_ACCESSTOKEN` and is **never empty** — the executor always needs a write-capable ADO token to perform safe-output operations.
 
-* `SYSTEM_ACCESSTOKEN: $(SC_WRITE_TOKEN)` — emitted when `permissions.write` is configured. Provides the write-capable ADO token to the executor.
-* `ADO_AW_DEBUG_GITHUB_TOKEN: $(ADO_AW_DEBUG_GITHUB_TOKEN)` — emitted when `ado-aw-debug.create-issue` is configured. Provides the GitHub PAT used by the debug-only `create-issue` safe output. See [`docs/ado-aw-debug.md`](ado-aw-debug.md).
+* `SYSTEM_ACCESSTOKEN: $(SC_WRITE_TOKEN)` — emitted when `permissions.write` is configured. Sources the executor's token from the ARM-minted write token. Use this for cross-org writes or when you need named-identity attribution.
+* `SYSTEM_ACCESSTOKEN: $(System.AccessToken)` — emitted by default (no `permissions.write` set). Sources the executor's token from the pipeline's built-in OAuth token, scoped by the pipeline's "Limit job authorization scope" settings. This is the *Project Collection Build Service* identity. Sufficient for the vast majority of agents.
+* `ADO_AW_DEBUG_GITHUB_TOKEN: $(ADO_AW_DEBUG_GITHUB_TOKEN)` — additionally emitted when `ado-aw-debug.create-issue` is configured. Provides the GitHub PAT used by the debug-only `create-issue` safe output. See [`docs/ado-aw-debug.md`](ado-aw-debug.md).
 
-If neither feature is configured, this marker is replaced with an empty string so that no `env:` block is emitted at all. Note: `System.AccessToken` is never used directly — all ADO tokens come from explicitly configured service connections, and the GitHub PAT is sourced from a dedicated pipeline variable separate from the read-only `GITHUB_TOKEN` the agent sees in Stage 1.
+The agent (Stage 1) never maps `SYSTEM_ACCESSTOKEN` — that is the cross-stage trust boundary that allows the executor to safely receive a write-capable token while the agent stays read-only. (The Setup-job trigger filter gate also maps `SYSTEM_ACCESSTOKEN` for self-cancellation and PR metadata fetching, but that runs before the agent.)
 
 ## {{ compiler_version }}