jev-use

# Jev Use

Overview

Splits an agent loop by whether a step must produce text. Steps that only produce a decision - is the build done, which of these 30 elements to click, is this shell command safe, keep or drop this message - are handed to Jev, TypeSafe's judgment model, which answers typed yes/no, pick-one and score questions about a state in one forward pass instead of generating tokens. The agent stays the planner and the writer; Jev takes the quick calls.

Everything Jev should not decide comes back under a typed escalation contract, so the handoff is explicit in both directions rather than a guess.

When to Use This Skill

- Use when the next step is a judgment over context you already have ("did X succeed?", "which option?", "how bad is this?") rather than something to write.

- Use when you are about to check the same state several times in a row, so the questions can be batched into one call.

- Use when you want a risk check on a proposed tool call before running it.

- Do not use when the step must produce new content - text, code, free-form tool arguments - or when the options cannot be enumerated. Those are structurally the model's own work.

How It Works

Step 1: Install and wire the server

npx -y jev-use install

`install` wires the stdio MCP server into Claude Code, Codex and pi through each harness's own CLI - whichever it finds - and `npx -y jev-use doctor` verifies backend resolution with one live round trip. Set a provider credential in the environment the agent runs in (`TYPESAFE_API_KEY`, `OPENROUTER_API_KEY` or `AI_GATEWAY_API_KEY`, auto-detected in that order), or set `JEV_BACKEND=mock` to run keyless with no network calls.

Step 2: Route each step before working on it

| The step is... | Route |

| ----------------------------------------------------------- | -------------------- |

| Producing new content: text, code, free-form tool args | You |

| A judgment, but the options can't be enumerated | You |

| A yes/no or "did it work?" over context you already have | `jev_judge` (`noul`) |

| Picking the next action from options you can list | `jev_judge` (`choice`) |

| Rating quality/severity/urgency on levels you can describe | `jev_judge` (`score`) |

| "Is this action safe to run?" before something risky | `jev_gate` |

Step 3: Batch every question about one state into one call

`jev_judge` takes a single `state` string plus a `questions[]` array. Latency is flat in question count, and the cost of the shared state amortizes across the batch, so 13 batched questions cost far less than 13 separate calls. Never call it once per question.

Step 4: Honor the escalation contract

Each verdict carries `{id, type, answer, confidence, escalate}`, plus `reason` and `hint` exactly when `escalate` is true. An escalated verdict is handed back to you - it is a normal verdict with a hint, never an exception:

| `reason` | When | What it means for you |

| ------------- | --------- | ---------------------------------------------------------------- |

| `writing` | pre-call | The step must produce new text or code - structurally yours. |

| `open_ended` | pre-call | Not expressible as `noul`/`choice`/`score`; nothing to enumerate. |

| `oversized` | pre-call | The state exceeds the size limit - shrink it or take the questions over. |

| `unsure` | post-call | The answer is too flat to act on; it stays in `answer` as a prior. |

| `unreachable` | on failure| Jev could not be reached - proceed as if it did not exist. |

The two pre-call reasons come from a deterministic router, so a step that was never Jev's does not spend a request.

Examples

Example 1: One state, three questions, one call

// jev_judge input
{
  "state": "CI run #142: build ok, 214 t