ticket: refine plugin feature layering

.yoi/objectives/00001KTR80WMN/item.md

@@ -1,63 +1,72 @@
 ---
-title: "MCP integration as external capability provider"
-state: "active"
-created_at: "2026-06-10T07:47:48Z"
-updated_at: "2026-06-10T07:47:48Z"
-linked_tickets: ["00001KST8H4M0", "00001KTR81P9X", "00001KTR82RB7"]
+title: 'MCP local stdio integration architecture'
+state: 'active'
+created_at: '2026-06-10T07:48:45Z'
+updated_at: '2026-06-13T15:30:22Z'
 ---
 
-## Goal
+## Objective
 
-Yoi が MCP (Model Context Protocol) server を external capability provider として安全に扱えるようにする。
+Add MCP local stdio integration to Yoi without weakening Worker history, prompt-context, scoped tool permission, or Plugin/Feature layering invariants.
 
-到達点は、MCP server が提供する tools / resources / prompts を、Yoi の既存の Pod / Feature / ToolRegistry / permission / scope / history / bounded result 境界に乗せて利用できる状態にすること。MCP は Yoi の plugin model そのものではなく、protocol-bound bridge / external provider runtime として扱う。
+MCP should be implemented as a protocol-backed integration layer on top of `pod::feature`. `pod::feature` supplies the contribution/lifecycle API substrate; MCP owns its own enablement, local server trust model, command/env/secret policy, and MCP-specific permissions. MCP is not the Plugin model, and Plugin permission policy is not implemented by feature-layer authority grants.
 
-## Motivation / background
+## Strategic direction
 
-MCP は AI application と外部 system を接続する標準 protocol になりつつあり、server は tools、resources、prompts などを提供する。Yoi にとって MCP support は有用だが、外部 server が返す schema、description、annotation、resource content、prompt template はすべて untrusted data であり、Yoi の instruction hierarchy、scope、permission、history persistence、prompt-context 加工原則を弱めてはいけない。
+- Baseline the implementation on MCP specification `2025-11-25`.
+- Start with local stdio MCP servers only.
+- Treat MCP server metadata, tools, resources, prompts, and results as untrusted content.
+- Do not allow MCP resources/prompts to be hidden context injection.
+  - They must be explicit tool operations with history records.
+- Use the normal Yoi tool registry, PreToolCall permission, history, and bounded result paths.
+- Do not add private MCP-only bypasses around Worker/tool invariants.
+- Keep sampling and elicitation fail-closed initially.
+- Keep Streamable HTTP, remote auth, OAuth, and MCP Registry/distribution out of the first slice.
+- Treat local stdio server execution as an explicit MCP config/trust decision, not as a `pod::feature` authority grant.
+- Document clearly that a configured local MCP server runs as a local executable; Yoi feature authority does not sandbox its OS-level side effects.
 
-現行の `pod::feature` API は static descriptor / static tool contribution を中心にしており、MCP のように startup 時の initialize / capability negotiation / discovery によって surface が決まる provider には不足がある。そのため、MCP 実装だけを先に ad-hoc に入れるのではなく、まず外部 protocol-backed provider を扱える Feature API boundary を整え、その上に MCP implementation を載せる。
+## Layering decisions
 
-## Strategy / design direction
+- `pod::feature` is an API/contribution substrate.
+  - It owns contribution declarations, provider/service lifecycle hooks, diagnostics, dynamic registration plumbing, and integration with normal Worker/ToolRegistry paths.
+  - It does not own Plugin permission policy or MCP server trust policy.
+- Plugin is a user-facing package/config/runtime layer over `pod::feature`.
+  - Plugin permissions are Plugin-layer policy.
+  - Plugin package discovery/enablement must not be conflated with MCP local server execution.
+- MCP is a separate feature-backed integration layer.
+  - MCP enablement, command/env/secret handling, server trust, and MCP-specific permission decisions live in MCP config/implementation.
+  - MCP dynamic tools/resources/prompts are exposed through the feature API and ordinary Yoi tool paths.
 
