feat: 支持 opencode agent 行内 PR 评论

[Svtter]

背景

目前 multi-review action 的评论是 PR 级普通评论（POST /issues/{n}/comments），review 结果以纯文本形式发在 PR 上，虽然有文件路径和行号信息，但不是真正的 GitHub 行内 review comment。

opencode 官方的 review workflow（anomalyco/opencode）通过给 agent 开放 gh 权限，让模型直接调用 gh api POST /repos/{repo}/pulls/{n}/comments 在具体行号上留评论，体验好很多。

需求

1. 支持配置 OPENCODE_PERMISSION 开放 gh 权限

目前 extra-env 里 OPENCODE_PERMISSION 被列为敏感 key，需要 extra-env-allow-sensitive: "true" 才能设置。建议：

• 新增一个 action 输入参数 permission（或 openencode-permission），直接支持配置 agent 权限
• 默认值为 { "bash": { "*": "deny" } }（保持当前行为）
• 用户可以设置为 { "bash": { "*": "deny", "gh*": "allow", "gh pr review*": "deny" } } 来启用行内评论
• 或新增一个 enable-inline-comments bool 参数，action 内部自动设置对应的 permission

2. 确保 gh CLI 在 agent 环境中可用

Action 自身的 platform.ts 已经在用 gh（postPRComment、fetchPRDiff 等），说明 runner 上有 gh。但需要确认这个 gh 在 opencode agent 进程内也可用。

如果是 self-hosted runner，gh 可能不在 PATH 上。建议在启动 agent 前做 which gh 检查，如果不可用则在日志中 warn。

3. Reviewer prompt 支持 gh 调用指令

当 permission 允许 gh 时，在 reviewer prompt 中追加行内评论的指令和 gh api 格式示例：

gh api \
  --method POST \
  -H "Accept: application/vnd.github+json" \
  /repos/{owner}/{repo}/pulls/{number}/comments \
  -f 'body=[问题说明]' \
  -f 'commit_id={sha}' \
  -f 'path=[文件路径]' \
  -F 'line=[行号]' \
  -f 'side=RIGHT'

参考

• opencode 官方 review workflow: https://github.com/anomalyco/opencode/blob/dev/.github/workflows/review.yml
• 当前 permission 拦截逻辑: multi-review/src/platform.ts 的 SENSITIVE_ENV_KEYS

期望效果

• PR review 评论出现在具体代码行上，而非 PR 底部的普通评论
• 保持安全性：默认不开 gh 权限，用户显式启用
• 禁止 gh pr review（防止自动 approve）

[Svitter]

Thanks for the detailed proposal. I've read through the relevant code; here's my analysis.

Restating the request

Three changes to multi-review:

1. A new action input to let the agent call gh (currently hard-coded to permission: { edit: "deny", bash: "deny" }).
2. A which gh guard before launching the agent.
3. Reviewer prompt additions with gh api examples for inline review comments.

Feasibility & scope

(1) Permission input — Straightforward. github-run-opencode already exposes a permission input (action.yml:120-126) that flows through GITHUB_RUN_OPENCODE_PERMISSION → run-github-opencode.py:645-656 → opencode config. multi-review currently hard-codes { edit: "deny", bash: "deny" } in index.ts:35. Adding a permission input that overrides/merges into that default is the natural approach. An enable-inline-comments convenience flag that expands to { "bash": { "gh api*": "allow", "gh pr review*": "deny" } } is reasonable too, but the opencode permission schema uses glob patterns on bash commands — the exact pattern syntax needs to match what opencode actually supports. This is the part that needs a maintainer decision.

(2) which gh check — platform.ts:72-82 already has hasGh() with caching. Adding a warning at startup in index.ts is a one-liner. Low risk.

(3) Prompt additions — The current architecture is: agents are read-only. They review the diff and return text; the action posts the comment via postPRComment(). Letting the agent post inline comments via gh api would mean each reviewer agent calls gh api POST /repos/.../pulls/.../comments directly, bypassing the action's own comment pipeline (postPRComment, cleanupErrorComments, hash-escaping in escapeHashReferences). This is a significant architectural shift:

