feat(plugins): hook system end-to-end — chat.send + per-agent opt-in + Plugins tab

Hook plugins were defined in the protocol but never actually wired —
RegisterPluginHooks had zero callers and there was no way for a
plugin to push a follow-up message back to the chat it received a
hook for. This change makes the whole loop work and adds a UI for
operators to control which agents each plugin attaches to.

## Protocol — chat.send

New method `chat.send` (plugin → fastclaw notification) that
delivers a fresh OutboundMessage to a specific chat. The plugin
manager turns it into a bus.OutboundMessage with optional
MediaItems (base64-encoded inline) and pushes onto bus.Outbound —
same path the agent's own reply takes, so the chatter sees a
second bubble. Unlike message.inbound (which spawns another agent
turn), chat.send skips the agent entirely.

HookFireParams gains Channel + AccountID so plugins receiving a
hook event have the full bus routing triple needed to echo back to
chat.send. Populated at every hooks.Run callsite in the agent
loop from msg.Channel / msg.AccountID.

## Ordering vs the agent's main reply

PostTurn hooks fire while the agent loop is still finishing, so a
fast plugin could win the bus.Outbound enqueue race and the chatter
would see the plugin's follow-up before the agent's actual reply.
chat.send dispatch is now async with a small default 50ms delay
(tunable via FASTCLAW_PLUGIN_CHAT_SEND_DELAY_MS) — gives the
gateway's microsecond-scale bus push a head start. Channel adapters
serialize sends per account, so bus enqueue order = user-visible
order.

## Wiring + per-agent enable

`registerHookPluginsForAgent` (new) attaches a plugin's hooks to
ONE agent's HookRegistry. Called from loadUserSpace (owner path)
AND EnsureAgent (foreign-attach path) so chatters reaching an
agent via channel binding get the same hooks the owner does.

Default is OPT-IN: a plugin enabled system-wide only means its
process runs and is available to attach. Each agent must individually
set `plugins.enabled[<id>] = true` (via the dashboard Plugins tab
or directly in the configs table) for hooks to fire on its turns.
Rationale: hook plugins can change agent behavior in surprising ways
(extra messages, modified prompts, recorded conversation data).
Default-deny avoids accidentally affecting agents the operator
didn't intend.

UserSpace gains a borrowed PluginMgr pointer so EnsureAgent doesn't
need to reach back to the gateway for it.

## Dashboard

- New `GET /api/plugins/hook` endpoint: read-only metadata listing
  of hook-type plugins (id / name / description / version). Not
  admin-gated — agent owners need it to populate the Plugins tab.
- handleUpdateAgent: accepts `plugins` map + `pluginsReset` flag;
  GET returns `plugins` per-agent overlay. Patch semantics so
  flipping one plugin doesn't clobber overrides for siblings.
- New dedicated Plugins tab in agent-settings-dialog (Plug icon),
  positioned between Skills and Channels — mirrors the Skills page
  layout (header + grid of cards). Replaces the inline card on the
  Context page (now removed; Context only carries Multi-bubble +
  Auto-remember).
- HookPlugin TypeScript type + listHookPlugins() client.

## Demo

`plugins/post-turn-echo-demo/` — minimal Python plugin (~100 lines)
that registers on PostTurn and ships a fixed follow-up text via
chat.send. Skeleton for richer plugins (audio replies, translations,
CRM sync, etc).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: idoubi

internal/agent/hooks.go

@@ -37,6 +37,12 @@ type HookContext struct {
 	Workspace     string    // agent workspace path (for PostTurn)
 	UserID        string    // owning user ID for multi-user namespace isolation
 	ChatID        string    // used by the plugin hook adapter
+	// Channel + AccountID complete the bus routing triple. Plugins
+	// reading these in a hook.fire payload can echo them back to
+	// chat.send so a follow-up message reaches the same chat that
+	// just got the agent's reply.
+	Channel   string
+	AccountID string
 	// Source mirrors bus.InboundMessage.Source so PostTurn hooks can
 	// distinguish a real user turn from a cron / heartbeat / sub-agent
 	// / goal-context turn. Empty means user. Hooks that should only

internal/agent/loop.go

@@ -1917,7 +1917,7 @@ func (a *Agent) HandleMessage(ctx context.Context, msg bus.InboundMessage) strin
 		)
 
 		// Hook: BeforeModelCall
