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>

Author: jamesadevine

docs/network.md

@@ -77,8 +77,11 @@ Instead, the prepare step does the detection itself at pipeline time:
   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 leaves `AW_AZ_MOUNTS` unset
-  (which expands to the empty string).
+  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.
@@ -87,6 +90,23 @@ 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

docs/tools.md

@@ -108,8 +108,11 @@ two things at pipeline time:
    pipeline variable
    `AW_AZ_MOUNTS=--mount /opt/az:/opt/az:ro --mount /usr/bin/az:/usr/bin/az:ro`.
 2. If either is missing, it emits a yellow ADO warning
-   (`##vso[task.logissue type=warning]`) and leaves the variable
-   unset.
+   (`##vso[task.logissue type=warning]`) and sets the variable to
+   the *empty string* (leaving it undefined would make ADO render
+   the literal `$(AW_AZ_MOUNTS)` in the AWF bash step, where bash
+   would interpret it as command substitution and kill the step
+   under `set -e`).
 
 The AWF invocation includes a `$(AW_AZ_MOUNTS) \` line in its
 `--mount` chain. ADO expands the variable at step start: present →
@@ -120,6 +123,15 @@ exist" on runners without `az`. See
 [`docs/network.md`](network.md#always-on-azure-cli-az) for the full
 design.
 
+**Conditional agent prompt advisory.** When (and only when) `az` is
+detected, a follow-up *Append Azure CLI prompt* step appends an
+Azure CLI advisory section to the agent prompt. The agent then knows
+`az` is on PATH and what it's good for (use cases and auth model
+below). The step is gated by
+`condition: ne(variables['AW_AZ_MOUNTS'], '')`; on runners without
+`az` it is skipped and the agent never sees Azure CLI guidance —
+preventing "told to use `az`, fails with command not found" loops.
+
 | Host posture                          | What you get                                              |
 | ------------------------------------- | --------------------------------------------------------- |
 | Microsoft-hosted `ubuntu-latest`      | Detected → mounted → `az` available in the sandbox        |

src/compile/extensions/azure_cli.rs

@@ -97,36 +97,57 @@ impl CompilerExtension for AzureCliExtension {
     }
 
     fn prepare_steps(&self, _ctx: &CompileContext) -> Vec<String> {
-        // Runtime detection step. Runs in the Agent job's prepare phase
-        // (NOT a separate Setup job) so it shares the same pipeline-
-        // variable scope as the subsequent AWF bash step. ADO pipeline
-        // variables set via `##vso[task.setvariable]` are visible as
-        // `$(NAME)` in later steps of the same job.
+        // Returns two YAML steps, in order:
         //
-        // Detection checks both /usr/bin/az (the launcher shim) AND
-        // /opt/az (the Python venv that az actually runs in). Mounting
-        // only one of the two would leave az partially available and
-        // produce confusing errors inside the sandbox.
+        // 1. Detection — runs in the Agent job's prepare phase (NOT a
+        //    separate Setup job) so it shares the same pipeline-variable
+        //    scope as the later AWF bash step. Sets `AW_AZ_MOUNTS` to
+        //    either the two `--mount` args or empty string, depending
+        //    on whether the host has azure-cli installed.
         //
-        // The setvariable value uses spaces between args so bash
-        // word-splits the unquoted `$(AW_AZ_MOUNTS)` expansion in the
-        // AWF invocation into clean `--mount <spec>` tokens. The value
-        // contains only path chars, `:`, and spaces — no shell
-        // metachars — so unquoted expansion is safe.
+        // 2. Conditional prompt append — appends an "Azure CLI" section
+        //    to `/tmp/awf-tools/agent-prompt.md` so the agent knows
+        //    `az` is on PATH inside the sandbox, what it's good for,
+        //    and the auth model. Gated by
+        //    `condition: ne(variables['AW_AZ_MOUNTS'], '')` so the
+        //    agent only sees the advisory on runners where az was
+        //    actually detected. The detection step above is the source
+        //    of truth for that variable and MUST run first.
         //
