Agent runtime
The agent runtime defines how Zephr changes what an AI agent actually does at runtime: what enters its context, what tools it can see, what a subagent is told, how it is steered before a mistake, how state survives compaction, and how Zephr proves the injection was used.
Status
Evolving. The Pack system, four injection positions, tiered tool surface, and subagent
brief are designed and partially wired. The attribution loop (proving injection was used) is
designed but not shipped. Hook transport and plumbing belong to surfaces; memory write
semantics belong to memory; ranking belongs to retrieval.
Core concepts
Pack — the sole injection unit
Every injection into an agent's context is a Pack:
interface InjectionPosition {}
interface PackItem {}
const pack: {
packId: string; // stable, reconstructible
scope: string; // worktree or session scope
revision: number; // monotonically increasing
position: InjectionPosition;
budgetTokens: number; // token budget for this pack
items: PackItem[]; // the actual content
integrity: string; // hash of the pack content
} = {} as never;
void pack;Zephr never emits memory as loose text. Any renderer path that produces context-bound
text without a packId is rejected at build time.
Pack item shape
Each item in a Pack is:
{
handle: string; // zh_<base32>, stable across sessions and clients
trust: TrustTier; // the trust level of this assertion
assertion: string; // a single normalized clause
cite?: string[]; // URLs and document references (metadata, never in assertion body)
}Injection positions
Zephr's injection vocabulary is P0 through P4. P0–P3 are the legal positions defined by the runtime contract; P4 is banned. Position emission is budget-aware and may emit nothing rather than blocking a session.
| Position | Purpose |
|---|---|
P0 | Initial context |
P1 | Pre-action context |
P2 | Advisory context |
P3 | Post-action context |
P4 | Banned |
Handle identity
Every Pack item carries a handle of the form zh_<base32> that is:
- Stable across sessions, clients, machines, and revisions
- Addressable — an agent can pass a handle to an expansion call and get full provenance
- Reconstructible — a dropped Pack can be rebuilt from
packIdalone
Pack delivery verification
Zephr records every Pack as emitted and separately confirms it as delivered using the
harness capability matrix. A Pack emitted through a channel recorded as dropped is counted as
undelivered and is not charged against the session injection budget.
Tool tiers
The MCP tool surface is classified into tiers. Each agent role carries an allowedTiers
array, and tool calls are rejected if the role's tiers do not include the tool's tier.
| Tier | Tools | Default access |
|---|---|---|
core | activate, constraint, get_observations, how_to_obtain, recall, remember, session, status, sync_status, timeline, tools_execute, tools_search | Role policy |
search | search, grep, lsp, why, verify, graph_query | Role policy |
docs | docs, files | docs_writer policy |
review | rules, admin, review, review_usage | Reviewer/admin policy |
extension | Verified extension-declared tools | No default |
hosted | Hosted catalog tools | No default |
Tier enforcement
Enforcement happens in packages/mcp-server/src/tool-tier-enforcement.ts via
evaluateTierEnforcement. The check is evaluated per-call, not at connection time.
Extension tools are assigned tier 'extension' — a tier not in any role's default
allowedTiers. An admin must add 'extension' to a role's allowedTiers for that role
to call extension tools.
Tool residency
Tools are classified as resident (hot-loaded at server start, always advertised) or
deferred (loaded on first call, advertised with defer_loading: true so MCP clients may
lazy-provision them).
Subagent brief
When Zephr dispatches a subagent, it injects a brief — a Pack scoped to the subagent's task. The brief carries:
- The subagent's objective
- Relevant memories (ranked by retrieval)
- Scope constraints (what the subagent may and may not touch)
- Trust tier attributes for each injected item
The subagent brief is the mechanism by which Zephr steers autonomous work without overriding the agent's own reasoning.
Setup and configuration
Tool tier grants
{
"roleId": "role-id",
"allowedTiers": ["core", "search", "docs", "hosted"]
}To enable extension tools for a role:
{
"roleId": "role-id",
"allowedTiers": ["core", "search", "docs", "extension"]
}Injection budget
Each Pack carries a budgetTokens field. The renderer enforces the budget; items that
exceed it are truncated or dropped, never silently injected past the limit.
Data flow
Agent turn starts
→ Eligible P0-P3 context selected within budget
→ Agent reasons and calls tools
→ Position-specific context may be emitted or omitted
→ Delivery and attribution recorded separatelyPersistence and security
- Pack integrity is verified by hash at injection time.
- Handles are deterministic and cannot be forged (base32-encoded provenance hash).
- The irreversible latch prevents scope widening after admission.
- Tenant isolation: Packs are scoped to a worktree; cross-worktree injection is rejected.
Limits
- Token budget is per-Pack, not cumulative — a session may inject multiple Packs.
- Deferred tools add latency on first invocation (load-on-demand overhead).
- The attribution loop (proving injection was used by the agent) is not yet shipped.
Failures and recovery
| Failure | Recovery |
|---|---|
| Pack integrity mismatch | Injection rejected; agent proceeds without steering |
| Budget exceeded | Items truncated to fit; no silent over-injection |
| Channel dropped (delivery failure) | Pack counted as undelivered; not charged to session budget |
| Extension tool call without tier grant | tier_denied error; admin must grant the tier |
What is designed but not shipped
- Attribution loop: proving that injected Packs were actually used by the agent (not just delivered).
- Pack reconstruction from transcript: rebuilding dropped Packs from conversation history
(designed, the
packIdfield supports it, but the reconstruction path is not wired).
Related references
- Agent runtime spec — full requirements and scenarios
- Surfaces — hook transport and lifecycle adapter
- Extensions — extension tool tier
- Hosted tools — hosted tool tier