agent-context-budget · diff
git:20260904.4e8a7fd to git:20261016.a802ce4
99 added, 96 removed. Audit A to A.
---
name: agent-context-budget
- description: Use when an agent task needs bounded context packets, checkpoint-aware compaction, a fresh-session primer, or policy-controlled child results without loading raw logs into the primary session.
+ 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
- Prepare bounded context for a task without inventing a second budget source.
- Numeric limits come from the policy referenced by the current TaskCheckpoint.
- The public contract and commands are documented in
- ../../docs/public-harness-contract.md.
-
- ## Use this skill for
+ 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.
- - A task that may spawn a delegated executor or reviewer.
- - A transcript approaching its configured checkpoint boundary.
- - A fresh session that needs a compact, evidence-linked primer.
- - Results or logs that are too large for the primary-agent context.
+ Do not use this skill to summarize away unresolved failures, human decisions,
+ raw scientific evidence, or security findings.
- Do not use it to summarize away unresolved failures, human decisions, raw
- scientific evidence, or security findings.
+ ## Before launching lanes
- ## Inputs
+ - 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.
- - Goal and task id.
- - Readable agent policy.
- - Current TaskCheckpoint.
- - Evidence and artifact paths needed by the next role.
- - Optional existing .coord/plan.yml and approved memory events.
+ Host mechanics (parallel calls, background runs, per-lane model, return
+ schemas) are in [native lanes](../../docs/native-lanes.md).
- If the policy is configured but unreadable, stop. If the optional
- agent-collab-harness package is unavailable, do not start an autonomous loop or
- child spawn; prepare the packet for human-controlled execution instead.
+ ## What goes into a brief
- ## Workflow
+ Only decision-relevant material:
- 1. Validate policy and checkpoint:
+ - goal and acceptance contract;
+ - explicit files and tools in scope;
+ - direct evidence paths;
+ - current recorded human decisions;
+ - relevant interfaces or schemas.
- agent-collab policy validate --policy <policy-ref> --json
- agent-collab checkpoint validate --checkpoint <checkpoint-ref> --json
+ Keep raw logs and complete artifacts at their paths. Include a short failure
+ excerpt only when the next action needs it.
- 2. Record current observed metrics in the checkpoint. Do not estimate a lower
- number to fit the policy.
- 3. Run policy evaluation before a child spawn:
+ ## Before context runs out
- agent-collab policy evaluate \
- --policy <policy-ref> \
- --checkpoint <checkpoint-ref> \
- --json
+ 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.
- 4. Obey the result:
- - continue and spawn_allowed=true: create the bounded task packet.
- - checkpoint: write a checkpoint/primer. A v2 slice with auto_continue
- advances atomically and resumes under the same goal; v1 returns control.
- For v2 scope=action with context_compaction_required, perform local context
- maintenance without asking for renewed approval: preserve full artifacts,
- acceptance evidence, failures, and authorization; build a smaller linked
- packet or use native compaction, record measured sizes, then re-evaluate.
- Do not spawn or advance a slice while this context gate is pending.
- - stop or spawn_allowed=false: do not spawn. Respect v2 decision scope;
- exhaustion of one action does not prohibit safe primary-agent diagnosis.
- 5. Put only decision-relevant material in the packet:
- - goal and acceptance contract
- - explicit files and tools in scope
- - direct evidence references
- - current recorded human decisions
- - relevant interfaces or schemas
- 6. Keep raw logs and complete artifacts at paths. Include a short failure
- excerpt only when it is needed to diagnose the next action.
- 7. After a result returns, update observed metrics and evaluate again.
+ ## Durable decisions (formerly agent-shared-memory)
- ## Outputs
+ 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.
- - .coord/context_<NNN>.md: round-specific packet plan.
- - .coord/session_primer.md: bounded fresh-session digest.
- - Updated TaskCheckpoint at the plan's checkpoint_ref.
+ - 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.
- These are scratch artifacts by default. Promote a checkpoint snapshot only when
- the repository explicitly needs it for resume, shipping, or acceptance
- evidence. Agent boundaries do not imply commits.
+ Full schema and apply rules:
+ [references/coord_memory_schema.md](references/coord_memory_schema.md).
- ## Packet shape
+ ## Harness mode
- # Context packet — <task id>
+ Applies when `AGENT_COLLAB_POLICY` is configured, or a round spans sessions or
+ tools, runs unattended, or must resume.
- Policy
- - policy_ref: <path>
- - policy_hash: <sha256>
- - checkpoint_ref: <path>
+ 1. Validate:
- Goal
- <one bounded objective>
+ agent-collab policy validate --policy <policy-ref> --json
+ agent-collab checkpoint validate --checkpoint <checkpoint-ref> --json
- Recorded decisions
- - <gate / actor / decision / action hash>
+ 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:
- Evidence
- - <path or stable source locator>
+ agent-collab policy evaluate \
+ --policy <policy-ref> \
+ --checkpoint <checkpoint-ref> \
+ --json
- Scope
- - may read: <paths>
- - may write: <paths>
- - must not touch: <paths>
+ 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.
- Acceptance
- - <runnable check>
+ Multi-cycle loop rules (retry counting, failure identity, no-progress cycles)
+ are in [references/harness-loop.md](references/harness-loop.md).
- Return contract
- - concise summary
- - files changed
- - tests run
- - risks and blockers
- - raw logs by path only
+ 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.
- - v2 slice counters reset only through checkpoint advance; goal totals and
- accepted evidence never reset. Retain the stricter explicit native/host limit.
- - Reserve child capacity for required independent review. Completed children
- release active concurrency; the host's actual capacity also limits spawning.
- - No silent retry, model switch, context discard, or result truncation.
- - Compaction changes active context, not cumulative usage or failure history.
- If safe compaction is unavailable, report that limitation, not a generic
- request to continue. Never clear an ambiguous legacy blocker automatically.
- - Missing evidence is reported as missing, not summarized as success.
- - A decline, cancellation, timeout, error, or null result remains non-success.
- - Recall systems may suggest context; they do not override repository state or
+ - 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
+ capped return that points to the full output is not truncation.
+ - Missing evidence is reported as missing. A decline, cancellation, timeout,
+ error, or `null` result remains non-success.
+ - Recall systems may suggest context; they never override repository state or
recorded human decisions.