feat: replace read-only-service-connection with permissions field (#26)

Replace the single 
ead-only-service-connection front matter field with a
structured permissions field that models ADO's two access levels via separate
ARM service connections:

- permissions.read: mints a read-only token for the agent (Stage 1)
- permissions.write: mints a write token for the executor (Stage 2 only)

System.AccessToken is no longer used for agent or executor operations.

Key changes:
- Add PermissionsConfig type with read/write service connection fields
- Generate separate SC_READ_TOKEN and SC_WRITE_TOKEN pipeline variables
- Add compile-time validation: fail if write safe-outputs lack permissions.write
- Update both standalone and 1ES compilers and templates
- Add Permissions step to interactive creation wizard
- Add 5 integration tests covering all permission combinations
- Update AGENTS.md documentation

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

Author: jamesadevine

AGENTS.md

@@ -177,7 +177,9 @@ network:                       # optional network policy (standalone target only
     - "*.mycompany.com"
   blocked:                     # blocked host patterns (takes precedence over allow)
     - "evil.example.com"
-read-only-service-connection: my-arm-connection  # optional: ARM service connection for read-only ADO token
+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 2 executor only)
 ---
 
 
@@ -568,20 +570,37 @@ Should be replaced with the description field from the front matter. This is use
 
 ## {{ acquire_ado_token }}
 
-Generates an `AzureCLI@2` step that acquires an Azure DevOps-scoped access token from an ARM service connection. This is only generated when `read-only-service-connection` is configured in the front matter.
+Generates an `AzureCLI@2` step that acquires a read-only ADO-scoped access token from the ARM service connection specified in `permissions.read`. This token is used by the agent in Stage 1 (inside the AWF sandbox).
 
 The step:
-- Uses the specified ARM service connection
+- Uses the ARM service connection from `permissions.read`
 - Calls `az account get-access-token` with the ADO resource ID
-- Stores the token in a secret pipeline variable `SC_ACCESS_TOKEN`
+- Stores the token in a secret pipeline variable `SC_READ_TOKEN`
 
-If no `read-only-service-connection` is configured, this marker is replaced with an empty string.
+If `permissions.read` is not configured, this marker is replaced with an empty string.
 
 ## {{ copilot_ado_env }}
 
-Generates environment variable entries for the copilot AWF step when `read-only-service-connection` is configured. Sets both `AZURE_DEVOPS_EXT_PAT` and `SYSTEM_ACCESSTOKEN` to the service connection token.
+Generates environment variable entries for the copilot AWF step when `permissions.read` is configured. Sets both `AZURE_DEVOPS_EXT_PAT` and `SYSTEM_ACCESSTOKEN` to the read service connection token (`SC_READ_TOKEN`).
 
-If no `read-only-service-connection` is configured, this marker is replaced with an empty string, and ADO access tokens are omitted from the copilot invocation.
+If `permissions.read` is not configured, this marker is replaced with an empty string, and ADO access tokens are omitted from the copilot invocation.
+
+## {{ 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 2 (`ProcessSafeOutputs` job) 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.
+
+## {{ executor_ado_env }}
+
+Generates environment variable entries for the Stage 2 executor step when `permissions.write` is configured. Sets `SYSTEM_ACCESSTOKEN` to the write service connection token (`SC_WRITE_TOKEN`).
+
+If `permissions.write` is not configured, this marker is replaced with an empty string. Note: `System.AccessToken` is never used directly — all ADO tokens come from explicitly configured service connections.
 
 ## {{ compiler_version }}
 
@@ -1030,22 +1049,42 @@ network:
 
 All hosts (core + MCP-specific + user-specified) are combined into a comma-separated domain list passed to AWF's `--allow-domains` flag.
 
-### Read-Only Service Connection
+### Permissions (ADO Access Tokens)
 
-For agents that need read-only access to Azure DevOps resources (e.g., reading repository information), you can configure an ARM service connection to provide a scoped access token:
+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.
 
 ```yaml
-read-only-service-connection: my-arm-connection
+permissions:
+  read: my-read-arm-connection    # Stage 1 agent — read-only ADO access
+  write: my-write-arm-connection  # Stage 2 executor — write access for safe-outputs
 ```
 
-When configured:
-- The pipeline mints an ADO-scoped token from the ARM service connection
-- The token is passed to the copilot via `AZURE_DEVOPS_EXT_PAT` and `SYSTEM_ACCESSTOKEN`
-- This allows the agent to authenticate to ADO APIs without using the pipeline's default System.AccessToken
+#### 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`**: Mints a write-capable ADO-scoped token used **only** by the executor in Stage 2 (`ProcessSafeOutputs` job). This token is never exposed to the agent.
+- **Both omitted**: No ADO tokens are passed anywhere. The agent has no ADO API access.
+
+#### Compile-Time Validation
+
+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.
 
