Trim repeated schema descriptions -> save tokens -> profit

[tmustier]

⚠️ ⚠️ Targets feat/acceptance-finalization / v0.28.0, which looks newer than main. Happy to rebase ⚠️ ⚠️

Hey Nico!

I was doing a context scrub for my Pi and noticed the subagent tool schema has quite a bit of repeated nested description text esp. for acceptance, chain steps, parallel & dynamic fanout.

It looks like this was mostly added around 0.26/27 dynamic fanout + acceptance-contract.

Adding this small PR to keep the same behaviour but trim nested description fields.

Gets 32% fewer chars (25k->17k). Comparing OpenAI+Ant reported before/after tokens, I get:

• 13% saving for openai (3.0k->2.6k tokens)
• 21% saving for opus-4-8 (11.6k->9.1k tokens)

Used/tested it a bunch locally today and seems to be working well. Let me know what you think!

Thomas

Pi description:

Summary

• prune nested description fields from the exported SubagentParams tool schema while keeping top-level parameter descriptions
• preserve TypeBox non-enumerable metadata/property descriptors while pruning provider-visible descriptions
• keep the provider payload inline and portable: no $ref / $defs
• add regression coverage for schema compactness, TypeBox metadata preservation, and nested acceptance validation paths

Size impact

• SubagentParams serialized schema: 24,359 → 16,564 chars
• saves 7,795 chars (~32.0%) in the source JSON Schema
• measured live-provider token impact with Pi CLI, thinking off, prompt hi, and only the subagent tool enabled:
  • Anthropic Claude Opus 4.8: 11,604 → 9,142 total tokens (11.6k → 9.1k), saving 2,462 tokens (~21.2%)
  • Anthropic reports this schema-heavy portion as prompt cache write: 11,598 → 9,136 cache-write tokens
  • OpenAI-Codex GPT-5.5 showed provider-side accounting variance; the stable lower-regime comparison was 2,967 → 2,576 input tokens (3.0k → 2.6k), saving 391 tokens (~13.2%), while some old-schema runs counted as high as 5,006 input tokens
• long acceptance-contract prose appears once instead of being duplicated through nested schema copies

Test plan

• mise x node@24.16.0 -- npm test — 510/510 passing
• mise x node@24.16.0 -- npm run test:integration — 377/377 passing
• mise x node@24.16.0 -- npm run test:all — unit + integration passing
• mise x node@24.16.0 -- npm pack --dry-run

Notes

• This targets feat/acceptance-finalization because that branch contains v0.28.0; main currently appears to lag at v0.26.0, which would make the PR unnecessarily noisy.