-		hcBefore := &HookContext{AgentName: a.name, Point: BeforeModelCall, Messages: messages, ChatID: msg.ChatID, UserID: a.ownerUserID}
+		hcBefore := &HookContext{AgentName: a.name, Point: BeforeModelCall, Messages: messages, Channel: msg.Channel, AccountID: msg.AccountID, ChatID: msg.ChatID, UserID: a.ownerUserID}
 		a.hooks.Run(ctx, hcBefore)
 
 		// PII scrubbing: redact sensitive data before sending to LLM
@@ -1955,7 +1955,7 @@ func (a *Agent) HandleMessage(ctx context.Context, msg bus.InboundMessage) strin
 		resp, err := a.streamChatToResponse(ctx, llmMessages, callTools)
 
 		// Hook: AfterModelCall
-		hcAfter := &HookContext{AgentName: a.name, Point: AfterModelCall, Messages: messages, Response: resp, Error: err, StartTime: hcBefore.StartTime, ChatID: msg.ChatID, UserID: a.ownerUserID, GoalSessionKey: a.registry.GoalSessionKey()}
+		hcAfter := &HookContext{AgentName: a.name, Point: AfterModelCall, Messages: messages, Response: resp, Error: err, StartTime: hcBefore.StartTime, Channel: msg.Channel, AccountID: msg.AccountID, ChatID: msg.ChatID, UserID: a.ownerUserID, GoalSessionKey: a.registry.GoalSessionKey()}
 		a.hooks.Run(ctx, hcAfter)
 
 		if err != nil {
@@ -2057,6 +2057,9 @@ func (a *Agent) HandleMessage(ctx context.Context, msg bus.InboundMessage) strin
 				Point:     BeforeToolCall,
 				ToolName:  tc.Function.Name,
 				ToolArgs:  tc.Function.Arguments,
+				Channel:   msg.Channel,
+				AccountID: msg.AccountID,
+				ChatID:    msg.ChatID,
 				UserID:    a.ownerUserID,
 			})
 		}
@@ -2147,6 +2150,9 @@ func (a *Agent) HandleMessage(ctx context.Context, msg bus.InboundMessage) strin
 				ToolName:       r.toolName,
 				ToolResult:     resultContent,
 				Error:          r.err,
+				Channel:        msg.Channel,
+				AccountID:      msg.AccountID,
+				ChatID:         msg.ChatID,
 				UserID:         a.ownerUserID,
 				GoalSessionKey: a.registry.GoalSessionKey(),
 				IsPlanMode:     isPlanMode(msg.Params),
