/agent-context-budget

name: agent-context-budget
description: Use when launching parallel or background subagents, or when a handoff, log, or result would be more than a short summary (roughly 2 KB). Caps return sizes (summary in the reply, detail by path), picks a cheap model tier for mechanical lanes, records durable decisions as proposals, and checkpoints or primes a fresh session before context runs out.

agent-context-budget

Keep the primary session small while lanes do the reading and writing. There is no second budget source: native mode follows the host's limits and the caps written into each brief; harness mode takes every number from the policy referenced by the current `TaskCheckpoint`. The "roughly 2 KB" in the description says when to use this skill; it is not a limit.

Do not use this skill to summarize away unresolved failures, human decisions, raw scientific evidence, or security findings.

Before launching lanes

• Put a return cap in every brief: status, short summary, files changed,

checks run, risks, blockers. Long output goes to a file and the lane returns the path. Raw logs, transcripts, and full diffs never come back inline.

• Reading lanes return conclusions with `file:line` references, not file

dumps. Name exact files and line ranges in the brief.

• Choose model tiers before launch: a cheap tier for mechanical lanes (pattern

edits, scaffolds, bulk reads), a strong tier for review, verdicts, root-cause analysis, security, and governance. Never switch a lane's model silently after a failure.

• Background lanes notify on completion. Keep working and read the result

then; do not poll.

• For a follow-up, continue the lane that already holds the context instead

of starting a fresh one.

Host mechanics (parallel calls, background runs, per-lane model, return schemas) are in [native lanes](../../docs/native-lanes.md).

What goes into a brief

Only decision-relevant material:

• goal and acceptance contract;
• explicit files and tools in scope;
• direct evidence paths;
• current recorded human decisions;
• relevant interfaces or schemas.

Keep raw logs and complete artifacts at their paths. Include a short failure excerpt only when the next action needs it.

Before context runs out

Write a fresh-session primer: goal, current state, decisions and who made them, open questions, evidence paths, next step. Keep unresolved failures, human decisions, and security findings visible. Compaction changes the active context, not cumulative usage or failure history.

Durable decisions (formerly agent-shared-memory)

Memory output is proposal-only. Repository state, current evidence, and recorded human decisions outrank memory; recall systems are optional caches. Native mode may write a proposal file and nothing else under `.coord/`; applying an approved proposal needs the signed approval of harness mode.

• Write a proposal to `.coord/memory-proposals/<proposal-id>.json` with an

immutable `action` (operation, target_ref, summary, evidence_refs).

• Supersede, archive, and delete need a specific `target_ref`. A proposal

with no evidence refs stays pending.

• Only an explicit human approval, recorded with actor, decision, timestamp,

rationale, affected action hash, and trusted-host HMAC authorization, lets a proposal be applied. Decline, timeout, and revise are not approval.

• Applying appends one new event to `.coord/memory.yml`.

It never edits an existing event; a resolution, correction, or supersession is a new append-only event.

• Never report an unapproved proposal as a canonical decision. Delegated

executors never receive the signing key.

Full schema and apply rules: [references/coord_memory_schema.md](references/coord_memory_schema.md).

Harness mode

Applies when `AGENT_COLLAB_POLICY` is configured, or a round spans sessions or tools, runs unattended, or must resume.

1. Validate:

agent-collab policy validate --policy <policy-ref> --json agent-collab checkpoint validate --checkpoint <checkpoint-ref> --json

2. Record the observed metrics in the checkpoint. Never estimate a lower number to fit the policy. 3. Before each child spawn and after each returned result, run:

agent-collab policy evaluate \ --policy <policy-ref> \ --checkpoint <checkpoint-ref> \ --json

4. Obey the decision:

• `continue` with `spawn_allowed=true`: build the bounded packet.
• `checkpoint`: write the checkpoint and primer. A v2 slice with

auto_continue advances atomically under the same goal; v1 returns control. For a v2 action-scope `context_compaction_required`, do local context maintenance without asking for renewed approval: keep full artifacts, acceptance evidence, failures, and authorization; build a smaller linked packet or use native compaction; record measured sizes; re-evaluate. Do not spawn or advance a slice while this gate is pending.

• `stop` or `spawn_allowed=false`: do not spawn. Respect the v2 scope; an

exhausted action still allows safe primary-agent diagnosis. 5. A configured but unreadable policy stops the run. If the harness package is unavailable, do not start an autonomous loop; prepare packets for human-controlled execution instead.

Multi-cycle loop rules (retry counting, failure identity, no-progress cycles) are in [references/harness-loop.md](references/harness-loop.md).

Outputs (scratch by default): `.coord/context_<NNN>.md` (shape in [references/harness-loop.md](references/harness-loop.md)), `.coord/session_primer.md`, and the updated checkpoint. Promote a checkpoint snapshot only when the repository needs it for resume, shipping, or acceptance evidence. Agent boundaries do not imply commits.

Invariants

• Policy values have one machine-readable source; the stricter of the policy

and the host's native limit wins.

• Reserve capacity for required independent review.
• No silent retry, model switch, context discard, or result truncation. A