feat(hooks/plugin): add lifecycle hooks + phase-1 plugin contract

README.md

@@ -996,6 +996,18 @@ PicoClaw routes providers by protocol family:
 
 This keeps the runtime lightweight while making new OpenAI-compatible backends mostly a config operation (`api_base` + `api_key`).
 
+### Lifecycle Hooks (Plugin-style Extensions)
+
+PicoClaw provides typed lifecycle hooks for observability, outbound filtering, and tool guardrails.
+
+- Register hooks in Go at startup with `hooks.NewHookRegistry()`.
+- Attach once via `agentLoop.SetHooks(registry)` before `Run()` and handle setup errors.
+- 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/plugin-system-roadmap.md](docs/plugin-system-roadmap.md)
+
 <details>
 <summary><b>Zhipu</b></summary>
 

docs/hooks-plugin-examples.md

@@ -0,0 +1,138 @@
+# Lifecycle Hooks: Plugin-Style Examples
+
+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](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(...)` (check error).
+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
+```
+
+Note: the map above is shown as a single pass for readability. In practice, the
+agent loop may iterate up to `MaxToolIterations`, and `llm_input`, `llm_output`,
+`before_tool_call`, and `after_tool_call` can fire multiple times.
+
+## Available Hooks
+
+| Hook | Type | Typical use |
+|---|---|---|
+| `message_received` | observe-only | inbound telemetry |
+| `message_sending` | modifying + cancel | content filtering, safety policy |
+| `before_tool_call` | modifying + cancel | tool allow/deny, arg rewriting |
+| `after_tool_call` | observe-only | latency/error metrics |
+| `llm_input` | observe-only | prompt size monitoring |
+| `llm_output` | observe-only | response/tool-call telemetry |
+| `session_start` | observe-only | session audit |
+| `session_end` | observe-only | session cleanup metrics |
+
+## Quick Start
+
+```go
+package main
+
+import (
+	"context"
+	"strings"
+
+	"github.com/sipeed/picoclaw/pkg/hooks"
+)
+
+func buildHooks() *hooks.HookRegistry {
+	reg := hooks.NewHookRegistry()
+
+	// 1) Guardrail: block shell tool globally.
+	reg.OnBeforeToolCall("block-shell", 100, func(_ context.Context, e *hooks.BeforeToolCallEvent) error {
+		if e.ToolName == "shell" {
+			e.Cancel = true
+			e.CancelReason = "shell tool is disabled by local policy"
+		}
+		return nil
+	})
+
+	// 2) Outbound filter: redact obvious API key patterns.
+	reg.OnMessageSending("redact-secrets", 50, func(_ context.Context, e *hooks.MessageSendingEvent) error {
+		e.Content = strings.ReplaceAll(e.Content, "sk-", "[redacted]-")
+		return nil
+	})
+
+	// 3) Telemetry: record tool latency or errors.
+	reg.OnAfterToolCall("tool-telemetry", 0, func(_ context.Context, e *hooks.AfterToolCallEvent) error {
+		// Send to metrics backend / logs as needed.
+		_ = e.ToolName
+		_ = e.Duration
+		_ = e.Result
+		return nil
+	})
+
+	return reg
+}
+```
+
+Attach once during startup:
+
+```go
+agentLoop := agent.NewAgentLoop(cfg, msgBus, provider)
+if err := agentLoop.SetHooks(buildHooks()); err != nil {
+	panic(err) // replace with your startup error handling
+}
+```
+
+## Priority and Cancellation
+
+- Lower `priority` runs first.
+- `message_sending` and `before_tool_call` are sequential and can cancel.
+- Other hooks are observe-only and run concurrently.
+
+Recommended ordering:
+- `0-49`: telemetry and logging
+- `50-89`: transforms (redaction, normalization)
+- `90+`: hard guardrails (block/cancel)
+
+## Safety Notes
+
+- Hook panics are recovered internally; one bad hook does not crash the loop.
+- Hook errors are logged and execution continues unless `Cancel` is set.
+- Observe-only hooks (`message_received`, `after_tool_call`, `llm_input`, `llm_output`, `session_start`, `session_end`) must treat events as read-only.
+- Keep hook handlers fast and non-blocking to avoid latency impact.

docs/plugin-system-roadmap.md

@@ -0,0 +1,108 @@
+# 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 PR:
+
+- 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
+- No Go `.so` plugin loading as default direction
+
+## Phase Plan
+
+## Phase 1: Static Plugin Contract (Compile-time) — Implemented
+
+Goal: define a minimal public plugin contract for Go modules.
+
+Implemented:
+
+- Add `pkg/plugin` with a small interface:
+  - `Name() string`
+  - `APIVersion() string`
+  - `Register(*hooks.HookRegistry) error`
+- Register plugins at startup in code.
+- Add compatibility metadata (`plugin.APIVersion`) and registration-time checks.
+
+Exit criteria (met):
+
+- 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.
+
+Preferred direction:
+
+- Runtime plugins run as subprocesses.
+- Host and plugin communicate via RPC/gRPC.
+- Host manages lifecycle (spawn/health/timeout/restart), not in-process dynamic loading.
+
+Why this direction:
+
+- Go native `.so` plugin loading has strict toolchain/ABI coupling with host binary.
+- Subprocess RPC model reduces coupling and improves fault isolation.
+- Process boundary provides a cleaner place for permissions and sandbox controls.
+
+Preconditions:
+
+- Threat model approved
+- Signature/trust model defined
+- Sandboxing and permission boundaries defined
+- Rollback and safe-disable behavior validated
+- Versioned RPC handshake and capability negotiation defined
+- Process supervision policy defined (timeouts, retries, crash loop backoff)
+
+Until then, compile-time registration remains the recommended model.
+
+## Maintainer Review Notes
+
+The current hooks PR should be reviewed as Phase 0+1 only. It intentionally establishes extension points while avoiding high-risk runtime plugin mechanics.