@@ -2418,6 +2424,8 @@ func (a *Agent) runPostTurn(ctx context.Context, msg bus.InboundMessage, message
 		ToolCallCount:  toolCallCount,
 		Workspace:      a.homePath,
 		UserID:         a.ownerUserID,
+		Channel:        msg.Channel,
+		AccountID:      msg.AccountID,
 		ChatID:         msg.ChatID,
 		Source:         msg.Source,
 		GoalSessionKey: a.registry.GoalSessionKey(),
@@ -2578,13 +2586,13 @@ func (a *Agent) HandleMessageStream(ctx context.Context, msg bus.InboundMessage)
 
 	// ReAct loop - use Chat for tool iterations
 	for i := 0; i < a.maxToolIterations; i++ {
-		hcBefore := &HookContext{AgentName: a.name, Point: BeforeModelCall, Messages: messages, ChatID: msg.ChatID, UserID: a.ownerUserID}
+		hcBefore := &HookContext{AgentName: a.name, Point: BeforeModelCall, Messages: messages, Channel: msg.Channel, AccountID: msg.AccountID, ChatID: msg.ChatID, UserID: a.ownerUserID}
 		a.hooks.Run(ctx, hcBefore)
 
 		dumpLLMRequest(a.name, a.model, messages, toolDefs)
 		resp, err := a.provider.Chat(ctx, messages, toolDefs, a.model, a.maxTokens, a.temperature)
 
-		hcAfter := &HookContext{AgentName: a.name, Point: AfterModelCall, Messages: messages, Response: resp, Error: err, StartTime: hcBefore.StartTime, ChatID: msg.ChatID, UserID: a.ownerUserID, GoalSessionKey: a.registry.GoalSessionKey()}
+		hcAfter := &HookContext{AgentName: a.name, Point: AfterModelCall, Messages: messages, Response: resp, Error: err, StartTime: hcBefore.StartTime, Channel: msg.Channel, AccountID: msg.AccountID, ChatID: msg.ChatID, UserID: a.ownerUserID, GoalSessionKey: a.registry.GoalSessionKey()}
 		a.hooks.Run(ctx, hcAfter)
 
 		if err != nil {
@@ -2721,7 +2729,7 @@ func (a *Agent) HandleMessageStream(ctx context.Context, msg bus.InboundMessage)
 
 		// Fire BeforeToolCall hooks
 		for _, tc := range resp.ToolCalls {
-			a.hooks.Run(ctx, &HookContext{AgentName: a.name, Point: BeforeToolCall, ToolName: tc.Function.Name, ToolArgs: tc.Function.Arguments, UserID: a.ownerUserID})
+			a.hooks.Run(ctx, &HookContext{AgentName: a.name, Point: BeforeToolCall, ToolName: tc.Function.Name, ToolArgs: tc.Function.Arguments, Channel: msg.Channel, AccountID: msg.AccountID, ChatID: msg.ChatID, UserID: a.ownerUserID})
 		}
 
 		// Execute tools concurrently via SDK engine
@@ -2731,7 +2739,7 @@ func (a *Agent) HandleMessageStream(ctx context.Context, msg bus.InboundMessage)
 		for idx, r := range results {
 			tc := resp.ToolCalls[idx]
 			resultContent, meta := extractToolMeta(r.result)
-			a.hooks.Run(ctx, &HookContext{AgentName: a.name, Point: AfterToolCall, ToolName: r.toolName, ToolResult: resultContent, Error: r.err, UserID: a.ownerUserID, GoalSessionKey: a.registry.GoalSessionKey(), IsPlanMode: isPlanMode(msg.Params), Source: msg.Source})
+			a.hooks.Run(ctx, &HookContext{AgentName: a.name, Point: AfterToolCall, ToolName: r.toolName, ToolResult: resultContent, Error: r.err, Channel: msg.Channel, AccountID: msg.AccountID, ChatID: msg.ChatID, UserID: a.ownerUserID, GoalSessionKey: a.registry.GoalSessionKey(), IsPlanMode: isPlanMode(msg.Params), Source: msg.Source})
 
 			if r.err != nil {
 				slog.Warn("tool execution error", "agent", a.name, "name", r.toolName, "error", r.err)

internal/gateway/gateway.go

@@ -352,7 +352,7 @@ func New(env *config.EnvConfig) (*Gateway, error) {
 		workspace:   ws,
 		usage:       meter,
 		sandboxPool: systemSandboxPool,
-		users:       newUserSpaceRegistry(mb, st, ws, meter, systemSandboxPool),
+		users:       newUserSpaceRegistry(mb, st, ws, meter, systemSandboxPool, pluginMgr),
 		chanMgr:     chanMgr,
 		webChan:     webChan,
 		scheduler:   scheduler,

internal/gateway/userspace.go

@@ -14,6 +14,7 @@ import (
 	"github.com/fastclaw-ai/fastclaw/internal/agent"
 	"github.com/fastclaw-ai/fastclaw/internal/bus"
 	"github.com/fastclaw-ai/fastclaw/internal/config"
+	"github.com/fastclaw-ai/fastclaw/internal/plugin"
 	"github.com/fastclaw-ai/fastclaw/internal/provider"
 	"github.com/fastclaw-ai/fastclaw/internal/sandbox"
 	"github.com/fastclaw-ai/fastclaw/internal/scope"
@@ -305,6 +306,11 @@ type UserSpace struct {
 	Provider    provider.Provider
 	Agents      *agent.Manager
 	SandboxPool sandbox.ExecutorPool
+	// PluginMgr is borrowed from the gateway (process-wide singleton).
+	// Held here so EnsureAgent — the foreign-agent attach path — can
+	// register hook plugins onto the lazy-built agent without
+	// reaching back into the gateway. Nil when systemPlugins is off.
+	PluginMgr *plugin.Manager
 
 	mu sync.Mutex
 }
@@ -575,6 +581,16 @@ func (sp *UserSpace) EnsureAgent(ctx context.Context, st store.Store, mb *bus.Me
 			ag.ToolRegistry().SetSandboxRoot(rc.Workspace)
 		}
 	}
+	// Wire hook plugins onto the freshly-attached agent. Mirrors what
+	// loadUserSpace does for owner agents — without this, hook
+	// plugins would only fire for the agent's owner and never for
+	// chatters who reach the agent through a foreign-attach (channel
+	// binding, public link, super_admin browse).
+	if sp.PluginMgr != nil {
+		if ag := sp.Agents.AgentByID(rc.ID); ag != nil {
+			registerHookPluginsForAgent(ctx, sp.PluginMgr, st, ag)
+		}
+	}
 	slog.Info("agent injected into foreign user space",
 		"caller", sp.UserID, "agent", rc.ID, "owner", rec.UserID)
 	return nil
@@ -591,7 +607,7 @@ func (sp *UserSpace) EnsureAgent(ctx context.Context, st store.Store, mb *bus.Me
 // by the resulting UserSpace. Pass nil when sandbox is disabled at
 // system scope; agents will run with path-only file roots in that
 // case.
-func loadUserSpace(ctx context.Context, userID string, mb *bus.MessageBus, st store.Store, ws workspace.Store, meter usage.Meter, systemSandboxPool sandbox.ExecutorPool) (*UserSpace, error) {
+func loadUserSpace(ctx context.Context, userID string, mb *bus.MessageBus, st store.Store, ws workspace.Store, meter usage.Meter, systemSandboxPool sandbox.ExecutorPool, pluginMgr *plugin.Manager) (*UserSpace, error) {
 	if userID == "" {
 		return nil, fmt.Errorf("loadUserSpace: userID required")
 	}
@@ -752,6 +768,16 @@ func loadUserSpace(ctx context.Context, userID string, mb *bus.MessageBus, st st
 
 	pool := attachSandboxToAgents(systemSandboxPool, userID, resolved, agentMgr)
 
+	// Wire hook plugins onto each agent's HookRegistry. Per-agent
+	// enable comes from the configs row at (scope=agent, agent_id=X,
+	// name=plugins.enabled) — falling back to the plugin manifest's
+	// boot-time enabled state when there's no per-agent override.
+	if pluginMgr != nil {
+		for _, ag := range agentMgr.All() {
+			registerHookPluginsForAgent(ctx, pluginMgr, st, ag)
+		}
+	}
+
 	slog.Info("loaded user space", "user", userID, "agents", agentMgr.Names())
 
 	return &UserSpace{
@@ -760,9 +786,77 @@ func loadUserSpace(ctx context.Context, userID string, mb *bus.MessageBus, st st
 		Provider:    prov,
 		Agents:      agentMgr,
 		SandboxPool: pool,
+		PluginMgr:   pluginMgr,
 	}, nil
 }
 
+// registerHookPluginsForAgent walks every running hook-type plugin
+// and attaches it to ag.HookRegistry IF this agent has explicitly
+// opted in via the per-agent plugins.enabled row.
+//
+// Default is OPT-IN: a plugin being enabled system-wide only means
+// its process runs and is available to attach. Each agent must
+// individually set `plugins.enabled[<id>] = true` (via the dashboard
+// Plugins card or directly in the configs table) for the plugin's
+// hooks to fire on its turns. System-wide enable without per-agent
+// opt-in = plugin idle for that agent.
+//
+// Rationale: hook plugins can change agent behavior in surprising
+// ways (extra messages, modified prompts, recorded conversation
+// data). Default-deny avoids accidentally affecting agents the
+// operator didn't intend.
+//
+// Idempotent at the manager level (Process is already running), but
+// the HookRegistry side accumulates — call sites must not double-
+// register for the same agent. Today the only call sites are
+// loadUserSpace (once per UserSpace boot) and EnsureAgent (once per
+// foreign attach), neither of which fires twice for the same agent.
+func registerHookPluginsForAgent(ctx context.Context, pluginMgr *plugin.Manager, st store.Store, ag *agent.Agent) {
+	overrides := readAgentScopePluginsEnabled(ctx, st, ag.Name())
+	if len(overrides) == 0 {
+		return // fast path: no opt-ins for this agent
+	}
+	for _, inst := range pluginMgr.HookPlugins() {
+		id := inst.Manifest.ID
+		// Opt-in: only attach if this agent explicitly set true.
+		// Missing key or explicit false → skip.
+		if !overrides[id] {
+			continue
+		}
+		if inst.Process == nil || !inst.Process.IsRunning() {
+			slog.Warn("plugin: agent opted in but plugin not running",
+				"plugin", id, "agent", ag.Name())
+			continue
+		}
+		if err := plugin.RegisterPluginHooks(ctx, pluginMgr, id, ag.HookRegistry(), ag.Name()); err != nil {
+			slog.Warn("plugin: hook register failed",
+				"plugin", id, "agent", ag.Name(), "error", err)
+		}
+	}
+}
+
+// readAgentScopePluginsEnabled reads the per-agent plugin enable
+// overlay from the configs table: scope=agent, name=plugins.enabled,
+// data = {"<pluginID>": true|false, ...}. Missing row / missing key
+// means "no override; use system default". Returns nil on lookup
+// error (callers treat nil as "no overrides").
+func readAgentScopePluginsEnabled(ctx context.Context, st store.Store, agentID string) map[string]bool {
+	if st == nil || agentID == "" {
+		return nil
+	}
+	rec, err := st.GetConfigByName(ctx, store.KindSetting, "", agentID, "plugins.enabled")
+	if err != nil || rec == nil {
+		return nil
+	}
+	out := make(map[string]bool, len(rec.Data))
+	for k, v := range rec.Data {
+		if b, ok := v.(bool); ok {
+			out[k] = b
+		}
+	}
+	return out
+}
+
 // newProviderFromConfig picks an LLM provider for the resolved default
 // model. Returns nil (with a clear log line) when nothing matches; the
 // agent loop surfaces the missing-provider state as an error on the
@@ -817,22 +911,28 @@ type userSpaceRegistry struct {
 	workspace         workspace.Store
 	meter             usage.Meter
 	systemSandboxPool sandbox.ExecutorPool
-	idleTTL           time.Duration
+	// pluginMgr is the shared (process-wide) plugin manager. Nil
+	// when systemPlugins is disabled. Used by loadUserSpace and
+	// EnsureAgent to register hook-type plugins onto each agent's
+	// HookRegistry, gated by per-agent plugins.enabled config.
+	pluginMgr *plugin.Manager
+	idleTTL   time.Duration
 }
 
 type userSpaceEntry struct {
 	space    *UserSpace
 	lastUsed time.Time
 }
 
-func newUserSpaceRegistry(mb *bus.MessageBus, st store.Store, ws workspace.Store, meter usage.Meter, systemSandboxPool sandbox.ExecutorPool) *userSpaceRegistry {
+func newUserSpaceRegistry(mb *bus.MessageBus, st store.Store, ws workspace.Store, meter usage.Meter, systemSandboxPool sandbox.ExecutorPool, pluginMgr *plugin.Manager) *userSpaceRegistry {
 	return &userSpaceRegistry{
 		spaces:            make(map[string]*userSpaceEntry),
 		bus:               mb,
 		store:             st,
 		workspace:         ws,
 		meter:             meter,
 		systemSandboxPool: systemSandboxPool,
+		pluginMgr:         pluginMgr,
 		idleTTL:           30 * time.Minute,
 	}
 }
@@ -860,7 +960,7 @@ func (r *userSpaceRegistry) getOrLoad(ctx context.Context, userID string) (*User
 		e.lastUsed = time.Now()
 		return e.space, nil
 	}
-	sp, err := loadUserSpace(ctx, userID, r.bus, r.store, r.workspace, r.meter, r.systemSandboxPool)
+	sp, err := loadUserSpace(ctx, userID, r.bus, r.store, r.workspace, r.meter, r.systemSandboxPool, r.pluginMgr)
 	if err != nil {
 		return nil, err
 	}

internal/plugin/hook_adapter.go

@@ -115,6 +115,8 @@ func buildHookFireParams(pointName string, hc *agent.HookContext) HookFireParams
 	params := HookFireParams{
 		Point:      pointName,
 		AgentName:  hc.AgentName,
+		Channel:    hc.Channel,
+		AccountID:  hc.AccountID,
 		ChatID:     hc.ChatID,
 		UserID:     hc.UserID,
 		ToolName:   hc.ToolName,

internal/plugin/manager.go

@@ -2,11 +2,13 @@ package plugin
 
 import (
 	"context"
+	"encoding/base64"
 	"encoding/json"
 	"fmt"
 	"log/slog"
 	"os"
 	"path/filepath"
+	"strconv"
 	"sync"
 	"time"
 
@@ -15,6 +17,23 @@ import (
 
 const shutdownTimeout = 5 * time.Second
 
+// defaultChatSendDelay is the small async delay applied before pushing
+// a plugin's chat.send into bus.Outbound — see the comment at the
+// chat.send case in handleNotification for the ordering rationale.
+const defaultChatSendDelay = 50 * time.Millisecond
+
+func pluginChatSendDelay() time.Duration {
+	v := os.Getenv("FASTCLAW_PLUGIN_CHAT_SEND_DELAY_MS")
+	if v == "" {
+		return defaultChatSendDelay
+	}
+	ms, err := strconv.Atoi(v)
+	if err != nil || ms < 0 {
+		return defaultChatSendDelay
+	}
+	return time.Duration(ms) * time.Millisecond
+}
+
 // Manifest is the plugin.json descriptor.
 type Manifest struct {
 	ID           string                       `json:"id"`
@@ -354,6 +373,68 @@ func (m *Manager) handleNotification(pluginID string, n Notification) {
 
 		slog.Info("plugin: inbound message", "plugin", pluginID, "channel", channel, "chat_id", params.ChatID)
 
+	case MethodChatSend:
+		var params ChatSendParams
+		if err := json.Unmarshal(n.Params, &params); err != nil {
+			slog.Warn("plugin: invalid chat.send", "plugin", pluginID, "error", err)
+			return
+		}
+		if params.Channel == "" || params.ChatID == "" {
+			slog.Warn("plugin: chat.send missing channel/chatId", "plugin", pluginID)
+			return
+		}
+		items := make([]bus.MediaItem, 0, len(params.Media))
+		for _, m := range params.Media {
+			data, err := base64.StdEncoding.DecodeString(m.BytesB64)
+			if err != nil {
+				slog.Warn("plugin: chat.send media base64 decode failed",
+					"plugin", pluginID, "filename", m.Filename, "error", err)
+				continue
+			}
+			items = append(items, bus.MediaItem{
+				Filename:    m.Filename,
+				ContentType: m.ContentType,
+				Bytes:       data,
+			})
+		}
+		out := bus.OutboundMessage{
+			Channel:    params.Channel,
+			AccountID:  params.AccountID,
+			AgentID:    params.AgentID,
+			ChatID:     params.ChatID,
+			Text:       params.Text,
+			MediaItems: items,
+		}
+		// Ordering vs the agent's main reply: PostTurn hook fires
+		// while the agent loop is still finishing, so when a plugin
+		// reacts to PostTurn and calls chat.send right away, the
+		// gateway hasn't yet pushed the agent's reply onto
+		// bus.Outbound. Without the delay below, a fast plugin can
+		// win the race and the chatter sees the plugin's follow-up
+		// bubble BEFORE the agent's actual reply.
+		//
+		// The gateway's bus.Outbound enqueue is sub-millisecond once
+		// HandleMessage returns. A short async delay here is enough
+		// to let it win in practice. Async so the plugin's stdout
+		// reader isn't blocked. Tunable via FASTCLAW_PLUGIN_CHAT_SEND_DELAY_MS;
+		// set 0 to disable the delay entirely.
+		delay := pluginChatSendDelay()
+		go func() {
+			if delay > 0 {
+				time.Sleep(delay)
+			}
+			select {
+			case m.bus.Outbound <- out:
+				slog.Info("plugin: chat.send dispatched",
+					"plugin", pluginID, "channel", out.Channel,
+					"chat_id", out.ChatID, "text_len", len(out.Text),
+					"media_count", len(out.MediaItems))
+			default:
+				slog.Warn("plugin: chat.send dropped — bus.Outbound full",
+					"plugin", pluginID, "channel", out.Channel, "chat_id", out.ChatID)
+			}
+		}()
+
 	default:
 		slog.Debug("plugin: unhandled notification", "plugin", pluginID, "method", n.Method)
 	}