# Optional Jev action judging

> Opt into TypeSafe Jev checks with your own key, review Noul and Score results, and keep existing Beam workflows independent.

Source: https://docs.agentbeam.com/agent-cli/jev

Jev is an optional remote judgment model from TypeSafe. To use a different model or your own decision service, see [Judge actions with any LLM or decision service](https://docs.agentbeam.com/agent-cli/decision-models). Beam can use it to review a proposed action through `beam jev judge`, or inside existing pre-tool hooks. Choose Noul, Score, or both; Beam combines the returned values in code.

> **Off by default.** Normal Beam setup does not enable Jev. Adding an API key alone does not enable checks. When you opt in, hook mode defaults to observation, which preserves the local decision even if Jev fails. Only an explicit enforcement setting lets this integration block eligible actions.

An enabled check sends selected, redacted action data to TypeSafe and may incur API charges. Redaction is heuristic. A passing judgment is not authorization, proof of safety, or evidence that the action executed.

## Check command availability

```sh
beam jev --help
beam jev status
```

The installed CLI must include the Jev integration. If `jev` is unknown, use a release containing the command or build the [Beam CLI source](https://github.com/whyashthakker/beam-cli):

```sh
git clone https://github.com/whyashthakker/beam-cli.git
cd beam-cli
npm ci
npm run build
node dist/cli.js jev --help
```

Use `node dist/cli.js` in place of `beam` for checks from that checkout, or install the reviewed build with `npm install --global .`. A repository push does not itself publish an npm release.

Explicit judgments do not need a running collector or dashboard enrollment. Automatic judgments require an installed [Beam agent hook](https://docs.agentbeam.com/agent-cli/agent-hooks); Jev configuration does not install hooks.

## Configure a key and observation mode

Supply `TYPESAFE_API_KEY` through the environment of the Beam process or a secret manager, then run:

```sh
beam jev configure --mode observe --primitive both
beam jev status
```

If your hook process does not inherit that environment, pipe the key from your secret manager into `beam jev configure --key-stdin`. Do not place a literal key in command arguments, committed files, shared logs, or chat.

The stored credential and settings live at `$BEAM_HOME/jev.json`, defaulting to `~/.beam/jev.json`. The file is written with mode `0600`; it is not an encrypted keychain. A nonempty `TYPESAFE_API_KEY` takes precedence over a stored key. `status` shows key presence without printing the credential.

Run configuration directly as the operator. Beam's self-protection blocks agent tool calls that attempt to configure or disable Jev or access its protected files.

| Configure option | Values and behavior |
| --- | --- |
| `--key-stdin` | Read a piped key and store it locally; interactive terminal input is rejected. |
| `--mode` | `observe` (default) or `enforce`; applies to hook checks. |
| `--primitive` | `both` (default), `noul`, or `score`. |
| `--model` | TypeSafe model ID; defaults to `jev-latest`. |

Each `configure` call enables the integration and applies the option defaults for omitted flags. Include your intended mode and primitive when rotating a key or changing the model. With no `--key-stdin`, configuration reuses the stored key or requires an environment key.

## Judge a proposed action

Create `action.json` with a nonempty action string or object and an optional context string:

```json
{
  "action": { "tool": "Bash", "command": "git diff --stat" },
  "context": "Inspect workspace changes without modifying files."
}
```

Use context grounded in the actual task. The file accepts only `action` and optional `context`, with a 32 KB limit.

```sh
beam jev judge action.json --dry-run
beam jev judge action.json
```

Dry-run prints the redacted state, model, and questions locally. It does not need a key or make an API call, and it does not evaluate the action. A valid existing configuration is still required if a configuration file is present.

A real judgment requires enabled settings and a usable key. It prints a JSON result with `verdict` and `reason`; successful evaluations also include the returned model and selected primitive values. It never executes the action.

| Exit status | Meaning |
| --- | --- |
| `0` | All selected checks passed (`allow`). |
| `2` | The result requires review or denies the action. |
| `1` | The integration is disabled, a key is missing, or input/configuration/evaluation failed. |

These exit statuses also apply in observation mode: hook mode does not convert an explicit negative judgment into a successful command. Treat nonzero results deliberately in scripts. Recheck materially changed arguments or targets rather than applying an earlier judgment to a different action.

## Interpret Noul and Score

Noul asks two independent yes/no questions: whether the action discloses credentials or private data externally, and whether it irreversibly deletes or overwrites existing user data. Each value ranges from 0 to 1. A value near 0.5 represents uncertainty about that statement, not medium damage. There is no separate Noul confidence field.

Score evaluates potential damage using four descriptive levels. Their positions run from 0 to 3: information access, reversible local changes, costly changes to shared systems or important data, and critical damage. The result can fall between levels. Read its `value`, `probabilities`, and separate `confidence` together.

| Check | Pass | Deny | Review |
| --- | --- | --- | --- |
| Noul | Both values at most 0.2 | Either value at least 0.8 | Otherwise |
| Score | Value at most 0.5 and confidence at least 0.7 | Value at least 2 | Otherwise |
| Both | All selected checks pass | Any check denies | Any remaining uncertainty |

These are Beam's fixed initial thresholds, not provider-certified safety levels or measurements on your workload. There are no threshold flags in the current command. A reversible write can still need review under this rubric. Observe representative actions before choosing enforcement, and investigate disagreements rather than retrying until a result passes.

## Choose hook behavior

Local policy and self-protection run before Jev. A local deny, ask, or redact decision skips Jev and remains in force. Eligible pre-tool events that would otherwise allow or warn can reach the optional check. Prompt submission and post-tool events skip it.

| State | Hook behavior |
| --- | --- |
| Disabled or never configured | No Jev request; existing local behavior continues. |
| Observe | Report the judgment on stderr; preserve the local decision, including on request failure. |
| Enforce with valid enabled settings | Allow a passing judgment to continue through the existing decision; block `review`, `deny`, and evaluation errors. |
| Invalid or unreadable configuration | Report an error and skip the optional check; preserve local policy. Repair settings before relying on Jev coverage. |

Enable enforcement only when you intend model uncertainty or a provider outage to stop eligible actions:

```sh
beam jev configure --mode enforce --primitive both
```

The client must invoke the hook and honor its response. This integration does not intercept every process or MCP transport. Hook checks do not automatically receive the user's task or conversation context, so they cannot establish whether the user authorized the action. Keep [workspace policy](https://docs.agentbeam.com/agent-cli/policies), host permissions, and model judgment separate.

## Understand data and request limits

Automatic requests include agent, tool, tool input, and command. They do not automatically open referenced files, load transcripts, or attach process environment values. Tool arguments themselves can contain private source code or data; redaction does not make those contents public.

Before sending the request, Beam redacts recognized credential patterns, sensitive field names, the effective Jev key, and applicable local policy custom detectors for hook checks. Explicit judgments use the supplied action/context and built-in redaction. Inspect dry-run output and minimize sensitive input before sending it.

Requests use `https://api.typesafe.ai/v1/systemone`, reject redirects, time out after two seconds, and are not automatically retried. Input is limited to 32 KB and the response body to 64 KB. Invalid answer types, out-of-range values, missing answers, and inconsistent Score distributions produce errors. Raw provider error bodies are not printed.

These requests are separate from workspace telemetry. `beam logout` is not the Jev off switch; use the command below. Offline `beam scan` remains offline. See [data and privacy](https://docs.agentbeam.com/agent-cli/data-privacy) for the other network boundaries.

## Disable checks or resolve a problem

```sh
beam jev disable
beam jev status
```

Disabling removes the stored key and resets Jev settings to disabled defaults. It does not revoke the key at TypeSafe or unset externally managed environment variables. Existing Beam local policy continues independently.

| Symptom | What to check |
| --- | --- |
| Key configured, but no checks run | `status` must show `enabled: true`; a key alone is insufficient. |
| Works in a terminal, not in hooks | Check the hook process's executable, environment, and `BEAM_HOME`; use a stored key if appropriate. |
| HTTP 401 or 429 | Check credential validity or quota with TypeSafe; do not repeatedly retry a denied action. |
| Timeout or invalid response | The action is unverified; observe preserves local behavior, while valid enabled enforcement blocks. |
| Invalid configuration | Repair with `configure`, or use `disable` to reset it. Until repaired, Jev is skipped. |
| A local block persists despite a passing explicit check | Expected: local policy takes precedence and the explicit command grants no permission. |

## Use the packaged skill

The `jev-action-judge` skill is included in the Beam CLI `Skills` distribution. Follow the [security skills guide](https://docs.agentbeam.com/agent-cli/security-skills) to review and install it into your client's discovery directory. It helps prepare bounded inputs and interpret results. Loading the skill does not enable Jev or authorize private-data transfer.

Implementation tests cover synthetic inputs, mocked provider transport, redaction, threshold decisions, policy precedence, and hook response output. They do not establish live provider accuracy, adversarial robustness, or successful native-agent enforcement on your machine.

Read the [Beam walkthrough](https://agentbeam.com/blog/beam-cli-jev-action-judging) or explore the [applied Jev use case](https://github.com/whyashthakker/awesome-jev-use-cases/blob/main/docs/beam-cli-action-judging.md) for additional examples.