feat: add comment-on-work-item safe output tool

Add a new safe output tool that allows agents to comment on existing
Azure DevOps work items. This is the ADO equivalent of gh-aw's
add-comment tool.

Features:
- Agent provides work_item_id and body (markdown comment text)
- Required 'target' field in frontmatter scopes which work items
  can be commented on: wildcard, specific ID(s), or area path prefix
- max field (default: 1) limits comments per run
- Area path targets validated via ADO API at Stage 2
- Compile-time validation ensures target is specified

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

Author: jamesadevine

AGENTS.md

@@ -39,6 +39,7 @@ Alongside the correctly generated pipeline yaml, an agent file is generated from
 │   ├── sanitize.rs       # Input sanitization for safe outputs
 │   └── tools/            # MCP tool implementations
 │       ├── mod.rs
+│       ├── comment_on_work_item.rs
 │       ├── create_pr.rs
 │       ├── create_wiki_page.rs
 │       ├── create_work_item.rs
@@ -759,6 +760,31 @@ Safe output configurations are passed to Stage 2 execution and used when process
 
 ### Available Safe Output Tools
 
+#### comment-on-work-item
+Adds a comment to an existing Azure DevOps work item. This is the ADO equivalent of gh-aw's `add-comment` tool.
+
+**Agent parameters:**
+- `work_item_id` - The work item ID to comment on (required, must be positive)
+- `body` - Comment text in markdown format (required, must be at least 10 characters)
+
+**Configuration options (front matter):**
+- `max` - Maximum number of comments per run (default: 1)
+- `target` - **Required** — scoping policy for which work items can be commented on:
+  - `"*"` - Any work item in the project (unrestricted, must be explicit)
+  - `12345` - A specific work item ID
+  - `[12345, 67890]` - A list of allowed work item IDs
+  - `"area:Some\\Path"` - Work items under the specified area path prefix (validated via ADO API at Stage 2)
+
+**Example configuration:**
+```yaml
+safe-outputs:
+  comment-on-work-item:
+    max: 3
+    target: "area:4x4\\QED"
+```
+
+**Note:** The `target` field is required. If omitted, compilation fails with an error. This ensures operators are intentional about which work items agents can comment on.
+
 #### create-work-item
 Creates an Azure DevOps work item.
 

src/compile/common.rs

@@ -553,7 +553,7 @@ pub fn generate_executor_ado_env(write_service_connection: Option<&str>) -> Stri
 }
 
 /// Safe-output names that require write access to ADO.
