Zephr Docs

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.

PositionPurpose
P0Initial context
P1Pre-action context
P2Advisory context
P3Post-action context
P4Banned

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 packId alone

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.

TierToolsDefault access
coreactivate, constraint, get_observations, how_to_obtain, recall, remember, session, status, sync_status, timeline, tools_execute, tools_searchRole policy
searchsearch, grep, lsp, why, verify, graph_queryRole policy
docsdocs, filesdocs_writer policy
reviewrules, admin, review, review_usageReviewer/admin policy
extensionVerified extension-declared toolsNo default
hostedHosted catalog toolsNo 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 separately

Persistence 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

FailureRecovery
Pack integrity mismatchInjection rejected; agent proceeds without steering
Budget exceededItems 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 granttier_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 packId field supports it, but the reconstruction path is not wired).