Context Engine

context-engine

Purpose

Context window management for long sessions. Detects when context is approaching limits, triggers smart compaction preserving critical decisions and progress, and coordinates with session-bridge to save state before compaction. Prevents the common failure mode of losing important context mid-workflow.

Behavioral Contexts

Context-engine also manages behavioral mode injection via contexts/ directory. Three modes are available:

| Mode | File | When to Use | |------|------|-------------| | dev | contexts/dev.md | Active coding — bias toward action, code-first | | research | contexts/research.md | Investigation — read widely, evidence-based | | review | contexts/review.md | Code review — systematic, severity-labeled |

Mode activation: Orchestrators (cook, team, rescue) can set the active mode by writing to .rune/active-context.md. The session-start hook injects the active context file into the session. Mode switches mid-session are supported — the orchestrator updates the file and references the new behavioral rules.

Default: If no .rune/active-context.md exists, no behavioral mode is injected (standard Claude behavior).

Triggers

• Called by cook and team automatically at context boundaries
• Auto-trigger: when tool call count exceeds threshold or context utilization is high
• Auto-trigger: before compaction events

Calls (outbound)

Exception: L3→L3 coordination

• session-bridge (L3): coordinate state save when context critical

Called By (inbound)

• cook (L1): Phase boundaries and when tool count exceeds thresholds
• team (L1): before parallel workstream dispatch, after merge
• rescue (L1): between refactoring sessions for state persistence
• context-pack (L3): when packaging context for sub-agent handoff
• session-bridge (L3): coordinates with context-engine for compaction timing
• adversary (L2): (oracle-mode) emit context.preview before bundle build to gate token cost

Execution

Step 1 — Count tool calls

Count total tool calls made so far in this session. This is the ONLY reliable metric — token usage is not exposed by Claude Code and any estimate will be dangerously inaccurate.

Do NOT attempt to estimate token percentages. Tool count is a directional proxy, not a precise measurement.

Step 2 — Classify health

Map tool call count to health level:

GREEN   (120 calls)   — Trigger immediate compaction, save state first

These thresholds are directional heuristics, not precise limits. Sessions with many large file reads may hit context limits earlier; sessions with mostly Grep/Glob may go longer.

Large-File Adjustment

Projects with large source files (Python modules often 500-1500 LOC, Java files similarly) consume significantly more context per Read call. If the session has read files averaging >500 lines, apply a 0.8x multiplier to all thresholds:

Adjusted thresholds (large-file sessions):
GREEN   (100 calls)   — Trigger immediate compaction, save state first

Detection: count Read tool calls that returned >500 lines. If ≥3 such calls → activate large-file thresholds for the remainder of the session.

Step 3 — If YELLOW

Emit advisory to the calling orchestrator:

> "[X] tool calls. Load only essential files. Avoid reading full files when Grep will do."

Do NOT trigger compaction yet. Continue execution.

Step 4 — If ORANGE

Emit recommendation to the calling orchestrator:

> "[X] tool calls. Recommend /compact at next phase boundary (after current module completes)."

Identify the next safe boundary (end of current loop iteration, end of current file being processed) and flag it.

Auto-activate Caveman Output Mode (see references/caveman-mode.md) — emit output.density.set with mode=caveman, scope=session, source=context-orange. Reduces output token cost ~75% with no information loss; persists until /compact returns context to GREEN. Manual override (/caveman or "stop caveman") always wins.

Step 5 — If RED

Immediately trigger state save via rune:session-bridge (Save Mode) before any compaction occurs. If caveman mode was not already active from ORANGE, emit output.density.set with mode=caveman, scope=session, source=context-red now.

Pass to session-bridge:

• Current task and phase description
• List of files touched this session
• Decisions made (architectural choices, conventions established)
• Remaining tasks not yet started

After session-bridge confirms save, emit:

> "Context CRITICAL ([X] tool calls, likely near limit). State saved to .rune/. Run /compact now."

Block further tool calls until compaction is acknowledged.

Step 6 — Report

Emit the context health report to the calling skill.

Step 6b — Context Percentage Advisory

In addition to tool-call counting, monitor context window percentage when available:

| Remaining | Level | Action | |-----------|-------|--------| | >35% | SAFE | Continue normally | | 25-35% | WARNING | Advise: "Context at ~[X]%. Consider /compact at next phase boundary" | | quantity for context loading.

Compaction Technique: Structured Summary with Continuation Point

When compaction is triggered (RED or approved ORANGE), generate a structured summary that replaces the full conversation history while preserving therapeutic continuity — the ability to resume exactly where work left off.

Summary Structure

The compaction summary MUST include these sections in order:

## Compaction Summary (generated at [tool call count])

### Topics Covered
- [bullet list of distinct topics/tasks worked on this session]

### Key Decisions Made
- [decision]: [rationale] — affects [files/modules]

