feat: add a plugin-first runtime

Author: voocel

README.md

@@ -54,6 +54,12 @@ This split matters. The agent loop stays small and reusable, while long-running
 - Non-interactive print mode for pipes and scripts (`-p`)
 - Slash commands: `/model`, `/compact`, `/plan`, `/resume`, `/copy`, ...
 
+**Extensibility**
+- Plugin-first architecture with project and user plugin scopes
+- Plugin contributions: skills, commands, MCP servers
+- `/plugins create`, `/plugins install`, and `/plugins remove` for local plugin lifecycle
+- Trust / enable / disable governance with runtime reload
+
 ## Installation
 
 **Pre-built binary (recommended):**
@@ -145,6 +151,8 @@ Config files: `~/.codebot/settings.json` (global) or `.codebot/settings.json` (p
 
 All fields are optional. See [settings.example.jsonc](settings.example.jsonc) for the full reference with comments.
 
+Plugin authoring guide: [docs/plugins.md](docs/plugins.md). Real example plugins live under `docs/examples/plugins/`, including `review-assistant`, `release-ops`, and `docs-context`.
+
 ## Requirements
 
 - API key for at least one provider

README_zh.md

@@ -54,6 +54,12 @@
 - 非交互管道模式（`-p`）
 - 斜杠命令：`/model`, `/compact`, `/plan`, `/resume`, `/copy`, ...
 
+**扩展**
+- plugin-first 架构，支持 project / user 两级 plugin
+- plugin 贡献：skills、commands、MCP servers
+- `/plugins create`、`/plugins install`、`/plugins remove` 管理本地 plugin 生命周期
+- trust / enable / disable 治理与运行时热刷新
+
 ## 安装
 
 **预编译二进制（推荐）：**
@@ -145,6 +151,8 @@ Codebot 采用分层的 Coding Agent 架构：
 
 所有字段可选，参考 [settings.example.jsonc](settings.example.jsonc) 了解完整配置项及说明。
 
+Plugin 开发参考 [docs/plugins.md](docs/plugins.md)。真实示例 plugin 放在 `docs/examples/plugins/`，目前包含 `review-assistant`、`release-ops`、`docs-context`。
+
 ## 环境要求
 
 - 至少一个 Provider 的 API Key

cmd/codebot/main.go

@@ -57,7 +57,7 @@ func main() {
 	if rt.Session != nil && rt.Session.ModelName() != "" {
 		modelName = rt.Session.ModelName()
 	}
-	if err := ui.RunTUI(rt.Session, rt.Cwd, rt.GitBranch, modelName, version, rt.ApprovalEngine, rt.TaskRuntime, rt.MCPManager, rt.MCPServers, rt.SkillCatalog, rt.EnvHint, rt.SessionStore, rt.PlanSlug, rt.PlanTitle, rt.PlanPhase, rt.PlanPreMode, rt.PlanAllowedCommands); err != nil {
+	if err := ui.RunTUI(rt.Session, rt.Cwd, rt.GitBranch, modelName, version, rt.ApprovalEngine, rt.TaskRuntime, rt.MCPManager, rt.MCPServers, rt.PluginCatalog, rt.SkillCatalog, rt.EnvHint, rt.SessionStore, rt.PlanSlug, rt.PlanTitle, rt.PlanPhase, rt.PlanPreMode, rt.PlanAllowedCommands); err != nil {
 		fmt.Fprintf(os.Stderr, "error: %v\n", err)
 		os.Exit(1)
 	}

internal/agent/session.go

@@ -133,7 +133,6 @@ type skillRuntimeState struct {
 	baseModel       string
 	baseChatModel   agentcore.ChatModel
 	baseThinking    string
-	hooks           config.HooksConfig
 	invoked         []invokedSkillSnapshot
 	invocationCount map[string]int
 }

internal/agent/session_compaction.go

@@ -30,6 +30,10 @@ func (c *sessionContextController) compactWithReason(reason string) (result Comp
 	result = CompactionResult{Reason: reason}
 	c.session.recordCompactionAttempt(CompactionKindFull)
 	c.session.emit(SessionEvent{Type: SEAutoCompactionStart, CompactionReason: reason, CompactionKind: CompactionKindFull})
+	if c.session.hookRunner != nil {
+		tokensBefore := agentctx.EstimateTotal(c.session.agent.Messages())
+		c.session.hookRunner.RunPreCompact(context.Background(), reason, tokensBefore)
+	}
 	defer func() {
 		if err != nil {
 			return
@@ -48,6 +52,9 @@ func (c *sessionContextController) compactWithReason(reason string) (result Comp
 			KeptCount:          result.KeptCount,
 			SplitTurn:          result.SplitTurn,
 		})
+		if c.session.hookRunner != nil {
+			c.session.hookRunner.RunPostCompact(context.Background(), reason, result.TokensBefore, result.TokensAfter)
+		}
 	}()
 
 	msgs := c.session.agent.Messages()

internal/agent/session_prompt.go

@@ -33,6 +33,10 @@ func (s *Session) ReplaceAllTools(tools []agentcore.Tool) {
 	s.prompts.replaceAllTools(tools)
 }
 
+func (s *Session) ReplaceMCPTools(tools []agentcore.Tool) {
+	s.prompts.replaceMCPTools(tools)
+}
+
 func (s *Session) SetSystemSuffix(suffix string) {
 	s.prompts.setApprovedPlanPrompt(suffix)
 }
@@ -65,6 +69,18 @@ func (s *Session) SkillCatalog() *skill.Catalog {
 	return s.skillCatalog
 }
 
+func (s *Session) SetSkillCatalog(catalog *skill.Catalog) {
+	s.skillCatalog = catalog
+	if catalog != nil {
+		s.skills = catalog.List()
+	} else {
+		s.skills = nil
+	}
+	if s.prompts != nil {
+		s.prompts.rebuildPrompt()
+	}
+}
+
 func (s *Session) Reload() {
 	s.prompts.reload()
 }
@@ -117,6 +133,25 @@ func (m *sessionPromptManager) replaceAllTools(tools []agentcore.Tool) {
 	m.rebuildPrompt()
 }
 
+func (m *sessionPromptManager) replaceMCPTools(tools []agentcore.Tool) {
+	wasAllTools := sameToolSet(m.session.activeTools, m.session.allTools)
+	activeHasMCP := hasMCPTools(m.session.activeTools)
+
+	m.session.allTools = replaceMCPToolsInSlice(m.session.allTools, tools)
+
+	switch {
+	case wasAllTools:
+		m.session.activeTools = m.session.allTools
+	case activeHasMCP:
+		m.session.activeTools = replaceMCPToolsInSlice(m.session.activeTools, tools)
+	default:
+		return
+	}
+
+	m.session.agent.SetTools(m.session.activeTools...)
+	m.rebuildPrompt()
+}
+
 func (m *sessionPromptManager) setMCPInstructions(text string) {
 	m.session.overlays.MCP = text
 	m.rebuildPrompt()
@@ -142,7 +177,7 @@ func (m *sessionPromptManager) reload() {
 		m.session.skillCatalog.Reload()
 		m.session.skills = m.session.skillCatalog.List()
 	} else {
-		m.session.skills = skill.NewCatalog(m.session.cwd).List()
+		m.session.skills = skill.NewCatalog(m.session.cwd, nil).List()
 	}
 	m.rebuildPrompt()
 }
@@ -215,6 +250,41 @@ func (m *sessionPromptManager) refreshSkillReminders() {
 	m.session.mu.Unlock()
 }
 
+const mcpToolPrefix = "mcp__"
+
+func replaceMCPToolsInSlice(base []agentcore.Tool, mcpTools []agentcore.Tool) []agentcore.Tool {
+	out := make([]agentcore.Tool, 0, len(base)+len(mcpTools))
+	for _, tool := range base {
+		if strings.HasPrefix(tool.Name(), mcpToolPrefix) {
+			continue
+		}
+		out = append(out, tool)
+	}
+	out = append(out, mcpTools...)
+	return out
+}
+
+func hasMCPTools(tools []agentcore.Tool) bool {
+	for _, tool := range tools {
+		if strings.HasPrefix(tool.Name(), mcpToolPrefix) {
+			return true
+		}
+	}
+	return false
+}
+
+func sameToolSet(a, b []agentcore.Tool) bool {
+	if len(a) != len(b) {
+		return false
+	}
+	for i := range a {
+		if a[i].Name() != b[i].Name() {
+			return false
+		}
+	}
+	return true
+}
+
 func (s *Session) skillUsageScoresLocked() map[string]float64 {
 	if s.skillUsage != nil {
 		return s.skillUsage.Scores(time.Now())

internal/agent/session_runtime.go

@@ -17,6 +17,11 @@ import (
 var errStaleSessionGeneration = errors.New("stale session generation")
 
 func (s *Session) Prompt(text string) error {
+	if s.hookRunner != nil {
+		if err := s.hookRunner.RunUserPromptSubmit(context.Background(), text); err != nil {
+			return err
+		}
+	}
 	s.beginTurn()
 	if s.beforePrompt != nil {
 		s.beforePrompt()

internal/agent/session_state.go

@@ -8,7 +8,6 @@ import (
 	"time"
 
 	"github.com/voocel/agentcore"
-	"github.com/voocel/codebot/internal/config"
 	"github.com/voocel/codebot/internal/skill"
 )
 
@@ -123,12 +122,6 @@ func (s *Session) ApplySkillDelta(name string, delta skill.Delta) error {
 	}
 	s.applyTemporarySkillThinking(delta.Effort)
 
-	s.mu.Lock()
-	if len(delta.Hooks) > 0 {
-		s.skillRuntime.hooks = mergeHooksConfig(s.skillRuntime.hooks, toConfigHooks(delta.Hooks))
-	}
-	s.mu.Unlock()
-
 	if s.skillAllowsSetter != nil {
 		s.skillAllowsSetter(delta.AllowedTools)
 	}
@@ -143,12 +136,6 @@ func (s *Session) clearSkillDelta() {
 	s.clearTemporarySkillOverrides()
 }
 
-func (s *Session) CurrentSkillHooks() config.HooksConfig {
-	s.mu.Lock()
-	defer s.mu.Unlock()
-	return cloneHooksConfig(s.skillRuntime.hooks)
-}
-
 func (s *Session) recordInvokedSkill(name, promptText string, paths []string) {
 	name = strings.TrimSpace(name)
 	promptText = strings.TrimSpace(promptText)
@@ -193,89 +180,6 @@ func (s *Session) recordInvokedSkill(name, promptText string, paths []string) {
 	}
 }
 
-func cloneHooksConfig(src config.HooksConfig) config.HooksConfig {
-	if len(src) == 0 {
-		return nil
-	}
-	dst := make(config.HooksConfig, len(src))
-	for event, entries := range src {
-		cp := make([]config.HookEntry, len(entries))
-		copy(cp, entries)
-		dst[event] = cp
-	}
-	return dst
-}
-
-func toConfigHooks(src skill.HooksConfig) config.HooksConfig {
-	if len(src) == 0 {
-		return nil
-	}
-	dst := make(config.HooksConfig, len(src))
-	for event, entries := range src {
-		cp := make([]config.HookEntry, len(entries))
-		for i, entry := range entries {
-			cp[i] = config.HookEntry{
-				Type:     entry.Type,
-				Command:  entry.Command,
-				Matcher:  entry.Matcher,
-				Blocking: entry.Blocking,
-				Timeout:  entry.Timeout,
-			}
-		}
-		dst[event] = cp
-	}
-	return dst
-}
-
-func mergeHooksConfig(base, add config.HooksConfig) config.HooksConfig {
-	if len(add) == 0 {
-		return cloneHooksConfig(base)
-	}
-	merged := cloneHooksConfig(base)
-	if merged == nil {
-		merged = make(config.HooksConfig, len(add))
-	}
-	for event, entries := range add {
-		for _, entry := range entries {
-			if !containsHookEntry(merged[event], entry) {
-				merged[event] = append(merged[event], entry)
-			}
-		}
-	}
-	return merged
-}
-
-func containsHookEntry(entries []config.HookEntry, target config.HookEntry) bool {
-	for _, entry := range entries {
-		if hookEntryEqual(entry, target) {
-			return true
-		}
-	}
-	return false
-}
-
-func hookEntryEqual(a, b config.HookEntry) bool {
-	return a.Type == b.Type &&
-		a.Command == b.Command &&
-		a.Matcher == b.Matcher &&
-		boolPtrValue(a.Blocking) == boolPtrValue(b.Blocking) &&
-		intPtrValue(a.Timeout) == intPtrValue(b.Timeout)
-}
-
-func boolPtrValue(v *bool) bool {
-	if v == nil {
-		return false
-	}
-	return *v
-}
-
-func intPtrValue(v *int) int {
-	if v == nil {
-		return 0
-	}
-	return *v
-}
-
 func cloneInvocationCounts(src map[string]int) map[string]int {
 	if len(src) == 0 {
 		return nil

internal/agent/session_test.go

@@ -591,6 +591,40 @@ func TestSetToolsRebuildsPrompt(t *testing.T) {
 	}
 }
 
+func TestReplaceMCPToolsUpdatesAllToolsWithoutBreakingFilteredActiveTools(t *testing.T) {
+	t.Parallel()
+
+	allTools := []agentcore.Tool{
+		&stubTool{name: "read", desc: "Read file contents"},
+		&stubTool{name: "write", desc: "Write file contents"},
+		&stubTool{name: "mcp__docs__search", desc: "Search docs"},
+	}
+
+	ag := agentcore.NewAgent(agentcore.WithModel(&stubChatModel{}), agentcore.WithTools(allTools...))
+	s := NewSession(SessionConfig{
+		Agent:    ag,
+		Settings: config.Resolved{MaxTurns: 30},
+		Cwd:      t.TempDir(),
+		Tools:    allTools,
+	})
+	t.Cleanup(s.Close)
+
+	s.SetTools(s.ToolsByName("read")...)
+	s.ReplaceMCPTools([]agentcore.Tool{
+		&stubTool{name: "mcp__ops__deploy", desc: "Deploy service"},
+	})
+
+	if got := len(s.ToolsByName("mcp__ops__deploy")); got != 1 {
+		t.Fatalf("expected refreshed MCP tool in all tools, got %d", got)
+	}
+	if got := len(s.ToolsByName("mcp__docs__search")); got != 0 {
+		t.Fatalf("expected stale MCP tool removed from all tools, got %d", got)
+	}
+	if len(s.activeTools) != 1 || s.activeTools[0].Name() != "read" {
+		t.Fatalf("expected filtered active tools to remain unchanged, got %#v", s.activeTools)
+	}
+}
+
 func TestBuildUserMessagePrependsRuntimeRemindersBeforeStaticReminders(t *testing.T) {
 	t.Parallel()