feat: cache-results key decouples blob caching from content-type (closes #319)

Caching was a side effect of declaring a mime: MCP allows mimeType only on
resource blocks, resource blocks need a URI, so content-type (text path) and
script-emitted mimeType (mcp-result path) forced a madder write on EVERY
output — and since virtually all ~55 mcp-result tools stamp a mime on every
block, each small status-y output paid a blob write (folio.ls 1.8k calls/mo,
jq 740/mo, all of freud/sisyphus/piers; measured via freud over 30 days).
Sampling showed small-output cache URIs are essentially never consumed,
while large outputs were already independently protected by the token
threshold.

New schema-3 key `cache-results = "always" | "threshold" | "never"`
(omitted = threshold), honored by both result paths:

- threshold (default): blob-cache only above the token threshold; small
  outputs are plain text blocks — no blob write, mime dropped (there is
  nowhere to put a mime without a resource block).
- always: every non-empty output cached; small outputs become resource
  blocks (URI + text + mime). For small-but-composable outputs.
- never: the blob store is never touched; even oversized output stays
  plain inline text. The author owns the context cost.

content-type is now a pure mime label stamped onto whatever resource block
caching produces. no-truncate is orthogonal (inlining above threshold) and
unchanged.

Annotated cache-results = "always" where small-output URIs are genuinely
re-piped: jq.jq, grit.diff, man.list/toc/section. Everything else moves to
threshold — the intended churn reduction; large outputs keep URIs
everywhere.

Also: the moxy.native:// → madder://blobs/ code migration happened
previously; this fixes the three folio read* TOML descriptions still
advertising the old scheme (doc-only per review — no legacy resolver).
moxin(7) gains a RESULT SHAPING section documenting result-type /
content-type / cache-results / no-truncate as one system; CLAUDE.md gets
the summary. Covered by unit tests (parse + all three modes on both paths)
and updated/extended bats: folio 36/36, native 44/44, mcp_proto 46/46 —
old-shape assertions updated to the new contract, fixtures that test the
resource mechanic opt into "always", new threshold-drops-mime cases on
both paths.

🤡 Generated with Clown (https://github.com/amarbel-llc/clown)

Author: friedenberg

CLAUDE.md

@@ -166,6 +166,16 @@ The `_moxin.toml` manifest declares server identity (`schema`, `name`,
 `[tools.input]`). Tools may declare `perms-request` to control permission
 behavior: `always-allow`, `each-use`, or `delegate-to-client` (default).
 
+Result shaping (see moxin(7) RESULT SHAPING for the full system):
+`result-type` picks envelope ownership (`mcp-result` default = script emits
+the full MCP result, needed for dynamic mimeTypes; `text` = moxy builds it).
+`cache-results` (`threshold` default | `always` | `never`) controls madder
+blob writes independently of mime declaration (#319): threshold caches only
+oversized outputs; `always` is for small-but-composable outputs (jq, man
+sections, diffs); `content-type` is a pure mime label stamped onto cached
+resource blocks — alone it never causes caching, and small uncached outputs
+drop the mime.
+
 **Moxin dependency rule:** All moxins (`moxins/*/*.toml`) must have their
 external dependencies provided via nix wrapping. Never rely on tools being on
 the ambient PATH --- they won't be outside the moxy devshell. The pattern: put

cmd/moxy/moxin.7

@@ -103,7 +103,89 @@ forbids backgrounding even for tools whose permission resolves to allow
 \(em use it for interactive, ordering-sensitive, or trivially-fast tools.
 The permission tier is a separate, additional gate: only allow-resolving
 tools may background regardless of this key.
+.It Sy result-type
+How the tool's stdout becomes an MCP result (schema 2/3 key).
+See
+.Sx RESULT SHAPING .
+.It Sy content-type
+MIME label stamped onto cached resource blocks (schema 3 key).
+See
+.Sx RESULT SHAPING .
+.It Sy cache-results
+When the tool's output is written to the madder blob store (schema 3
+key).
+See
+.Sx RESULT SHAPING .
+.It Sy no-truncate
+Disable the head/tail summary for oversized outputs (boolean; schema 3
+key).
+See
+.Sx RESULT SHAPING .
 .El
+.Sh RESULT SHAPING
+Four keys control how a tool's stdout becomes an MCP result.
+.Pp
+.Sy result-type
+selects who owns the result envelope:
+.Bl -tag -width "mcp-result"
+.It Li mcp-result
+The default when omitted on schema 2/3.
+Stdout must be a complete MCP
+.Li ToolCallResult
+JSON object.
+Use when the script needs dynamic control \(em per-call MIME types
+(e.g. a diff tool switching between
+.Li text/x-diff
+and
+.Li text/plain ) ,
+output-format parameters, or multiple content blocks.
+.It Li text
+Stdout is plain text; moxy builds the result.
+.El
+.Pp
+.Sy cache-results
+controls when output is written to the madder blob store and surfaced
+as a
+.Li madder://blobs/<digest>
+resource URI, on both result-type paths:
+.Bl -tag -width "threshold"
+.It Li threshold
+The default when omitted.
+Outputs above the token threshold are blob-cached and returned as a
+head/tail summary pointing at the URI; small outputs are plain text
+blocks with no blob write.
+.It Li always
+Every non-empty output is blob-cached; small outputs come back as
+resource blocks (URI, full text, MIME).
+Declare it when small outputs are composable artifacts that get
+re-piped into other tools (jq filters, man sections, diffs).
+.It Li never
+The blob store is never touched \(em even oversized output is returned
+as plain full text.
+The tool author owns the context cost.
+.El
+.Pp
+.Sy content-type
+is a pure MIME label: it is stamped onto whatever resource block
+caching produces and is otherwise inert.
+Small outputs under the
+.Li threshold
+default come back as plain text with the MIME dropped \(em the MCP spec
+has nowhere to put a MIME without a resource block, and a resource
+block requires a URI.
+Declaring
+.Sy content-type
+alone does not cause caching; pair it with
+.Sy cache-results No = Li \(dqalways\(dq
+when the label must always be present.
+The same policy governs MIME-bearing text blocks emitted by
+.Li mcp-result
+tools.
+.Pp
+.Sy no-truncate
+keeps the full text inline (prefixed with the blob URI) instead of the
+head/tail summary when an oversized output is cached.
+It does not affect whether caching happens.
 .Sh PERMISSIONS
 Each tool may declare a
 .Sy perms-request

internal/native/config.go

@@ -104,6 +104,7 @@ type ToolSpec struct {
 	PermitAsync          *bool             // nil = eligible (see PermitsAsync); #317
 	ContentType          string
 	ResultType           ResultType
+	CacheResults         CacheResults // resolved; never empty (#319)
 	NoTruncate           bool
 	SubstituteResultURIs *bool
 	Annotations          *ToolAnnotations
@@ -148,6 +149,7 @@ type rawToolFile struct {
 	PermsRequest         PermsRequest      `toml:"perms-request"`
 	DynamicPerms         *DynamicPermsSpec `toml:"dynamic-perms"` // Added for moxy POC dynamic-perms
 	PermitAsync          *bool             `toml:"permit-async"`  // #317
+	CacheResults         string            `toml:"cache-results"` // #319
 	ContentType          string            `toml:"content-type"`
 	ResultType           string            `toml:"result-type"`
 	NoTruncate           bool              `toml:"no-truncate"`
@@ -284,6 +286,11 @@ func ParseMoxinDirFull(dirPath string) (*ParseResult, error) {
 			return nil, fmt.Errorf("tool file %s: %w", filename, err)
 		}
 
+		cacheResults, err := resolveCacheResults(raw.CacheResults)
+		if err != nil {
+			return nil, fmt.Errorf("tool file %s: %w", filename, err)
+		}
+
 		ts := ToolSpec{
 			Name:                 toolName,
 			Description:          raw.Description,
@@ -296,6 +303,7 @@ func ParseMoxinDirFull(dirPath string) (*ParseResult, error) {
 			PermitAsync:          raw.PermitAsync,  // #317
 			ContentType:          raw.ContentType,
 			ResultType:           resultType,
+			CacheResults:         cacheResults, // #319
 			NoTruncate:           raw.NoTruncate,
 			SubstituteResultURIs: raw.SubstituteResultURIs,
 			Annotations:          raw.Annotations,
@@ -343,6 +351,40 @@ func resolveResultType(schema int, raw string) (ResultType, error) {
 	}
 }
 
+// CacheResults controls when a tool's output is written to the madder blob
+// store and surfaced as a resource URI (#319). Decoupled from content-type:
+// the mime is a label stamped onto whatever resource block caching produces,
+// never itself a reason to cache.
+type CacheResults string
+
+const (
+	// CacheAlways writes every non-empty output to the blob store; small
+	// outputs come back as resource blocks (URI + text + mime if declared).
+	// For tools whose small outputs are composable artifacts (re-piped
+	// into jq, folio.read, etc.).
+	CacheAlways CacheResults = "always"
+	// CacheThreshold (the default) writes only outputs above the token
+	// threshold; small outputs are plain text blocks with no blob write
+	// and no mime.
+	CacheThreshold CacheResults = "threshold"
+	// CacheNever never writes the blob store — even oversized outputs are
+	// returned as plain full text. The tool author owns the context cost.
+	CacheNever CacheResults = "never"
+)
+
+func resolveCacheResults(raw string) (CacheResults, error) {
+	if raw == "" {
+		return CacheThreshold, nil
+	}
+	cr := CacheResults(raw)
+	switch cr {
+	case CacheAlways, CacheThreshold, CacheNever:
+		return cr, nil
+	default:
+		return "", fmt.Errorf("invalid cache-results %q (want always, threshold, or never)", raw)
+	}
+}
+
 func validatePermsRequest(pr PermsRequest) error {
 	switch pr {
 	case "", PermsDelegateToClient, PermsAlwaysAllow, PermsEachUse, PermsDynamic:
@@ -409,6 +451,7 @@ func detectUndecodedTool(data []byte, filename string, schema int) []string {
 		"arg-order", "stdin-param", "perms-request",
 		"dynamic-perms", // Added for moxy POC dynamic-perms
 		"permit-async",  // #317
+		"cache-results", // #319
 		"content-type", "result-type", "no-truncate", "substitute-result-uris",
 	}
 	if schema <= 2 {

internal/native/config_test.go

@@ -4,6 +4,7 @@ import (
 	"encoding/json"
 	"os"
 	"path/filepath"
+	"strings"
 	"testing"
 )
 
@@ -498,6 +499,66 @@ timeout-ms = 5000
 	}
 }
 
+// cache-results (#319): omitted resolves to the threshold default; the three
+// explicit values parse; anything else is a config error.
+func TestParseMoxinDirCacheResults(t *testing.T) {
+	dir := writeMoxinDir(t, t.TempDir(), "test", `
+schema = 1
+name = "test"
+`, map[string]string{
+		"defaulted": `
+schema = 3
+command = "echo"
+`,
+		"always": `
+schema = 3
+command = "echo"
+cache-results = "always"
+`,
+		"never": `
+schema = 3
+command = "echo"
+cache-results = "never"
+`,
+	})
+
+	cfg, err := ParseMoxinDir(dir)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	byName := map[string]ToolSpec{}
+	for _, tool := range cfg.Tools {
+		byName[tool.Name] = tool
+	}
+	if got := byName["defaulted"].CacheResults; got != CacheThreshold {
+		t.Errorf("defaulted: CacheResults = %q, want threshold", got)
+	}
+	if got := byName["always"].CacheResults; got != CacheAlways {
+		t.Errorf("always: CacheResults = %q, want always", got)
+	}
+	if got := byName["never"].CacheResults; got != CacheNever {
+		t.Errorf("never: CacheResults = %q, want never", got)
+	}
+}
+
+func TestParseMoxinDirCacheResultsInvalid(t *testing.T) {
+	dir := writeMoxinDir(t, t.TempDir(), "test", `
+schema = 1
+name = "test"
+`, map[string]string{
+		"bad": `
+schema = 3
+command = "echo"
+cache-results = "sometimes"
+`,
+	})
+
+	_, err := ParseMoxinDir(dir)
+	if err == nil || !strings.Contains(err.Error(), "invalid cache-results") {
+		t.Fatalf("err = %v, want invalid cache-results", err)
+	}
+}
+
 // permit-async (#317): omitted = eligible, explicit false forbids, explicit
 // true is recorded distinctly from omitted (*bool) for future tools/list
 // execution.taskSupport surfacing.

internal/native/server.go

@@ -453,11 +453,13 @@ func (s *Server) buildMCPResult(ctx context.Context, spec *ToolSpec, output stri
 
 	// Rewrite text blocks that carry mimeType into resource blocks with
 	// cache URIs — the MCP spec only allows mimeType on resource blocks.
+	// Whether a block is cached is the tool's cache-results policy (#319):
+	// the mime is just the label stamped onto whatever caching produces.
 	// Skip empty text — EmbeddedResourceContents requires non-empty text or blob.
 	cleaned := result.Content[:0]
 	for _, block := range result.Content {
 		if block.Type == "text" && block.MimeType != "" {
-			if block.Text != "" && s.madder != nil {
+			if block.Text != "" && s.madder != nil && s.shouldCache(spec, block.Text) {
 				uri, cacheErr := s.cacheAndGetURI(ctx, block.Text)
 				if cacheErr == nil {
 					text := block.Text
@@ -488,13 +490,31 @@ func (s *Server) buildMCPResult(ctx context.Context, spec *ToolSpec, output stri
 	return marshalResult(&result)
 }
 
+// shouldCache applies the tool's cache-results policy to one output (#319):
+// always caches everything, threshold (the default) only above the token
+// threshold, never caches nothing.
+func (s *Server) shouldCache(spec *ToolSpec, text string) bool {
+	switch spec.CacheResults {
+	case CacheAlways:
+		return true
+	case CacheNever:
+		return false
+	default: // CacheThreshold (and zero value for hand-built specs)
+		return estimateTokens(text) > tokenThreshold
+	}
+}
+
 func (s *Server) buildTextResult(ctx context.Context, spec *ToolSpec, output string) (json.RawMessage, error) {
 	if output == "" {
 		return marshalResult(&protocol.ToolCallResultV1{})
 	}
 
+	// cache-results policy (#319): "never" skips the blob store entirely
+	// (even oversized output stays plain inline text — the author owns the
+	// context cost); "threshold"/"always" blob-cache oversized output with
+	// the summary (or no-truncate inline) shape.
 	tokens := estimateTokens(output)
-	if tokens > tokenThreshold && s.madder != nil {
+	if spec.CacheResults != CacheNever && tokens > tokenThreshold && s.madder != nil {
 		digest, storeErr := s.madder.Write(ctx, strings.NewReader(output))
 		if storeErr == nil {
 			if spec.NoTruncate {
@@ -513,7 +533,12 @@ func (s *Server) buildTextResult(ctx context.Context, spec *ToolSpec, output str
 		}
 	}
 
-	if spec.ContentType != "" && s.madder != nil {
+	// "always" additionally caches small outputs as resource blocks, with
+	// content-type as the mime label. content-type alone no longer forces a
+	// cache write: small outputs under "threshold"/"never" are plain text
+	// blocks with the mime dropped (the MCP spec has nowhere to put a mime
+	// without a resource block, and a resource block needs a URI).
+	if spec.CacheResults == CacheAlways && s.madder != nil {
 		uri, cacheErr := s.cacheAndGetURI(ctx, output)
 		if cacheErr == nil {
 			block := protocol.ContentBlockV1{