feat(plugin, api): prevent plugin recursion on host model callbacks, enable targeted interceptor skipping

- Updated host model callback logic to skip originating plugin's interceptors during nested model executions.
- Added `SkipInterceptorPluginID` field to plugin API structs for controlling interceptor bypass behavior.
- Introduced supporting logic in host API handlers, plugin host registry, and callback contexts to identify and skip specific plugins.
- Enhanced unit tests across plugin host, API handlers, and execution paths to verify interceptor skipping behavior and plugin isolation.
- Revised documentation to clarify non-recursive behavior of host model callbacks and the use of `SkipInterceptorPluginID`.

Author: luispater

examples/plugin/README.md

@@ -43,6 +43,8 @@ plugins:
 
 `host-model-callback` declares the Management API capability and exposes a browser resource named `Host Model Callback`. The resource calls `host.model.execute` for non-streaming requests and `host.model.execute_stream` plus `host.model.stream_read` for streaming requests. It demonstrates explicit stream close with `host.model.stream_close` and an `implicit_close=true` option for RPC-scope host cleanup.
 
+When the resource forwards its `host_callback_id`, CPA identifies the plugin that initiated the host model callback and skips that same plugin's interceptors for the nested execution. This makes host model callbacks non-recursive for the caller while allowing other plugins to intercept the nested request.
+
 ```yaml
 plugins:
   configs:

examples/plugin/README_CN.md

@@ -43,6 +43,8 @@ plugins:
 
 `host-model-callback` 声明 Management API 能力，并暴露名为 `Host Model Callback` 的浏览器资源。该资源在非流式请求中调用 `host.model.execute`，在流式请求中调用 `host.model.execute_stream` 和 `host.model.stream_read`。它演示了通过 `host.model.stream_close` 显式关闭流，也提供 `implicit_close=true` 用于演示 RPC 作用域结束时的宿主隐式清理。
 
+当该资源转发自身收到的 `host_callback_id` 时，CPA 会识别发起宿主模型回调的插件，并在嵌套模型执行中跳过同一个插件的拦截器。因此宿主模型回调不会递归调用发起插件自身，但其他已启用插件仍可拦截这次嵌套请求。
+
 ```yaml
 plugins:
   configs:

examples/plugin/host-model-callback/README.md