• Hash-number escaping (#N → ＃N) would need to happen inside the agent or be lost.
• Error comment cleanup logic wouldn't know about agent-posted inline comments.
• Coordinator synthesis currently reads agent text output; with inline comments, reviews are partially on the PR itself.
• commit_id for inline comments must reference the PR head SHA, which needs to be passed into the agent environment.

Open questions for the maintainer

1. Inline vs. formatted body — Would a middle ground work? Keep agents read-only but enrich the final posted comment with file/line anchors using GitHub's suggestion blocks in the Markdown? This avoids the gh permission surface entirely while improving readability.

2. If inline comments are the goal — Should the action itself post them (parse agent output for structured findings → POST /pulls/{n}/comments from the action), or should the agent post them directly? The former keeps the security boundary (agents stay read-only) but requires structured output parsing. The latter is what the issue describes but widens the permission surface.

3. Permission input design — Should multi-review mirror github-run-opencode's freeform permission JSON input, or should it expose a purpose-built enable-inline-comments: bool that maps to a curated permission set? The freeform approach is more flexible; the bool approach is safer and easier to document.

4. Self-hosted runner consideration — On self-hosted runners, gh may be absent or GITHUB_TOKEN may lack write scope for pull_request comments. Should the action fail, warn, or silently degrade?

[Svtter]

实现方案补充：用 helper fn 替代 gh api 示例

关于需求 3（prompt 中的 gh api 指令），建议改为实现一个 helper 函数，理由：

• hash 转义（#N → ＃N）、commit_id 拼接、error comment cleanup 都在 action 侧统一处理，不会丢失
• 权限收窄：agent 只需放行这个 helper（如 post-inline-comment），不需要通配 gh*
• prompt 精简：只需说明 "use post-inline-comment <file> <line> <body>" 即可，不用贴大段 gh api 模板

整体方向：结构化输出 + action 代发，agent 不直接碰 gh api。

[Svitter]

This is a much better design. It resolves every architectural tension I flagged:

• Hash escaping (escapeHashReferences in platform.ts:184) stays in the action's control, not scattered across agent prompts.
• commit_id resolution happens once in the action (we already have GITHUB_SHA in the environment), not replicated per-agent.
• Error comment cleanup (cleanupErrorComments) can track these helper-posted comments too, since the action is the sole publisher.
• Permission surface narrows from gh api* wildcard to a single allowed command — post-inline-comment.

Implementation-wise, platform.ts already has postCommentGithub (line 234) with the curl-based fallback for self-hosted runners. A new postInlineComment(file, line, body) function can follow the same pattern: try gh api POST /repos/…/pulls/…/comments first, fallback to curl with the same auth header.

The remaining maintainer decision: should this ship as a permission JSON input (mirroring github-run-opencode's design) or as an enable-inline-comments: bool that expands to { bash: { "post-inline-comment": "allow" } } internally? The helper-fn approach makes the bool safe enough that I'd lean toward the bool for simplicity, but the JSON input offers future extensibility for other permissions beyond inline comments.

[Svtter]

同意用 enable-inline-comments: bool。理由：helper fn 方案下权限范围已经收窄到单条命令，bool 足够安全且易文档。如果将来需要更细粒度的 permission 控制，再加 JSON input 也不迟（向后兼容）。

[Svitter]

Design settled then. Summary for implementation when authorized:

• New enable-inline-comments input on multi-review/action.yml, default "false".
• When true, buildSdkConfig in index.ts sets permission: { edit: "deny", bash: { "post-inline-comment": "allow" } } instead of bash: "deny".
• New postInlineComment(file, line, body) in platform.ts following the existing postCommentGithub pattern (gh api → curl fallback), sourcing commit_id from GITHUB_SHA.
• Reviewer prompts append a brief instruction: "use post-inline-comment <file> <line> <body> to leave inline comments."

All backward-compatible — default unchanged.