The Beam CLI Jev integration adds an optional model judgment to a proposed agent action. You supply a TypeSafe key, choose Noul, Score or both, and decide whether the result is informational or a reason to stop an eligible tool call. Jev starts disabled. A key in your environment does not switch it on.
This is useful when you want a semantic second look at a command or tool call alongside Beam's existing local rules. The distinction matters: a rule can match a known path or command, while a model can assess the action description against a question. Both have limits. A favorable judgment does not grant permission, establish that an action completed, or prove the action safe.
| What changes for my workflow? | Direct answer |
|---|---|
| Must I create a TypeSafe account? | Only if you choose to use Jev. |
| Does normal Beam setup enable it? | No. Setup only points to the optional command. |
| What happens when I first configure it? | Hook mode defaults to observation. |
| Does action data leave the machine? | Yes, when an enabled check calls TypeSafe. |
| Can it replace a local block with an allow? | No. Local blocking and approval decisions take precedence. |
| Can I inspect a request before sending it? | Yes, with the explicit command's --dry-run flag. |
| Does this require a third-party Jev hook CLI? | No. Beam calls the TypeSafe HTTP API through its own integration. |
How do I get the Beam CLI Jev integration?
The implementation lives in the Beam CLI repository. Check your installed version with beam jev --help. A push to the repository does not publish a new npm package; if your installed package does not have the command, install the implementation from source:
git clone https://github.com/whyashthakker/beam-cli.git
cd beam-cli
npm ci
npm run build
npm install --global .
beam jev --help
You can use the explicit judgment command without enrolling a dashboard device or starting a collector. Automatic checks use existing Beam pre-tool hooks. If those hooks are not installed for your agent, configuring Jev does not install them. Use your normal Beam setup procedure and inspect beam agent list when you want hook integration.
Our earlier Jev agent-hook security article discussed discovery of independent Jev CLIs. That remains a separate feature. The direct API integration does not modify another project's Jev configuration or claim that every external wrapper follows the same contract.
How do I add my key without putting it in a command?
Supply TYPESAFE_API_KEY through your shell environment or secret manager. Once it is available to the Beam process, run:
beam jev configure --mode observe --primitive both
beam jev status
For persistent hook processes that do not inherit your shell environment, pipe the key from your secret manager into beam jev configure --key-stdin. This reads the credential through standard input and stores it in ~/.beam/jev.json, or under BEAM_HOME if you use a custom home. The file is written with mode 0600. It is a local credential file, not an operating-system keychain or encrypted vault.
Avoid putting the literal credential into an argument or a shell command saved in history. beam jev status reports whether a key is configured without displaying its value. An environment key takes precedence over a stored key, which is useful for managed sessions but also explains why replacing a stored key might not change the credential an already configured shell uses.
Run configuration yourself in a terminal. Beam's agent self-protection treats changes to its Jev settings as protected operations. The accompanying skill tells an agent to respect that boundary, rather than finding another way to change the settings. Our agent permission review guide explains why configuration ownership matters independently of model judgments.
How do I review one proposed action?
Create a JSON file with a nonempty action string or object and an optional context string. Keep the context factual and specific to the user's actual task:
{
"action": {
"tool": "Bash",
"command": "git diff --stat"
},
"context": "Inspect the current workspace changes without modifying files."
}
Then inspect the outbound representation and request a judgment:
beam jev judge action.json --dry-run
beam jev judge action.json
The first command prints redacted state and the selected questions locally. It performs no API request, needs no key and does not evaluate the action. Review that preview before sending private action data. The second command needs an enabled configuration and a usable key; it prints a structured result without running the proposed command.
Exit status makes the explicit command usable inside another workflow: 0 means the selected checks passed, 2 means review or deny, and 1 means an error. A caller should handle all three. Do not turn an API error into approval merely because no high-risk score was returned. Do not execute a different command after checking a benign description: the judgment belongs to the submitted action and its evidence.
The explicit command keeps these exit semantics in observation mode too. Observation controls automatic hooks; it does not turn an explicit negative judgment into a successful command. This separation lets a human experiment with checks while the agent's ordinary workflow continues unchanged.
What do Noul and Score actually measure?
TypeSafe's Noul primitive produces a yes/no probability. Beam asks two independent questions: whether the action discloses credentials or private data to an external recipient, and whether it irreversibly deletes or overwrites existing user data. A value near the middle indicates uncertainty about the proposition. It is not a medium-severity category, and Noul has no separate confidence field.
The Score primitive uses an ordered rubric. Beam defines four descriptions covering information access, reversible local changes, costly changes to shared systems or important data, and critical damage. Their positions run from 0 to 3. A returned value may fall between positions, and Beam retains the probability distribution and confidence alongside it.
Beam combines these answers using explicit initial thresholds:
| Selected check | Pass | Deny | Review |
|---|---|---|---|
| Noul | Both values at most 0.2 | Either value at least 0.8 | Values between those boundaries |
| Score | Value at most 0.5 and confidence at least 0.7 | Value at least 2 | Other valid results |
| Both | Every selected check passes | Any selected check denies | Any remaining review result |
These are implementation defaults, not a measured operating point on your organization's action history. In particular, a reversible write can reasonably land in review under this rubric. Start by observing the results on representative benign actions, uncertain actions and actions your policy clearly forbids. Record disagreements instead of changing the request repeatedly until the model approves it.
The API request follows TypeSafe's documented System One HTTP contract: a model, state and map of typed questions. Beam validates the expected answer types and numeric ranges before using them. For Score, it also checks the distribution's total and consistency with the returned weighted value. Malformed or missing answers are errors, never a synthetic passing score.
What happens inside an existing Beam hook?
The hook first makes its local policy decision and applies existing self-protection checks. Local deny, ask and redact decisions skip Jev. Only eligible pre-tool events that would otherwise allow or warn proceed to the optional model check. Prompt submission and post-tool events skip it.
In observation mode, Beam prints the judgment on stderr and keeps the local decision. A rejected API key, timeout, quota response, invalid answer or unfavorable judgment does not add a block. No configured Jev integration means no Jev request. These boundaries keep optional evaluation from becoming a prerequisite for everyday Beam use.
When the operator deliberately selects enforcement, an evaluated result of review, deny or error becomes a hook denial:
beam jev configure --mode enforce --primitive both
Enforcement applies only while valid enabled settings are available. Invalid configuration reports an error and skips this optional integration, preserving local policy. That is a deliberate compatibility boundary: malformed settings mean Jev coverage is unavailable, not that protection is working. Repair the configuration before relying on it. The monitoring versus blocking guide explains why an observed judgment and an enforced decision are different claims.
The underlying client must invoke the hook and honor its response. This addition does not intercept arbitrary terminal commands, uninstrumented programs or every MCP transport. Beam's MCP security review guide covers the separate question of what a server and its tools can do.
What data leaves the machine, and what happens on failure?
Automatic requests include the agent, tool, tool input and command. They do not automatically open referenced files, load conversation transcripts, attach the user's task or serialize the process environment. However, tool arguments can already contain a source-code patch, customer text or another sensitive value. Selecting fields limits collection; it does not make their contents public.
Before the request, Beam redacts known credential patterns, sensitive field names, the effective Jev key and applicable local policy custom detectors. That filtering is best effort. Use small, non-sensitive action summaries for explicit checks and inspect the dry-run output. Our application and supply-chain security guide discusses credential and data boundaries in the surrounding tools.
Each request goes to a fixed HTTPS endpoint with a two-second timeout, no automatic retries and redirects rejected. Inputs are limited to 32 KB; response bodies are limited to 64 KB. Oversized data is rejected rather than silently shortened into a potentially misleading action. Provider error bodies are not copied into the judgment output. These are operational bounds, not a claim that the provider always responds within two seconds.
To stop remote checks and remove the locally stored credential:
beam jev disable
This does not revoke the key at TypeSafe or unset environment variables managed elsewhere. Normal Beam local policy and offline beam scan continue independently.
How does the skill fit into this workflow?
The bundled jev-action-judge skill helps an agent prepare a bounded action, inspect the request, interpret the selected primitive and distinguish a model result from permission to execute. Loading the skill does not configure the integration. Installing it does not authorize uploading private evidence.
Use the Beam skills installation guide to copy a reviewed skill into your client's discovery directory. Its workflow preserves the operator's chosen mode, avoids credentials in chat or command arguments, and treats uncertainty as a review outcome rather than a reason to retry until approval.
The Awesome Jev use-case collection links this integration as an applied action-review example alongside its visual demonstrations. Those demonstrations use labeled fixtures in preview mode. Neither fixture agreement nor this integration's mocked transport tests establish real provider quality.
Automated validation here covers configuration, request shapes, redaction, bounded responses, threshold decisions, local-policy precedence and vendor-specific hook denial output. Live TypeSafe behavior, native agent execution and accuracy on adversarial actions remain separate validation tasks. Keep those claims separate when deciding whether to enable enforcement for your own work.
Implementation and documentation checked on September 20, 2026. Repository availability, installed package versions, provider models and agent hook behavior can change independently.