-        // Both branches MUST set the variable (the else branch sets it
-        // to empty string). If left undefined, ADO leaves the literal
-        // `$(AW_AZ_MOUNTS)` in subsequent bash steps, where bash
-        // interprets it as a `$(...)` command substitution, tries to
-        // run a program named `AW_AZ_MOUNTS`, gets exit 127, and the
-        // AWF invocation step dies under `set -e` — the opposite of
-        // graceful degradation. Defining the variable as empty makes
-        // ADO expand it to nothing, leaving a harmless `\`-continuation.
-        //
-        // Warning text is intentionally short and operator-facing.
-        // Agents that don't invoke `az` are unaffected; agents that do
-        // will get a normal "command not found" inside the sandbox.
-        let step = r###"- bash: |
+        // We do not implement `prompt_supplement()` because the
+        // existing `wrap_prompt_append` helper doesn't emit a
+        // `condition:` field. Emitting our own step here keeps the
+        // trait API unchanged and confines the conditionality entirely
+        // to this extension.
+        vec![self.detection_step(), self.prompt_append_step()]
+    }
+}
+
+impl AzureCliExtension {
+    /// Bash step that detects azure-cli on the host and sets the
+    /// `AW_AZ_MOUNTS` pipeline variable. Always runs.
+    ///
+    /// Detection checks BOTH `/usr/bin/az` (the launcher shim) and
+    /// `/opt/az` (the Python venv that az actually runs in). Mounting
+    /// only one of the two would leave az partially available and
+    /// produce confusing errors inside the sandbox.
+    ///
+    /// The setvariable value uses spaces between args so bash
+    /// word-splits the unquoted `$(AW_AZ_MOUNTS)` expansion in the
+    /// AWF invocation into clean `--mount <spec>` tokens. The value
+    /// contains only path chars, `:`, and spaces — no shell
+    /// metachars — so unquoted expansion is safe.
+    ///
+    /// Both branches MUST set the variable (the else branch sets it
+    /// to empty string). If left undefined, ADO leaves the literal
+    /// `$(AW_AZ_MOUNTS)` in subsequent bash steps, where bash
+    /// interprets it as a `$(...)` command substitution, tries to
+    /// run a program named `AW_AZ_MOUNTS`, gets exit 127, and the
+    /// AWF invocation step dies under `set -e` — the opposite of
+    /// graceful degradation. Defining the variable as empty makes
+    /// ADO expand it to nothing, leaving a harmless `\`-continuation.
+    fn detection_step(&self) -> String {
+        r###"- bash: |
     set -eo pipefail
     if [ -f /usr/bin/az ] && [ -d /opt/az ]; then
       echo "##vso[task.setvariable variable=AW_AZ_MOUNTS]--mount /opt/az:/opt/az:ro --mount /usr/bin/az:/usr/bin/az:ro"
@@ -136,8 +157,50 @@ impl CompilerExtension for AzureCliExtension {
       echo "##vso[task.logissue type=warning]Azure CLI not detected on this runner (missing /usr/bin/az or /opt/az). The az command will not be available inside the agent sandbox. Install azure-cli on the runner image to enable it."
     fi
   displayName: "Detect Azure CLI on host (for AWF mount)"
-"###;
-        vec![step.to_string()]
+"###
+        .to_string()
+    }
+
+    /// Conditional `cat >>` step that appends an Azure CLI advisory
+    /// section to the agent prompt file at pipeline time, only when
+    /// the detection step above set `AW_AZ_MOUNTS` to non-empty.
+    ///
+    /// Uses a SINGLE-QUOTED heredoc delimiter (`<< 'AZURE_CLI_PROMPT_EOF'`)
+    /// so `$AZURE_DEVOPS_EXT_PAT` and any other dollar references inside
+    /// the prompt body are appended literally rather than expanded by
+    /// bash. The closing delimiter is indented to match the bash block
+    /// scalar style used by `wrap_prompt_append`.
+    ///
+    /// The `condition:` clause uses an ADO runtime expression. ADO
+    /// evaluates it at step start against the variables visible at
+    /// that moment — the detection step above has already run by
+    /// then (steps execute sequentially within a job), so the
+    /// expression sees the value just written by `setvariable`.
+    ///
+    /// displayName must stay in sync with the entry in
+    /// `tests/bash_lint_tests.rs::REQUIRED_STEP_DISPLAY_NAMES`.
+    fn prompt_append_step(&self) -> String {
+        r#"- bash: |
+    cat >> "/tmp/awf-tools/agent-prompt.md" << 'AZURE_CLI_PROMPT_EOF'
+
+    ---
+
+    ## Azure CLI (`az`)
+
+    The Azure CLI is available inside this sandbox at `/usr/bin/az`. Prefer it over hand-rolled curl calls when it covers what you need:
+
+    - **Azure DevOps management** — `az devops`, `az pipelines`, `az repos`, `az boards`. These are authenticated automatically from `$AZURE_DEVOPS_EXT_PAT` when the pipeline declares `permissions: read:`. List/inspect operations Just Work; write operations honour the PAT's scopes.
+    - **Azure Resource Manager** — `az resource`, `az account`, `az group`. These require a separate Azure identity that ado-aw does not provision out of the box; sign in with `az login` using credentials supplied by another mechanism (e.g. a service connection writing them into your sandbox env) before invoking them.
+    - **Microsoft Graph** — `az ad`, `az rest`. Same caveat as ARM.
+
+    If a command you need isn't covered above, file a `missing-tool` safe output naming `azure-cli` so the operator can extend coverage rather than blocking on it silently.
+    AZURE_CLI_PROMPT_EOF
+
+    echo "Azure CLI prompt appended"
+  displayName: "Append Azure CLI prompt"
+  condition: ne(variables['AW_AZ_MOUNTS'], '')
+"#
+        .to_string()
     }
 }
 
@@ -189,22 +252,27 @@ mod tests {
         let fm = fm();
         let ctx = CompileContext::for_test(&fm);
         let steps = ext.prepare_steps(&ctx);
+        // Two prepare steps: [0] detection (always runs), [1] conditional
+        // prompt-append (skipped when AW_AZ_MOUNTS is empty). The
+        // detection step MUST stay at index 0 — it is what sets the
+        // pipeline variable that the prompt-append step's
+        // `condition:` reads.
         assert_eq!(
             steps.len(),
-            1,
-            "expected exactly one prepare step (the az detection step), got: {steps:?}"
+            2,
+            "expected two prepare steps (detection, conditional prompt-append), got: {steps:?}"
         );
         let step = &steps[0];
         // Detection must check both the launcher shim and the venv
         // directory — mounting only one would leave az partially
         // available and produce confusing errors inside the sandbox.
         assert!(
             step.contains("[ -f /usr/bin/az ]"),
-            "prepare step must test for /usr/bin/az launcher: {step}"
+            "first prepare step (detection) must test for /usr/bin/az launcher: {step}"
         );
         assert!(
             step.contains("[ -d /opt/az ]"),
-            "prepare step must test for /opt/az venv directory: {step}"
+            "first prepare step (detection) must test for /opt/az venv directory: {step}"
         );
     }
 
@@ -316,6 +384,108 @@ mod tests {
         );
     }
 