-When not configured:
-- ADO access tokens are omitted from the copilot invocation
-- The agent cannot authenticate to ADO APIs
+#### Examples
+
+```yaml
+# Agent can read ADO, safe-outputs can write
+permissions:
+  read: my-read-sc
+  write: my-write-sc
+
+# Agent can read ADO, no write safe-outputs needed
+permissions:
+  read: my-read-sc
+
+# Agent has no ADO access, but safe-outputs can create PRs/work items
+permissions:
+  write: my-write-sc
+```
 
 ## MCP Firewall
 

src/compile/common.rs

@@ -486,6 +486,99 @@ pub fn generate_pipeline_path(output_path: &std::path::Path) -> String {
     format!("{{{{ workspace }}}}/{}", filename)
 }
 
+// ==================== Permission helpers ====================
+
+/// ADO resource ID for minting ADO-scoped tokens via Azure CLI.
+const ADO_RESOURCE_ID: &str = "499b84ac-1321-427f-aa17-267ca6975798";
+
+/// Generate an AzureCLI@2 step to acquire an ADO-scoped token from an ARM service connection.
+/// The `variable_name` parameter controls which pipeline variable the token is stored in
+/// (e.g. "SC_READ_TOKEN" for the agent, "SC_WRITE_TOKEN" for the executor).
+/// Returns empty string if no service connection is provided.
+pub fn generate_acquire_ado_token(service_connection: Option<&str>, variable_name: &str) -> String {
+    match service_connection {
+        Some(sc) => {
+            let mut lines = Vec::new();
+            lines.push("- task: AzureCLI@2".to_string());
+            lines.push(format!(
+                r#"  displayName: "Acquire ADO token ({variable_name})""#
+            ));
+            lines.push("  inputs:".to_string());
+            lines.push(format!("    azureSubscription: '{}'", sc));
+            lines.push("    scriptType: 'bash'".to_string());
+            lines.push("    scriptLocation: 'inlineScript'".to_string());
+            lines.push("    addSpnToEnvironment: true".to_string());
+            lines.push("    inlineScript: |".to_string());
+            lines.push("      ADO_TOKEN=$(az account get-access-token \\".to_string());
+            lines.push(format!(
+                "        --resource {} \\",
+                ADO_RESOURCE_ID
+            ));
+            lines.push("        --query accessToken -o tsv)".to_string());
+            lines.push(format!(
+                "      echo \"##vso[task.setvariable variable={variable_name};issecret=true]$ADO_TOKEN\""
+            ));
+            lines.join("\n")
+        }
+        None => String::new(),
+    }
+}
+
+/// Generate the env block entries for the copilot AWF step (Stage 1 agent).
+/// Uses the read-only token from the read service connection.
+/// When not configured, omits ADO access tokens entirely.
+pub fn generate_copilot_ado_env(read_service_connection: Option<&str>) -> String {
+    match read_service_connection {
+        Some(_) => {
+            "AZURE_DEVOPS_EXT_PAT: $(SC_READ_TOKEN)\nSYSTEM_ACCESSTOKEN: $(SC_READ_TOKEN)"
+                .to_string()
+        }
+        None => String::new(),
+    }
+}
+
+/// Generate the env block entries for the executor step (Stage 2 ProcessSafeOutputs).
+/// Uses the write token from the write service connection.
+/// When not configured, omits ADO access tokens entirely.
+pub fn generate_executor_ado_env(write_service_connection: Option<&str>) -> String {
+    match write_service_connection {
+        Some(_) => "SYSTEM_ACCESSTOKEN: $(SC_WRITE_TOKEN)".to_string(),
+        None => String::new(),
+    }
+}
+
+/// Safe-output names that require write access to ADO.
+const WRITE_REQUIRING_SAFE_OUTPUTS: &[&str] = &["create-pull-request", "create-work-item"];
+
+/// Validate that write-requiring safe-outputs have a write service connection configured.
+pub fn validate_write_permissions(front_matter: &FrontMatter) -> Result<()> {
+    let has_write_sc = front_matter
+        .permissions
+        .as_ref()
+        .is_some_and(|p| p.write.is_some());
+
+    if has_write_sc {
+        return Ok(());
+    }
+
+    let missing: Vec<&str> = WRITE_REQUIRING_SAFE_OUTPUTS
+        .iter()
+        .filter(|name| front_matter.safe_outputs.contains_key(**name))
+        .copied()
+        .collect();
+
+    if !missing.is_empty() {
+        anyhow::bail!(
+            "Safe outputs [{}] require write access to ADO, but no write service connection \
+             is configured. Add a 'permissions.write' field to the front matter:\n\n  \
+             permissions:\n    write: <your-write-arm-service-connection>\n",
+            missing.join(", ")
+        );
+    }
+
+    Ok(())
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

src/compile/mod.rs

@@ -18,7 +18,7 @@ use std::path::{Path, PathBuf};
 
 pub use common::parse_markdown;
 pub use common::sanitize_filename;
-pub use types::{CompileTarget, FrontMatter};
+pub use types::{CompileTarget, FrontMatter, PermissionsConfig};
 
 /// Trait for pipeline compilers.
 ///

src/compile/onees.rs

@@ -18,10 +18,11 @@ use std::path::Path;
 use super::Compiler;
 use super::common::{
     self, AWF_VERSION, DEFAULT_POOL, compute_effective_workspace, generate_copilot_params,
-    generate_checkout_self, generate_checkout_steps, generate_ci_trigger,
+    generate_acquire_ado_token, generate_checkout_self, generate_checkout_steps,
+    generate_ci_trigger, generate_copilot_ado_env, generate_executor_ado_env,
     generate_pipeline_path, generate_pipeline_resources, generate_pr_trigger,
     generate_repositories, generate_schedule, generate_source_path,
-    generate_working_directory, replace_with_indent,
+    generate_working_directory, replace_with_indent, validate_write_permissions,
 };
 use super::types::{FrontMatter, McpConfig};
 
@@ -113,6 +114,25 @@ displayName: "Finalize""#,
             threat_analysis_prompt,
         );
 