-- Broad MCP integration Ticket は progress-container として使わず、この Objective に中期方針を移す。
-- 実装 work item は concrete Ticket に分ける。
-  - `00001KTR81P9X`: `pod::feature` / Worker / ToolRegistry API を external protocol-backed provider に耐える形へ拡張する。
-  - `00001KTR82RB7`: MCP `2025-11-25` local stdio server-feature bridge を実装する。
-- MCP 実装は local stdio transport から始める。
-  - Streamable HTTP、remote auth/OAuth、MCP Registry distribution、workspace-provided package auto-start は後続判断とする。
-- tools / resources / prompts は無理に分けず、MCP server features として扱う。
-  - ただし resources/prompts は direct context injection ではなく、明示 tool operation の結果として history に残す。
-  - `resources/read` / `prompts/get` の結果を history に残らない形で context に注入しない。
-- MCP server は untrusted external capability provider として扱う。
-  - server-provided schema/description/annotation/content/error は instruction ではなく data。
-  - ToolRegistry / PreToolCall permission / history / bounded result path を迂回しない。
-- local process execution は explicit authority として扱う。
-  - filesystem/network authority から暗黙に subprocess 起動権限を派生させない。
-  - secrets は explicit secret/env references で扱い、diagnostics / logs / model context / project records に plaintext として残さない。
-- dynamic discovery / list_changed は prompt/tool schema consistency を壊さない範囲で扱う。
-  - live refresh が危険なら next-turn refresh または restart/reinitialize-required diagnostic を選ぶ。
-  - silent stale state は避ける。
-- Sampling / elicitation は external server が Yoi 側の LLM/user interaction を要求する強い authority なので、初期段階では fail-closed とし、必要なら別 Ticket で approval/resume/UI path を設計する。
+## Work breakdown
 
-## Success criteria / exit conditions
+1. `00001KTR81P9X` — Extend `pod::feature` API for protocol-backed external providers.
+   - provider/service lifecycle
+   - startup discovery and dynamic contribution registration
+   - bounded refresh semantics
+   - metadata/result normalization
+   - no feature-layer authority model for MCP/Plugin permissions
+2. `00001KTR82RB7` — Implement MCP `2025-11-25` local stdio server bridge.
+   - explicit MCP config and trust model
+   - initialize/capability negotiation
+   - tools/resources/prompts list/call/read/get
+   - bounded result serialization
+   - list-changed diagnostics/refresh behavior
+3. `00001KV0SP0TY` — Remove feature-layer HostAuthority model.
+   - remove authority/grant terminology from `pod::feature`
+   - keep real permission/trust policy in owning Plugin/MCP/manifest/tool layers
+4. Later follow-ups, if needed.
+   - richer MCP tasks / task-support integration
+   - remote/HTTP transports
+   - OAuth / registry / package distribution
+   - Plugin package/runtime alignment, if an explicit MCP/plugin bridge is later approved
 
-- `pod::feature` が external protocol-backed capability provider を表現できる。
-- local subprocess execution authority が明示的に型・config・grant として扱われる。
-- Feature-provided long-running service / connection manager を Pod lifetime に安全に接続できる。
-- discovery 後の dynamic tool contribution が通常 ToolRegistry と permission path に統合される。
-- MCP spec baseline `2025-11-25` に基づく local stdio server integration がある。
-- MCP tools が namespaced stable Yoi tool として使える。
-- MCP resources/prompts が明示 tool operation として使え、取得結果は通常 tool result として history に残る。
-- server-provided data が system/developer instruction、scope、permission、prompt-context、history persistence rules を弱めない。
-- secrets / env values / command args containing secrets が diagnostics、logs、model context に plaintext で出ない。
-- Streamable HTTP、remote auth、distribution、sampling、elicitation の扱いが out-of-scope / fail-closed / follow-up として明示されている。
-- local mock MCP server による focused tests と、関連 crate tests、`nix build .#yoi` による packaging validation が定義されている。
+## Success criteria
 
-## Decision context
-
-- `00001KST8H4M0` は broad MCP integration Ticket として作られていたが、今後はこの Objective の背景 context として扱い、実装 authority は concrete Tickets に置く。
-- `00001KTR81P9X` は API/architecture prerequisite。MCP 実装が ToolRegistry / permission / history path を迂回しないための土台を作る。
-- `00001KTR82RB7` は MCP implementation Ticket。API 拡張の結果に乗って local stdio MCP server features を実装する。
-- Objective-to-Ticket links は context であり、dependency/scheduling authority ではない。実際の routing / readiness / blockers は各 Ticket の body/thread/artifacts と Orchestrator 判断に置く。
-- `resources/prompts` は scope 外に固定しない。安全条件は「direct hidden context injection をしない」ことであり、明示 tool result として扱うなら MCP integration の対象に含める。
+- A local mock MCP server can be configured explicitly and initialized.
+- Discovered MCP tools appear as ordinary Yoi tools with stable namespacing.
+- Tool calls go through ordinary permission and history paths.
+- MCP resources/prompts are explicit operations, not hidden context injections.
+- MCP result forms are bounded and safely serialized.
+- Secret values, command/env details, and server diagnostics are redacted where required.
+- Local server trust boundary is documented: Yoi does not sandbox the configured executable through feature authority.
+- Feature, Plugin, and MCP permission/trust responsibilities are documented as separate layers.