feat: conversion-driven extensions — resolvers, DefineTool, hooks, ops controls

Phase 9a (ADR-0014): Registry.RegisterResolver for dynamic tiers;
DefineTool[Args] typed tools; Usage cache/reasoning detail fields wired
through anthropic/openai/google; WithPromptCaching (Anthropic
cache_control); agent supervision hooks (WithMaxStepsFunc, WithSteer,
WithCompactor, WithToolErrorLimits + ErrToolLoop); health
Bench/Unbench/Snapshot; ChainConfig.Observer failover events.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

agent/agent.go

@@ -27,6 +27,11 @@ const DefaultMaxSteps = 10
 // carrying the transcript so far.
 var ErrMaxSteps = errors.New("agent: max steps reached without a final answer")
 
+// ErrToolLoop reports that the loop tripped a tool-error guard
+// (consecutive all-error steps or identical repeated calls; see
+// WithToolErrorLimits). Run returns it alongside the partial *Result.
+var ErrToolLoop = errors.New("agent: tool-error guard tripped")
+
 // Skill is the contract skills satisfy (defined here so agent does not
 // depend on the skill package; package skill provides implementations).
 // Instructions are appended to the agent's system prompt; Tools (optional,
@@ -67,13 +72,17 @@ type Result struct {
 // it later. Agents are safe to share across goroutines only after
 // configuration is complete.
 type Agent struct {
-	model     llm.Model
-	system    string
-	toolboxes []*llm.Toolbox
-	skills    []Skill
-	maxSteps  int
-	reqOpts   []llm.Option
-	observers []func(Step)
+	model                    llm.Model
+	system                   string
+	toolboxes                []*llm.Toolbox
+	skills                   []Skill
+	maxSteps                 int
+	maxStepsFunc             func() int
+	compactor                func(ctx context.Context, msgs []llm.Message) ([]llm.Message, error)
+	maxConsecutiveToolErrors int
+	maxSameCallRepeats       int
+	reqOpts                  []llm.Option
+	observers                []func(Step)
 }
 
 // Option configures an Agent at construction.
@@ -99,6 +108,34 @@ func WithMaxSteps(n int) Option {
 	return func(a *Agent) { a.maxSteps = n }
 }
 
+// WithMaxStepsFunc makes the step ceiling dynamic: the function is
+// consulted before every step, so a supervisor can extend (or shrink) a
+// running agent's budget. It overrides WithMaxSteps while non-nil; a
+// non-positive return falls back to the static value.
+func WithMaxStepsFunc(fn func() int) Option {
+	return func(a *Agent) { a.maxStepsFunc = fn }
+}
+
+// WithCompactor installs a context-compaction hook, called with the full
+// message slice before every model call; whatever it returns is sent
+// instead (e.g. summarize the middle of a long transcript). A compactor
+// error is non-fatal: the original messages are used.
+func WithCompactor(fn func(ctx context.Context, msgs []llm.Message) ([]llm.Message, error)) Option {
+	return func(a *Agent) { a.compactor = fn }
+}
+
+// WithToolErrorLimits installs loop guards: maxConsecutiveErrors bounds
+// successive steps whose tool results were ALL errors, and
+// maxSameCallRepeats bounds identical (name + arguments) tool calls within
+// one run. Either guard tripping ends the run with ErrToolLoop and the
+// partial result. Zero disables a guard.
+func WithToolErrorLimits(maxConsecutiveErrors, maxSameCallRepeats int) Option {
+	return func(a *Agent) {
+		a.maxConsecutiveToolErrors = maxConsecutiveErrors
+		a.maxSameCallRepeats = maxSameCallRepeats
+	}
+}
+
 // WithRequestOptions sets default request options (temperature, max
 // tokens, ...) applied to every step of every run.
 func WithRequestOptions(opts ...llm.Option) Option {
@@ -134,6 +171,7 @@ type runConfig struct {
 	history []llm.Message
 	reqOpts []llm.Option
 	onStep  []func(Step)
+	steer   func() []llm.Message
 }
 
 // WithHistory seeds the run with prior conversation messages (e.g. a
@@ -153,6 +191,15 @@ func OnStep(fn func(Step)) RunOption {
 	return func(rc *runConfig) { rc.onStep = append(rc.onStep, fn) }
 }
 
+// WithSteer installs a steering source for this run: the function is
+// drained before every step and any returned messages are appended to the
+// conversation — the mechanism for a supervisor nudging a running agent
+// ("wrap up", "focus on X"). It is called from Run's goroutine; the
+// function owns its own synchronization.
+func WithSteer(fn func() []llm.Message) RunOption {
+	return func(rc *runConfig) { rc.steer = fn }
+}
+
 // systemPrompt composes the agent's system prompt with each skill's
 // instructions, in attachment order.
 func (a *Agent) systemPrompt() string {
@@ -227,8 +274,34 @@ func (a *Agent) Run(ctx context.Context, input string, opts ...RunOption) (*Resu
 	reqOpts := append(append([]llm.Option(nil), a.reqOpts...), rc.reqOpts...)
 	system := a.systemPrompt()
 
-	for stepIdx := range a.maxSteps {
-		req := llm.Request{System: system, Messages: msgs, Tools: ordered}
+	// Loop-guard state (WithToolErrorLimits).
+	consecutiveErrorSteps := 0
+	callCounts := make(map[string]int)
+
+	maxSteps := func() int {
+		if a.maxStepsFunc != nil {
+			if n := a.maxStepsFunc(); n > 0 {
+				return n
+			}
+		}
+		return a.maxSteps
+	}
+
+	for stepIdx := 0; stepIdx < maxSteps(); stepIdx++ {
+		// Steering: drain supervisor nudges into the conversation.
+		if rc.steer != nil {
+			msgs = append(msgs, rc.steer()...)
+		}
+
+		sendMsgs := msgs
+		if a.compactor != nil {
+			// Compaction failures are non-fatal: send the original.
+			if compacted, err := a.compactor(ctx, msgs); err == nil && compacted != nil {
+				sendMsgs = compacted
+			}
+		}
+
+		req := llm.Request{System: system, Messages: sendMsgs, Tools: ordered}
 		resp, err := a.model.Generate(ctx, req, reqOpts...)
 		if err != nil {
 			result.Messages = msgs
@@ -249,11 +322,19 @@ func (a *Agent) Run(ctx context.Context, input string, opts ...RunOption) (*Resu
 		}
 
 		results := make([]llm.ToolResult, 0, len(resp.ToolCalls))
+		repeatTripped := ""
 		for _, call := range resp.ToolCalls {
 			if err := ctx.Err(); err != nil {
 				result.Messages = msgs
 				return result, err
 			}
+			if a.maxSameCallRepeats > 0 {
+				sig := call.Name + "\x00" + string(call.Arguments)
+				callCounts[sig]++
+				if callCounts[sig] > a.maxSameCallRepeats {
+					repeatTripped = call.Name
+				}
+			}
 			tool, ok := byName[call.Name]
 			if !ok {
 				results = append(results, llm.ToolResult{
@@ -272,10 +353,33 @@ func (a *Agent) Run(ctx context.Context, input string, opts ...RunOption) (*Resu
 		result.Steps = append(result.Steps, step)
 		a.notify(rc, step)
 		msgs = append(msgs, llm.ToolResultsMessage(results...))
+
+		if repeatTripped != "" {
+			result.Messages = msgs
+			return result, fmt.Errorf("%w: %q called identically more than %d times",
+				ErrToolLoop, repeatTripped, a.maxSameCallRepeats)
+		}
+		allErrors := len(results) > 0
+		for _, r := range results {
+			if !r.IsError {
+				allErrors = false
+				break
+			}
+		}
+		if allErrors {
+			consecutiveErrorSteps++
+			if a.maxConsecutiveToolErrors > 0 && consecutiveErrorSteps >= a.maxConsecutiveToolErrors {
+				result.Messages = msgs
+				return result, fmt.Errorf("%w: %d consecutive steps with only failing tool calls",
+					ErrToolLoop, consecutiveErrorSteps)
+			}
+		} else {
+			consecutiveErrorSteps = 0
+		}
 	}
 
 	result.Messages = msgs
-	return result, fmt.Errorf("%w (max %d)", ErrMaxSteps, a.maxSteps)
+	return result, fmt.Errorf("%w (max %d)", ErrMaxSteps, maxSteps())
 }
 
 // notify fans a step out to agent observers and run callbacks; observer