perf(output): add token-aware semantic output budgeting (PR11)

docs/HOW_ZERO_WORKS.md

@@ -272,7 +272,8 @@ sequenceDiagram
         Agent->>Tool: execute(ctx, args)
         Tool-->>Agent: output, error, metadata
         Agent->>Hooks: afterTool hooks
-        Agent->>Agent: redact, truncate, classify success/failure
+        Agent->>Agent: redact secrets, apply semantic output budget, enforce byte ceiling
+        Agent->>Agent: classify success/failure
         Agent-->>Surface: OnToolResult callback
         Agent->>Transcript: append tool result message
     end
@@ -604,10 +605,22 @@ flowchart TD
     Prompt -- Yes --> Decision[Permission callback]
     Prompt -- No --> Run[Registry.RunWithOptions]
     Decision --> Run
-    Run --> Redact[Redact secrets + enforce output ceiling]
-    Redact --> Message[Return tool result to model]
+    Run --> Redact[Redact secrets]
+    Redact --> Budget[Token-aware semantic output budget]
+    Budget --> Ceiling[Existing hard byte ceiling]
+    Ceiling --> Message[Return one tool result to model]
 ```
 
+Oversized results use deterministic, provider-neutral estimated-token budgets.
+Policies retain useful structure for files, search matches, tests, process logs,
+diffs, and worker conclusions; tools without a declared category use a UTF-8-safe
+head/tail fallback. The estimate is intentionally conservative for non-ASCII
+text and is not exact provider tokenization. Existing byte ceilings remain the
+authoritative safety limit. When the existing spill mechanism can persist the
+complete redacted text received by the budgeting layer, the result includes its
+safe spill reference. This does not imply capture of subprocess bytes already
+discarded by a tool's established internal buffer.
+
 Core tool groups include:
 
 - **Read-only tools**: file reads, directory listing, glob, grep, LSP navigation,

internal/agent/ask_user_test.go

@@ -141,9 +141,11 @@ func TestRunAskUserCancellationAbortsRun(t *testing.T) {
 	registry := registryWithAskUser()
 	args := `{"questions":[{"question":"Which framework?"}]}`
 	provider := providerCallingAskUserThenAnswer(args, "done")
+	var toolResults []ToolResult
 
 	result, err := Run(context.Background(), "clarify", provider, Options{
-		Registry: registry,
+		Registry:     registry,
+		OnToolResult: func(result ToolResult) { toolResults = append(toolResults, result) },
 		OnAskUser: func(_ context.Context, _ AskUserRequest) (AskUserResponse, error) {
 			return AskUserResponse{}, context.Canceled
 		},
@@ -158,6 +160,9 @@ func TestRunAskUserCancellationAbortsRun(t *testing.T) {
 	if len(provider.requests) != 1 {
 		t.Fatalf("expected the run to stop after the canceled ask_user (1 turn), got %d", len(provider.requests))
 	}
+	if len(toolResults) != 1 || toolResults[0].ToolCallID == "" {
+		t.Fatalf("cancellation must emit exactly one result for the call, got %#v", toolResults)
+	}
 	// The recorded tool result must reflect cancellation, not a synthetic answer.
 	var toolMsg string
 	for _, m := range result.Messages {

internal/agent/loop.go

@@ -7,6 +7,7 @@
 	"fmt"
 	"io"
 	"sort"
+	"strconv"
 	"strings"
 	"sync"
 
@@ -656,6 +657,7 @@
 				toolSpan.End()
 			}
 			options.Trace.Counter(trace.CounterToolCalls, 1)
+			recordOutputBudgetTrace(options.Trace, toolResult)
 			if options.OnToolResult != nil {
 				options.OnToolResult(toolResult)
 			}
@@ -841,6 +843,28 @@
 	return result, nil
 }
 
+func recordOutputBudgetTrace(recorder *trace.Recorder, result ToolResult) {
+	if recorder == nil || result.Meta["output_budget_category"] == "" {
+		return
+	}
+	parseInt := func(key string) int {
+		value, _ := strconv.Atoi(result.Meta[key])
+		return value
+	}
+	spillCreated, _ := strconv.ParseBool(result.Meta["output_budget_spill_created"])
+	recorder.EmitOutputBudget(trace.OutputBudgetEvent{
+		Tool:                    result.Name,
+		Category:                result.Meta["output_budget_category"],
+		OriginalBytes:           parseInt("output_budget_original_bytes"),
+		RetainedBytes:           parseInt("output_budget_retained_bytes"),
+		EstimatedOriginalTokens: parseInt("output_budget_estimated_original_tokens"),
+		EstimatedRetainedTokens: parseInt("output_budget_estimated_retained_tokens"),
+		Truncated:               result.Truncated,
+		Reason:                  result.Meta["output_budget_reason"],
+		SpillCreated:            spillCreated,
+	})
+}
+
 func finalAnswerAfterMaxTurns(ctx context.Context, provider Provider, messages []zeroruntime.Message, toolDefs []zeroruntime.ToolDefinition, options Options) (string, []zeroruntime.Message, string) {
 	finalMessages := copyMessages(messages)
 	finalMessages = append(finalMessages, zeroruntime.Message{
@@ -1295,6 +1319,7 @@
 			if didRedact {
 				result.Redacted = true
 			}
+			result = registry.RebudgetAfterHook(call.Name, args, result)
 		}
 	}
 	// Secret scrubbing happens at the registry boundary (the single point both
@@ -1305,6 +1330,7 @@
 		Name:         call.Name,
 		Status:       result.Status,
 		Output:       result.Output,
+		Truncated:    result.Truncated,
 		Meta:         result.Meta,
 		Redacted:     result.Redacted,
 		ChangedFiles: result.ChangedFiles,
@@ -1615,6 +1641,7 @@
 		Name:           call.Name,
 		Status:         result.Status,
 		Output:         output,
+		Truncated:      result.Truncated,
 		Meta:           meta,
 		Redacted:       result.Redacted || outputRedacted || summaryRedacted || metaRedacted,
 		ChangedFiles:   result.ChangedFiles,
@@ -1884,6 +1911,7 @@
 			Name:         call.Name,
 			Status:       result.Status,
 			Output:       result.Output,
+			Truncated:    result.Truncated,
 			Meta:         result.Meta,
 			Redacted:     result.Redacted,
 			ChangedFiles: result.ChangedFiles,
@@ -2714,7 +2742,7 @@
 // through tool_search. Non-deferred tools (including tool_search) are always
 // exposed. The exposed slice is alpha-sorted by name, matching the legacy order
 // so the inactive path is stable.
 func partitionTools(registry *tools.Registry, permissionMode PermissionMode, options Options, loaded map[string]bool) ([]zeroruntime.ToolDefinition, string) {
 	return partitionToolsCached(registry, permissionMode, options, loaded, nil)
 }
 

internal/agent/output_budget_propagation_test.go

@@ -0,0 +1,167 @@
+package agent
+
+import (
+	"context"
+	"os"
+	"strconv"
+	"strings"
+	"testing"
+
+	"github.com/Gitlawb/zero/internal/hooks"
+	"github.com/Gitlawb/zero/internal/tools"
+	"github.com/Gitlawb/zero/internal/trace"
+	"github.com/Gitlawb/zero/internal/zeroruntime"
+)
+
+type propagationOutputTool struct {
+	output string
+}
+
+func TestOutputBudgetHookHelperProcess(t *testing.T) {
+	for index, arg := range os.Args {
+		if arg != "--zero-output-budget-hook" || index+1 >= len(os.Args) {
+			continue
+		}
+		if _, err := os.Stdout.WriteString(os.Args[index+1]); err != nil {
+			os.Exit(2)
+		}
+		os.Exit(0)
+	}
+}
+
+func largeOutputBudgetHookDispatcher() *hooks.Dispatcher {
+	feedback := strings.Repeat("hook feedback ", 200)
+	return hooks.NewDispatcher(hooks.DispatcherOptions{Config: hooks.Config{
+		Enabled: true,
+		Hooks: []hooks.Definition{{
+			ID:      "large-feedback",
+			Event:   hooks.EventAfterTool,
+			Matcher: "propagation_output",
+			Command: os.Args[0],
+			Args: []string{
+				"-test.run=TestOutputBudgetHookHelperProcess",
+				"--",
+				"--zero-output-budget-hook",
+				feedback,
+			},
+			Enabled: true,
+		}},
+	}})
+}
+
+func (tool propagationOutputTool) Name() string        { return "propagation_output" }
+func (tool propagationOutputTool) Description() string { return "returns output for propagation tests" }
+func (tool propagationOutputTool) Parameters() tools.Schema {
+	return tools.Schema{Type: "object", AdditionalProperties: false}
+}
+func (tool propagationOutputTool) Safety() tools.Safety {
+	return tools.Safety{SideEffect: tools.SideEffectRead, Permission: tools.PermissionAllow, Reason: "test read"}
+}
+func (tool propagationOutputTool) Run(context.Context, map[string]any) tools.Result {
+	return tools.Result{Status: tools.StatusOK, Output: tool.output}
+}
+
+func TestExecuteToolCallPropagatesOutputTruncation(t *testing.T) {
+	t.Setenv("TMPDIR", t.TempDir())
+	t.Setenv("ZERO_TOOL_OUTPUT_CEILING_TOKENS", "80")
+	registry := tools.NewRegistry()
+	registry.Register(propagationOutputTool{output: strings.Repeat("large output\n", 1000)})
+
+	result, abortErr := executeToolCall(context.Background(), registry, ToolCall{
+		ID:        "call-budget",
+		Name:      "propagation_output",
+		Arguments: `{}`,
+	}, PermissionModeAuto, Options{Cwd: t.TempDir()})
+	if abortErr != nil {
+		t.Fatalf("executeToolCall abort error: %v", abortErr)
+	}
+	if !result.Truncated {
+		t.Fatalf("agent ToolResult lost tools.Result.Truncated: %#v", result)
+	}
+	if result.Meta["spill_path"] == "" {
+		t.Fatalf("agent ToolResult lost spill metadata: %#v", result.Meta)
+	}
+}
+
+func TestRecordOutputBudgetTraceUsesOnlyCompactMetadata(t *testing.T) {
+	recorder := trace.NewRecorder("session", "run", "")
+	recorder.Start()
+	recordOutputBudgetTrace(recorder, ToolResult{
+		Name:      "grep",
+		Truncated: true,
+		Output:    "SECRET OUTPUT MUST NOT ENTER TRACE",
+		Meta: map[string]string{
+			"output_budget_category":                  "search",
+			"output_budget_original_bytes":            "1000",
+			"output_budget_retained_bytes":            "100",
+			"output_budget_estimated_original_tokens": "250",
+			"output_budget_estimated_retained_tokens": "25",
+			"output_budget_reason":                    "semantic_search_budget",
+			"output_budget_spill_created":             "true",
+			"spill_path":                              "/secret/path/not-for-trace",
+		},
+	})
+	events := recorder.Finish().OutputBudgets
+	if len(events) != 1 {
+		t.Fatalf("events = %#v", events)
+	}
+	event := events[0]
+	if event.Tool != "grep" || event.Category != "search" || event.OriginalBytes != 1000 || event.RetainedBytes != 100 || !event.SpillCreated {
+		t.Fatalf("unexpected trace event: %#v", event)
+	}
+}
+
+func TestExecuteToolCallRebudgetsOversizedAfterToolFeedback(t *testing.T) {
+	t.Setenv("ZERO_TOOL_OUTPUT_CEILING_TOKENS", "80")
+	registry := tools.NewRegistry()
+	registry.Register(propagationOutputTool{output: "tool output"})
+	dispatcher := largeOutputBudgetHookDispatcher()
+
+	result, abortErr := executeToolCall(context.Background(), registry, ToolCall{
+		ID:        "call-hook-budget",
+		Name:      "propagation_output",
+		Arguments: `{}`,
+	}, PermissionModeAuto, Options{Hooks: dispatcher})
+	if abortErr != nil {
+		t.Fatalf("executeToolCall abort error: %v", abortErr)
+	}
+	if !result.Truncated || len(result.Output) > 80*4 {
+		t.Fatalf("afterTool feedback bypassed output budget: truncated=%t bytes=%d meta=%#v", result.Truncated, len(result.Output), result.Meta)
+	}
+	if result.Meta["output_budget_category"] == "" || result.Meta["output_budget_retained_bytes"] != strconv.Itoa(len(result.Output)) {
+		t.Fatalf("post-hook budget metadata does not describe final output: %#v", result.Meta)
+	}
+}
+
+func TestRunTraceReflectsPostHookBudget(t *testing.T) {
+	t.Setenv("ZERO_TOOL_OUTPUT_CEILING_TOKENS", "80")
+	registry := tools.NewRegistry()
+	registry.Register(propagationOutputTool{output: "tool output"})
+	dispatcher := largeOutputBudgetHookDispatcher()
+	provider := &mockProvider{turns: [][]zeroruntime.StreamEvent{
+		{
+			{Type: zeroruntime.StreamEventToolCallStart, ToolCallID: "call-hook-trace", ToolName: "propagation_output"},
+			{Type: zeroruntime.StreamEventToolCallDelta, ToolCallID: "call-hook-trace", ArgumentsFragment: `{}`},
+			{Type: zeroruntime.StreamEventToolCallEnd, ToolCallID: "call-hook-trace"},
+			{Type: zeroruntime.StreamEventDone},
+		},
+		{{Type: zeroruntime.StreamEventText, Content: "done"}, {Type: zeroruntime.StreamEventDone}},
+	}}
+	recorder := trace.NewRecorder("session", "run", "")
+	var toolResults []ToolResult
+	if _, err := Run(context.Background(), "budget hook", provider, Options{
+		Registry:     registry,
+		Hooks:        dispatcher,
+		Trace:        recorder,
+		OnToolResult: func(result ToolResult) { toolResults = append(toolResults, result) },
+	}); err != nil {
+		t.Fatalf("Run: %v", err)
+	}
+	if len(toolResults) != 1 || !toolResults[0].Truncated {
+		t.Fatalf("tool result = %#v, want one truncated post-hook result", toolResults)
+	}
+	events := recorder.Finish().OutputBudgets
+	if len(events) != 1 || !events[0].Truncated || events[0].RetainedBytes != len(toolResults[0].Output) {
+		t.Fatalf("trace does not describe final post-hook output: events=%#v result=%#v", events, toolResults[0])
+	}
+}

internal/agent/types.go

@@ -61,10 +61,13 @@
 )
 
 type ToolResult struct {
-	ToolCallID   string
-	Name         string
-	Status       tools.Status
-	Output       string
+	ToolCallID string
+	Name       string
+	Status     tools.Status
+	Output     string
+	// Truncated reports that the tool's model-visible output omitted content.
+	// The full result may be recoverable through Meta["spill_path"].
+	Truncated    bool
 	Meta         map[string]string
 	Redacted     bool
 	ChangedFiles []string
@@ -345,7 +348,7 @@
 // Truncated reports whether the final response ended abnormally (cut off at the
 // output token cap or withheld by a content filter) rather than completing
 // naturally. Callers can use it to warn the user that FinalAnswer is incomplete.
 func (result Result) Truncated() bool {
 	return result.FinishReason != ""
 }
 

internal/cli/exec.go

@@ -636,6 +636,9 @@ func runExec(args []string, stdout io.Writer, stderr io.Writer, deps appDeps) in
 			if len(result.Meta) > 0 {
 				payload["meta"] = result.Meta
 			}
+			if result.Truncated {
+				payload["truncated"] = true
+			}
 			if result.Redacted {
 				payload["redacted"] = true
 			}

internal/cli/exec_writer.go

@@ -153,6 +153,9 @@ func (writer *execEventWriter) toolResult(result agent.ToolResult) {
 		if len(result.Meta) > 0 {
 			payload["meta"] = result.Meta
 		}
+		if result.Truncated {
+			payload["truncated"] = true
+		}
 		if result.Redacted {
 			payload["redacted"] = true
 		}
@@ -166,7 +169,8 @@ func (writer *execEventWriter) toolResult(result agent.ToolResult) {
 		return
 	}
 	if writer.format == execOutputStreamJSON {
-		output, truncated := truncateForStreamJSONOutput(result.Output)
+		output, surfaceTruncated := truncateForStreamJSONOutput(result.Output)
+		truncated := result.Truncated || surfaceTruncated
 		event := streamjson.Event{
 			Type:         streamjson.EventToolResult,
 			RunID:        writer.runID,

internal/cli/exec_writer_test.go

@@ -1,8 +1,12 @@
 package cli
 
 import (
+	"bytes"
+	"encoding/json"
+	"strings"
 	"testing"
 
+	"github.com/Gitlawb/zero/internal/agent"
 	"github.com/Gitlawb/zero/internal/tools"
 )
 
@@ -16,3 +20,35 @@ func TestStreamJSONSideEffectReportsNoneForControlTool(t *testing.T) {
 		t.Fatalf("streamJSONSideEffect(escalate_model) = %q, want none", got)
 	}
 }
+
+func TestExecWriterPropagatesToolResultTruncation(t *testing.T) {
+	for _, format := range []execOutputFormat{execOutputJSON, execOutputStreamJSON} {
+		t.Run(string(format), func(t *testing.T) {
+			var stdout, stderr bytes.Buffer
+			writer := execEventWriter{
+				stdout:       &stdout,
+				stderr:       &stderr,
+				format:       format,
+				runID:        "run_budget",
+				streamedText: &strings.Builder{},
+			}
+			writer.toolResult(agent.ToolResult{
+				ToolCallID: "call_budget",
+				Name:       "read_file",
+				Status:     tools.StatusOK,
+				Output:     "bounded output",
+				Truncated:  true,
+			})
+			if writer.err != nil {
+				t.Fatalf("toolResult: %v", writer.err)
+			}
+			var payload map[string]any
+			if err := json.Unmarshal(bytes.TrimSpace(stdout.Bytes()), &payload); err != nil {
+				t.Fatalf("decode output %q: %v", stdout.String(), err)
+			}
+			if payload["truncated"] != true {
+				t.Fatalf("truncated = %#v, want true; payload=%#v", payload["truncated"], payload)
+			}
+		})
+	}
+}