+    // ── Conditional prompt-append step (step index 1) ──────────────────────
+
+    #[test]
+    fn test_azure_cli_prompt_append_step_is_conditional() {
+        // The prompt-append step MUST be gated by the AW_AZ_MOUNTS
+        // pipeline variable so the agent only sees Azure CLI guidance
+        // on runners where az was actually detected. Without this
+        // gate the agent on a runner without az would be told to use
+        // `az devops ...` and then fail with "command not found".
+        let ext = AzureCliExtension;
+        let fm = fm();
+        let ctx = CompileContext::for_test(&fm);
+        let steps = ext.prepare_steps(&ctx);
+        let append = &steps[1];
+        assert!(
+            append.contains("condition: ne(variables['AW_AZ_MOUNTS'], '')"),
+            "prompt-append step must be gated by condition: \
+             ne(variables['AW_AZ_MOUNTS'], '') so it is skipped when \
+             az is not detected on the host. Step:\n{append}"
+        );
+    }
+
+    #[test]
+    fn test_azure_cli_prompt_append_step_targets_agent_prompt_file() {
+        // Must `cat >>` to the same path other extensions' supplements
+        // use (the conventional `wrap_prompt_append` target) so the
+        // agent reads everything from one file.
+        let ext = AzureCliExtension;
+        let fm = fm();
+        let ctx = CompileContext::for_test(&fm);
+        let append = &ext.prepare_steps(&ctx)[1];
+        assert!(
+            append.contains(r#"cat >> "/tmp/awf-tools/agent-prompt.md""#),
+            "prompt-append step must append to /tmp/awf-tools/agent-prompt.md \
+             (matching wrap_prompt_append). Step:\n{append}"
+        );
+    }
+
+    #[test]
+    fn test_azure_cli_prompt_append_step_has_advisory_anchors() {
+        // Lock the advisory wording to the load-bearing parts: tool
+        // names, env var, and the missing-tool escape hatch. Style
+        // changes elsewhere in the prose are free; these anchors aren't.
+        let ext = AzureCliExtension;
+        let fm = fm();
+        let ctx = CompileContext::for_test(&fm);
+        let append = &ext.prepare_steps(&ctx)[1];
+        for anchor in [
+            "Azure CLI",
+            "/usr/bin/az",
+            "az devops",
+            "AZURE_DEVOPS_EXT_PAT",
+            "missing-tool",
+        ] {
+            assert!(
+                append.contains(anchor),
+                "prompt-append step must contain anchor `{anchor}`. Step:\n{append}"
+            );
+        }
+    }
+
+    #[test]
+    fn test_azure_cli_prompt_append_uses_single_quoted_heredoc() {
+        // The advisory body contains `$AZURE_DEVOPS_EXT_PAT` and other
+        // literal dollar references. Single-quoting the heredoc
+        // delimiter (`<< 'DELIM'`) is what prevents bash from
+        // expanding them while building the prompt file. If anyone
+        // ever swaps to an unquoted heredoc, `$AZURE_DEVOPS_EXT_PAT`
+        // would be replaced by the runner's PAT value (a secret) and
+        // baked into the agent prompt — a real leak.
+        let ext = AzureCliExtension;
+        let fm = fm();
+        let ctx = CompileContext::for_test(&fm);
+        let append = &ext.prepare_steps(&ctx)[1];
+        assert!(
+            append.contains("<< 'AZURE_CLI_PROMPT_EOF'"),
+            "prompt-append heredoc delimiter must be single-quoted to \
+             prevent expansion of $AZURE_DEVOPS_EXT_PAT and similar \
+             literals inside the prompt body. Step:\n{append}"
+        );
+    }
+
+    #[test]
+    fn test_azure_cli_prompt_append_displayname_matches_lint_list() {
+        // The lint test in tests/bash_lint_tests.rs has a coverage
+        // list (REQUIRED_STEP_DISPLAY_NAMES) keyed on displayName.
+        // If we ever rename this step the lint stops exercising it
+        // silently. Lockstep the exact string here so a future rename
+        // forces an explicit update in both places.
+        let ext = AzureCliExtension;
+        let fm = fm();
+        let ctx = CompileContext::for_test(&fm);
+        let append = &ext.prepare_steps(&ctx)[1];
+        assert!(
+            append.contains(r#"displayName: "Append Azure CLI prompt""#),
+            "prompt-append step displayName must be exactly \
+             \"Append Azure CLI prompt\" to match the coverage entry \
+             in tests/bash_lint_tests.rs::REQUIRED_STEP_DISPLAY_NAMES. \
+             Step:\n{append}"
+        );
+    }
+
     #[test]
     fn test_azure_cli_required_bash_commands_includes_az() {
         let ext = AzureCliExtension;

tests/bash_lint_tests.rs

@@ -115,6 +115,7 @@ const REQUIRED_STEP_DISPLAY_NAMES: &[&str] = &[
     "Resolve ADO organization",               // src/engine.rs copilot_install_from_nuget (1ES, no org)
     "Append Node prompt",   // src/runtimes/node/extension.rs via wrap_prompt_append("Node")
     "Append dotnet prompt", // src/runtimes/dotnet/extension.rs via wrap_prompt_append("dotnet")
+    "Append Azure CLI prompt", // src/compile/extensions/azure_cli.rs conditional prompt-append step
     "ado-aw",               // src/compile/extensions/ado_aw_marker.rs metadata marker step
 ];