+        // Generate service connection token acquisition steps and env vars
+        let acquire_read_token = generate_acquire_ado_token(
+            front_matter.permissions.as_ref().and_then(|p| p.read.as_deref()),
+            "SC_READ_TOKEN",
+        );
+        let copilot_ado_env = generate_copilot_ado_env(
+            front_matter.permissions.as_ref().and_then(|p| p.read.as_deref()),
+        );
+        let acquire_write_token = generate_acquire_ado_token(
+            front_matter.permissions.as_ref().and_then(|p| p.write.as_deref()),
+            "SC_WRITE_TOKEN",
+        );
+        let executor_ado_env = generate_executor_ado_env(
+            front_matter.permissions.as_ref().and_then(|p| p.write.as_deref()),
+        );
+
+        // Validate that write-requiring safe-outputs have a write service connection
+        validate_write_permissions(front_matter)?;
+
         // Replace all template markers
         let compiler_version = env!("CARGO_PKG_VERSION");
         let replacements: Vec<(&str, &str)> = vec![
@@ -143,6 +163,10 @@ displayName: "Finalize""#,
             ("{{ pipeline_path }}", &pipeline_path),
             ("{{ working_directory }}", &working_directory),
             ("{{ agency_params }}", &agency_params),
+            ("{{ acquire_ado_token }}", &acquire_read_token),
+            ("{{ copilot_ado_env }}", &copilot_ado_env),
+            ("{{ acquire_write_token }}", &acquire_write_token),
+            ("{{ executor_ado_env }}", &executor_ado_env),
         ];
 
         let pipeline_yaml = replacements

src/compile/standalone.rs

@@ -15,10 +15,12 @@ use std::path::Path;
 use super::Compiler;
 use super::common::{
     self, AWF_VERSION, DEFAULT_POOL, compute_effective_workspace, generate_copilot_params,
-    generate_cancel_previous_builds, generate_checkout_self, generate_checkout_steps,
-    generate_ci_trigger, generate_pipeline_path, generate_pipeline_resources, generate_pr_trigger,
-    generate_repositories, generate_schedule, generate_source_path, generate_working_directory,
-    replace_with_indent, sanitize_filename,
+    generate_acquire_ado_token, generate_cancel_previous_builds, generate_checkout_self,
+    generate_checkout_steps, generate_ci_trigger, generate_copilot_ado_env,
+    generate_executor_ado_env, generate_pipeline_path, generate_pipeline_resources,
+    generate_pr_trigger, generate_repositories, generate_schedule, generate_source_path,
+    generate_working_directory, replace_with_indent, sanitize_filename,
+    validate_write_permissions,
 };
 use super::types::{FrontMatter, McpConfig};
 use crate::allowed_hosts::{CORE_ALLOWED_HOSTS, mcp_required_hosts};
