Context Control

Purpose and Scope

Context control is the practice of deciding what an eve agent's model can see on every turn, what it can discover only when needed, and what should be isolated behind tools or delegation. In eve, the default answer is not to paste the whole project into a prompt. The documented model separates always-on identity, load-on-demand procedures, workspace inspection, subagent delegation, and runtime-specific dynamic context so agent authors can keep prompts focused while still giving the agent access to useful capabilities.

Sources: docs/concepts/context-control.md

This page is for developers designing an agent's information boundary. It explains where stable behavior belongs, how richer procedures become available without bloating every model call, why authored files and sandbox state are exposed through runtime tools, and when to move work into a specialist subagent. It also covers the dynamic path for context that depends on the caller, such as team, tenant, plan, or feature flags. The goal is to help you choose the smallest context surface that still lets the agent complete the user's task reliably.

Relevant Source Files

• docs/concepts/context-control.md - Defines the public context-control model for eve agents, including always-on instructions, TypeScript-composed instructions, demand-loaded skills, workspace inspection, subagents, and dynamic context with defineDynamic.

Core Primitives

The always-on primitive is agent/instructions.md, or the equivalent agent/instructions.ts module. The markdown form is the simplest place for the agent's base identity: what it is, how it should behave, and which rules apply on every turn. The documentation's example describes a careful support assistant that is concise, verifies facts, and explains tool use. That kind of stable behavioral contract belongs in instructions because it should be present regardless of the user's specific request.

Sources: docs/concepts/context-control.md

Use agent/instructions.ts when the base prompt needs to be assembled from code. The documented pattern imports defineInstructions from eve/instructions, calls project helper code such as buildInstructionsPrompt(), and returns an object with a markdown field. This is still a build-time context primitive, not a per-turn computation hook. eve captures the generated markdown into the compiled manifest, so sessions receive the same prompt without re-running the module at runtime.

Skills are the main on-demand primitive. Files under agent/skills/ are available to the agent, but they are not part of the always-on prompt by default. eve advertises the available skills and provides a framework-owned load_skill tool. When the user clearly asks for a procedure that matches a skill description, or names the skill explicitly, the model can activate that skill. eve then appends the skill markdown to the active instructions for later work in that turn or session context.

Sources: docs/concepts/context-control.md

The workspace and sandbox are context primitives too, but they are intentionally mediated. eve gives the model a shallow workspace hint and tools for deeper inspection instead of inlining authored files into the prompt. Skill files and packaged skill assets can appear under the runtime workspace root, where the shared bash tool lets the model inspect files or run commands when it has a reason to do so. This makes file access explicit, reduces prompt size, and preserves a clearer audit trail of what the model looked at.

Authoring Always-On Context

Start with the smallest durable contract in instructions.md. Good always-on instructions describe the agent's role, durable policies, tone, and tool-use expectations. They should avoid transient customer data, long operating procedures, or large reference material because those increase cost and reduce the space available for the user's actual task. If a rule must apply to every turn and every user, put it here. If the rule is conditional, procedural, or specific to a domain, it is usually a better fit for a skill, subagent, or dynamic resolver.

Sources: docs/concepts/context-control.md

A concise instruction file is also easier to reason about during review. Because eve treats the filesystem as the authoring surface, developers can inspect the base prompt in the same way they inspect tools, skills, and schedules. When using instructions.ts, keep the generated output similarly focused. The TypeScript form is useful for composing a prompt from typed helpers, shared library code, or environment-derived build inputs, but the resulting markdown is captured into the manifest and served consistently at runtime.

import { defineInstructions } from "eve/instructions";
import { buildInstructionsPrompt } from "./lib/prompts.js";
 
export default defineInstructions({
  markdown: buildInstructionsPrompt(),
});

Loading Procedures with Skills

Skills let you keep detailed procedures outside the base prompt until the model needs them. A flat skill can be a single markdown file such as agent/skills/get-weather.md that tells the agent to use the weather tool before answering forecast or temperature questions. A packaged skill can use a directory such as agent/skills/research/SKILL.md with frontmatter, including a description, followed by the procedure. The description is important because it helps eve and the model identify when the skill should be loaded.

Sources: docs/concepts/context-control.md

Packaged skills are useful when the procedure depends on sibling material. The documentation calls out sibling paths such as references/, assets/, and scripts/ under the same skill directory. Those files are not pasted directly into the prompt. Instead, they appear under the runtime workspace root so the model can inspect them through normal file or shell tools. This gives the agent access to rich supporting material while preserving the separation between instructions, available resources, and explicit runtime actions.

A useful rule of thumb is to make the skill description narrow and the skill content actionable. The description should say when the skill applies, while the markdown should say how to perform the work once loaded. If a skill is too broad, it may load too often and recreate prompt bloat. If it is too vague, the model may not discover it when the user needs it. The context-control page points readers to the Skills documentation for the full authoring model and installation notes.

Workspace, Sandbox, and Subagents

The workspace is best used for context that can be inspected on demand. eve does not inline the entire authored surface into the model prompt. Instead, it exposes a shallow hint and lets runtime tools perform deeper inspection. This matters for repositories, packaged skill resources, generated files, and command output. By forcing the model to ask for file contents or run a shell command, eve makes context acquisition part of the visible execution flow rather than hidden prompt stuffing.

Sources: docs/concepts/context-control.md

Subagents are the stronger boundary when a task deserves its own prompt and tool surface. Rather than continuously expanding the root agent's instructions, create a local subagent with its own instructions.md, tools, and sandbox. The subagent runs in a delegated context instead of extending the root agent inline. That makes it appropriate for specialist workflows where different policies, tools, or files should be available without permanently changing the root agent's active context.

This distinction is architectural, not just organizational. Skills extend the active instructions after loading, so they are appropriate for procedures the root agent can carry out. Subagents isolate work behind a delegated call, so they are appropriate when the root agent should coordinate rather than directly execute. If the context would make the root agent harder to control, or if the work needs a different sandbox or tool set, a subagent is the cleaner context-control lever.

Dynamic Context at Runtime

Static context is authored once and reused across sessions. The documented dynamic path is for context that depends on who is calling or which channel metadata is present. defineDynamic in agent/instructions/ returns a per-session system prompt, while defineDynamic in agent/skills/ returns the set of skills a caller can load. These resolvers can read ctx.session.auth or channel metadata, allowing different callers to receive different instructions and playbooks.

Sources: docs/concepts/context-control.md

Use dynamic context for tenant-specific policy, team-specific procedure, feature-flagged behavior, or plan-gated capability. For example, the documentation frames runtime resolution around values such as team, tenant, plan, and feature flags, and mentions a caller on the billing team receiving billing instructions and a playbook. This is different from instructions.ts: module-backed instructions run once at build time, while dynamic context is resolved at runtime for the active session.

Design Checklist and Next Steps

When designing an eve agent, first write the base identity in instructions.md and keep it limited to stable, universal behavior. Next, move optional procedures into skills/ so they are advertised but not loaded until relevant. Put bulky reference material, assets, scripts, and runtime files in the workspace so tools can inspect them explicitly. Delegate specialized work to subagents when the task needs a separate prompt, tool surface, or sandbox. Finally, use defineDynamic only when the right instructions or skills depend on session identity or channel metadata.

Sources: docs/concepts/context-control.md

Read the related pages in order if you are implementing this in a real project. The Skills page explains the full skill authoring model, the Sandbox page explains workspace and runtime inspection, and the Subagents page explains delegated execution. If your context changes by user or tenant, pair this page with the session-context guide so your dynamic resolvers and authored runtime code use ctx.session.auth consistently.