@bobobowis/jev-kit 0.1.0 → 0.2.0

package/README.md

@@ -78,6 +78,46 @@ const r = await askFileBool("src/billing.ts", "Does this file round money anywhe
 console.log(r.answer, r.noul);   // your script, or the agent, never loads the file
 ```
 
+## Recipes: the lab's levels 1 to 5
+
+The package doesn't export the use cases from levels 1 to 5: they are examples with the lab's own
+categories built in, so copy the one you need. Each one is a single short file that uses only what
+the package exports. Copy it into your project, point its imports at the package, and change the
+options and criteria to your own:
+
+```ts
+// In the lab
+import { jev } from "../../core/client.ts";
+import { noul } from "../../core/helpers.ts";
+import type { NoulAnswer } from "../../core/types.ts";
+import { CONFIDENCE } from "./confidence.ts";          // or { normalized } from "./normalize.ts"
+
+// In your project
+import { jev, noul, type NoulAnswer } from "@bobobowis/jev-kit";
+import { CONFIDENCE, normalized } from "@bobobowis/jev-kit/policy";
+```
+
+| Level | Recipe | Use it for |
+|---|---|---|
+| 1 Single decisions | [`injectionGate`](https://github.com/bobobowis/ten-levels-of-jev/blob/main/apps/ten-levels/src/levels/level01/injection-gate.ts) | A prompt injection gate in front of anything that sends user text to an LLM |
+| | [`urgentGate`](https://github.com/bobobowis/ten-levels-of-jev/blob/main/apps/ten-levels/src/levels/level01/urgency-gate.ts) | Pinging a human only when a message is urgent, with your threshold |
+| | [`classifyTicket`](https://github.com/bobobowis/ten-levels-of-jev/blob/main/apps/ten-levels/src/levels/level01/ticket-classifier.ts) | Routing a ticket to one department, with its confidence |
+| 2 Multiple choice | [`triageTicket`](https://github.com/bobobowis/ten-levels-of-jev/blob/main/apps/ten-levels/src/levels/level02/support-triage.ts) | Route, priority, and a human handoff for a support ticket in one call |
+| | [`screenResume`](https://github.com/bobobowis/ten-levels-of-jev/blob/main/apps/ten-levels/src/levels/level02/resume-screening.ts) | Seniority and fit of a resume against a job description |
+| | [`qualifySponsorForm`](https://github.com/bobobowis/ten-levels-of-jev/blob/main/apps/ten-levels/src/levels/level02/sponsor-qualification.ts) | Qualifying inbound forms or leads by intent and product |
+| 3 Composite scoring | [`ticketPriority`](https://github.com/bobobowis/ten-levels-of-jev/blob/main/apps/ten-levels/src/levels/level03/ticket-priority.ts) | A weighted priority from several scores |
+| | [`codeReviewRisk`](https://github.com/bobobowis/ten-levels-of-jev/blob/main/apps/ten-levels/src/levels/level03/code-review-risk.ts) | The risk of a diff in CI, before a human reviews it |
+| | [`ideaVerdict`](https://github.com/bobobowis/ten-levels-of-jev/blob/main/apps/ten-levels/src/levels/level03/idea-verdict.ts) | Kill, fix, or ship on a pitch or proposal |
+| 4 Confidence gating | [`gateShellCommand`](https://github.com/bobobowis/ten-levels-of-jev/blob/main/apps/ten-levels/src/levels/level04/shell-command-gate.ts) | Allowing a shell command, or asking a human when Jev is unsure |
+| | [`routeAccountAction`](https://github.com/bobobowis/ten-levels-of-jev/blob/main/apps/ten-levels/src/levels/level04/account-actions.ts) | Running an account action on its own, asking for a confirmation before a transfer, and handing off to a human when unsure |
+| | [`checkCitation`](https://github.com/bobobowis/ten-levels-of-jev/blob/main/apps/ten-levels/src/levels/level04/citation-check.ts) | Checking that a quote supports a claim, for RAG answers |
+| 5 Routing | [`routeIntent`](https://github.com/bobobowis/ten-levels-of-jev/blob/main/apps/ten-levels/src/levels/level05/intent-router.ts) | Sending a message to the right handler, and to reasoning only when it needs it |
+| | [`routeModel`](https://github.com/bobobowis/ten-levels-of-jev/blob/main/apps/ten-levels/src/levels/level05/model-router.ts) | The cheapest model and the effort a task needs |
+| | [`routeAgent`](https://github.com/bobobowis/ten-levels-of-jev/blob/main/apps/ten-levels/src/levels/level05/agent-router.ts) | Picking which coding agent takes a task |
+
+Levels 6 to 10 need no copying: they ship as `/guards`, `/compact`, `/files`, and `/tools`, and
+behind `jev guard`, `jev setup`, and `jev mcp`.
+
 ## The jev command
 
 Results go to stdout as JSON, diagnostics to stderr, so stdout pipes straight into `jq`. Every
@@ -146,6 +186,7 @@ else alone:
 jev setup --harness claude --guards bash,write,result --tools ask_jev    # .claude/settings.json, .mcp.json
 jev setup --harness codex  --guards bash,write --compact                  # a marked block in .codex/config.toml
 jev setup --harness claude --level 6 --dry-run                            # print, write nothing
+jev setup --harness claude --guards bash,write,mcp --ask --allow-read-only   # the Level 4 ladder, below
 ```
 
 Each run sets the whole selection and replaces only what an earlier run wrote. A settings file that
@@ -204,6 +245,36 @@ echo '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command"
   | jev hook --harness claude --event PreToolUse --guards bash
 ```
 
+### Ask, don't guess: the Level 4 ladder (Claude Code)
+
+A block or a pass is two answers. Level 4 adds the third: when Jev is unsure, a human decides. Two
+flags put it on the bash gate and the MCP gate, and both work on their own:
+
+- **`--ask`**: short of a block, the bash gate asks you instead of passing when Jev is unsure (effect
+  confidence under 0.5), picks irreversible below the block line, leans destructive (0.4 or more),
+  or sees the command reach outside the machine (publish, deploy, push, `curl … | sh`).
+- **`--allow-read-only`**: a command or MCP call Jev is sure only reads (above 0.9, no destructive
+  or outward lean) is approved, so Claude Code doesn't prompt you for `git status` or a `SELECT`.
+
+The **`mcp` guard** runs the same ladder before any tool from another MCP server (`mcp__<server>__*`;
+Jev's own tools are skipped). Destructive, outward, and unsure calls ask you; it never denies,
+because you connected the server, so you decide. It is opt-in: `--level 6` and `jev hook` without
+`--guards` leave it off.
+
+What it did on live Jev, with both flags:
+
+| Call | Verdict |
+|---|---|
+| `git status`, `grep -rn TODO`, `Neon run_sql SELECT count(*)`, `clerk list_users` | approved: read only (1.00) |
+| `pnpm test`, `git commit`, `mv`, `Neon create_branch`, `Neon run_sql UPDATE ...` | your usual permissions |
+| `npm publish`, `kubectl apply`, `git push`, `curl … \| sh`, `slack send_message` | asks: reaches outside |
+| `git rebase main`, `psql -f migrate.sql` | asks: Jev is unsure (0.27, 0.48) |
+| `Neon run_sql DROP TABLE`, `Neon delete_branch` | asks: destructive |
+| `git push --force`, `git reset --hard`, `rm -rf` | denied, as without the flags |
+
+Codex hooks read only deny, so there the flags and the `mcp` guard would do nothing; `jev setup`
+refuses them for Codex rather than write hooks that don't act.
+
 Hooks fail open: a missing key, a Jev error, or a timeout (8 s by default) allows the action and
 reports an error. They never exit 2. The contracts they rely on are in
 [docs/NOTES-claude.md](docs/NOTES-claude.md) and [docs/NOTES-codex.md](docs/NOTES-codex.md).

package/dist/cli/hook.js

@@ -4,7 +4,7 @@
  * action. Never exits 2, which both harnesses read as "block".
  */
 import { parseArgs } from "node:util";
-import { ALL_GUARDS, runHarnessHook, HOOK_LINES } from "../hooks/index.js";
+import { ALL_GUARDS, LEVEL6_GUARDS, runHarnessHook, HOOK_LINES } from "../hooks/index.js";
 import { deciderFor, list, readAll, withDeadline } from "./common.js";
 export const HOOK_HELP = `Usage: jev hook --harness claude|codex --event <HookEvent> [options]
 
@@ -13,7 +13,9 @@ Reads the hook payload on stdin and answers on stdout. Exit 0 always, except 1 f
 Options:
   --harness <name>     claude or codex
   --event <name>       PreToolUse, PostToolUse, UserPromptSubmit, Stop, PreCompact
-  --guards <list>      bash,write,result (default: all)
+  --guards <list>      bash,write,result,mcp (default: bash,write,result)
+  --ask                the bash and mcp gates ask you when Jev is unsure or leans destructive (Claude Code)
+  --allow-read-only    the bash and mcp gates approve what Jev is sure only reads (Claude Code)
   --compact            run the Level 7 advisor on UserPromptSubmit and Stop
   --lines <n,n,n>      notice, recommend, request lines in context tokens (default ${HOOK_LINES.notice},${HOOK_LINES.recommend},${HOOK_LINES.request})
   --window <tokens>    the model's context window, for percentages
@@ -27,6 +29,7 @@ export async function hook(argv, io) {
             args: argv, strict: true,
             options: {
                 harness: { type: "string" }, event: { type: "string" }, guards: { type: "string" }, compact: { type: "boolean" },
+                ask: { type: "boolean" }, "allow-read-only": { type: "boolean" },
                 lines: { type: "string" }, window: { type: "string" }, "timeout-ms": { type: "string" }, mock: { type: "boolean" }, help: { type: "boolean", short: "h" },
             },
         }));
