Skip to content

feat: add max_context_tokens to agent YAML for enforced context budget #699

@agents-squads

Description

@agents-squads

Problem

Agent YAML has no context limit field. website ($11.49/run, 15M cache tokens) and intelligence ($10.92/run, 13M cache tokens) account for 36% of org cycle spend due to unconstrained context bloat.

budget.per_run documents a soft cost cap but does not enforce context limits. Agents silently accumulate 13-15M tokens without warning or abort.

Proposed Solution

Add optional context section to agent YAML frontmatter:

context:
  max_tokens: 3000000
  warn_at: 2000000

If context would exceed max_tokens at invocation, log error and abort. If warn_at exceeded, emit structured warning with current token count.

Alternatives Applied

  • context_from narrowing (ops applied 2026-03-31, hq commit dabfadbd) — reduces loaded memory but does not prevent runtime accumulation
  • CLAUDE.md context diet instructions — behavioral, not enforced

Reference

analytics/reports/execution-economics-2026-03-28.md | hq #393 | source: operations-lead 2026-03-31

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions