Jev and internal tooling
Feature docs index · Configuration · Tools and safety model
magi-code uses TypeSafe Jev for bounded semantic judgments. Jev receives state plus a typed question and returns structured probabilities. It does not replace the main conversation model.
All Jev features require the shared beta opt-in and are disabled by default.
Set up Jev
- Create a TypeSafe API key.
- Export it before starting magi-code:
export TYPESAFE_API_KEY="your-key"
magi-code
- Open
/settings→ Beta features and enable Enable beta features. - On the Beta features page, open Jev. Enable Jev tooling at the top, then open the check groups below it to enable only the features you need. All seven groups require Jev tooling: Bash file tracking, Bash protection, compaction timing, completion checks, humanize protection, prompt injection protection, and skill suggestions.
- Save settings and restart magi-code.
All Jev runtime features require both beta: true and internal_tooling.jev.enabled: true, plus each feature's own enable setting. With beta off, the Beta features page shows an overview instead of Jev controls; Jev Search/Browse controls and the cache-reset action are hidden. No new Jev assessments, skill suggestions, completion checks, early compaction decisions, or Bash file inferences run. Saved Jev configuration, cache entries, and historical assessments remain intact; existing replay protection remains enforced. Active work retains its captured settings, so restart after saving to apply all changes.
Do not put the API key in settings.json. With beta enabled, enabling Jev without a non-empty TYPESAFE_API_KEY causes settings validation to fail. With beta off, Jev semantic validation and credential checks are skipped; JSON types remain checked.
Bash protection
Bash protection scores overall operational risk and four independent hazards: destructive effects, credential exposure, privilege or persistence, and untrusted code execution. Any dimension reaching the selected risk threshold or falling below its confidence threshold requires approval. State includes command text, working directory, workspace, and explicit unknowns; scripts and environment values are not inspected.
Protection levels, from least to most restrictive:
permissiverelaxed(default)balancedcautiousstrict
Mission Control shows Jev's score, confidence, probabilities, cache status, and decision on the tool card. Flagged commands open an approval prompt before execution.
Metadata records all dimensions and the returned model. The displayed score is the highest dimension score. Commands over 32 KiB cannot be assessed and use the configured failure policy.
API failure policy controls what happens when Jev cannot assess a command:
auto_approveallows execution. This is the default.auto_denyblocks execution.
Bash file tracking
Track Bash file activity adds inferred reads, writes, and edits to Session files. Enable it under /settings → Beta features → Jev → Bash file tracking, or set internal_tooling.jev.bash_file_tracking.enabled to true with beta and Jev enabled. Restart after saving.
The tracker extracts literal path candidates without executing them. Plain cat, head, and tail calls with literal filenames are handled locally. Other supported commands go to Jev in one batch. Entries carry an (inferred) label; a later dedicated-tool operation replaces the inferred label for that operation. Inferences survive session reloads but never grant hash_edit anchors, load directory instructions, or count as confirmed mutations.
Bash transcript cards show a separate Jev: file tracking row with inferred file counts, R/W/E counts, and minimum confidence among accepted classifications. Local-only reads say local. Empty results, skipped assessments, failures, and timeouts get an outcome instead of file counts. Disabled tracking adds no row.
Limits and omissions:
- At most 16 KiB of command text and 32 candidate paths per call. Jev must return both confidence and selected probability of at least
0.9. This starting threshold has not been calibrated against shell workloads. - One background assessment at a time across sessions and subagents. It runs alongside Bash; short commands may wait for the remainder of a two-second assessment budget. Busy workers, cancellation, API errors, and late answers omit tracking without changing command results; the completed card reports the outcome.
- Only commands exiting with code
0contribute entries. Paths must identify regular files after execution. Deleted files, directories, final symlinks, computed paths, glob expansion, working-directory changes, and unsupported control flow are omitted. A successful exit still does not prove every inferred operation happened. - No repository scan or file-content upload. The bounded command, including inline scripts or heredocs, and literal candidate paths may be sent to TypeSafe. Commands matching secret-redaction patterns are skipped. Redaction cannot detect every secret; leave tracking disabled for commands you cannot send to TypeSafe.
Tracking assessments bypass the shared Jev response cache and do not retry. Their results are saved as local tool-result metadata, not added to provider context.
Prose protection
Prose protection checks added or replacement documentation and code comments through write or hash_edit. It compares prepared before/after content under file mutation locks, before any writes. Deletion-only edits and unchanged files require no assessment. Prose presence and quality run together; quality matters only when prose is present. A style rejection tells the agent to load $writer-humanizer, revise, and retry.
Settings:
- Prose detection threshold decides when an edit counts as comments or documentation. Default:
0.7. - Humanized threshold sets the probability required to allow prose. Default:
0.65. - API failure policy either allows or denies the edit when assessment fails. Default:
auto_deny.
Both thresholds must be between 0 and 1.
Changed passages have a 32 KiB evidence budget, with bounded surrounding context. Budget, file-read, and API failures use the failure policy and are reported as unavailable assessments, not poor prose. Quoted examples, code samples, generated content, and necessary technical terms are excluded by the rubric; these judgments are not guaranteed.
Prompt injection protection
Prompt injection protection assesses selected untrusted tool outputs before they return to provider context. It checks for instructions aimed at an agent, injection likelihood, and potential impact.
Assessment defaults to observe-only. Enable Enforce decisions to apply the result:
annotateretains risky output with a warning.quarantinewithholds risky output from provider context. This is the default failure policy.
Choose a protection level from permissive, relaxed, balanced (default), cautious, or strict. Maximum assessed bytes bounds content sent for one assessment; default is 32 KiB. Protected tools defaults to web.
write, hash_edit, and magi_control results are trusted control output and bypass this assessment.
With enforcement enabled, output exceeding the assessment budget is withheld in full, without an API call. Observe-only mode preserves it unchanged. The annotate failure policy can forward unassessed output with a warning after an API failure; it does not override the oversized-output rule. escalate, like quarantine, withholds output; it does not open an approval prompt.
Raw results and execution effects are saved before assessment, with normal session redaction. Assessment records link to a unique result id; intervening background events do not change that link. Live delivery checks the assessed bytes and SHA-256; replay and compaction check full assessment coverage plus the redacted stored content's bytes and SHA-256. Enforced pending or incomplete records remain withheld. Output without recorded protection metadata replays unchanged with a visible warning, not an implied assessment. Start a new session if that history is untrusted. Existing summaries are not reassessed.
Only configured tools are covered. Semantic detection can miss adversarial instructions; permissions and source trust still apply independently.
Completion verification
Completion verification evaluates a proposed terminal response against bounded prior context and current-turn evidence. It checks request satisfaction, accurate disclosure of blockers, support for material claims, and scope. Each dimension selects pass, fail, insufficient_evidence, or not_applicable.
Assessment defaults to observe-only. With Enforce completion decisions enabled, supported failures trigger bounded corrective continuation or a limitation message. Low confidence or insufficient evidence produces unknown, accepts the response with a warning, and does not invent unfinished work. Service or evidence-budget failures produce unavailable. Only positive assessments report passed; diagnostics retain judgments, coverage, model, and cache status.
Settings:
- Completion threshold applies to both selected probability and confidence for each dimension. Default:
0.7. - Maximum evidence bytes bounds state sent to Jev. Default: 32 KiB.
- Maximum continuations caps verifier-triggered continuations per user turn. Default:
1. - Verifier failure policy accepts with a warning, or rejects with a warning when enforcement is enabled and assessment is unavailable. Default:
accept_with_warning. - Show Jev debug messages displays successful completion-check diagnostics. Default: off. Warnings remain visible.
The request and proposed response remain intact, or assessment fails explicitly. History and tool receipts keep complete JSON records, recent outcomes, and omission counts; long fields use marked excerpts. Missing evidence is uncertainty, not proof of failure. Confidence measures answer-distribution concentration, not correctness. Evaluate thresholds on representative workflows before relying on them.
Skill suggestion
Skill suggestion checks each prompt you type against your installed skills. When one clearly fits, it adds a short note after your prompt naming that skill. The agent can ignore the note if the skill does not fit what you asked for.
It is off by default. When off, requests are unchanged. The note is added as a user message, so the system prompt and prompt caching are not affected. It is saved with the session and restored when the session is reloaded.
No note is added for steering messages, automatic compaction, subagents, prompts that already name a skill with $name, or projects with fewer than two skills. If Jev fails, the prompt is sent without a note.
Settings:
- Gate threshold decides whether the prompt needs a skill at all. Default:
0.3. - Fit threshold sets how well the best skill must fit before it is suggested. Default:
0.3.
Each typed prompt waits for up to two Jev requests while this is enabled.
Compaction timing
Compaction timing can compact a session before the normal limit when you start unrelated work. Between the soft threshold and automatic compaction limit, Jev compares the incoming prompt against recent user/assistant history, excluding that prompt. It asks whether the request depends on prior task details; ambiguous follow-ups should not count as independent work.
It is off by default. The automatic compaction limit still applies, and a failed Jev request leaves compaction unchanged.
Settings:
- Soft threshold percent sets the share of the model's context window where checks begin. Range:
1to99. Default:60. - Threshold sets the probability of unrelated work required to compact early. Default:
0.7.
Compaction timing requires Jev to be enabled. It does not verify generated summaries.
Cache and data handling
Jev requests send the state needed for an enabled assessment to TypeSafe. This may include commands, proposed file edits, selected tool output, or bounded conversation evidence. Do not enable a feature for data you cannot send to TypeSafe.
Responses are cached by request hash under the magi-code cache directory in jev/; cache files use owner-only permissions on Unix. Save beta opt-in before opening /settings → Beta features → Jev → Reset Jev cache, then confirm deletion. This operation runs immediately, outside Save/Discard. A repeated request may use its cached response instead of calling TypeSafe again.
Requests pin jev-1.13.0; the request hash includes that model and the questions. Assessment metadata retains the returned model where available. Cache writes are best effort; network requests do not hold the cache lock. Reset prevents in-flight requests in the current process from restoring deleted entries. Cached clients allow one retry for HTTP 408, 429, or server errors within the original 15-second deadline. Background inference keeps its own deadline without retries. Response bodies are limited to 2 MiB.
Troubleshooting
TYPESAFE_API_KEY is required when Jev tooling is enabled: export the key in the environment that launches magi-code, then restart.- Unexpected blocks after an API error: check the feature's failure policy.
- Prompt injection findings do not change behavior: enable Enforce decisions; assessment alone is observe-only.
- Completion findings do not trigger correction: enable Enforce completion decisions.
- Stale-looking assessment: reset the Jev cache and retry.