fix(artifactstore): redact storage errors

agent/invocation.go

@@ -922,6 +922,16 @@ func WithToolFilter(filter tool.FilterFunc) RunOption {
 	}
 }
 
+// WithMandatoryToolFilter sets a non-negotiable tool visibility boundary for
+// this run. Unlike WithToolFilter, it applies to the complete invocation tool
+// surface, including framework-managed tools, and is preserved across derived
+// child invocations.
+func WithMandatoryToolFilter(filter tool.FilterFunc) RunOption {
+	return func(opts *RunOptions) {
+		opts.MandatoryToolFilter = filter
+	}
+}
+
 // WithAdditionalTools appends tools that are visible only for this run.
 //
 // Additional tools are treated as user tools, so WithToolFilter can still
@@ -997,6 +1007,71 @@ func WithToolPermissionPolicyFunc(fn tool.PermissionPolicyFunc) RunOption {
 	return WithToolPermissionPolicy(fn)
 }
 
+// WithMandatoryToolPermissionPolicy sets a non-negotiable permission policy
+// that derived child invocations must preserve. It is checked before the
+// ordinary per-run ToolPermissionPolicy.
+func WithMandatoryToolPermissionPolicy(policy tool.PermissionPolicy) RunOption {
+	return func(opts *RunOptions) {
+		opts.MandatoryToolPermissionPolicy = policy
+	}
+}
+
+// WithMandatoryToolPermissionPolicyFunc adapts fn into a mandatory per-run
+// tool permission policy.
+func WithMandatoryToolPermissionPolicyFunc(fn tool.PermissionPolicyFunc) RunOption {
+	return WithMandatoryToolPermissionPolicy(fn)
+}
+
+// CheckToolPermission applies the non-negotiable policy followed by the
+// ordinary per-run policy. The first non-allow decision terminates the chain.
+func (opts *RunOptions) CheckToolPermission(
+	ctx context.Context,
+	req *tool.PermissionRequest,
+) (tool.PermissionDecision, error) {
+	if opts == nil {
+		return tool.AllowPermission(), nil
+	}
+	policies := [...]tool.PermissionPolicy{
+		opts.MandatoryToolPermissionPolicy,
+		opts.ToolPermissionPolicy,
+	}
+	for _, policy := range policies {
+		if isNilToolPermissionPolicy(policy) {
+			continue
+		}
+		decision, err := policy.CheckToolPermission(ctx, req)
+		if err != nil {
+			return tool.PermissionDecision{}, err
+		}
+		decision, err = tool.NormalizePermissionDecision(decision)
+		if err != nil {
+			return tool.PermissionDecision{}, err
+		}
+		if decision.Action != tool.PermissionActionAllow {
+			return decision, nil
+		}
+	}
+	return tool.AllowPermission(), nil
+}
+
+func isNilToolPermissionPolicy(policy tool.PermissionPolicy) bool {
+	if policy == nil {
+		return true
+	}
+	value := reflect.ValueOf(policy)
+	switch value.Kind() {
+	case reflect.Chan,
+		reflect.Func,
+		reflect.Interface,
+		reflect.Map,
+		reflect.Pointer,
+		reflect.Slice:
+		return value.IsNil()
+	default:
+		return false
+	}
+}
+
 func appendRunTools(opts *RunOptions, tools []tool.Tool) {
 	if opts == nil || len(tools) == 0 {
 		return
@@ -1336,7 +1411,12 @@ type RunOptions struct {
 	// StructuredOutputType is the Go type to unmarshal the final JSON into for this run.
 	StructuredOutputType reflect.Type
 
-	// ToolFilter is a custom function to filter tools for this run.
+	// MandatoryToolFilter is a non-negotiable visibility boundary applied to
+	// the complete invocation tool surface, including framework-managed tools.
+	// Derived child invocations must preserve it.
+	MandatoryToolFilter tool.FilterFunc
+
+	// ToolFilter is a custom function to filter user tools for this run.
 	// If set, only tools for which the filter returns true will be available to the model.
 	// If nil, all registered tools will be available (default behavior).
 	//
@@ -1389,6 +1469,10 @@ type RunOptions struct {
 	// externally and later provide tool results (RoleTool messages).
 	ToolExecutionFilter tool.FilterFunc
 
+	// MandatoryToolPermissionPolicy is checked before ToolPermissionPolicy and
+	// is preserved across derived child invocations.
+	MandatoryToolPermissionPolicy tool.PermissionPolicy
+
 	// ToolPermissionPolicy checks whether a tool call may run after the model
 	// has requested it, after argument repair, and after before-tool callbacks
 	// have finalized arguments.

agent/invocation_surface.go

@@ -36,6 +36,24 @@ type InvocationToolSurfaceProvider interface {
 	) ([]tool.Tool, map[string]bool)
 }
 
+// InvocationToolActivationProvider is an optional interface implemented by
+// agents that apply invocation-scoped activation after run-option tools have
+// been appended to the base surface.
+//
+// The provider must return the activated tool surface together with updated
+// user and external tool classifications. Callers provide private slice/map
+// copies, so implementations may mutate the inputs without affecting the
+// invocation's configured surface.
+type InvocationToolActivationProvider interface {
+	ApplyInvocationToolActivation(
+		ctx context.Context,
+		inv *Invocation,
+		tools []tool.Tool,
+		userToolNames map[string]bool,
+		externalToolNames map[string]bool,
+	) ([]tool.Tool, map[string]bool, map[string]bool)
+}
+
 // InvocationSkillRepositoryProvider is an optional interface implemented by
 // agents that can expose the effective, invocation-scoped skill repository.
 //

agent/invocation_test.go

@@ -1229,6 +1229,74 @@ func TestWithToolPermissionPolicy(t *testing.T) {
 	require.Equal(t, tool.PermissionActionDeny, decision.Action)
 }
 
+func TestRunOptionsCheckToolPermissionAppliesMandatoryPolicyFirst(
+	t *testing.T,
+) {
+	var calls []string
+	opts := NewRunOptions(
+		WithMandatoryToolPermissionPolicyFunc(
+			func(
+				context.Context,
+				*tool.PermissionRequest,
+			) (tool.PermissionDecision, error) {
+				calls = append(calls, "mandatory")
+				return tool.DenyPermission("tenant policy"), nil
+			},
+		),
+		WithToolPermissionPolicyFunc(
+			func(
+				context.Context,
+				*tool.PermissionRequest,
+			) (tool.PermissionDecision, error) {
+				calls = append(calls, "ordinary")
+				return tool.AllowPermission(), nil
+			},
+		),
+	)
+
+	decision, err := opts.CheckToolPermission(
+		context.Background(),
+		&tool.PermissionRequest{ToolName: "shell"},
+	)
+	require.NoError(t, err)
+	require.Equal(t, tool.PermissionActionDeny, decision.Action)
+	require.Equal(t, []string{"mandatory"}, calls)
+}
+
+func TestRunOptionsCheckToolPermissionAllowsOrdinaryPolicyToTighten(
+	t *testing.T,
+) {
+	var calls []string
+	opts := NewRunOptions(
+		WithMandatoryToolPermissionPolicyFunc(
+			func(
+				context.Context,
+				*tool.PermissionRequest,
+			) (tool.PermissionDecision, error) {
+				calls = append(calls, "mandatory")
+				return tool.AllowPermission(), nil
+			},
+		),
+		WithToolPermissionPolicyFunc(
+			func(
+				context.Context,
+				*tool.PermissionRequest,
+			) (tool.PermissionDecision, error) {
+				calls = append(calls, "ordinary")
+				return tool.DenyPermission("child policy"), nil
+			},
+		),
+	)
+
+	decision, err := opts.CheckToolPermission(
+		context.Background(),
+		&tool.PermissionRequest{ToolName: "shell"},
+	)
+	require.NoError(t, err)
+	require.Equal(t, tool.PermissionActionDeny, decision.Action)
+	require.Equal(t, []string{"mandatory", "ordinary"}, calls)
+}
+
 func TestWithInstruction(t *testing.T) {
 	opts := &RunOptions{}
 	WithInstruction(testRunInstruction)(opts)

agent/llmagent/llm_agent.go

@@ -1645,8 +1645,12 @@ func (a *LLMAgent) resolveBaseModel(inv *agent.Invocation) baseModelResolution {
 // setupInvocation sets up the invocation.
 func (a *LLMAgent) setupInvocation(invocation *agent.Invocation) {
 	// Set agent identity before resolving node-scoped surfaces.
-	invocation.Agent = a
-	invocation.AgentName = a.name
+	if invocation.Agent != a {
+		invocation.Agent = a
+	}
+	if invocation.AgentName != a.name {
+		invocation.AgentName = a.name
+	}
 
 	// Set the base model once for compatibility with existing callbacks.
 	resolution := a.resolveBaseModel(invocation)

agent/llmagent/surface_runtime_test.go

@@ -670,6 +670,73 @@ func TestLLMAgent_Run_AgentToolFilterStillAppliesWithInvocationToolSurface(
 	require.Contains(t, m.got.Tools, testTransferToolName)
 }
 
+func TestLLMAgent_Run_MandatoryToolFilterAppliesToFrameworkTools(
+	t *testing.T,
+) {
+	m := &captureModel{}
+	agt := New(
+		"test-agent",
+		WithModel(m),
+		WithTools([]tool.Tool{
+			dummyTool{decl: &tool.Declaration{Name: "allowed_user_tool"}},
+		}),
+		WithSubAgents([]agent.Agent{&mockAgent{name: "child"}}),
+		WithAwaitUserReplyTool(true),
+	)
+	inv := agent.NewInvocation(
+		agent.WithInvocationMessage(model.NewUserMessage("hello")),
+		agent.WithInvocationRunOptions(agent.NewRunOptions(
+			agent.WithMandatoryToolFilter(
+				func(_ context.Context, tl tool.Tool) bool {
+					switch tl.Declaration().Name {
+					case testTransferToolName, testAwaitReplyToolName:
+						return false
+					default:
+						return true
+					}
+				},
+			),
+		)),
+	)
+
+	ch, err := agt.Run(context.Background(), inv)
+	require.NoError(t, err)
+	for range ch {
+	}
+
+	require.NotNil(t, m.got)
+	require.Contains(t, m.got.Tools, "allowed_user_tool")
+	require.NotContains(t, m.got.Tools, testTransferToolName)
+	require.NotContains(t, m.got.Tools, testAwaitReplyToolName)
+}
+
+func TestLLMAgent_SetupInvocationDoesNotRewritePreinitializedIdentity(
+	t *testing.T,
+) {
+	agt := New("test-agent", WithModel(&captureModel{}))
+	inv := agent.NewInvocation(agent.WithInvocationAgent(agt))
+	const iterations = 10000
+	start := make(chan struct{})
+	done := make(chan struct{})
+	go func() {
+		<-start
+		for i := 0; i < iterations; i++ {
+			_ = inv.Agent
+			_ = inv.AgentName
+		}
+		close(done)
+	}()
+
+	close(start)
+	for i := 0; i < iterations; i++ {
+		agt.setupInvocation(inv)
+	}
+	<-done
+
+	require.Same(t, agt, inv.Agent)
+	require.Equal(t, "test-agent", inv.AgentName)
+}
+
 func TestLLMAgent_Run_SurfacePatch_OverridesToolDeclarations(t *testing.T) {
 	m := &captureModel{}
 	agt := New(

agent/llmagent/tool_activation.go

@@ -332,6 +332,23 @@ func (a *LLMAgent) applyToolActivation(
 	)
 }
 
+// ApplyInvocationToolActivation implements agent.InvocationToolActivationProvider.
+func (a *LLMAgent) ApplyInvocationToolActivation(
+	ctx context.Context,
+	inv *agent.Invocation,
+	tools []tool.Tool,
+	userToolNames map[string]bool,
+	externalToolNames map[string]bool,
+) ([]tool.Tool, map[string]bool, map[string]bool) {
+	return a.applyToolActivation(
+		ctx,
+		inv,
+		tools,
+		userToolNames,
+		externalToolNames,
+	)
+}
+
 func (a *LLMAgent) toolActivationInputs() (
 	[]tool.ToolSet,
 	[]toolActivationRule,