feat(extension): Plugin / Hook framework with command pruning

.github/workflows/ci.yml

@@ -30,7 +30,7 @@ jobs:
       - name: Build
         run: go build ./...
       - name: Vet
-        run: go vet ./...
+        run: go vet -tags testing ./...
       - name: Check formatting
         run: |
           unformatted=$(gofmt -l .)
@@ -63,7 +63,7 @@ jobs:
       - name: Fetch meta data
         run: python3 scripts/fetch_meta.py
       - name: Run tests
-        run: go test -v -race -count=1 -timeout=5m ./cmd/... ./internal/... ./shortcuts/...
+        run: go test -tags testing -v -race -count=1 -timeout=5m ./cmd/... ./internal/... ./shortcuts/... ./extension/...
 
   lint:
     needs: fast-gate
@@ -81,7 +81,7 @@ jobs:
       - name: Fetch meta data
         run: python3 scripts/fetch_meta.py
       - name: Run golangci-lint
-        run: go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.1.6 run --new-from-rev=origin/main
+        run: go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.1.6 run --build-tags=testing --new-from-rev=origin/main
 
   coverage:
     needs: fast-gate
@@ -99,7 +99,7 @@ jobs:
       - name: Run tests with coverage
         run: |
           packages=$(go list ./... | grep -v '^github.com/larksuite/cli/tests/cli_e2e$' | grep -v '^github.com/larksuite/cli/tests/cli_e2e/')
-          go test -race -coverprofile=coverage.txt -covermode=atomic $packages
+          go test -tags testing -race -coverprofile=coverage.txt -covermode=atomic $packages
       - name: Upload coverage to Codecov
         uses: codecov/codecov-action@3f20e214133d0983f9a10f3d63b0faf9241a3daa # v6
         with:
@@ -153,14 +153,14 @@ jobs:
         run: |
           # Analyze current HEAD (strip line:col for stable diff across line shifts)
           # Filter "go: downloading ..." lines to avoid false diffs from module cache state
