kandev/docs/decisions/2026-08-22-agent-owned-pr-walkthrough-rendering.md

ADR-2026-08-22-agent-owned-pr-walkthrough-rendering: Keep PR walkthrough rendering agent owned and provider neutral

Status: accepted Date: 2026-08-22 Area: workflow, infra, security

Context

PR walkthrough generation starts with OpenCode, but the selected agent runner may change later. The agent must be able to correct invalid walkthrough data after seeing renderer errors, while the secret-bearing pull_request_target workflow must not grant a model broad write access or permission to execute pull-request-owned code.

Decision

The provider-neutral .agents/skills/pr-walkthrough/SKILL.md owns the complete generation procedure. The selected agent creates the walkthrough data, invokes the trusted renderer, inspects any validation error, and revises the data until both the JSON and HTML outputs exist.

Each managed agent runner supplies the narrowest adapters needed to perform that procedure. The OpenCode runner exposes base-commit-controlled render_pr_walkthrough and read_pr_file custom tools. The renderer tool accepts walkthrough JSON, binds authoritative pull-request identity from the GitHub event, removes model-owned link overrides, and runs only the trusted renderer against fixed output paths. The file tool reads only bounded regular UTF-8 blobs from the immutable pull request head Git object. It never checks the untrusted head out in the secret-bearing worktree. The runner does not grant generic edit, shell, or external-directory access. A future Codex or other runner must preserve these boundaries, follow the same skill, and produce the same artifacts.

The generated artifact is one HTML file, not a fully offline bundle. Its fixed shell loads Tailwind, Mermaid, Marked, DOMPurify, Shiki, and fonts from exact-version or commit-pinned HTTPS URLs. Those providers are an explicit runtime trust dependency. Pull request data cannot choose or override these asset URLs.

Provider installation, credentials, and invocation remain workflow adapter concerns. They must not be embedded in the walkthrough skill or renderer contract.

Consequences

• The agent can repair malformed data during its own turn instead of returning invalid JSON for a later workflow step to reject.
• Replacing OpenCode changes the runner adapter and workflow wiring, not the skill, JSON schema, renderer, object key, or hosting contract.
• The OpenCode adapter adds a small trusted custom tool, but avoids broad model access to shell execution or repository writes.
• Reviewers need network access to the trusted external asset hosts when they open a walkthrough; R2 stores no separate runtime asset bundle.
• Workflow verification checks the agent-produced files rather than rebuilding HTML from the agent's final response.

Alternatives Considered

• Render after the agent exits: simpler workflow plumbing, but the agent cannot see renderer failures and repair its data.
• Allow generic edit and shell tools: lets the agent run the renderer directly, but also permits source mutation and execution of untrusted PR content in a secret-bearing workflow.
• Make the skill OpenCode-specific: avoids an adapter abstraction, but couples the durable walkthrough instructions to the first selected provider.