pi-jev

Why Choose pi-jev?

pi-jev is useful when the missing layer in a Pi workflow is not another coding model, but a lightweight semantic judge. Traditional safety hooks are good at recognizing known command patterns such as destructive Git operations or obvious filesystem deletion. pi-jev instead asks Jev narrow questions about the meaning and scope of an action, then lets ordinary code decide what to do with the returned probabilities.

That distinction matters for operations that are syntactically ordinary but contextually suspicious. A write to a system configuration file may be perfectly valid in one task and clearly outside scope in another. The extension is designed to make that kind of judgment explicit rather than forcing the main coding model to reason about its own action and then trust its own conclusion.

It is also important to treat pi-jev as a guardrail layer, not a sandbox. Pi itself runs with the permissions of the local user, and its documentation recommends containers, VMs, micro-VMs, or other OS-level isolation for untrusted repositories or unattended execution. pi-jev can add an additional decision point, but it does not create a privilege boundary.

Core Workflow

The practical workflow is a two-stage review around selected Pi tool activity. Before a mutating action executes, pi-jev builds a compact state from the current task context and asks Jev separate questions about risk dimensions. The answers remain independent numeric signals, while the extension owns the threshold logic. This separation is useful because the policy can be changed without asking the model to invent a new explanation or action.

After a shell command finishes, a second judgment can examine the returned text. This is where the extension can reason about information that did not exist before execution, such as whether output appears to contain a credential or whether a failure looks transient, environmental, permission-related, invocation-related, or code-related.

The jev_ask path is broader than safety. It gives the active Pi agent a way to delegate narrow semantic decisions to Jev when the desired result is a probability, category, or score rather than a generated paragraph. In practice, that is most useful when downstream code needs to branch on the answer.

Use Cases

The strongest fit is a Pi setup where deterministic rules catch obvious hazards but there is still a gap around intent and task scope. Examples include deciding whether an otherwise normal command sends local data away from the machine, whether a proposed edit reaches beyond the user's request, or whether a tool result should change the next recovery step.

Another useful pattern is agent-side classification. A Pi extension or project workflow can use jev_ask to label an error, judge whether evidence is relevant, or score a result against a small rubric. This avoids spending a general coding model turn on a decision that ultimately needs to become an if statement.

The approach is less compelling for deterministic policies. If a command must never run, a direct rule or sandbox policy is easier to audit than a probabilistic threshold. Semantic judgment is most valuable where the boundary depends on context that a string matcher cannot reliably encode.

Comparison to Alternatives

Compared with rule-based Pi guardrails such as Pi Safety, CC Safety Net, or AST-oriented command filters, pi-jev trades deterministic matching for semantic interpretation. That can cover context-dependent cases that do not have a stable command signature, but it also introduces network latency, external API dependence, and threshold tuning.

Pi Permission Gate is a closer comparison because it also uses model-assisted risk classification before execution. The main difference is the decision interface: pi-jev is built around TypeSafe Jev's typed probability-oriented outputs and fixed decision dimensions, whereas a general LLM-based gate can be more expressive but may require more prompt and output handling.

Neither approach should be confused with containment. For repositories or automation that may be hostile, an OS-level sandbox remains the stronger control because it limits what the process can actually access even when the model or guardrail makes a bad decision.

Best Configuration

A sensible rollout is to keep the gate in shadow mode while collecting examples from the actual repositories and commands that matter to the user. The bundled thresholds were smoke-tested by the author, but the README explicitly does not present the pre-call calibration as a labeled production evaluation set. Real projects can have very different definitions of destructive, out-of-scope, or acceptable data egress.

For privacy-sensitive projects, reducing the set of judged tools can be more important than changing model thresholds. Restricting the gate to bash avoids sending write and edit file bodies through that pre-call path. Lowering argument and output character limits further reduces the amount of context sent externally, at the cost of giving Jev less evidence.

For unattended or RPC-driven sessions, review the headless behavior before relying on enforcement. Interactive confirmation cannot appear in headless mode, so a deployment that expects a hard stop needs to explicitly configure the non-UI blocking behavior and test it under the same execution mode used in production.

Migration Notes

When replacing a deterministic guardrail, do not immediately remove the old policy layer. Run pi-jev in shadow mode first and compare which actions each system flags. Deterministic rules are usually better for non-negotiable bans, while semantic judgments are better for ambiguous intent and scope.

If another extension already hooks the same Pi tool calls, test the combined behavior for duplicate prompts, conflicting decisions, and ordering effects. The cleanest setup is usually to assign each layer a distinct responsibility: hard rules for absolute prohibitions, pi-jev for contextual judgment, and a sandbox for privilege isolation.

Because pi-jev depends on an external Jev endpoint, migration planning should also cover API availability. Its documented default behavior is fail-open on request errors, so workflows that require guaranteed blocking should not assume the remote judgment service is itself the security boundary.