-          go run golang.org/x/tools/cmd/deadcode@v0.31.0 -test ./... 2>&1 | \
+          go run golang.org/x/tools/cmd/deadcode@v0.31.0 -tags=testing -test ./... 2>&1 | \
             grep -v '^go: ' | \
             sed 's/:[0-9][0-9]*:[0-9][0-9]*:/:/' | sort > /tmp/dc-head.txt
 
           # Analyze base branch via worktree
           git worktree add -q /tmp/dc-base "origin/${{ github.base_ref }}"
           (cd /tmp/dc-base && python3 scripts/fetch_meta.py && \
-           go run golang.org/x/tools/cmd/deadcode@v0.31.0 -test ./... 2>&1 | \
+           go run golang.org/x/tools/cmd/deadcode@v0.31.0 -tags=testing -test ./... 2>&1 | \
             grep -v '^go: ' | \
             sed 's/:[0-9][0-9]*:[0-9][0-9]*:/:/' | sort > /tmp/dc-base.txt) || {
             echo "::warning::Failed to analyze base branch — skipping incremental dead code check"

Makefile

@@ -8,7 +8,7 @@ DATE     := $(shell date +%Y-%m-%d)
 LDFLAGS  := -s -w -X $(MODULE)/internal/build.Version=$(VERSION) -X $(MODULE)/internal/build.Date=$(DATE)
 PREFIX   ?= /usr/local
 
-.PHONY: all build vet test unit-test integration-test install uninstall clean fetch_meta gitleaks
+.PHONY: all build vet fmt-check test unit-test integration-test examples-build install uninstall clean fetch_meta gitleaks
 
 all: test
 
@@ -19,15 +19,37 @@ build: fetch_meta
 	go build -trimpath -ldflags "$(LDFLAGS)" -o $(BINARY) .
 
 vet: fetch_meta
-	go vet ./...
+	go vet -tags testing ./...
 
+# fmt-check fails when any file would be reformatted by gofmt. Keep this
+# in sync with the fast-gate "Check formatting" step in CI.
+fmt-check:
+	@unformatted=$$(gofmt -l . | grep -v '^\.claude/' || true); \
+	if [ -n "$$unformatted" ]; then \
+		echo "Unformatted Go files:"; \
+		echo "$$unformatted"; \
+		echo "Run 'gofmt -w .' and commit."; \
+		exit 1; \
+	fi
+
+# unit-test passes -tags testing because public-SDK packages gate test-only
+# helpers (e.g. platform.ResetForTesting) behind //go:build testing. The
+# ./extension/... package list keeps the public plugin SDK in the default
+# test matrix.
 unit-test: fetch_meta
-	go test -race -gcflags="all=-N -l" -count=1 ./cmd/... ./internal/... ./shortcuts/...
+	go test -tags testing -race -gcflags="all=-N -l" -count=1 \
+		./cmd/... ./internal/... ./shortcuts/... ./extension/...
+
+# examples-build keeps the shipped plugin-SDK examples compilable. If this
+# breaks, the plugin author guide's "go build ./..." path is broken.
+examples-build:
+	go build ./extension/platform/examples/audit-observer
+	go build ./extension/platform/examples/readonly-policy
 
 integration-test: build
 	go test -v -count=1 ./tests/...
 
-test: vet unit-test integration-test
+test: vet fmt-check unit-test examples-build integration-test
 
 install: build
 	install -d $(PREFIX)/bin

cmd/auth/login.go

@@ -50,7 +50,7 @@ For AI agents: this command blocks until the user completes authorization in the
 browser. Run it in the background and retrieve the verification URL from its output.`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			if mode := f.ResolveStrictMode(cmd.Context()); mode == core.StrictModeBot {
-				return output.ErrWithHint(output.ExitValidation, "strict_mode",
+				return output.ErrWithHint(output.ExitValidation, "command_denied",
 					fmt.Sprintf("strict mode is %q, user login is disabled in this profile", mode),
 					"if the user explicitly wants to switch to user identity, see `lark-cli config strict-mode --help` (confirm with the user before switching; switching does NOT require re-bind)")
 			}

cmd/build.go

@@ -19,7 +19,9 @@
 	cmdupdate "github.com/larksuite/cli/cmd/update"
 	_ "github.com/larksuite/cli/events"
 	"github.com/larksuite/cli/internal/build"
+	"github.com/larksuite/cli/internal/cmdpolicy"
 	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/hook"
 	"github.com/larksuite/cli/internal/keychain"
 	"github.com/larksuite/cli/shortcuts"
 	"github.com/spf13/cobra"
@@ -60,17 +62,22 @@
 }
 
 // Build constructs the full command tree without executing.
-// Returns only the cobra.Command; Factory is internal.
+// Returns only the cobra.Command; Factory and hook Registry are internal.
 // Use Execute for the standard production entry point.
 func Build(ctx context.Context, inv cmdutil.InvocationContext, opts ...BuildOption) *cobra.Command {
-	_, rootCmd := buildInternal(ctx, inv, opts...)
+	_, rootCmd, _ := buildInternal(ctx, inv, opts...)
 	return rootCmd
 }
 
 // buildInternal is a pure assembly function: it wires the command tree from
 // inv and BuildOptions alone. Any state-dependent decision (disk, network,
 // env) belongs in the caller and must be threaded in via BuildOption.
-func buildInternal(ctx context.Context, inv cmdutil.InvocationContext, opts ...BuildOption) (*cmdutil.Factory, *cobra.Command) {
+//
+// Returns (factory, rootCmd, registry). The registry is nil when plugin
+// install failed (FailClosed guard installed) or when no plugin produced
+// hooks; callers that wire Shutdown emit must nil-check before calling
+// hook.Emit.
+func buildInternal(ctx context.Context, inv cmdutil.InvocationContext, opts ...BuildOption) (*cmdutil.Factory, *cobra.Command, *hook.Registry) {
 	// cfg.globals.Profile is left zero here; it's bound to the --profile
 	// flag in RegisterGlobalFlags and filled by cobra's parse step.
 	cfg := &buildConfig{}
@@ -124,10 +131,75 @@
 	service.RegisterServiceCommandsWithContext(ctx, rootCmd, f)
 	shortcuts.RegisterShortcutsWithContext(ctx, rootCmd, f)
 
+	installUnknownSubcommandGuard(rootCmd)
+
 	// Prune commands incompatible with strict mode.
 	if mode := f.ResolveStrictMode(ctx); mode.IsActive() {
 		pruneForStrictMode(rootCmd, mode)
 	}
 
-	return f, rootCmd
+	// Run the platform host: install registered plugins, collecting
+	// their Restrict() contributions and their hooks. FailClosed
+	// failures (and untrusted-config failures like restricts_mismatch)
+	// are abort-worthy: InstallAll returns an error in those cases.
+	// We honour that by installing a PersistentPreRunE that emits
+	// the structured envelope at command-dispatch time -- buildInternal
+	// itself cannot return an error without breaking its assembly
+	// contract, but cobra runs PersistentPreRunE before any RunE so
+	// the user sees the error on their very next invocation.
+	installResult, installErr := installPluginsAndHooks(cfg.streams.ErrOut)
+	if installErr != nil {
+		installPluginInstallErrorGuard(rootCmd, installErr)
+		// Stop wiring more state from a failed install -- the rest of
+		// the function would only matter if the CLI is allowed to
+		// proceed normally, which it isn't.
+		return f, rootCmd, nil
+	}
+	var pluginRules []cmdpolicy.PluginRule
+	var registry *hook.Registry
+	if installResult != nil {
+		pluginRules = installResult.PluginRules
+		registry = installResult.Registry
+	}
+
+	// Apply user-layer command pruning: yaml + Plugin.Restrict.
+	//
+	// **Error policy splits by source**:
+	//   - Plugin path (any pluginRules contributed): a validation or
+	//     conflict error is a HARD failure -- the plugin author asked
+	//     for a security policy, silently dropping it would leave the
+	//     CLI more permissive than intended. Abort via the conflict
+	//     guard so every command surfaces the structured envelope.
+	//   - yaml-only path: stays fail-OPEN with a warning. A user typo
+	//     in policy.yml must not lock them out of every command.
+	if err := applyUserPolicyPruning(rootCmd, pluginRules); err != nil {
+		if len(pluginRules) > 0 {
+			installPluginConflictGuard(rootCmd, err)
+			return f, rootCmd, nil
+		}
+		warnPolicyError(cfg.streams.ErrOut, err)
+	}
+
+	// Install hooks onto the (now-pruned) command tree and emit the
+	// Startup lifecycle event so Plugin.On(Startup) handlers can run.
+	//
+	// Startup handler error or panic is a HARD failure: a plugin's
+	// Startup logic is part of its install contract, and silently
+	// continuing would mean the plugin's invariants do not hold while
+	// the rest of its hooks (Wrap / Observe) still fire. Install the
+	// plugin_lifecycle guard and short-circuit so every subsequent
+	// dispatch surfaces the envelope.
+	if registry != nil {
+		if err := wireHooks(ctx, rootCmd, registry); err != nil {
+			installPluginLifecycleErrorGuard(rootCmd, err)
+			return f, rootCmd, nil
+		}
+	}
+
+	// Snapshot the plugin inventory so `config plugins show` can answer
+	// "what plugins / hooks / rules are currently in effect" without
+	// re-calling plugin methods at display time.
+	recordInventory(installResult)
+
+	return f, rootCmd, registry
 }

cmd/config/config.go

@@ -14,6 +14,11 @@ func NewCmdConfig(f *cmdutil.Factory) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "config",
 		Short: "Global CLI configuration management",
+		Long: `Global CLI configuration management.
+
+Diagnostic (hidden) commands — runnable but omitted from --help:
+  lark-cli config policy show    Inspect active user-layer policy
+  lark-cli config plugins show   Inspect installed plugins and hooks`,
 		PersistentPreRunE: func(cmd *cobra.Command, args []string) error {
 			// Replicate rootCmd's PersistentPreRun behaviour: cobra stops at the first
 			// PersistentPreRun[E] found walking up the chain, so the root-level
@@ -31,6 +36,8 @@ func NewCmdConfig(f *cmdutil.Factory) *cobra.Command {
 	cmd.AddCommand(NewCmdConfigShow(f, nil))
 	cmd.AddCommand(NewCmdConfigDefaultAs(f))
 	cmd.AddCommand(NewCmdConfigStrictMode(f))
+	cmd.AddCommand(NewCmdConfigPolicy(f))
+	cmd.AddCommand(NewCmdConfigPlugins(f))
 	return cmd
 }
 

cmd/config/plugins.go

@@ -0,0 +1,99 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package config
+
+import (
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/output"
+	internalplatform "github.com/larksuite/cli/internal/platform"
+)
+
+// NewCmdConfigPlugins exposes the plugin inventory diagnostic command.
+//
+// `config policy show` is intentionally focused on the user-layer Rule
+// (Restrict). Plugins also contribute hooks (Observe / Wrap / Lifecycle)
+// that are not policy gates but still mutate the CLI's runtime behaviour.
+// This command surfaces both halves so an operator can answer "what is
+// this binary doing differently from stock lark-cli?" in one place.
+//
+// Like config policy show, the dispatch path is exempt from policy
+// enforcement (see internal/cmdpolicy/diagnostic.go) so it remains
+// usable under any Rule.
+func NewCmdConfigPlugins(f *cmdutil.Factory) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:    "plugins",
+		Hidden: true, // diagnostic-only; kept callable, omitted from --help so it stays out of AI-agent context
+		Short:  "Inspect installed plugins and their hook contributions",
+		// Same leaf-level no-op as config policy: the parent `config`
+		// group's PersistentPreRunE requires builtin credential, but
+		// this is a read-only diagnostic that must work everywhere.
+		PersistentPreRunE: func(c *cobra.Command, _ []string) error {
+			c.SilenceUsage = true
+			return nil
+		},
+	}
+	cmd.AddCommand(newCmdConfigPluginsShow(f))
+	return cmd
+}
+
+func newCmdConfigPluginsShow(f *cmdutil.Factory) *cobra.Command {
+	return &cobra.Command{
+		Use:   "show",
+		Short: "List successfully installed plugins, their rules, and registered hooks",
+		Long: `Print every plugin that committed during bootstrap, including:
+
+  - name / version / capabilities (FailurePolicy, Restricts, RequiredCLIVersion)
+  - rule (when the plugin called r.Restrict)
+  - hooks: observers (Before / After), wrappers, lifecycle handlers
+
+Hooks are attributed by their namespaced name -- the framework prepends
+the plugin name as the prefix at registration time, so an entry
+"secaudit.audit-pre" belongs to plugin "secaudit".`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return runConfigPluginsShow(f)
+		},
+	}
+}
+
+func runConfigPluginsShow(f *cmdutil.Factory) error {
+	inv := internalplatform.GetActiveInventory()
+	if inv == nil {
+		// Always emit the same field set as the populated branch so
+		// AI agents and CI scripts don't have to branch on whether
+		// `total` is present. `note` makes the unusual state explicit
+		// for human readers.
+		output.PrintJson(f.IOStreams.Out, map[string]any{
+			"plugins": []any{},
+			"total":   0,
+			"note":    "no inventory recorded; bootstrap did not finish",
+		})
+		return nil
+	}
+
+	plugins := make([]map[string]any, 0, len(inv.Plugins))
+	for _, p := range inv.Plugins {
+		entry := map[string]any{
+			"name":         p.Name,
+			"version":      p.Version,
+			"capabilities": p.Capabilities,
+		}
+		if p.Rule != nil {
+			entry["rule"] = p.Rule
+		}
+		entry["hooks"] = map[string]any{
+			"observers": p.Observers,
+			"wrappers":  p.Wrappers,
+			"lifecycle": p.Lifecycles,
+			"count":     len(p.Observers) + len(p.Wrappers) + len(p.Lifecycles),
+		}
+		plugins = append(plugins, entry)
+	}
+	output.PrintJson(f.IOStreams.Out, map[string]any{
+		"plugins": plugins,
+		"total":   len(plugins),
+	})
+	return nil
+}