[Priority: Med] [Architecture] 收敛过界的 workspace/worktree mutation extensions

[liujuanjuan1984]

背景

本仓库当前的 opencode.* JSON-RPC extensions 已经形成一套较完整的 provider-private surface，但其中有一部分能力已经超出了 adapter 应承担的边界，需要收敛。

本次审查的重点结论是：

• workspace/worktree mutation methods 当前默认暴露，已经更接近 host/project control plane，而不是低风险的 A2A adapter extension。
• 这些 mutation methods 当前和只读 discovery methods 混在同一个 workspace_control extension 中，对外宣称为稳定能力，但其底层直接依赖上游 /experimental/* surface，稳定性口径偏满。
• OpenCode Session Query v1 的命名/描述也存在失真：它已不只是 query，还包含 prompt_async、command、share/unshare、revert/unrevert 等控制面操作；这部分更适合作为后续 issue 单独梳理分组与命名。

发现

1. workspace/worktree mutation methods 过界

当前默认暴露的方法包括：

• opencode.workspaces.create
• opencode.workspaces.remove
• opencode.worktrees.create
• opencode.worktrees.remove
• opencode.worktrees.reset

这些方法会直接改动 active deployment project 的 workspace/worktree 状态，不属于“优先暴露只读 discovery 与低风险 control”的 adapter 边界。

2. 稳定性宣称偏高

当前 contract / compatibility profile 将 workspace_control 相关方法统一标注为 stable、always，但其实现直接调用上游 /experimental/workspace、/experimental/worktree、/experimental/worktree/reset 等实验性 surface。

3. OpenCode Session Query v1 命名失真

当前 external naming 仍使用 Session Query，但实际已经混入多个 mutation / control methods。这个问题建议作为后续项单独整理，不和本次 workspace/worktree 收敛混在一个 PR 里做大改。

建议

本次优先收敛

• 为 workspace/worktree mutation methods 增加独立 deployment toggle
• 默认关闭这些 mutation methods
• 默认情况下：
  • 不在 all_jsonrpc_methods / Agent Card / OpenAPI examples 中声明这些方法
  • 调用这些方法时返回明确的 METHOD_NOT_SUPPORTED
• 保留只读 discovery methods：
  • opencode.projects.list
  • opencode.projects.current
  • opencode.workspaces.list
  • opencode.worktrees.list

后续建议

• 单独开后续 issue，重构 OpenCode Session Query v1 的命名与 contract 分组，避免继续把 control/mutation surface 伪装成“query / low-risk”能力。

验收标准

• 新增独立 toggle，默认关闭 workspace/worktree mutation methods
• Agent Card / wire contract / OpenAPI / docs 与默认关闭行为保持一致
• 新增回归测试，覆盖 disabled 状态下的 unsupported method 行为
• 保留只读 workspace discovery surface

[liujuanjuan1984]

基于当前分支已完成第一阶段收敛，并已推送到现有 Draft PR：

• PR: fix(runtime): tighten extension boundaries and unsupported surfaces #392
• Commit: 2e70c9c fix(runtime): gate workspace mutation extensions by default (#393)

本次已落地内容：

• 新增 A2A_ENABLE_WORKSPACE_MUTATIONS，默认关闭 workspace/worktree mutation methods
• 默认情况下不再在 Agent Card / wire contract / OpenAPI examples 中声明这些 mutation methods
• 默认调用这些方法时返回明确的 METHOD_NOT_SUPPORTED
• 保留只读 discovery methods：opencode.projects.list/current、opencode.workspaces.list、opencode.worktrees.list
• 文档、runtime profile 与回归测试已同步更新

验证：

• ./scripts/doctor.sh
• 530 tests passed
• coverage 91.10%

OpenCode Session Query v1 的命名/分组问题本次没有一起改动，仍建议后续单独跟踪。

[liujuanjuan1984]

在本次分支的后续独立审查中，又补充并收口了两个 extension 边界点，已继续并入当前 PR #392：

1. workspace control 的稳定性口径补充

• 保留 project discovery 的稳定声明
• 将 workspace/worktree surfaces 明确标注为 upstream experimental 依赖
• 在 contract / compatibility profile 中补充 machine-readable upstream_stability 语义，避免继续把这部分能力笼统等同于稳定 surface

2. interrupt recovery 的语义口径补充

• 明确 opencode.permissions.list / opencode.questions.list 读的是 adapter-local interrupt binding registry
• 明确它是 identity-scoped recovery surface，而不是上游全局 pending queue
• 在 contract 中补充 recovery_scope / implementation_scope / identity_scope 语义

验证已完成：

• ./scripts/doctor.sh
• 530 tests passed
• coverage 91.10%

PR：#392
新增 commit：4d46e70 fix(contracts): clarify workspace and interrupt extension boundaries (#393)