Runtime Guidance and Project Instructions

VT Code has two distinct prompt sources:

Source	Loaded from	Purpose	Trust boundary
Compiled runtime guidance	crates/codegen/vtcode-core/src/prompts/runtime_guidance.rs	Small, universal user-facing behavior included in Default, Minimal, Lightweight, and Specialized profiles	Part of the application runtime
Project instruction map	User/workspace AGENTS.md, CLAUDE.md, and .vtcode/rules/	Project conventions, local architecture, and maintainer workflows	User-controlled context, never a security boundary

The compiled section is deterministic, cached with the static profile, and kept below its approximate 256-token cap. It must not read, embed, or generate content from repository instruction files. Profile-specific operating details remain in the prompt builder; correctness-critical behavior belongs in runtime policy, schemas, tests, or lints.

Continuity and long-running work

The runtime keeps prompt additions small and cache-stable while preserving the newest working context. Automatic compaction uses a non-configurable continuity tail target of approximately 20,000 estimated tokens. It retains complete user/assistant/tool protocol groups verbatim, removes an incomplete trailing tool call, and summarizes only the older prefix. Unless an explicit harness threshold is configured, the effective hard threshold is based on the smaller of the provider's hard context capacity and the 160,000-token default session budget; the trigger is 90% of that ceiling. Explicit thresholds remain capped by the provider capacity. A soft threshold at 90% of the effective hard threshold marks compaction pending for the next outer turn boundary; the hard threshold compacts before the next model request. Provider-native compaction results are normalized through the same tail rules, with local fallback when the provider does not return a usable tail.

Long-running command sessions have an explicit wait action. A wait deadline returns a bounded in-progress result without killing the process, so the model does not need to spend repeated turns issuing 30-second polls. Full command output is written to the tool-output spool; responses expose only a bounded preview and its spool metadata. A spool reference is emitted only after its file is open and has not reported a write failure; spool_complete distinguishes an active readable partial snapshot from a fully drained output stream. Exited sessions with an unfinished spool retain the session and defer the reference until a later wait can safely observe the complete file.

Interactive follow-ups are durable steering intents. Each queued intent has a UUID, the session envelope stores at most 16 pending intents and a 64-ID applied window, and the intent is acknowledged only after its tagged user message is durably checkpointed. Recovery compares IDs in the envelope with tagged history, not just instruction text, so duplicate text remains meaningful.

Even when .vtcode/prompts/system.md replaces the static base prompt, the compiled section is reattached after prompt layers are resolved. This keeps the universal baseline present without treating workspace prompt content as a security boundary.

The dynamic instruction pipeline remains enabled by default. It discovers user and workspace sources in precedence order, loads nested files for the active directory, applies path-scoped rules and exclusions, and appends the resulting project appendix separately from the compiled base prompt. AGENTS.md files therefore remain useful maintainer maps without becoming an implicit source of universal VT Code behavior.

When changing this boundary, run:

cargo nextest run -p vtcode-core
cargo check --locked
./scripts/check-dev.sh --changed

Release archives are independently allowlisted to contain the binary, man page, and shell completions only. They must never include AGENTS.md or other workspace guidance.