@@ -48,7 +51,7 @@ export async function hook(argv, io) {
         io.stderr.write(`jev hook: --event is required\n`);
         return 1;
     }
-    const guards = values.guards ? list(values.guards) : ALL_GUARDS;
+    const guards = values.guards ? list(values.guards) : LEVEL6_GUARDS;
     const unknown = guards.filter((g) => !ALL_GUARDS.includes(g));
     if (unknown.length) {
         io.stderr.write(`jev hook: unknown guard ${unknown.join(", ")}; known: ${ALL_GUARDS.join(", ")}\n`);
@@ -74,7 +77,7 @@ export async function hook(argv, io) {
         reporter.report("error", { hook: values.event, message: `unreadable hook payload: ${err?.message ?? err}` });
         return 0;
     }
-    const response = await withDeadline(runHarnessHook(values.event, payload, { harness, guards, compact: values.compact, lines, window, decide, report: (k, p) => reporter.report(k, p) })
+    const response = await withDeadline(runHarnessHook(values.event, payload, { harness, guards, ladder: { ask: values.ask, allowReadOnly: values["allow-read-only"] }, compact: values.compact, lines, window, decide, report: (k, p) => reporter.report(k, p) })
         .catch((err) => { reporter.report("error", { hook: values.event, message: err?.message ?? String(err) }); return null; }), timeoutMs, () => { reporter.report("error", { hook: values.event, message: `timed out after ${timeoutMs} ms; allowed` }); return null; });
     if (response)
         io.stdout.write(JSON.stringify(response));

package/dist/cli/setup.d.ts

@@ -1,3 +1,3 @@
 import { type Io } from "./common.ts";
-export declare const SETUP_HELP = "Usage: jev setup --harness claude|codex [options]\n\nWrites or merges the Jev entries into the project's agent config, leaving everything else alone.\nClaude Code: .mcp.json and .claude/settings.json. Codex: a marked block in .codex/config.toml.\nEach run sets the whole selection: running it again replaces only what it set up before.\n\nOptions:\n  --harness <name>    claude or codex\n  --guards <list>     bash,write,result: the Level 6 hooks\n  --tools <list>      Jev tools to serve over MCP, for example ask_jev,ask_jev_files\n  --compact           the Level 7 advisor hooks\n  --level <n>         a lab level: 6 guards, 7 advisor, 8 to 10 their tools\n  --out <dir>         the project directory (default: the current one)\n  --command <cmd>     how to run jev in the hooks and the MCP entry (default: node and this package's bin)\n  --hook-args <args>  extra jev hook flags, for example \"--lines 60000,120000,180000\"\n  --dry-run           print what would change, write nothing\n";
+export declare const SETUP_HELP = "Usage: jev setup --harness claude|codex [options]\n\nWrites or merges the Jev entries into the project's agent config, leaving everything else alone.\nClaude Code: .mcp.json and .claude/settings.json. Codex: a marked block in .codex/config.toml.\nEach run sets the whole selection: running it again replaces only what it set up before.\n\nOptions:\n  --harness <name>    claude or codex\n  --guards <list>     bash,write,result: the Level 6 hooks; mcp: the MCP gate on other servers' tools (Claude Code)\n  --ask               the bash and mcp gates ask you when Jev is unsure or leans destructive (Claude Code)\n  --allow-read-only   the bash and mcp gates approve what Jev is sure only reads (Claude Code)\n  --tools <list>      Jev tools to serve over MCP, for example ask_jev,ask_jev_files\n  --compact           the Level 7 advisor hooks\n  --level <n>         a lab level: 6 guards, 7 advisor, 8 to 10 their tools\n  --out <dir>         the project directory (default: the current one)\n  --command <cmd>     how to run jev in the hooks and the MCP entry (default: node and this package's bin)\n  --hook-args <args>  extra jev hook flags, for example \"--lines 60000,120000,180000\"\n  --dry-run           print what would change, write nothing\n";
 export declare function setup(argv: string[], io: Io): Promise<number>;

package/dist/cli/setup.js

@@ -14,7 +14,9 @@ Each run sets the whole selection: running it again replaces only what it set up
 
 Options:
   --harness <name>    claude or codex
-  --guards <list>     bash,write,result: the Level 6 hooks
+  --guards <list>     bash,write,result: the Level 6 hooks; mcp: the MCP gate on other servers' tools (Claude Code)
+  --ask               the bash and mcp gates ask you when Jev is unsure or leans destructive (Claude Code)
+  --allow-read-only   the bash and mcp gates approve what Jev is sure only reads (Claude Code)
   --tools <list>      Jev tools to serve over MCP, for example ask_jev,ask_jev_files
   --compact           the Level 7 advisor hooks
   --level <n>         a lab level: 6 guards, 7 advisor, 8 to 10 their tools
@@ -30,6 +32,7 @@ export async function setup(argv, io) {
             args: argv, strict: true,
             options: {
                 harness: { type: "string" }, guards: { type: "string" }, tools: { type: "string" }, compact: { type: "boolean" },
+                ask: { type: "boolean" }, "allow-read-only": { type: "boolean" },
                 level: { type: "string" }, out: { type: "string" }, command: { type: "string" }, "hook-args": { type: "string" },
                 "dry-run": { type: "boolean" }, help: { type: "boolean", short: "h" },
             },
@@ -54,6 +57,8 @@ export async function setup(argv, io) {
             guards: values.guards ? list(values.guards) : undefined,
             tools: values.tools ? list(values.tools) : undefined,
             compact: values.compact,
+            ask: values.ask,
+            allowReadOnly: values["allow-read-only"],
             level: values.level !== undefined ? Number(values.level) : undefined,
         };
         const changes = plan({

package/dist/guards/bash-gate.d.ts

@@ -6,7 +6,17 @@ export declare const BASH_QUESTIONS: {
 export interface BashGateAnswers {
     effect: ChoiceAnswer;
     destructive_intent: NoulAnswer;
+    /** Asked only with a ladder that asks. */
+    outward?: NoulAnswer;
 }
+/** With `ask`, one more question: a command can change nothing here and still publish or deploy. */
+export declare const BASH_LADDER_QUESTIONS: {
+    outward: import("../core/types.ts").NoulQuestion;
+    effect: import("../core/types.ts").ChoiceQuestion;
+    destructive_intent: import("../core/types.ts").NoulQuestion;
+};
+/** The outward Noul at which a laddered command asks. */
+export declare const BASH_OUTWARD = 0.5;
 export interface BashThresholds {
     /** Confidence the irreversible pick needs before it blocks on its own. */
     irreversible: number;
@@ -14,16 +24,42 @@ export interface BashThresholds {
     destructive: number;
 }
 export declare const BASH_THRESHOLDS: BashThresholds;
+/**
+ * What a hook does with a call, on the Level 4 ladder: deny it, ask the user, approve it without
+ * the harness's own prompt, or pass it to the harness's usual permissions.
+ */
+export type Verdict = "deny" | "ask" | "allow" | "pass";
+export interface Ladder {
+    /** Ask the user, instead of passing, when Jev is unsure or leans destructive without blocking. */
+    ask?: boolean;
+    /** Approve what Jev is sure only reads, so the harness doesn't prompt for it. */
+    allowReadOnly?: boolean;
+    /** Below this confidence a human decides. */
+    floor?: number;
+    /** Above this confidence a read-only pick is approved. */
+    bar?: number;
+}
 export interface GateDecision {
     block: boolean;
     reason: string;
+    /** Set when a ladder was given; `block` is then `verdict === "deny"`. */
+    verdict?: Verdict;
 }
 /** What the agent reads after every block. The block is the answer, not a puzzle to route around. */
 export declare const BLOCK_NOTICE = "This block is final. Do not try to work around it with another command, another tool, a different path, or an encoding that does the same thing. Stop and tell the user what was blocked and why.";
 /** Block or allow. A hook has no third option, so the middle ground allows and says why. */
 export declare function gateBash(a: BashGateAnswers, t?: BashThresholds): GateDecision;
+/**
+ * The bash gate on the Level 4 ladder. Blocks stay blocks. Below them, an irreversible pick, a
+ * destructive lean, or confidence under the floor asks the user; a read-only pick above the bar is
+ * approved. Without `ask` or `allowReadOnly` this is gateBash.
+ */
+export declare function bashVerdict(a: BashGateAnswers, ladder?: Ladder, t?: BashThresholds): GateDecision;
 export type Decide = (state: State, questions: Questions) => Promise<{
     answers: Record<string, unknown>;
 }>;
-/** A: one call before the command runs. `decide` defaults to the shared client; the extension passes a reporting one. */
-export declare function gateBashCommand(command: string, cwd: string, decide?: Decide): Promise<GateDecision>;
+/**
+ * A: one call before the command runs. `decide` defaults to the shared client; the extension passes a reporting one.
+ * With a ladder the decision carries a verdict.
+ */
+export declare function gateBashCommand(command: string, cwd: string, decide?: Decide, ladder?: Ladder): Promise<GateDecision>;

package/dist/guards/bash-gate.js

@@ -4,6 +4,7 @@
  */
 import { jev } from "../core/client.js";
 import { choice, noul } from "../core/helpers.js";
+import { CONFIDENCE } from "../policy/index.js";
 export const BASH_QUESTIONS = {
     effect: choice("What does running `command` in `cwd` do to the machine?", {
         read_only: "Lists, reads, searches, tests, builds into a scratch directory; nothing durable changes",
@@ -15,6 +16,16 @@ export const BASH_QUESTIONS = {
         false: "Reading, listing, testing, installing, generating, or editing in place",
     }),
 };
+/** With `ask`, one more question: a command can change nothing here and still publish or deploy. */
+export const BASH_LADDER_QUESTIONS = {
+    ...BASH_QUESTIONS,
+    outward: noul("Does `command` reach people or systems outside this machine: publish, deploy, push to production, send, or run code downloaded from the internet?", {
+        true: "npm publish, kubectl apply, terraform apply, a migration against a remote database, curl ... | sh, sending email",
+        false: "Works only on this machine and this repository, or only downloads dependencies through the package manager",
+    }),
+};
+/** The outward Noul at which a laddered command asks. */
+export const BASH_OUTWARD = 0.5;
 export const BASH_THRESHOLDS = { irreversible: 0.6, destructive: 0.7 };
 /** What the agent reads after every block. The block is the answer, not a puzzle to route around. */
 export const BLOCK_NOTICE = "This block is final. Do not try to work around it with another command, another tool, a different path, or an encoding that does the same thing. Stop and tell the user what was blocked and why.";
@@ -28,8 +39,40 @@ export function gateBash(a, t = BASH_THRESHOLDS) {
     }
     return { block: false, reason: `${a.effect.choice} (${a.effect.confidence.toFixed(2)}), destructive ${a.destructive_intent.noul.toFixed(2)}` };
 }
-/** A: one call before the command runs. `decide` defaults to the shared client; the extension passes a reporting one. */
-export async function gateBashCommand(command, cwd, decide = (s, q) => jev.systemOne(s, q)) {
-    const { answers } = await decide({ command, cwd }, BASH_QUESTIONS);
-    return gateBash(answers);
+/** Bash read below the destructive line, where a ladder asks rather than passes. */
+const LEANS_DESTRUCTIVE = 0.4;
+/** The most destructive intent a command may show and still be approved as read-only. */
+const READ_ONLY_INTENT = 0.1;
+/**
+ * The bash gate on the Level 4 ladder. Blocks stay blocks. Below them, an irreversible pick, a
+ * destructive lean, or confidence under the floor asks the user; a read-only pick above the bar is
+ * approved. Without `ask` or `allowReadOnly` this is gateBash.
+ */
+export function bashVerdict(a, ladder = {}, t = BASH_THRESHOLDS) {
+    const d = gateBash(a, t);
+    if (d.block)
+        return { ...d, verdict: "deny" };
+    const floor = ladder.floor ?? CONFIDENCE.REVIEW_FLOOR, bar = ladder.bar ?? CONFIDENCE.DESTRUCTIVE_BAR;
+    if (ladder.ask) {
+        if (a.effect.confidence < floor)
+            return { block: false, verdict: "ask", reason: `Jev is unsure what this does (${a.effect.choice} at ${a.effect.confidence.toFixed(2)})` };
+        if (a.effect.choice === "irreversible")
+            return { block: false, verdict: "ask", reason: `may be irreversible (${a.effect.confidence.toFixed(2)})` };
+        if (a.destructive_intent.noul >= LEANS_DESTRUCTIVE)
+            return { block: false, verdict: "ask", reason: `leans destructive (${a.destructive_intent.noul.toFixed(2)})` };
+        if (a.outward && a.outward.noul >= BASH_OUTWARD)
+            return { block: false, verdict: "ask", reason: `reaches outside this machine (${a.outward.noul.toFixed(2)}): it publishes, deploys, sends, or runs downloaded code` };
+    }
+    if (ladder.allowReadOnly && a.effect.choice === "read_only" && a.effect.confidence > bar && a.destructive_intent.noul < READ_ONLY_INTENT && (a.outward?.noul ?? 0) < BASH_OUTWARD) {
+        return { block: false, verdict: "allow", reason: `read only (${a.effect.confidence.toFixed(2)})` };
+    }
+    return { ...d, verdict: "pass" };
+}
+/**
+ * A: one call before the command runs. `decide` defaults to the shared client; the extension passes a reporting one.
+ * With a ladder the decision carries a verdict.
+ */
+export async function gateBashCommand(command, cwd, decide = (s, q) => jev.systemOne(s, q), ladder) {
+    const { answers } = await decide({ command, cwd }, ladder?.ask ? BASH_LADDER_QUESTIONS : BASH_QUESTIONS);
+    return ladder ? bashVerdict(answers, ladder) : gateBash(answers);
 }

package/dist/guards/index.d.ts

@@ -4,3 +4,4 @@
 export * from "./bash-gate.ts";
 export * from "./write-gate.ts";
 export * from "./result-screen.ts";
+export * from "./mcp-gate.ts";

package/dist/guards/index.js

@@ -4,3 +4,4 @@
 export * from "./bash-gate.js";
 export * from "./write-gate.js";
 export * from "./result-screen.js";
+export * from "./mcp-gate.js";

package/dist/guards/mcp-gate.d.ts

@@ -0,0 +1,23 @@
+import type { ChoiceAnswer, NoulAnswer } from "../core/types.ts";
+import type { Decide, GateDecision, Ladder } from "./bash-gate.ts";
+export declare const MCP_QUESTIONS: {
+    effect: import("../core/types.ts").ChoiceQuestion;
+    outward: import("../core/types.ts").NoulQuestion;
+};
+export interface McpGateAnswers {
+    effect: ChoiceAnswer;
+    outward: NoulAnswer;
+}
+/** The outward Noul at which a call asks whatever its effect. */
+export declare const MCP_OUTWARD = 0.5;
+/** Inputs are cut to this many characters before they go to Jev. */
+export declare const MCP_INPUT_CHARS = 4000;
+/** Ask, approve, or pass; `block` is always false. */
+export declare function mcpVerdict(a: McpGateAnswers, ladder?: Ladder): GateDecision;
+/** `mcp__<server>__<tool>`, split; null for a name that isn't an MCP tool. */
+export declare function mcpToolName(name: string): {
+    server: string;
+    tool: string;
+} | null;
+/** One call before the tool runs. */
+export declare function gateMcpCall(name: string, input: unknown, decide?: Decide, ladder?: Ladder): Promise<GateDecision>;

package/dist/guards/mcp-gate.js

@@ -0,0 +1,52 @@
+/**
+ * The MCP gate: the Level 4 account-actions ladder over an agent's MCP tool calls.
+ * Before a tool from a connected server runs: does it only read, change something that can be
+ * changed back, or destroy or reach outside? Destructive and outward calls ask the user, never run
+ * on their own; an unsure call asks too; a call Jev is sure only reads can be approved. It never
+ * denies: the user connected the server, so the user decides.
+ */
+import { jev } from "../core/client.js";
+import { choice, noul } from "../core/helpers.js";
+import { CONFIDENCE } from "../policy/index.js";
+export const MCP_QUESTIONS = {
+    effect: choice("What does calling the MCP tool `tool` with `input` do?", {
+        read_only: "Reads, lists, searches, describes, explains, or fetches; nothing changes",
+        reversible: "Creates or updates something that can be edited back or deleted again: a draft, a branch, a record",
+        destructive: "Deletes, drops, revokes, resets, overwrites, or restores over existing data, with no way back",
+    }),
+    outward: noul("Does calling `tool` with `input` reach people or systems outside this work: send a message, publish, deploy, invite, charge money?", {
+        true: "Sends email or chat, posts, publishes, deploys to production, changes billing or access for others",
+        false: "Stays within the user's own data and environments",
+    }),
+};
+/** The outward Noul at which a call asks whatever its effect. */
+export const MCP_OUTWARD = 0.5;
+/** Inputs are cut to this many characters before they go to Jev. */
+export const MCP_INPUT_CHARS = 4000;
+/** Ask, approve, or pass; `block` is always false. */
+export function mcpVerdict(a, ladder = {}) {
+    const floor = ladder.floor ?? CONFIDENCE.REVIEW_FLOOR, bar = ladder.bar ?? CONFIDENCE.DESTRUCTIVE_BAR;
+    const c = a.effect.confidence.toFixed(2);
+    if (a.effect.confidence < floor)
+        return { block: false, verdict: "ask", reason: `Jev is unsure what this call does (${a.effect.choice} at ${c})` };
+    if (a.effect.choice === "destructive")
+        return { block: false, verdict: "ask", reason: `destructive (${c}): there is no way back` };
+    if (a.outward.noul >= MCP_OUTWARD)
+        return { block: false, verdict: "ask", reason: `reaches outside (${a.outward.noul.toFixed(2)}): it sends, publishes, deploys, or charges` };
+    if (ladder.allowReadOnly && a.effect.choice === "read_only" && a.effect.confidence > bar)
+        return { block: false, verdict: "allow", reason: `read only (${c})` };
+    return { block: false, verdict: "pass", reason: `${a.effect.choice} (${c}), outward ${a.outward.noul.toFixed(2)}` };
+}
+/** `mcp__<server>__<tool>`, split; null for a name that isn't an MCP tool. */
+export function mcpToolName(name) {
+    const m = name.match(/^mcp__(.+?)__(.+)$/);
+    return m ? { server: m[1], tool: m[2] } : null;
+}
+/** One call before the tool runs. */
+export async function gateMcpCall(name, input, decide = (s, q) => jev.systemOne(s, q), ladder = {}) {
+    const parsed = mcpToolName(name);
+    const json = JSON.stringify(input ?? {});
+    const state = { tool: parsed?.tool ?? name, server: parsed?.server ?? "", input: json.length > MCP_INPUT_CHARS ? `${json.slice(0, MCP_INPUT_CHARS)}…` : json };
+    const { answers } = await decide(state, MCP_QUESTIONS);
+    return mcpVerdict(answers, ladder);
+}

package/dist/hooks/handle.d.ts

@@ -4,6 +4,7 @@
  * the compaction advisor make the same decisions under pi, Claude Code, and Codex.
  *
  *   shell          before a shell command runs: the bash gate
+ *   mcp-call       before an MCP tool runs: the MCP gate
  *   write          before a file is created or changed: the write gate
  *   read-result    after a read returns: the result screen
  *   shell-result   after a shell command returns: the result screen
@@ -12,10 +13,13 @@
  * Every handler fails open: a Jev error allows the action and reports an `error` event.
  */
 import type { Decider } from "../events/index.ts";
+import { type Ladder, type Verdict } from "../guards/bash-gate.ts";
 import { type Evaluation, type TurnInput } from "../compact/evaluate.ts";
 import type { CompactAction } from "../compact/should-compact.ts";
-export type Guard = "bash" | "write" | "result";
+export type Guard = "bash" | "write" | "result" | "mcp";
 export declare const ALL_GUARDS: Guard[];
+/** Level 6's guards, and what runs when no guards are named. The MCP gate is opt-in. */
+export declare const LEVEL6_GUARDS: Guard[];
 interface Base {
     cwd: string;
     /** The harness's own name for the event, used in reports: tool_call, PreToolUse, ... */
@@ -25,6 +29,10 @@ export type HookEvent = (Base & {
     kind: "shell";
     tool: string;
     command: string;
+}) | (Base & {
+    kind: "mcp-call";
+    tool: string;
+    input: unknown;
 }) | (Base & {
     kind: "write";
     tool: string;
@@ -43,6 +51,8 @@ export interface HookOutcome {
     /** Deny the action; `reason` is what the agent reads. */
     block?: boolean;
     reason?: string;
+    /** Before a call, short of a block: ask the user, or approve without the harness's prompt. */
+    verdict?: Exclude<Verdict, "deny" | "pass">;
     /** For results: a banner to show above, or alongside, the content. */
     banner?: string;
     /** For turn ends: a message for the agent's next turn. */
@@ -53,10 +63,14 @@ export interface HookOutcome {
 export interface HookContext {
     decide: Decider;
     report(kind: string, payload: Record<string, unknown>): void;
-    /** Which guards are on. Defaults to all. */
+    /** Which guards are on. Defaults to Level 6's. */
     guards?: Guard[];
+    /** The Level 4 ladder for the bash and MCP gates: when to ask, when to approve. */
+    ladder?: Ladder;
 }
 /** The text the agent reads when a guard blocks. */
 export declare const blockMessage: (what: string, reason: string) => string;
+/** The text the user reads when a guard asks. */
+export declare const askMessage: (what: string, reason: string) => string;
 export declare function handleHook(event: HookEvent, ctx: HookContext): Promise<HookOutcome>;
 export {};

package/dist/hooks/handle.js

@@ -1,24 +1,37 @@
 import { BLOCK_NOTICE, gateBashCommand } from "../guards/bash-gate.js";
+import { gateMcpCall } from "../guards/mcp-gate.js";
 import { gateWriteCall } from "../guards/write-gate.js";
 import { screenToolResult } from "../guards/result-screen.js";
 import { evaluateCompaction } from "../compact/evaluate.js";
-export const ALL_GUARDS = ["bash", "write", "result"];
+export const ALL_GUARDS = ["bash", "write", "result", "mcp"];
+/** Level 6's guards, and what runs when no guards are named. The MCP gate is opt-in. */
+export const LEVEL6_GUARDS = ["bash", "write", "result"];
 const DEFAULT_HOOK = {
-    shell: "tool_call", write: "tool_call", "read-result": "tool_result", "shell-result": "tool_result", "turn-end": "turn_end",
+    shell: "tool_call", "mcp-call": "tool_call", write: "tool_call", "read-result": "tool_result", "shell-result": "tool_result", "turn-end": "turn_end",
 };
 /** The text the agent reads when a guard blocks. */
 export const blockMessage = (what, reason) => `jev-guard blocked this ${what}: ${reason}. ${BLOCK_NOTICE}`;
+/** The text the user reads when a guard asks. */
+export const askMessage = (what, reason) => `jev-guard asks before this ${what}: ${reason}.`;
+const laddered = (verdict, what, reason) => verdict === "ask" ? { verdict: "ask", reason: askMessage(what, reason) } : verdict === "allow" ? { verdict: "allow", reason: `jev-guard approved this ${what}: ${reason}.` } : {};
 export async function handleHook(event, ctx) {
-    const on = (g) => (ctx.guards ?? ALL_GUARDS).includes(g);
+    const on = (g) => (ctx.guards ?? LEVEL6_GUARDS).includes(g);
     const hook = event.hook ?? DEFAULT_HOOK[event.kind];
     try {
         switch (event.kind) {
             case "shell": {
                 if (!on("bash"))
                     return {};
-                const d = await gateBashCommand(event.command, event.cwd, (s, q) => ctx.decide(`${hook} ${event.tool}`, s, q));
-                ctx.report("hook", { hook, tool: event.tool, command: event.command, block: d.block, reason: d.reason });
-                return d.block ? { block: true, reason: blockMessage("command", d.reason) } : {};
+                const d = await gateBashCommand(event.command, event.cwd, (s, q) => ctx.decide(`${hook} ${event.tool}`, s, q), ctx.ladder);
+                ctx.report("hook", { hook, tool: event.tool, command: event.command, block: d.block, reason: d.reason, ...(d.verdict ? { verdict: d.verdict } : {}) });
+                return d.block ? { block: true, reason: blockMessage("command", d.reason) } : laddered(d.verdict, "command", d.reason);
+            }
+            case "mcp-call": {
+                if (!on("mcp"))
+                    return {};
+                const d = await gateMcpCall(event.tool, event.input, (s, q) => ctx.decide(`${hook} ${event.tool}`, s, q), ctx.ladder);
+                ctx.report("hook", { hook, tool: event.tool, block: false, verdict: d.verdict, reason: d.reason });
+                return laddered(d.verdict, `${event.tool} call`, d.reason);
             }
             case "write": {
                 if (!on("write"))

package/dist/hooks/harness.d.ts

@@ -4,6 +4,8 @@
  * they differ in tool names and where context usage lives.
  *
  *   PreToolUse        Bash: bash gate. Write, Edit, MultiEdit, NotebookEdit, apply_patch: write gate. Deny on block.
+ *                     mcp__*: the MCP gate, except the jev server's own tools. With a ladder, Claude Code
+ *                     also gets ask and allow; Codex only reads deny, so there they pass.
  *   PostToolUse       Read, Bash: result screen. The banner goes back as additionalContext.
  *   UserPromptSubmit  Level 7: record the request; inject a waiting tier message once.
  *   Stop              Level 7: the four questions, the tier saved for the next prompt.
@@ -11,6 +13,7 @@
  */
 import type { Decider } from "../events/index.ts";
 import type { Lines } from "../compact/should-compact.ts";
+import type { Ladder } from "../guards/bash-gate.ts";
 import { type Guard, type HookContext } from "./handle.ts";
 export type Harness = "claude" | "codex";
 /** Lines for real sessions, whose system prompt alone passes the lab's demo lines. */
@@ -18,6 +21,8 @@ export declare const HOOK_LINES: Lines;
 export interface HarnessHookOptions {
     harness: Harness;
     guards?: Guard[];
+    /** When the bash and MCP gates ask or approve instead of passing. */
+    ladder?: Ladder;
     /** Run the Level 7 advisor on UserPromptSubmit and Stop. */
     compact?: boolean;
     lines?: Lines;

package/dist/hooks/harness.js

@@ -1,4 +1,4 @@
-import { ALL_GUARDS, handleHook } from "./handle.js";
+import { LEVEL6_GUARDS, handleHook } from "./handle.js";
 import { readState, stateDir, writeState } from "./state.js";
 import { claudeUsage, codexUsage } from "./transcript.js";
 /** Lines for real sessions, whose system prompt alone passes the lab's demo lines. */
@@ -40,9 +40,12 @@ function resultText(tool, response) {
     return null;
 }
 const deny = (reason) => ({ hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: reason } });
+const decision = (permissionDecision, reason) => ({ hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision, permissionDecisionReason: reason } });
 const context = (event, text) => ({ hookSpecificOutput: { hookEventName: event, additionalContext: text } });
 export async function runHarnessHook(event, payload, opts) {
-    const ctx = { decide: opts.decide, report: opts.report, guards: opts.guards ?? ALL_GUARDS };
+    const ctx = { decide: opts.decide, report: opts.report, guards: opts.guards ?? LEVEL6_GUARDS, ladder: opts.ladder };
+    /** Codex hooks honor deny only; an ask or allow there passes to Codex's own approvals. */
+    const pre = (r) => r.block ? deny(r.reason) : r.verdict && opts.harness === "claude" ? decision(r.verdict, r.reason) : null;
     const cwd = String(payload?.cwd || process.cwd());
     const tool = String(payload?.tool_name ?? "");
     const session = String(payload?.session_id ?? "default");
@@ -50,7 +53,12 @@ export async function runHarnessHook(event, payload, opts) {
         case "PreToolUse": {
             if (tool === "Bash") {
                 const r = await handleHook({ kind: "shell", tool, command: String(payload?.tool_input?.command ?? ""), cwd, hook: event }, ctx);
-                return r.block ? deny(r.reason) : null;
+                return pre(r);
+            }
+            if (tool.startsWith("mcp__")) {
+                if (tool.startsWith("mcp__jev__"))
+                    return null; // Jev's own tools only read
+                return pre(await handleHook({ kind: "mcp-call", tool, input: payload?.tool_input, cwd, hook: event }, ctx));
             }
             const targets = writeTargets(tool, payload?.tool_input);
             if (!targets)

package/dist/setup/index.d.ts

@@ -8,6 +8,10 @@ export interface SetupOptions {
     tools?: string[];
     /** Run the Level 7 advisor hooks. */
     compact?: boolean;
+    /** The bash and MCP gates ask the user when Jev is unsure or leans destructive. Claude Code only. */
+    ask?: boolean;
+    /** The bash and MCP gates approve what Jev is sure only reads. Claude Code only. */
+    allowReadOnly?: boolean;
     /** A lab level: 6 means the guards, 7 the advisor and should_i_compact, 8 to 10 their tools. */
     level?: number;
     /** How the harness runs this package's bin. Defaults to node and its absolute path. */
@@ -35,8 +39,13 @@ export interface Resolved {
     guards: Guard[];
     tools: string[];
     compact: boolean;
+    ask?: boolean;
+    allowReadOnly?: boolean;
 }
-export declare function resolveSelection(o: Pick<SetupOptions, "guards" | "tools" | "compact" | "level">): Resolved;
+type Selection = Pick<SetupOptions, "guards" | "tools" | "compact" | "level" | "ask" | "allowReadOnly"> & {
+    harness?: SetupHarness;
+};
+export declare function resolveSelection(o: Selection): Resolved;
 interface HookGroup {
     matcher?: string;
     hooks: {
@@ -61,7 +70,7 @@ export declare function codexBlock(sel: Resolved, command: string[], extra?: str
  */
 export declare function planCodex(o: SetupOptions): FileChange[];
 /** One line for people: what the selection turns on. */
-export declare function describeSelection(o: Pick<SetupOptions, "guards" | "tools" | "compact" | "level">): string;
+export declare function describeSelection(o: Selection): string;
 export declare function plan(o: SetupOptions): FileChange[];
 export declare function apply(changes: FileChange[]): void;
 export {};

package/dist/setup/index.js

@@ -7,7 +7,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { ALL_GUARDS } from "../hooks/handle.js";
+import { ALL_GUARDS, LEVEL6_GUARDS } from "../hooks/handle.js";
 import { LEVEL_TOOLS, selectTools } from "../tools/sets.js";
 export class SetupError extends Error {
 }
@@ -32,7 +32,7 @@ export function resolveSelection(o) {
     let compact = o.compact ?? false;
     if (o.level !== undefined) {
         if (o.level === 6)
-            ALL_GUARDS.forEach((g) => guards.add(g));
+            LEVEL6_GUARDS.forEach((g) => guards.add(g));
         else if (LEVEL_TOOLS[o.level]) {
             LEVEL_TOOLS[o.level].forEach((t) => tools.add(t));
             if (o.level === 7)
@@ -52,20 +52,30 @@ export function resolveSelection(o) {
     }
     if (!guards.size && !tools.size && !compact)
         throw new SetupError("nothing to set up: pass --guards, --tools, --compact, or --level");
-    return { guards: [...guards], tools: [...tools], compact };
+    const ladder = o.ask || o.allowReadOnly;
+    if (ladder && !guards.has("bash") && !guards.has("mcp"))
+        throw new SetupError("--ask and --allow-read-only apply to the bash and mcp guards; add one of them to --guards");
+    if (o.harness === "codex" && (ladder || guards.has("mcp"))) {
+        throw new SetupError("Codex hooks can only deny, so the mcp guard, --ask, and --allow-read-only are Claude Code only");
+    }
+    return { guards: [...guards], tools: [...tools], compact, ...(o.ask ? { ask: true } : {}), ...(o.allowReadOnly ? { allowReadOnly: true } : {}) };
 }
 /** The hook entries, by event, that a selection needs. Same shape for Claude Code and Codex. */
 export function hookGroups(harness, sel, command, extra = [], timeoutSec = 10) {
     const run = (event, flags) => ({ type: "command", command: [...command, "hook", "--harness", harness, "--event", event, ...flags, ...extra].map(quote).join(" "), timeout: timeoutSec });
     const out = {};
     const guardFlag = (gs) => ["--guards", gs.join(",")];
+    const ladder = [...(sel.ask ? ["--ask"] : []), ...(sel.allowReadOnly ? ["--allow-read-only"] : [])];
     const pre = [];
     if (sel.guards.includes("bash"))
         pre.push("Bash");
     if (sel.guards.includes("write"))
         pre.push(...(harness === "codex" ? ["apply_patch"] : ["Write", "Edit", "MultiEdit", "NotebookEdit"]));
+    const preGuards = sel.guards.filter((g) => g === "bash" || g === "write");
     if (pre.length)
-        out.PreToolUse = [{ matcher: pre.join("|"), hooks: [run("PreToolUse", guardFlag(sel.guards.filter((g) => g !== "result")))] }];
+        out.PreToolUse = [{ matcher: pre.join("|"), hooks: [run("PreToolUse", [...guardFlag(preGuards), ...(sel.guards.includes("bash") ? ladder : [])])] }];
+    if (sel.guards.includes("mcp"))
+        (out.PreToolUse ??= []).push({ matcher: "mcp__.*", hooks: [run("PreToolUse", [...guardFlag(["mcp"]), ...ladder])] });
     if (sel.guards.includes("result"))
         out.PostToolUse = [{ matcher: harness === "codex" ? "Bash" : "Read|Bash", hooks: [run("PostToolUse", guardFlag(["result"]))] }];
     if (sel.compact) {
@@ -191,6 +201,8 @@ export function describeSelection(o) {
     const sel = resolveSelection(o);
     const parts = [
         sel.guards.length ? `guards ${sel.guards.join(",")}` : "",
+        sel.ask ? "ask when unsure" : "",
+        sel.allowReadOnly ? "approve read only" : "",
         sel.compact ? "compaction advisor" : "",
         sel.tools.length ? `tools ${sel.tools.join(",")}` : "",
     ].filter(Boolean);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bobobowis/jev-kit",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Jev, TypeSafe AI's System One decision model, as a typed client, guards, file reads, agent tools, hooks, an MCP server, and a CLI. Zero runtime dependencies.",
   "type": "module",
   "license": "MIT",