[plan] Add compile-time warning when write permissions appear directly on agent job #19541

Objective

Add a validation warning during gh aw compile (or make compile) when write permissions (e.g., issues: write, pull-requests: write, contents: write) are found directly in the agent job's permissions block. The correct pattern is to keep the agent job read-only and route all writes through safe-outputs.

Background

Discussion #19488 (Agent Persona Exploration report) identified that one AI-generated workflow placed issues: write directly on the agent job instead of relying exclusively on safe-outputs. This is a security anti-pattern: the agent job should stay read-only, and writes should be performed by the safe-outputs system using a scoped GitHub App token.

Approach

1. In pkg/workflow/permissions_validation.go (or pkg/workflow/compiler.go in validateWorkflowData()), add a check that iterates the agent job's permissions block.
2. If any write-level permission is found on the agent job itself, emit a console.FormatWarningMessage (not a hard error, since there may be valid edge cases).
3. The warning message should explain the preferred pattern:

   ⚠️ Agent job has issues: write permission. Best practice is to keep the agent job read-only and use safe-outputs for all writes. See docs/safe-outputs.md.

4. Add a unit test in the relevant *_test.go file covering:
   • Agent job with write permission → warning emitted
   • Agent job with only read permissions → no warning
   • Agent job with safe-outputs configured + write permission → warning still emitted (pattern clarification)

Files to Modify

• pkg/workflow/permissions_validation.go — add write-on-agent-job detection logic
• pkg/workflow/compiler.go — wire up the new validation in validateWorkflowData()
• pkg/workflow/permissions_validation_test.go (or new test file) — add unit tests

Acceptance Criteria

• gh aw compile prints a warning (not error) when a write permission is found on the agent job
• Warning message is actionable and points to the safe-outputs pattern
• Unit tests cover the warning and non-warning paths
• make agent-finish passes (fmt, lint, test-unit)

Generated by Plan Command for issue #discussion #19488 · ◷

• expires on Mar 6, 2026, 8:04 AM UTC