@@ -104,10 +106,24 @@ impl Compiler for StandaloneCompiler {
         let finalize_steps = generate_finalize_steps(&front_matter.post_steps);
         let agentic_depends_on = generate_agentic_depends_on(&front_matter.setup);
 
-        // Generate service connection token acquisition step and env vars
-        let acquire_ado_token =
-            generate_acquire_ado_token(&front_matter.read_only_service_connection);
-        let copilot_ado_env = generate_copilot_ado_env(&front_matter.read_only_service_connection);
+        // Generate service connection token acquisition steps and env vars
+        let acquire_read_token = generate_acquire_ado_token(
+            front_matter.permissions.as_ref().and_then(|p| p.read.as_deref()),
+            "SC_READ_TOKEN",
+        );
+        let copilot_ado_env = generate_copilot_ado_env(
+            front_matter.permissions.as_ref().and_then(|p| p.read.as_deref()),
+        );
+        let acquire_write_token = generate_acquire_ado_token(
+            front_matter.permissions.as_ref().and_then(|p| p.write.as_deref()),
+            "SC_WRITE_TOKEN",
+        );
+        let executor_ado_env = generate_executor_ado_env(
+            front_matter.permissions.as_ref().and_then(|p| p.write.as_deref()),
+        );
+
+        // Validate that write-requiring safe-outputs have a write service connection
+        validate_write_permissions(front_matter)?;
 
         // Load threat analysis prompt template
         let threat_analysis_prompt = include_str!("../../templates/threat-analysis.md");
@@ -148,8 +164,10 @@ impl Compiler for StandaloneCompiler {
             ("{{ workspace }}", &working_directory),
             ("{{ allowed_domains }}", &allowed_domains),
             ("{{ agent_content }}", markdown_body),
-            ("{{ acquire_ado_token }}", &acquire_ado_token),
+            ("{{ acquire_ado_token }}", &acquire_read_token),
             ("{{ copilot_ado_env }}", &copilot_ado_env),
+            ("{{ acquire_write_token }}", &acquire_write_token),
+            ("{{ executor_ado_env }}", &executor_ado_env),
         ];
 
         let pipeline_yaml = replacements
@@ -408,46 +426,6 @@ pub fn generate_firewall_config(front_matter: &FrontMatter) -> FirewallConfig {
     }
 }
 
-/// Generate the AzureCLI@2 step to acquire an ADO-scoped token from an ARM service connection.
-/// Returns empty string if no service connection is configured.
-fn generate_acquire_ado_token(service_connection: &Option<String>) -> String {
-    match service_connection {
-        Some(sc) => {
-            let mut lines = Vec::new();
-            lines.push("- task: AzureCLI@2".to_string());
-            lines.push(r#"  displayName: "Get ADO token from service connection""#.to_string());
-            lines.push("  inputs:".to_string());
-            lines.push(format!("    azureSubscription: '{}'", sc));
-            lines.push("    scriptType: 'bash'".to_string());
-            lines.push("    scriptLocation: 'inlineScript'".to_string());
-            lines.push("    addSpnToEnvironment: true".to_string());
-            lines.push("    inlineScript: |".to_string());
-            lines.push("      ADO_TOKEN=$(az account get-access-token \\".to_string());
-            lines.push("        --resource 499b84ac-1321-427f-aa17-267ca6975798 \\".to_string());
-            lines.push("        --query accessToken -o tsv)".to_string());
-            lines.push(
-                "      echo \"##vso[task.setvariable variable=SC_ACCESS_TOKEN;issecret=true]$ADO_TOKEN\""
-                    .to_string(),
-            );
-            lines.join("\n")
-        }
-        None => String::new(),
-    }
-}
-
-/// Generate the env block entries for the copilot AWF step.
-/// When a service connection is configured, uses the SC token.
-/// When not configured, omits ADO access tokens entirely.
-fn generate_copilot_ado_env(service_connection: &Option<String>) -> String {
-    match service_connection {
-        Some(_) => {
-            "AZURE_DEVOPS_EXT_PAT: $(SC_ACCESS_TOKEN)\nSYSTEM_ACCESSTOKEN: $(SC_ACCESS_TOKEN)"
-                .to_string()
-        }
-        None => String::new(),
-    }
-}
-
 /// Generate the steps to download agent memory from the previous successful run
 /// and restore it to the staging directory.
 fn generate_memory_download() -> String {