### Active Threads
- [what was being worked on when compaction triggered — the "where we are now" anchor]
- Current file: [path], current function/section: [name]
- Partial progress: [what's done vs what remains in the immediate task]

### Emotional/Priority Context
- [user urgency level, blocking issues, deadlines mentioned]
- [any user frustrations or preferences expressed this session]

### Continuation Point
> Resume: [exact next action to take — not vague "continue working" but specific "implement the validation logic in src/auth/validate.ts:47 using the Zod schema defined in Step 2"]

Why This Structure

Most compaction loses the continuation point — the agent knows WHAT was discussed but not WHERE to resume. The "Active Threads" and "Continuation Point" sections solve this by preserving:

1. The exact file and function being edited
2. What's done vs remaining in the current micro-task
3. The specific next action (not a summary of the plan, but the next concrete step)

Rules

• Summary MUST be 4000 characters | Fold to artifact |

| Tool output > 120 lines | Fold to artifact | | Multiple tool outputs from the same command class (e.g., 5+ Grep results) | Fold all into single artifact | | Code block output > 200 lines | Fold to artifact |

Folding Procedure

1. Save full output to .rune/artifacts/artifact-{timestamp}-{tool}.md:

```markdown # Artifact: {toolname} output Generated: {timestamp} Command: {toolcall_summary}

{full_output} ```

1. Replace in context with a compact preview:

`` [FOLDED: {tool_name} output — {line_count} lines, {char_count} chars] Preview (first 10 lines): {first_10_lines} ... Full output: .rune/artifacts/artifact-{timestamp}-{tool}.md Use Read to access the full artifact if needed. ``

1. On compaction: Artifact files survive compaction — the continuation summary references them by path. This means large outputs are preserved across compaction boundaries without consuming context.

Rules

• Never fold user messages — only tool outputs
• Never fold error outputs — errors need full visibility for debugging
• **Never fold outputs 120 calls) — Save state NOW via session-bridge, compact immediately

Note: These are tool call counts, NOT token percentages. Claude Code does not expose context utilization to skills. Tool count is a directional signal only.

## Output Format

Context Health

• Tool Calls: [count]
• Status: GREEN | YELLOW | ORANGE | RED
• Recommendation: continue | load-essential-only | compact-at-boundary | compact-immediately
• Note: Tool count is a directional proxy. Check CLI status bar for actual context usage.

Critical Context (preserved on compaction)

• Task: [current task]
• Phase: [current phase]
• Decisions: [count saved to .rune/]
• Files touched: [list]
• Blockers: [if any]

## Strategic Compact Decision Table

When ORANGE or RED is reached, use this table to determine whether compaction is safe at the current boundary:

| Transition | Compact? | Reason |
|-----------|----------|--------|
| Research → Planning | YES | Research findings summarize well; key decisions survive |
| Planning → Implementation | YES | Plan is in files (.rune/plan-*.md); context can reload from artifacts |
| Debug → Next feature | YES | Debug findings are in Debug Report; fix has the diagnosis |
| Mid-implementation (Phase 4) | **CONDITIONAL** | Safe ONLY at task boundaries within Phase 4 (after a file is fully written + tested). Never mid-file-edit. See Mid-Loop Compaction below |
| After failed approach → Pivot | YES | Failed approach should be discarded; fresh context helps |
| Quality (Phase 5) → Verify | **NO** | Quality findings reference specific file:line in current context |
| After commit (Phase 7) | YES | Work is persisted in git; safe boundary |

**What survives compaction**: Task description, file paths mentioned, key decisions, plan reference, current phase.
**What is lost**: Full file contents read, intermediate reasoning, exact error messages, tool output details.

### Mid-Loop Compaction (Phase 4 Emergency)

> From goclaw (nextlevelbuilder/goclaw, 832★): "Compact during run, not just at session boundary."

When context hits RED during Phase 4 (implementation), compaction IS possible at **clean split points**:

1. **Find a clean boundary**: completed task within the phase (file fully written + tests pass for that file)
2. **Flush state first**: call `session-bridge` to save progress, then call `neural-memory` to capture decisions
3. **Split 70/30**: preserve 70% of remaining context for continuation, summarize 30% of completed work
4. **Never break tool pairs**: compaction MUST NOT split a `tool_use` from its `tool_result` — always keep pairs together
5. **Inject continuation marker**: after compaction, include: "Resuming Phase 4. Tasks [1-3] complete. Currently on task 4. Plan file: `.rune/plan-X-phaseN.md`"

**Timeout fallback**: If clean boundary can't be found within 30 seconds, create `.rune/.continue-here.md` and pause instead.

**Skip if**: Context is ORANGE (not RED), or fewer than 3 tasks remain in the phase.

## Context Budget Audit (Baseline Cost Awareness)

MCP tool schemas and agent descriptions consume significant baseline context before any work begins. This section helps identify and reduce invisible context waste.

