Fix custom safe-outputs documentation: correct agent data access pattern

[Copilot]

Documentation incorrectly showed custom safe-output jobs accessing agent data via ${{ inputs.message }} expressions. This syntax doesn't work—jobs must read from the GH_AW_AGENT_OUTPUT JSON file.

Changes

Corrected all examples to use proper agent output access:

• Quick Start: Slack notification example
• Complete Example: Webhook notification (switched to JavaScript)
• Notion integration: API comment posting
• Environment variables table: removed misleading ${{ inputs.NAME }} row

Added "Accessing Agent Output" section with working patterns:

# Bash pattern
MESSAGE=$(cat "$GH_AW_AGENT_OUTPUT" | jq -r '.items[] | select(.type == "my_job") | .message')

// JavaScript pattern
const agentOutput = JSON.parse(fs.readFileSync(process.env.GH_AW_AGENT_OUTPUT, 'utf8'));
const items = agentOutput.items.filter(item => item.type === 'my_job');

Added "Understanding inputs:" section clarifying:

• inputs: defines MCP tool schema for AI agent
• Does NOT create workflow inputs or enable ${{ inputs.* }} expressions
• Agent writes values to GH_AW_AGENT_OUTPUT JSON file

Added "Common Mistakes" section documenting:

• Using ${{ inputs.* }} syntax (won't work)
• Wrong type filter (job names: dashes → underscores in JSON)
• Missing file existence checks

Evidence

Working examples in codebase already use correct pattern:

• pkg/cli/workflows/test-copilot-safe-jobs.md
• pkg/cli/workflows/test-claude-safe-jobs.md
• pkg/cli/templates/create-shared-agentic-workflow.md
• pkg/cli/workflows/shared/mcp/slack.md

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• telemetry.astro.build
  • Triggering command: /opt/hostedtoolcache/node/24.13.0/x64/bin/node node /home/REDACTED/work/gh-aw/gh-aw/docs/node_modules/.bin/astro build bash --no�� js/**/*.json' --ignore-path ../../../.prettierignore (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Behaviour of custom safe outputs inputs not matching docs</issue_title>
<issue_description>I'm looking in to a bug in safe-outputs

Trying to understand if it's a bug in docs, implementation, or test,

I'm following instructions here: https://githubnext.github.io/gh-aw/guides/custom-safe-outputs/

But inputs.message is not being set. Equally I can't quite see who/what should be setting this. Wondering if docs are wrong.

Workflow is here: https://github.com/githubnext/gh-aw-test/blob/main/.github/workflows/test-claude-safe-jobs.md?plain=1

---
on: 
  workflow_dispatch:

permissions: read-all

engine: claude

safe-outputs:
  jobs:
    print:
      #name: "print the message"
      runs-on: ubuntu-latest
      inputs:
        message:
          description: "Message to print"
          required: true
          type: string
      steps:
        - name: print message
          env:
            MESSAGE: "${{ inputs.message }}"
          run: |
              if [ -z "$MESSAGE" ]; then
                echo "Error: message is empty"
                exit 1
              fi
              echo "print: $MESSAGE"
              echo "### Print Step Summary" >> "$GITHUB_STEP_SUMMARY"
              echo "$MESSAGE" >> "$GITHUB_STEP_SUMMARY"    
            
---
Summarize and use print the message using the `print` tool.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Lock file here: https://github.com/githubnext/gh-aw-test/blob/main/.github/workflows/test-claude-safe-jobs.lock.yml?plain=1

Looking at other examples uses of inputs: in safe outputs in gh-aw files, they seem to process like this:
const outputContent = process.env.GH_AW_AGENT_OUTPUT;

....
Ian't find an example that goes via inputs like the docs say

I'm asking what the spec is.

Question is whether it is it right to expect this to work, as it says in the docs:
env:
MESSAGE: "${{ inputs.message }}"

This seems unlikely. Inputs is reserved for workflow inputs as far as I can tell. I think the docs have been hallucinated here.

AFAICS all that is available is GH_AW_AGENT_OUTPUT env var and the use code must process that.

I won't fix it just yet, will write it up as an issue for your guidance on how the safe output job gets the agent output.</issue_description>

Comments on the Issue (you are @copilot in this section)

@dsyme # Bug: Documentation Incorrectly Shows `${{ inputs.* }}` Usage in Custom Safe-Output Jobs

Summary

The Custom Safe Outputs documentation incorrectly suggests that custom safe-output jobs can access agent-provided data via ${{ inputs.message }} or similar expressions. This is misleading - safe-output jobs must instead read from the GH_AW_AGENT_OUTPUT environment variable and parse the JSON file.

Incorrect Documentation

Location: docs/src/content/docs/guides/custom-safe-outputs.md

Issue 1: Environment Variables Table (lines 272-279)

| Variable | Description |
|----------|-------------|
| `GH_AW_AGENT_OUTPUT` | Path to JSON file with agent output |
| `GH_AW_SAFE_OUTPUTS_STAGED` | Set to `"true"` in staged mode |
| `${{ inputs.NAME }}` | Each input as a variable |  ❌ WRONG

Access inputs using `${{ inputs.name }}` in steps or via `process.env` in JavaScript.  ❌ WRONG

Issue 2: Complete Example (lines 282-310)

safe-outputs:
  jobs:
    webhook-notify:
      description: "Send a notification to a webhook URL"
      runs-on: ubuntu-latest
      output: "Notification sent!"
      inputs:
        title:
          description: "Notification title"
          required: true
          type: string
        body:
          description: "Notification body"
          required: true
          type: string
      steps:
        - name: Send webhook
          env:
            WEBHOOK_URL: "${{ secrets.WEBHOOK_URL }}"
            TITLE: "${{ inputs.title }}"           ❌ WRONG
            BODY: "${{ inputs.body }}"             ❌ WRONG
          run: |
            PAYLOAD=$(jq -n --arg title "$TITLE" --arg body "$BODY" \
              '{title: $title, body: $body}')
            curl -X POST "$WEBHOOK_URL" \
              -H "Content-Type: application/json" \
              -d "$PAYLOAD"

Issue 3: Quick Start Example (lines 30-45)

The Quick Start example has the same issue:

- name: Send Slack message
  env:
    SLACK_WEBHOOK: "${{ secrets.SLACK_WEBHOOK }}...

</details>



<!-- START COPILOT CODING AGENT SUFFIX -->

- Fixes githubnext/gh-aw#11529

<!-- START COPILOT CODING AGENT TIPS -->
---

✨ Let Copilot coding agent [set things up for you](https://github.com/githubnext/gh-aw/issues/new?title=✨+Set+up+Copilot+instructions&body=Configure%20instructions%20for%20this%20repository%20as%20documented%20in%20%5BBest%20practices%20for%20Copilot%20coding%20agent%20in%20your%20repository%5D%28https://gh.io/copilot-coding-agent-tips%29%2E%0A%0A%3COnboard%20this%20repo%3E&assignees=copilot) — coding agent works faster and does higher quality work when set up for your repo.