docs(plugin): document plugin model and phased roadmap

README.md

@@ -1012,6 +1012,7 @@ PicoClaw provides typed lifecycle hooks for observability, outbound filtering, a
 - If hooks are not set, default behavior is unchanged.
 
 See runnable examples: [docs/hooks-plugin-examples.md](docs/hooks-plugin-examples.md)
+Roadmap for plugin system evolution: [docs/design/plugin-system-roadmap.md](docs/design/plugin-system-roadmap.md)
 
 <details>
 <summary><b>Zhipu</b></summary>

docs/design/plugin-system-roadmap.md

@@ -0,0 +1,92 @@
+# Plugin System Roadmap
+
+This document defines how PicoClaw evolves from hook-based extension points to a fuller plugin system in low-risk phases.
+
+## Current Status (Phase 0: Foundation)
+
+Implemented in current hooks MR:
+
+- Typed lifecycle hooks (`pkg/hooks`)
+- Priority-based handler ordering
+- Cancellation support for modifying hooks
+- Panic recovery and error isolation
+- Agent-loop integration via `agentLoop.SetHooks(...)`
+
+Compatibility:
+
+- If no hooks are registered, runtime behavior is unchanged.
+- No config migration is required.
+
+## Non-Goals in Phase 0
+
+- No dynamic runtime plugin loading
+- No remote plugin marketplace/distribution
+- No plugin sandboxing model
+- No stable external plugin ABI yet
+
+## Phase Plan
+
+## Phase 1: Static Plugin Contract (Compile-time)
+
+Goal: define a minimal public plugin contract for Go modules.
+
+Proposed:
+
+- Add `pkg/plugin` with a small interface:
+  - `Name() string`
+  - `Register(*hooks.HookRegistry) error`
+- Register plugins at startup in code.
+- Add compatibility metadata (`PluginAPIVersion`) for forward checks.
+
+Exit criteria:
+
+- Example plugin module builds against the contract.
+- Startup validation logs loaded plugins and registration errors clearly.
+
+## Phase 2: Config-driven Enable/Disable
+
+Goal: operational control without code changes.
+
+Proposed:
+
+- Add plugin list/config in `config.json`:
+  - enabled/disabled flags
+  - optional plugin-specific settings
+- Deterministic load order and conflict resolution rules.
+
+Exit criteria:
+
+- Users can toggle plugins without rebuilding.
+- Clear startup diagnostics for invalid plugin config.
+
+## Phase 3: Developer Experience
+
+Goal: make third-party plugin development straightforward.
+
+Proposed:
+
+- Provide `examples/plugins/*` reference implementations.
+- Publish plugin authoring guide (lifecycle map, best practices, safety constraints).
+- Add plugin-focused test harness pattern for hook behavior verification.
+
+Exit criteria:
+
+- New plugin can be built from template with minimal boilerplate.
+- CI examples demonstrate expected behavior and regression checks.
+
+## Phase 4: Optional Dynamic Loading (Separate RFC)
+
+Goal: support runtime-loaded plugins only if security and operability are acceptable.
+
+Preconditions:
+
+- Threat model approved
+- Signature/trust model defined
+- Sandboxing and permission boundaries defined
+- Rollback and safe-disable behavior validated
+
+Until then, compile-time registration remains the recommended model.
+
+## Maintainer Review Notes
+
+The current hooks MR should be reviewed as Phase 0 only. It intentionally establishes extension points while avoiding high-risk runtime plugin mechanics.

docs/hooks-plugin-examples.md

@@ -2,11 +2,54 @@
 
 This guide shows how to extend PicoClaw behavior with `pkg/hooks` without modifying core agent logic.
 
+For future direction (beyond current hooks foundation), see [Plugin System Roadmap](design/plugin-system-roadmap.md).
+
 Current model:
 - "Plugin-style" means registering Go handlers at startup.
 - Hooks are in-process (no dynamic `.so` loading).
 - If no hooks are registered, the runtime follows the normal zero-cost path.
 
+## How Plugin Works
+
+PicoClaw's plugin model is a startup-time hook registry:
+
+1. Build a registry (`hooks.NewHookRegistry()`).
+2. Register one or more handlers per lifecycle hook with priority.
+3. Attach once with `agentLoop.SetHooks(registry)` before `agentLoop.Run(...)`.
+4. Agent loop triggers hook handlers at specific lifecycle points.
+
+Execution semantics:
+
+- Observe-only hooks (`message_received`, `after_tool_call`, `llm_input`, `llm_output`, `session_start`, `session_end`)
+  - run concurrently
+  - cannot block core behavior
+- Modifying hooks (`message_sending`, `before_tool_call`)
+  - run sequentially by priority (lower number first)
+  - may mutate event data
+  - may cancel operation via `Cancel=true`
+
+Safety model:
+
+- Panic in one handler is recovered and logged.
+- Handler errors are logged; pipeline continues unless canceled by event flag.
+- With no registered hooks, agent loop behavior is unchanged.
+
+Lifecycle map:
+
+```text
+Inbound message
+  -> message_received
+  -> session_start
+  -> llm_input
+  -> llm_output
+  -> before_tool_call (cancelable)
+  -> tool execute
+  -> after_tool_call
+  -> message_sending (cancelable)
+  -> outbound publish
+  -> session_end
+```
+
 ## Available Hooks
 
 | Hook | Type | Typical use |