plugin: create extension surface ticket

work-items/open/20260531-010005-plugin-extension-surface/item.md

@@ -0,0 +1,87 @@
+---
+id: 20260531-010005-plugin-extension-surface
+slug: plugin-extension-surface
+title: Plugin: define extension surface for hooks and tools
+status: open
+kind: feature
+priority: P2
+labels: [plugin, hooks, tools, wasm, mcp]
+created_at: 2026-05-31T01:00:05Z
+updated_at: 2026-05-31T01:01:09Z
+assignee: null
+legacy_ticket: null
+---
+
+## Background
+
+insomnia currently has internal Hook / Tool concepts, plus a separate planned MCP integration ticket (`mcp-integration`). The next design step is to define the project-level Plugin surface: how user/project-provided extensions can contribute Tools and Hooks without weakening scope, permission, history, or prompt-context invariants.
+
+The plugin surface should not be a grab bag of arbitrary code execution. Candidate extension mechanisms have different trust and protocol properties:
+
+- MCP: protocol-bound external tool/resource/prompt provider surface.
+- TOML/config-only hooks: declarative configuration for simple hook behavior without arbitrary code.
+- WASM: planned first programmable plugin runtime for Hooks and Tools, with explicit capability imports and sandboxing.
+- General scripting languages: considered, but not the initial direction because arbitrary script execution broadens the trust/runtime surface too quickly.
+
+## Related work
+
+- `work-items/open/20260529-161928-mcp-integration/` — MCP integration as one plugin backend / external capability bridge.
+- Existing internal hooks/tools code: `crates/pod`, `crates/tools`, `crates/llm-worker`.
+- Manifest permission policy and scope enforcement must remain authoritative for plugin-provided tools.
+
+## Requirements
+
+- Define a Plugin surface that can provide:
+  - Tools callable by the LLM through the normal ToolRegistry / permission / scope path;
+  - Hooks observing or influencing Pod/Worker lifecycle through the existing Hook boundary, not by directly mutating worker history/context.
+- Separate plugin description/registration from plugin runtime implementation.
+  - A plugin manifest should declare provided tools/hooks, required capabilities, configuration schema or config values, and trust/runtime type.
+  - Runtime implementations can include MCP, declarative config hooks, and WASM in separate phases.
+- Keep MCP as a related backend, not the whole plugin model.
+  - MCP servers remain untrusted external capability providers bridged through allowlists, bounded output, scope/permission policy, and explicit resource/prompt use.
+- Define a declarative hook path for simple TOML/config-only behavior where code execution is unnecessary.
+- Define a WASM plugin direction for programmable Hooks/Tools.
+  - WASM modules must receive explicit host imports/capabilities only.
+  - File/network/process access must not be ambient; all external effects go through host-provided capability APIs and existing policy checks.
+  - Tool outputs must be bounded and recorded through normal history/tool-result paths.
+- Preserve LLM context/history invariants.
+  - Plugins must not inject cross-turn invisible context.
+  - If plugin output becomes model-visible, it must enter through durable history/tool/hook paths according to existing rules.
+- Preserve scope and permission invariants.
+  - Plugin-provided tools must not bypass `ScopedFs`, manifest tool permission policy, child scope delegation, or web/network policy.
+- Clarify trust model and lifecycle.
+  - Builtin vs project vs user plugins.
+  - Discovery/enablement through manifest/profile/config.
+  - Versioning / compatibility boundaries.
+  - Diagnostics when a plugin cannot load or asks for unavailable capabilities.
+
+## Non-goals
+
+- Implementing the full WASM runtime in the first design step.
+- Implementing MCP itself beyond referencing the existing MCP integration ticket.
+- Supporting arbitrary host scripting languages as a first-class plugin runtime.
+- Allowing plugins to mutate session history, memory, prompt context, or scope outside approved APIs.
+- Adding UI plugin systems or TUI rendering extensions.
+
+## Suggested phases
+
+1. **Design / architecture note**
+   - Define Plugin, PluginManifest, PluginRuntimeKind, Tool contribution, Hook contribution, capability request, and trust/source model.
+   - Map MCP, declarative hooks, and WASM onto that model.
+2. **Internal registry boundary**
+   - Introduce code structure that can register plugin-provided tool/hook descriptors without changing runtime behavior yet.
+3. **Declarative hooks MVP**
+   - Add a non-code configuration path for simple hook behavior if an immediate use case exists.
+4. **WASM spike**
+   - Evaluate runtime (`wasmtime` or alternative), host imports, resource limits, serialization, and Nix/package impact.
+5. **MCP bridge alignment**
+   - Ensure `mcp-integration` plugs into the same Tool/permission/output boundary rather than becoming a parallel extension path.
+
+## Acceptance criteria
+
+- The repository has a documented plugin architecture proposal covering Tools, Hooks, runtimes, capability model, trust model, and discovery/enablement.
+- MCP is positioned as one plugin backend / bridge and linked to `mcp-integration`, not treated as the only extension mechanism.
+- The proposal explicitly explains why arbitrary scripting languages are deferred and why WASM is the initial programmable runtime direction.
+- The design preserves existing scope, permission, history, and prompt-context invariants.
+- Follow-up implementation tickets can be cut independently for declarative hooks, WASM runtime, and MCP bridge integration.
+- Any code changes in this ticket, if taken beyond design docs, are limited to safe internal boundaries and have focused tests.

work-items/open/20260531-010005-plugin-extension-surface/thread.md

@@ -0,0 +1,24 @@
+<!-- event: create author: tickets.sh at: 2026-05-31T01:00:05Z -->
+
+## Created
+
+Created by tickets.sh create.
+
+---
+
+<!-- event: decision author: hare at: 2026-05-31T01:01:09Z -->
+
+## Decision
+
+Initial decision note from user discussion:
+
+- The plugin surface should mainly expose Hooks and Tools.
+- MCP is related, but should be treated as one protocol-bound backend/bridge rather than the entire plugin model.
+- Planned plugin mechanisms:
+  - MCP for protocol-constrained external capability providers;
+  - TOML/config-only hooks for simple behavior that does not need arbitrary code;
+  - WASM for programmable Hooks/Tools with explicit host capabilities.
+- General scripting languages were considered, but the initial direction is WASM because it offers a clearer sandbox/capability boundary.
+
+
+---