### Token Cost Reference

| Source | Approx. Cost | Loaded When |
|--------|-------------|-------------|
| Each MCP tool schema | ~500 tokens | Session start (always) |
| Each agent description | ~200-400 tokens | Every `Task()` invocation |
| CLAUDE.md | ~100-2000 tokens | Session start (always) |
| Skill SKILL.md (full load) | ~500-3000 tokens | When skill is invoked |

### Budget Rules

| Rule | Threshold | Action |
|------|-----------|--------|
| Max MCP servers | 80 MCP tools:

1. Count total MCP tool schemas loaded (from session start messages)
2. Count agent descriptions available
3. Estimate baseline cost: `(tools × 500) + (agents × 300) + CLAUDE.md tokens`
4. If baseline >15% of estimated context window → flag as **Context Budget Warning**
5. Rank MCP servers by tool count — suggest disabling servers with most tools and least usage

### Report Addition

When Context Budget Warning fires, append to Context Health report:

Context Budget

• Baseline cost: ~[N]k tokens ([X]% of estimated window)
• MCP tools loaded: [count] across [N] servers
• Top consumers: [server1] ([N] tools), [server2] ([N] tools)
• Recommendation: Disable [server] to save ~[N]k tokens

## Output Density Mode (Caveman)

Caveman is a terse output mode that strips filler, articles, hedging, and pleasantries while preserving full technical accuracy. ~75% output token reduction with no information loss when applied per the rules in `references/caveman-mode.md`.

### Activation triggers

| Trigger | Source | Persistence |
|---------|--------|-------------|
| Context health = ORANGE or RED | Auto from Step 4-5 above | Until `/compact` returns to GREEN |
| User says "caveman" / "/caveman" / "be brief" / "less tokens" | Explicit user signal | Until "stop caveman" / "normal mode" |
| Per-workstream override (e.g., `team` worker exceeds output budget) | Per-workstream scope | Scoped to that workstream only |

Auto-activation emits `output.density.set` signal carrying `{mode: caveman, scope, source}`. Orchestrators (cook, team, rescue) honor the signal for the duration of their session.

### Auto-clarity exceptions (revert ONE response, then resume)

- Security warnings (data loss, credential exposure)
- Confirmations of irreversible actions (`rm -rf`, force-push, drop table, prod deploy)
- Multi-step sequences where fragment ordering risks misreading
- User says "explain" / "clarify" / repeats the same question
- Root-cause diagnosis where cause-and-effect chains need grammatical structure

### Anti-pattern

Caveman in the FIRST response of a task. The user can't calibrate severity from a single output yet — verbose first response is fine. Caveman starts on response 2+.

## Mode: preview (v1.1.0)

Pre-flight cost check for expensive escalations. Caller (`adversary` oracle-mode, `team` workstream spawn, `review` multi-file, `audit` cross-pack) MUST emit `context.preview` BEFORE building the bundle, so context-engine can estimate token cost and gate the dispatch against a per-caller threshold.

### Why

Without preview, callers learn about budget overruns AFTER the bundle is built and dispatched — too late to prune. `team` parallel workstreams especially can blow $20 of Opus tokens in a single session if context bundles are unchecked.

### Token Estimation (no tokenizer dep)

estimatedtokens = totalchars × 0.25

Char count includes the `[SYSTEM]` line, `[USER]` line, and all `### File N:` blocks per `references/preview-gate.md`. The 0.25 ratio is calibrated for English code/markdown — overestimates Japanese/Chinese, underestimates highly-repetitive content. Both error directions are safe (overestimate → over-cautious block; underestimate → caller still hits dispatch-time hard cap).

### Threshold Defaults (per caller)

| Caller | warn-at (tokens) | block-at (tokens) |
|--------|------------------|-------------------|
| `adversary` oracle-mode | 50k | 100k |
| `team` parallel workstream (per worker) | 30k | 80k |
| `review` multi-file | 40k | 100k |
| `audit` cross-pack | 60k | 120k |

Caller passes its identity in the preview request; context-engine resolves to the correct threshold.

### Action Enum

`context.preview` payload includes a single `action` field:

| Action | Meaning | Caller behavior |
|--------|---------|-----------------|
| `proceed` | Under warn threshold | Continue without warning |
| `warn` | Between warn and block | Log warning to user, continue |
| `block` | At or over block threshold | Abort dispatch, emit caller-specific failure (e.g. `oracle.failed` reason=`context_budget_exceeded`) |

### Signal Payload Schema

```yaml
context.preview:
  caller: adversary | team | review | audit
  estimated_tokens: 
  file_count: 
  top_5_files_by_size:
    - { path: , chars:  }
  threshold:
    warn_at: 
    block_at: 
  action: proceed | warn | block

Step P1 — Re

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Rune-kit
• Source: Rune-kit/rune
• License: MIT

Install and usage instructions live in the source repository linked above.