-const WRITE_REQUIRING_SAFE_OUTPUTS: &[&str] = &["create-pull-request", "create-work-item", "create-wiki-page", "update-wiki-page"];
+const WRITE_REQUIRING_SAFE_OUTPUTS: &[&str] = &["comment-on-work-item", "create-pull-request", "create-work-item", "create-wiki-page", "update-wiki-page"];
 
 /// Validate that write-requiring safe-outputs have a write service connection configured.
 pub fn validate_write_permissions(front_matter: &FrontMatter) -> Result<()> {
@@ -584,6 +584,33 @@ pub fn validate_write_permissions(front_matter: &FrontMatter) -> Result<()> {
     Ok(())
 }
 
+/// Validate that comment-on-work-item has a required `target` field when configured.
+pub fn validate_comment_target(front_matter: &FrontMatter) -> Result<()> {
+    if let Some(config_value) = front_matter.safe_outputs.get("comment-on-work-item") {
+        // Check that "target" key is present in the config
+        if let Some(obj) = config_value.as_object() {
+            if !obj.contains_key("target") {
+                anyhow::bail!(
+                    "safe-outputs.comment-on-work-item requires a 'target' field to scope \
+                     which work items the agent can comment on. Options:\n\n  \
+                     target: \"*\"           # any work item (unrestricted)\n  \
+                     target: 12345          # specific work item ID\n  \
+                     target: [12345, 67890] # list of work item IDs\n  \
+                     target: \"area:Path\"   # work items under area path prefix\n"
+                );
+            }
+        } else {
+            // If the value is not an object (e.g., `comment-on-work-item: true`), that's invalid
+            anyhow::bail!(
+                "safe-outputs.comment-on-work-item must be a configuration object with at \
+                 least a 'target' field. Example:\n\n  \
+                 safe-outputs:\n    comment-on-work-item:\n      target: \"*\"\n"
+            );
+        }
+    }
+    Ok(())
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

src/compile/onees.rs

@@ -22,7 +22,8 @@ use super::common::{
     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, validate_write_permissions,
+    generate_working_directory, replace_with_indent, validate_comment_target,
+    validate_write_permissions,
 };
 use super::types::{FrontMatter, McpConfig};
 
@@ -132,6 +133,8 @@ displayName: "Finalize""#,
 
         // Validate that write-requiring safe-outputs have a write service connection
         validate_write_permissions(front_matter)?;
+        // Validate comment-on-work-item has required target field
+        validate_comment_target(front_matter)?;
 
         // Replace all template markers
         let compiler_version = env!("CARGO_PKG_VERSION");

src/compile/standalone.rs

@@ -21,6 +21,7 @@ use super::common::{
     generate_pr_trigger, generate_repositories, generate_schedule, generate_source_path,
     generate_working_directory, replace_with_indent, sanitize_filename,
     validate_write_permissions,
+    validate_comment_target,
 };
 use super::types::{FrontMatter, McpConfig};
 use crate::allowed_hosts::{CORE_ALLOWED_HOSTS, mcp_required_hosts};
@@ -124,6 +125,8 @@ impl Compiler for StandaloneCompiler {
 
         // Validate that write-requiring safe-outputs have a write service connection
         validate_write_permissions(front_matter)?;
+        // Validate comment-on-work-item has required target field
+        validate_comment_target(front_matter)?;
 
         // Load threat analysis prompt template
         let threat_analysis_prompt = include_str!("../../templates/threat-analysis.md");

src/execute.rs

@@ -10,8 +10,8 @@ use std::path::Path;
 
 use crate::ndjson::{self, SAFE_OUTPUT_FILENAME};
 use crate::tools::{
-    CreatePrResult, CreateWikiPageResult, CreateWorkItemResult, UpdateWikiPageResult,
-    ExecutionContext, ExecutionResult, Executor,
+    CommentOnWorkItemResult, CreatePrResult, CreateWikiPageResult, CreateWorkItemResult,
+    UpdateWikiPageResult, ExecutionContext, ExecutionResult, Executor,
 };
 
 // Re-export memory types for use by main.rs
@@ -172,6 +172,17 @@ pub async fn execute_safe_output(
             );
             output.execute_sanitized(ctx).await?
         }
+        "comment-on-work-item" => {
+            debug!("Parsing comment-on-work-item payload");
+            let mut output: CommentOnWorkItemResult = serde_json::from_value(entry.clone())
+                .map_err(|e| anyhow::anyhow!("Failed to parse comment-on-work-item: {}", e))?;
+            debug!(
+                "comment-on-work-item: work_item_id={}, body length={}",
+                output.work_item_id,
+                output.body.len()
+            );
+            output.execute_sanitized(ctx).await?
+        }
         "create-pull-request" => {
             debug!("Parsing create-pull-request payload");
             let mut output: CreatePrResult = serde_json::from_value(entry.clone())
@@ -478,4 +489,46 @@ mod tests {
                 .contains("AZURE_DEVOPS_ORG_URL")
         );
     }
+
+    #[tokio::test]
+    async fn test_execute_malformed_comment_on_work_item_returns_err() {
+        // Missing required fields (work_item_id and body)
+        let entry = serde_json::json!({"name": "comment-on-work-item"});
+        let ctx = ExecutionContext::default();
+
+        let result = execute_safe_output(&entry, &ctx).await;
+        assert!(result.is_err());
+    }
+
+    #[tokio::test]
+    async fn test_execute_comment_on_work_item_missing_context() {
+        let entry = serde_json::json!({
+            "name": "comment-on-work-item",
+            "work_item_id": 12345,
+            "body": "This is a comment on the work item."
+        });
+
+        // Context without required fields (ado_org_url, etc.)
+        let ctx = ExecutionContext {
+            ado_org_url: None,
+            ado_organization: None,
+            ado_project: None,
+            access_token: None,
+            working_directory: PathBuf::from("."),
+            source_directory: PathBuf::from("."),
+            tool_configs: HashMap::new(),
+            repository_id: None,
+            repository_name: None,
+            allowed_repositories: HashMap::new(),
+        };
+
+        let result = execute_safe_output(&entry, &ctx).await;
+        assert!(result.is_err());
+        assert!(
+            result
+                .unwrap_err()
+                .to_string()
+                .contains("AZURE_DEVOPS_ORG_URL")
+        );
+    }
 }

src/mcp.rs

@@ -11,6 +11,7 @@ use std::path::PathBuf;
 use crate::ndjson::{self, SAFE_OUTPUT_FILENAME};
 use crate::sanitize::sanitize as sanitize_text;
 use crate::tools::{
+    CommentOnWorkItemParams, CommentOnWorkItemResult,
     CreatePrParams, CreatePrResult, CreateWikiPageParams, CreateWikiPageResult,
     CreateWorkItemParams, CreateWorkItemResult,
     UpdateWikiPageParams, UpdateWikiPageResult, MissingDataParams, MissingDataResult,
@@ -335,6 +336,41 @@ impl SafeOutputs {
         Ok(CallToolResult::success(vec![]))
     }
 
+    #[tool(
+        name = "comment-on-work-item",
+        description = "Add a comment to an existing Azure DevOps work item. \
+Provide the work item ID and the comment body in markdown. The comment will be \
+posted during safe output processing. Target restrictions may apply based on \
+pipeline configuration."
+    )]
+    async fn comment_on_work_item(
+        &self,
+        params: Parameters<CommentOnWorkItemParams>,
+    ) -> Result<CallToolResult, McpError> {
+        info!(
+            "Tool called: comment-on-work-item - work item #{}",
+            params.0.work_item_id
+        );
+        debug!("Body length: {} chars", params.0.body.len());
+        // Sanitize untrusted agent-provided text fields (IS-01)
+        let mut sanitized = params.0;
+        sanitized.body = sanitize_text(&sanitized.body);
+        let result: CommentOnWorkItemResult = sanitized.try_into()?;
+        let written = self.write_safe_output_file_with_maximum(&result, 1).await
+            .map_err(|e| anyhow_to_mcp_error(anyhow::anyhow!("Failed to write safe output: {}", e)))?;
+        if !written {
+            warn!("comment-on-work-item limit reached, ignoring");
+            return Ok(CallToolResult::success(vec![Content::text(
+                "Maximum number of comments reached for this run. This comment was not recorded.",
+            )]));
+        }
+        info!("Comment queued for work item #{}", result.work_item_id);
+        Ok(CallToolResult::success(vec![Content::text(format!(
+            "Comment queued for work item #{}. The comment will be posted during safe output processing.",
+            result.work_item_id
+        ))]))
+    }
+
     #[tool(
         name = "create-pull-request",
         description = "Create a new pull request to propose code changes. Use this after making file edits to submit them for review and merging. The PR will be created from the current branch with your committed changes. Use 'self' for the pipeline's own repository, or a repository alias from the checkout list."