Optional Jev action judging

Jev is an optional remote judgment model from TypeSafe. 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.

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

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:

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; 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:

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.

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:

{
  "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.

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.

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.

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.

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

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, 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 for the other network boundaries.

Disable checks or resolve a problem

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.

Use the packaged skill

The jev-action-judge skill is included in the Beam CLI Skills distribution. Follow the security skills guide 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 or explore the applied Jev use case for additional examples.