@@ -115,6 +115,12 @@ By default, streaming mode explicitly closes the host-owned stream with `host.mo
 
 When `implicit_close=true` is set, the plugin intentionally skips the explicit close call. CPA injects `host_callback_id` into the `management.handle` request, and this example forwards that callback ID to `host.model.execute_stream` so the host can close the stream when the `management.handle` RPC callback scope returns. This mode exists only to demonstrate host cleanup behavior; normal plugin code should explicitly close streams it opens.
 
+## Recursion Guard
+
+This example forwards the `host_callback_id` received from `management.handle` when it calls `host.model.execute` or `host.model.execute_stream`. CPA uses that callback scope to identify the plugin that initiated the host model callback and skips that same plugin's request, response, and stream interceptors for the nested model execution.
+
+Host model callbacks are therefore not recursive for the caller. Other enabled plugins can still intercept the nested request.
+
 ## Billing and Usage
 
 The callback uses the existing CPA model executor path. Usage collection, request accounting, and billing metadata are handled by the same executor and usage reporter path as normal proxied requests. The callback layer does not bill twice and does not create an additional usage record by itself.

examples/plugin/host-model-callback/go/main.go

@@ -427,6 +427,9 @@ func executeOnce(opts runOptions) (pluginapi.HostModelExecutionResponse, error)
 	if errBody != nil {
 		return pluginapi.HostModelExecutionResponse{}, errBody
 	}
+	// Forward HostCallbackID so the host skips this plugin's interceptors on the
+	// nested model execution. Host model callbacks do not recursively call the
+	// originating plugin's interceptor chain.
 	result, errCall := callHost(pluginabi.MethodHostModelExecute, hostModelExecutionRequest{
 		HostModelExecutionRequest: pluginapi.HostModelExecutionRequest{
 			EntryProtocol: opts.EntryProtocol,
@@ -456,6 +459,9 @@ func executeStream(opts runOptions) (data streamPageData) {
 		data.Error = errBody.Error()
 		return data
 	}
+	// Forward HostCallbackID so the host skips this plugin's interceptors on the
+	// nested model execution. Host model callbacks do not recursively call the
+	// originating plugin's interceptor chain.
 	result, errCall := callHost(pluginabi.MethodHostModelExecuteStream, hostModelExecutionRequest{
 		HostModelExecutionRequest: pluginapi.HostModelExecutionRequest{
 			EntryProtocol: opts.EntryProtocol,

internal/pluginhost/abi.go

@@ -14,5 +14,5 @@ type pluginClient interface {
 }
 
 type pluginLoader interface {
-	Open(path string, host *Host) (pluginClient, error)
+	Open(file pluginFile, host *Host) (pluginClient, error)
 }

internal/pluginhost/adapters.go

@@ -569,25 +569,34 @@ func (h *Host) callStreamChunkInterceptor(ctx context.Context, pluginID string,
 }
 
 func (h *Host) InterceptRequestBeforeAuth(ctx context.Context, req pluginapi.RequestInterceptRequest) pluginapi.RequestInterceptResponse {
+	return h.InterceptRequestBeforeAuthExcept(ctx, req, "")
+}
+
+func (h *Host) InterceptRequestBeforeAuthExcept(ctx context.Context, req pluginapi.RequestInterceptRequest, skipPluginID string) pluginapi.RequestInterceptResponse {
 	return h.interceptRequest(ctx, req, "RequestInterceptor.InterceptRequestBeforeAuth", func(interceptor pluginapi.RequestInterceptor, ctx context.Context, req pluginapi.RequestInterceptRequest) (pluginapi.RequestInterceptResponse, error) {
 		return interceptor.InterceptRequestBeforeAuth(ctx, req)
-	})
+	}, skipPluginID)
 }
 
 func (h *Host) InterceptRequestAfterAuth(ctx context.Context, req pluginapi.RequestInterceptRequest) pluginapi.RequestInterceptResponse {
+	return h.InterceptRequestAfterAuthExcept(ctx, req, "")
+}
+
+func (h *Host) InterceptRequestAfterAuthExcept(ctx context.Context, req pluginapi.RequestInterceptRequest, skipPluginID string) pluginapi.RequestInterceptResponse {
 	return h.interceptRequest(ctx, req, "RequestInterceptor.InterceptRequestAfterAuth", func(interceptor pluginapi.RequestInterceptor, ctx context.Context, req pluginapi.RequestInterceptRequest) (pluginapi.RequestInterceptResponse, error) {
 		return interceptor.InterceptRequestAfterAuth(ctx, req)
-	})
+	}, skipPluginID)
 }
 
-func (h *Host) interceptRequest(ctx context.Context, req pluginapi.RequestInterceptRequest, method string, invoke func(pluginapi.RequestInterceptor, context.Context, pluginapi.RequestInterceptRequest) (pluginapi.RequestInterceptResponse, error)) pluginapi.RequestInterceptResponse {
+func (h *Host) interceptRequest(ctx context.Context, req pluginapi.RequestInterceptRequest, method string, invoke func(pluginapi.RequestInterceptor, context.Context, pluginapi.RequestInterceptRequest) (pluginapi.RequestInterceptResponse, error), skipPluginID string) pluginapi.RequestInterceptResponse {
 	current := pluginapi.RequestInterceptResponse{
 		Headers: cloneHeader(req.Headers),
 		Body:    bytes.Clone(req.Body),
 	}
+	skipPluginID = strings.TrimSpace(skipPluginID)
 	for _, record := range h.Snapshot().records {
 		interceptor := record.plugin.Capabilities.RequestInterceptor
-		if h.isPluginFused(record.id) || interceptor == nil {
+		if h.isPluginFused(record.id) || interceptor == nil || record.id == skipPluginID {
 			continue
 		}
 		nextReq := req
@@ -607,13 +616,18 @@ func (h *Host) interceptRequest(ctx context.Context, req pluginapi.RequestInterc
 }
 
 func (h *Host) InterceptResponse(ctx context.Context, req pluginapi.ResponseInterceptRequest) pluginapi.ResponseInterceptResponse {
+	return h.InterceptResponseExcept(ctx, req, "")
+}
+
+func (h *Host) InterceptResponseExcept(ctx context.Context, req pluginapi.ResponseInterceptRequest, skipPluginID string) pluginapi.ResponseInterceptResponse {
 	current := pluginapi.ResponseInterceptResponse{
 		Headers: cloneHeader(req.ResponseHeaders),
 		Body:    bytes.Clone(req.Body),
 	}
+	skipPluginID = strings.TrimSpace(skipPluginID)
 	for _, record := range h.Snapshot().records {
 		interceptor := record.plugin.Capabilities.ResponseInterceptor
-		if h.isPluginFused(record.id) || interceptor == nil {
+		if h.isPluginFused(record.id) || interceptor == nil || record.id == skipPluginID {
 			continue
 		}
 		nextReq := req
@@ -634,13 +648,18 @@ func (h *Host) InterceptResponse(ctx context.Context, req pluginapi.ResponseInte
 }
 
 func (h *Host) InterceptStreamChunk(ctx context.Context, req pluginapi.StreamChunkInterceptRequest) pluginapi.StreamChunkInterceptResponse {
+	return h.InterceptStreamChunkExcept(ctx, req, "")
+}
+
+func (h *Host) InterceptStreamChunkExcept(ctx context.Context, req pluginapi.StreamChunkInterceptRequest, skipPluginID string) pluginapi.StreamChunkInterceptResponse {
 	current := pluginapi.StreamChunkInterceptResponse{
 		Headers: cloneHeader(req.ResponseHeaders),
 		Body:    bytes.Clone(req.Body),
 	}
+	skipPluginID = strings.TrimSpace(skipPluginID)
 	for _, record := range h.Snapshot().records {
 		interceptor := record.plugin.Capabilities.StreamChunkInterceptor
-		if h.isPluginFused(record.id) || interceptor == nil || current.DropChunk {
+		if h.isPluginFused(record.id) || interceptor == nil || current.DropChunk || record.id == skipPluginID {
 			continue
 		}
 		nextReq := req

internal/pluginhost/adapters_test.go

@@ -1342,6 +1342,81 @@ func TestInterceptRequestAfterAuthPassesTargetFormat(t *testing.T) {
 	}
 }
 
+func TestInterceptorsSkipExceptedPlugin(t *testing.T) {
+	originCalls := 0
+	otherCalls := 0
+	host := newHostWithRecords(
+		capabilityRecord{
+			id:       "origin",
+			priority: 20,
+			plugin: pluginapi.Plugin{Capabilities: pluginapi.Capabilities{
+				RequestInterceptor: requestInterceptorFunc(func(ctx context.Context, req pluginapi.RequestInterceptRequest) (pluginapi.RequestInterceptResponse, error) {
+					originCalls++
+					return pluginapi.RequestInterceptResponse{Body: append(req.Body, []byte("|origin-request")...)}, nil
+				}),
+				ResponseInterceptor: responseInterceptorFunc{
+					interceptResponse: func(ctx context.Context, req pluginapi.ResponseInterceptRequest) (pluginapi.ResponseInterceptResponse, error) {
+						originCalls++
+						return pluginapi.ResponseInterceptResponse{Body: append(req.Body, []byte("|origin-response")...)}, nil
+					},
+				},
+				StreamChunkInterceptor: responseInterceptorFunc{
+					interceptStreamChunk: func(ctx context.Context, req pluginapi.StreamChunkInterceptRequest) (pluginapi.StreamChunkInterceptResponse, error) {
+						originCalls++
+						return pluginapi.StreamChunkInterceptResponse{Body: append(req.Body, []byte("|origin-stream")...)}, nil
+					},
+				},
+			}},
+		},
+		capabilityRecord{
+			id:       "other",
+			priority: 10,
+			plugin: pluginapi.Plugin{Capabilities: pluginapi.Capabilities{
+				RequestInterceptor: requestInterceptorFunc(func(ctx context.Context, req pluginapi.RequestInterceptRequest) (pluginapi.RequestInterceptResponse, error) {
+					otherCalls++
+					return pluginapi.RequestInterceptResponse{Body: append(req.Body, []byte("|other-request")...)}, nil
+				}),
+				ResponseInterceptor: responseInterceptorFunc{
+					interceptResponse: func(ctx context.Context, req pluginapi.ResponseInterceptRequest) (pluginapi.ResponseInterceptResponse, error) {
+						otherCalls++
+						return pluginapi.ResponseInterceptResponse{Body: append(req.Body, []byte("|other-response")...)}, nil
+					},
+				},
+				StreamChunkInterceptor: responseInterceptorFunc{
+					interceptStreamChunk: func(ctx context.Context, req pluginapi.StreamChunkInterceptRequest) (pluginapi.StreamChunkInterceptResponse, error) {
+						otherCalls++
+						return pluginapi.StreamChunkInterceptResponse{Body: append(req.Body, []byte("|other-stream")...)}, nil
+					},
+				},
+			}},
+		},
+	)
+
+	reqOut := host.InterceptRequestBeforeAuthExcept(context.Background(), pluginapi.RequestInterceptRequest{Body: []byte("body")}, "origin")
+	afterOut := host.InterceptRequestAfterAuthExcept(context.Background(), pluginapi.RequestInterceptRequest{Body: []byte("body")}, "origin")
+	respOut := host.InterceptResponseExcept(context.Background(), pluginapi.ResponseInterceptRequest{Body: []byte("body")}, "origin")
+	streamOut := host.InterceptStreamChunkExcept(context.Background(), pluginapi.StreamChunkInterceptRequest{Body: []byte("body")}, "origin")
+
+	if originCalls != 0 {
+		t.Fatalf("origin plugin calls = %d, want 0", originCalls)
+	}
+	if otherCalls != 4 {
+		t.Fatalf("other plugin calls = %d, want 4", otherCalls)
+	}
+	if string(reqOut.Body) != "body|other-request" {
+		t.Fatalf("request body = %q, want body|other-request", reqOut.Body)
+	}
+	if string(afterOut.Body) != "body|other-request" {
+		t.Fatalf("after-auth request body = %q, want body|other-request", afterOut.Body)
+	}
+	if string(respOut.Body) != "body|other-response" {
+		t.Fatalf("response body = %q, want body|other-response", respOut.Body)
+	}
+	if string(streamOut.Body) != "body|other-stream" {
+		t.Fatalf("stream body = %q, want body|other-stream", streamOut.Body)
+	}
+}
+
 func TestResponseInterceptorsChainAndStreamHistory(t *testing.T) {
 	var seenHistory [][]byte
 	var sawSecondResponse bool

internal/pluginhost/callback_contexts.go

@@ -3,6 +3,7 @@ package pluginhost
 import (
 	"context"
 	"strconv"
+	"strings"
 	"sync"
 	"sync/atomic"
 )
@@ -14,24 +15,27 @@ type callbackContextRegistry struct {
 }
 
 type callbackContextEntry struct {
-	ctx     context.Context
-	cleanup []func()
+	ctx      context.Context
+	pluginID string
+	cleanup  []func()
 }
 
 func newCallbackContextRegistry() *callbackContextRegistry {
 	return &callbackContextRegistry{contexts: make(map[string]callbackContextEntry)}
 }
 
-func (r *callbackContextRegistry) open(ctx context.Context) (string, func()) {
+func (r *callbackContextRegistry) open(ctx context.Context, pluginID string) (string, func()) {
 	if r == nil {
 		return "", func() {}
 	}
 	if ctx == nil {
 		ctx = context.Background()
 	}
+	pluginID = strings.TrimSpace(pluginID)
+	ctx = withHostCallbackPluginID(ctx, pluginID)
 	id := strconv.FormatUint(r.next.Add(1), 10)
 	r.mu.Lock()
-	r.contexts[id] = callbackContextEntry{ctx: ctx}
+	r.contexts[id] = callbackContextEntry{ctx: ctx, pluginID: pluginID}
 	r.mu.Unlock()
 
 	var once sync.Once
@@ -52,6 +56,16 @@ func (r *callbackContextRegistry) open(ctx context.Context) (string, func()) {
 	}
 }
 
+func (r *callbackContextRegistry) pluginID(id string) string {
+	if r == nil || id == "" {
+		return ""
+	}
+	r.mu.RLock()
+	entry := r.contexts[id]
+	r.mu.RUnlock()
+	return strings.TrimSpace(entry.pluginID)
+}
+
 func (r *callbackContextRegistry) addCleanup(id string, cleanup func()) bool {
 	if r == nil || id == "" || cleanup == nil {
 		return false
@@ -87,10 +101,14 @@ func (r *callbackContextRegistry) resolve(id string, fallback context.Context) c
 }
 
 func (h *Host) openCallbackContext(ctx context.Context) (string, func()) {
+	return h.openCallbackContextForPlugin(ctx, "")
+}
+
+func (h *Host) openCallbackContextForPlugin(ctx context.Context, pluginID string) (string, func()) {
 	if h == nil || h.callbackContexts == nil {
 		return "", func() {}
 	}
-	return h.callbackContexts.open(ctx)
+	return h.callbackContexts.open(ctx, pluginID)
 }
 
 func (h *Host) addCallbackCleanup(id string, cleanup func()) bool {
@@ -112,3 +130,10 @@ func (h *Host) resolveCallbackContext(id string, fallback context.Context) conte
 	}
 	return h.callbackContexts.resolve(id, fallback)
 }
+
+func (h *Host) callbackContextPluginID(id string) string {
+	if h == nil || h.callbackContexts == nil {
+		return ""
+	}
+	return h.callbackContexts.pluginID(id)
+}

internal/pluginhost/host.go

@@ -186,7 +186,7 @@ func (h *Host) ApplyConfig(ctx context.Context, cfg *config.Config) {
 }
 
 func (h *Host) loadLocked(file pluginFile) (*loadedPlugin, error) {
-	client, errOpen := h.loader.Open(file.Path, h)
+	client, errOpen := h.loader.Open(file, h)
 	if errOpen != nil {
 		return nil, errOpen
 	}