@pi-in-go/pigpen-jev 0.1.0

package/CREDITS.md

@@ -0,0 +1,22 @@
+# Credits
+
+`extensions/jev` is a Go port of **pi-jev** (`@y0usaf/pi-jev` 0.2.2), https://github.com/y0usaf/pi-jev,
+by **y0usaf** (MIT, Copyright (c) 2026 y0usaf). The idea, the three surfaces (tool-call gate, output
+judge, `jev_ask`), the questions and their measured phrasing, the thresholds and their calibration
+tables, the wording of every notice, the `/jev` command and the fail-open policy are y0usaf's.
+
+- Original: `src/client.ts`, `src/config.ts`, `src/gate.ts`, `src/output.ts`, `src/index.ts`
+- Pinned commit: `88e5fb3888948e7065110d47cdf6ac57abb71ba4` (release 0.2.2, "failing visibly on a
+  response that skips a question"). The npm `latest` is still 0.2.0; this is the reviewed Git commit.
+- The unmodified sources are kept in [`port/oracle/src/`](port/oracle/src) as the equivalence oracle, with
+  the upstream license at [`port/oracle/LICENSE`](port/oracle/LICENSE), `package.json` and README.
+
+[TypeSafe](https://docs.typesafe.ai) defines Jev (its typed decision model: Noul, Choice, Score).
+The HTTP protocol and the own-model backend come from the shared Go client
+[`components/typesafe`](../typesafe/CREDITS.md) (ports of TypeSafe's `typesafe-sdk-js` and
+`system-one-adapter-python`), which this Package uses; it does not carry a client of its own.
+
+The Go code, the tests and the scenarios were written for this Package by Michael Kinsy. What was
+modified relative to the original, and why, is the list of corrections in
+[`port/PORT.md`](port/PORT.md) (C1 to C10) and the opt-in, disclosure and trust rules in the README.
+Everything else follows the original's behavior, checked against the original under Pi.

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 y0usaf
+Copyright (c) 2026 Michael Kinsy (the Go port)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,237 @@
+# Jev for PiG
+
+A second opinion on what your agent is about to do, and on what it just printed. Jev asks a judge
+typed questions ("is this destructive?", "does this send local data off the machine?", "does this
+output contain a secret?") and gets back numbers, not prose, so the answer is something PiG can branch on.
+
+```text
+ ⚠ Jev flagged bash (shadow mode: reported, not blocked)
+   ⚠ destructive   ██████████  0.99  ≥ 0.90
+   ⚠ exfiltration  ████████··  0.79  ≥ 0.70
+   ⚠ beyond scope  ██████████  0.98  ≥ 0.85
+   ⚠ impact        ██████████  3.00/3  ≥ 2.50  (confidence 0.91)
+```
+
+**It is off until you turn it on.** Nothing is judged, nothing is sent, and it prints nothing at start-up
+until you opt in. Judging sends parts of your session to a judge, so `/jev on` shows exactly what and where
+before it does anything.
+
+Three surfaces, from y0usaf's [pi-jev](https://github.com/y0usaf/pi-jev) (this is its Go port; see
+[CREDITS.md](CREDITS.md)):
+
+| Surface | What it does |
+|---|---|
+| **Gate** | Before `bash`, `write` or `edit` runs, judges the call: destructive? sends data off the machine? beyond what you asked? how much damage? In **shadow** mode (default) it only reports. In **enforce** mode a flagged call asks you first. |
+| **Output judge** | After `bash` finishes, reads what it printed: does it carry a secret? What kind of failure is it? It adds one line to the result the model reads ("do not repeat the value", "fix the environment before retrying"). It never blocks. |
+| **`jev_ask`** | A tool the model can call to ask typed questions (yes/no probability, pick one, rubric score) about a piece of text. Exists only while Jev is on. |
+
+## Turn it on
+
+```sh
+pig install ./components/jev            # or select the Package from a Piglet (pig-with-batteries does)
+```
+
+then, in a session:
+
+```text
+/jev on
+```
+
+```text
+ Turn on Jev for this session?
+ What leaves this machine for each judgment:
+   • the working directory and the tool name
+   • your last message (first 1200 characters)
+   • the tool arguments (bash/write/edit; long fields are cut at 400 characters, and write/edit arguments are file content)
+   • bash output (first 2000 characters)
+ Also sent: text the model passes to jev_ask (up to 8000 characters) and text you pass to /jev check.
+ Destination: the model acme/judge-1 (through PiG, the provider that already receives your conversation)
+ If the judge is unavailable, tool calls run unjudged (it fails open). A judgment is probabilistic advice, not a sandbox.
+ Turn Jev on?
+```
+
+To keep it on for every session, edit **your own** `<agent dir>/pi-jev.json` (`~/.pig/agent/pi-jev.json`;
+`PIG_CODING_AGENT_DIR` moves it):
+
+```json
+{ "enabled": true }
+```
+
+Jev then shows the notice above at every start-up until you add `"acknowledged": true`.
+`/jev off` turns it off again for the session. Nothing turns it on for you: not a key in the environment,
+not a file in a repository you opened (see [What a project can change](#what-a-project-can-change)).
+
+## Who judges
+
+| Backend | `"backend"` | Where the content goes | Needs |
+|---|---|---|---|
+| **The model PiG is configured with** (default) | `"model"` | The provider of your current model, through PiG's own model access and credentials. When you switch models, the judge follows (Jev says so) and earlier verdicts are dropped. Set `"model": "provider/id"` to use another model of your registry. | nothing else |
+| **The TypeSafe API** | `"typesafe"` | The endpoint you configure. There is no built-in default and no default model name. | `endpoint`, `model`, and a key (`TYPESAFE_API_KEY`, `apiKey` or `apiKeyFile`) |
+
+Both come from the shared Go client in [`components/typesafe`](../typesafe/README.md): the model backend asks the
+model for typed answers in prompted JSON mode and validates them strictly; the TypeSafe backend speaks TypeSafe's
+API. **Calibration caveat:** the thresholds below were measured by y0usaf against TypeSafe's Jev on a handful of
+states ("a smoke calibration, not a labelled evaluation set", in the original's words). Nobody has measured them
+against an arbitrary chat model. Read them as starting points; that is one reason shadow mode is the default.
+
+```json
+{
+  "enabled": true,
+  "backend": "typesafe",
+  "endpoint": "https://<your TypeSafe API root>",
+  "model": "<a TypeSafe model name>",
+  "apiKeyFile": "~/keys/typesafe.txt"
+}
+```
+
+The key is sent only to that endpoint, which must be `https` (or `http` to `localhost`). `TYPESAFE_BASE_URL` and the
+other `TYPESAFE_*` variables are ignored.
+
+## The gate
+
+| Question | Type | Reads | Threshold |
+|---|---|---|---|
+| Is this action destructive? | noul | `destructive` | 0.90 |
+| Does this send local data or secrets off-machine? | noul | `exfiltration` | 0.70 |
+| Does this affect anything beyond what the user asked for? | noul | `beyond_scope` | 0.85 |
+| How much damage if the user did not want it? | score (4 levels) | `impact` | 2.50 |
+
+All four go in one request. **Shadow mode is the default:** a flagged call produces a notification and a footer
+status. In **enforce** mode (`/jev mode enforce`) a flagged call opens a dialog:
+
+```text
+ Jev flagged this tool call
+ bash  rm -rf src && git push --force origin main
+
+   ⚠ destructive   ██████████  0.99  ≥ 0.90
+   ⚠ exfiltration  ████████··  0.79  ≥ 0.70
+   ⚠ beyond scope  ██████████  0.98  ≥ 0.85
+   ⚠ impact        ██████████  3.00/3  ≥ 2.50  (confidence 0.91)
+
+ Judged by the model acme/judge-1 (through PiG, the provider that already receives your conversation)
+ Run it anyway?
+```
+
+Print and JSON runs have no UI (RPC and the terminal do), so enforcement there degrades to the same warning unless you set
+`gate.blockWithoutUI`. If the dialog cannot be shown (the UI call fails), the flagged call is blocked, as in the original:
+fail-open covers an unavailable judge, not a missing approval.
+
+## Failure policy: it fails open
+
+**If the judge is unavailable, tool calls run unjudged.** A missing key, a timeout, a 429, a malformed or incomplete
+answer produces no verdict and the tool call proceeds; a dead endpoint never stops your agent. The footer says so
+(`⚖ jev ✗ unavailable (failing open)`) instead of keeping an old "clear", and errors are reported at most once a minute.
+This is y0usaf's policy, kept on purpose, and stated at start-up and in `/jev`. Do not treat a clear verdict as
+authorization: a model's judgment is probabilistic advice, not a sandbox, and the judge can be wrong or steered by the
+very content it reads.
+
+## The output judge
+
+`tool_result` asks two questions in one request and appends one line to the result when either fires:
+
+| Question | Type | Reads | Threshold |
+|---|---|---|---|
+| Does this output contain a secret or credential? | noul | `leaks_secret` | 0.90 |
+| What kind of failure is this? | choice (6 options) | `failure_class` | confidence 0.60 |
+
+A leak appends "Do not repeat the value in a reply, a file, or a command; refer to it by name instead" and raises a
+notification. A failure class appends what to do about it (retry a `transient` failure, fix the environment for
+`environment`, fix the code for `code_bug`, do not retry `permission`, fix the invocation for `user_error`). `no_failure`
+says nothing. Judged tools default to `["bash"]`.
+
+## `jev_ask`
+
+```json
+{ "state": "the tool output, diff, or message to judge",
+  "questions": [
+    { "id": "relevant", "type": "noul",   "instructions": "Is this relevant to the user's question?" },
+    { "id": "label",    "type": "choice", "instructions": "Which bucket?",
+      "options": [{ "name": "bug", "description": "Defect in existing behaviour" }, { "name": "feature" }] },
+    { "id": "quality",  "type": "score",  "instructions": "How thorough is this?",
+      "levels": ["Superficial", "Adequate", "Thorough"] } ] }
+```
+
+It is registered when Jev is on and refuses ("Jev is off") after `/jev off`. The text is cut to `maxStateChars`.
+
+## Commands
+
+- `/jev` shows the judge, what is sent, the failure policy and the last verdicts
+- `/jev on` and `/jev off` toggle both judges for the session (`on` asks first, with the disclosure)
+- `/jev mode shadow|enforce`
+- `/jev last` prints the last gate verdict with all four answers
+- `/jev output` prints the last judged output (also when it was clean)
+- `/jev check <text>` runs the gate questions on text you supply (it sends that text, so it needs Jev on)
+
+```text
+ Jev is ON — shadow mode, output judge on
+   Judge     the model acme/judge-1 (through PiG, the provider that already receives your conversation)
+   Gate      bash, write, edit (on)
+   Output    bash (on)
+   Sends     working directory, tool name, your last message, tool arguments, tool output, jev_ask text — cut to your limits
+   If down   tool calls run unjudged (fails open)
+   Last      bash: destructive 0.99, exfiltration 0.79, beyond_scope 0.98, impact 3.00/3 at confidence 0.91
+   Commands  /jev on|off · /jev mode shadow|enforce · /jev last · /jev output · /jev check <text>
+```
+
+## Configure
+
+`<agent dir>/pi-jev.json` is yours. A project's `<cwd>/.pig/pi-jev.json` may tune the gate. Only keys you set override; the
+rest are the defaults below.
+
+```json
+{
+  "enabled": false, "acknowledged": false, "backend": "model", "display": "rich",
+  "endpoint": "", "model": "", "apiKey": "", "apiKeyFile": "", "timeoutMs": 20000, "retries": 2,
+  "maxStateChars": 8000,
+  "gate": { "enabled": true, "mode": "shadow", "tools": ["bash", "write", "edit"], "argumentChars": 400,
+            "cacheSeconds": 120, "minConfidence": 0.5, "blockWithoutUI": false,
+            "blockOn": { "destructive": 0.9, "exfiltration": 0.7, "beyondScope": 0.85, "impact": 2.5 } },
+  "output": { "enabled": true, "tools": ["bash"], "outputChars": 2000, "leakThreshold": 0.9, "minConfidence": 0.6 }
+}
+```
+
+`"display": "plain"` uses the original's exact wording and no glyphs (the equivalence scenarios run in it). The API key
+resolves in the order `TYPESAFE_API_KEY`, `apiKey`, `apiKeyFile` (`~/` expanded); `/jev` reports which one is in use.
+`blockOn.impact` is on the 0 to 3 damage rubric, and `minConfidence` gates that dimension only (the three noul
+questions return a probability and no confidence).
+
+### What a project can change
+
+A repository you open must not be able to send your data somewhere or switch judging on. So a project file **cannot** set
+`enabled`, `acknowledged`, `backend`, `endpoint`, `model`, `apiKey`, `apiKeyFile`, `timeoutMs`, `retries` or `display`
+(each is reported once as "ignored project setting"), and it can only **lower** what leaves the machine:
+`maxStateChars`, `gate.argumentChars` and `output.outputChars` can shrink, and `gate.tools` / `output.tools` can pick among
+the tools your own config already judges. Thresholds, mode and the rest may be tuned: they cannot leak anything. A project
+that relaxes the protection your own config sets up (turns the gate or the output judge off, `enforce` into `shadow`,
+`blockWithoutUI` off, raises a threshold, or judges fewer tools) is applied, since it only sends less, but never silently:
+each start-up warns "`<project file>` relaxes the gate your own `pi-jev.json` sets: ..." with the settings it changed.
+
+## What leaves the machine
+
+Each judgment sends, to the judge named in `/jev`: the working directory, the tool name, your last message (first 1200
+characters) and the tool's arguments. For `write` and `edit` those arguments contain file content. The output judge sends the
+first `output.outputChars` characters of a `bash` result plus the same arguments. Any string longer than `gate.argumentChars`
+(400) is cut at any nesting depth and replaced with `…[N chars elided]`; the omitted text never leaves. Set `gate.tools` to
+`["bash"]` to keep file content out of the gate entirely, or lower a limit. The whole document is held to `maxStateChars`.
+`jev_ask` sends the text the model passes to it (cut to `maxStateChars`), and `/jev check` sends the text you type after it.
+The API key is sent only in the `Authorization` header to your endpoint, and notification text is scrubbed of it.
+
+## Differences from pi-jev
+
+This port follows y0usaf's behavior and differs only where the roadmap's code review found defects or the owner's rules
+require it. Each is a test in [`port/PORT.md`](port/PORT.md) (C1 to C10): a verdict cache bound to the user's request and
+the judge (C1), no project-chosen credential destination and no built-in endpoint (C2), `maxStateChars` applied (C3),
+opt-in and disclosure (C4), strict typed-response validation (C5), a truthful "unavailable" status (C6), long strings
+elided at every depth (C7), duplicate `jev_ask` ids refused (C8), `/jev` reporting the real key source and clean outputs
+(C9), and `jev_ask` refusing while off (C10). The review of this port added R1 to R5 (same file): a failed enforce dialog
+blocks, the default judge follows a model switch, the disclosure names `jev_ask` and `/jev check`, a project that relaxes
+the gate is reported, and more trust-boundary tests.
+
+## Proof
+
+`port/` holds the evidence: the unmodified original (`port/oracle/`, MIT), the scenarios, the recorded Pi traces, the
+mutation list and [`port/PORT.md`](port/PORT.md). Go tests drive the real SDK through a fake PiG host; the differential
+scenarios run the original under Pi (traces re-recorded on Pi 1.0.1) and the port under PiG 0.4 against a fake judge endpoint and compare every
+request and UI effect.
+
+MIT. Original © y0usaf; port © Michael Kinsy. Depends on the shared client Package `components/typesafe`.

package/extensions/jev/ask.go

@@ -0,0 +1,166 @@
+package jev
+
+import (
+	"fmt"
+	"strings"
+
+	sdk "github.com/MichaelKinsy/PiG/extensions/sdk"
+)
+
+// jev_ask: the model asks typed questions itself. It sends the model-chosen text to
+// the judge, so it exists only while Jev is on and refuses when it is off.
+
+func (x *ext) registerAsk(ctx sdk.Context) {
+	x.mu.Lock()
+	done := x.askReg
+	x.askReg = true
+	x.mu.Unlock()
+	if done {
+		return
+	}
+	str := func(desc string) sdk.Schema { return sdk.Schema{"type": "string", "description": desc} }
+	question := sdk.Schema{
+		"type": "object",
+		"properties": sdk.Schema{
+			"id":           str("Short key for this question. The answer comes back under it."),
+			"type":         sdk.Schema{"type": "string", "enum": []any{"noul", "choice", "score"}, "description": "noul = yes/no probability, choice = pick one option, score = value on a rubric"},
+			"instructions": str("The one thing to judge. One specific, well-scoped gut-check per question."),
+			"options": sdk.Schema{"type": "array", "description": "choice only: the options to choose between", "items": sdk.Schema{
+				"type": "object", "properties": sdk.Schema{"name": str("Option key"), "description": str("When this option applies")}, "required": []any{"name"}}},
+			"levels": sdk.Schema{"type": "array", "description": "score only: ordered rubric levels, lowest first, at least two", "items": sdk.Schema{"type": "string"}},
+		},
+		"required": []any{"id", "type", "instructions"},
+	}
+	ctx.RegisterTool(sdk.ToolDefinition{
+		Name:          "jev_ask",
+		Label:         "Jev Ask",
+		Description:   "Ask TypeSafe Jev typed questions about a piece of text and get calibrated answers (probabilities, a chosen option, a rubric score) instead of prose.",
+		PromptSnippet: "Ask Jev typed questions (yes/no, choice, rubric) about text and get calibrated answers",
+		PromptGuidelines: []string{
+			"Use jev_ask when a judgement must be typed and calibrated rather than written: classification, relevance, yes/no checks, rubric scores.",
+			"Ask one specific question per entry in jev_ask; split multi-factor judgements into separate questions and combine the answers yourself.",
+		},
+		Parameters: sdk.Schema{
+			"type": "object",
+			"properties": sdk.Schema{
+				"state":     str("The text to judge: tool output, a diff, a message, a document excerpt."),
+				"questions": sdk.Schema{"type": "array", "description": "One or more questions. All are evaluated in parallel against the same state.", "items": question},
+			},
+			"required": []any{"state", "questions"},
+		},
+		Execute: x.execAsk,
+	})
+}
+
+func askFail(format string, a ...any) (any, error) {
+	return sdk.ToolResult{Content: "jev_ask: " + fmt.Sprintf(format, a...), Details: map[string]any{"ok": false}}, nil
+}
+
+func (x *ext) execAsk(ctx sdk.Context, params map[string]any) (any, error) {
+	s := x.snapshot()
+	if !s.on || s.be == nil {
+		return askFail("Jev is off (the user turns it on with /jev on); nothing was sent")
+	}
+	state, ok := params["state"].(string)
+	if !ok {
+		return askFail("state must be text")
+	}
+	raw, _ := params["questions"].([]any)
+	qs := make([]question, 0, len(raw))
+	for _, item := range raw {
+		m, _ := item.(map[string]any)
+		q, msg := toQuestion(m)
+		if msg != "" {
+			return askFail("%s", msg)
+		}
+		qs = append(qs, q)
+	}
+	if err := validateQuestions(qs); err != nil {
+		return askFail("%s", err.Error())
+	}
+	gctx, cancel := goContext(ctx)
+	defer cancel()
+	// maxStateChars caps what the model can send, like the gate's state.
+	resp, err := s.be.Ask(gctx, ctx, jsonString(elide(state, s.cfg.MaxStateChars)), true, qs)
+	if err != nil {
+		return askFail("%s", x.redact(err.Error()))
+	}
+	details := map[string]any{"ok": true, "model": resp.Model, "answers": detailAnswers(resp)}
+	if resp.Usage != nil {
+		details["usage"] = map[string]any{"input_tokens": resp.Usage.Input, "output_tokens": resp.Usage.Output}
+	}
+	return sdk.ToolResult{Content: renderAnswers(resp, qs), Details: details}, nil
+}
+
+// toQuestion returns a question, or a message explaining why the shape is invalid.
+func toQuestion(m map[string]any) (question, string) {
+	id, _ := m["id"].(string)
+	typ, _ := m["type"].(string)
+	instr, _ := m["instructions"].(string)
+	q := question{ID: id, Type: typ, Instructions: instr}
+	switch typ {
+	case "choice":
+		opts, _ := m["options"].([]any)
+		if len(opts) == 0 {
+			return q, fmt.Sprintf("question %q: choice needs at least one option", id)
+		}
+		for _, o := range opts {
+			om, _ := o.(map[string]any)
+			name, _ := om["name"].(string)
+			var d *string
+			if s, ok := om["description"].(string); ok {
+				d = &s
+			}
+			q.Options = append(q.Options, option{name, d})
+		}
+	case "score":
+		lv, _ := m["levels"].([]any)
+		if len(lv) < 2 {
+			return q, fmt.Sprintf("question %q: score needs at least two levels", id)
+		}
+		for _, l := range lv {
+			s, _ := l.(string)
+			q.Levels = append(q.Levels, s)
+		}
+	case "noul":
+	default:
+		return q, fmt.Sprintf("question %q: type must be noul, choice or score", id)
+	}
+	return q, ""
+}
+
+func renderAnswers(r *response, qs []question) string {
+	lines := []string{"model " + r.Model}
+	for _, q := range qs {
+		a := r.Answers[q.ID]
+		text := describeAnswer(&a)
+		if a.Type == "choice" {
+			text = formatChoice(a)
+		}
+		lines = append(lines, fmt.Sprintf("%s: %s  <- %s", q.ID, text, q.Instructions))
+	}
+	if r.Usage != nil {
+		lines = append(lines, fmt.Sprintf("tokens %d in / %d out", int(r.Usage.Input), int(r.Usage.Output)))
+	}
+	return strings.Join(lines, "\n")
+}
+
+// detailAnswers is the answers as the judge sent them (the original's details.answers).
+func detailAnswers(r *response) map[string]any {
+	out := map[string]any{}
+	for id, a := range r.Answers {
+		probs := map[string]any{}
+		for _, p := range a.Probabilities {
+			probs[p.Name] = p.Value
+		}
+		switch a.Type {
+		case "noul":
+			out[id] = map[string]any{"type": "noul", "noul": a.Noul}
+		case "choice":
+			out[id] = map[string]any{"type": "choice", "choice": a.Choice, "confidence": a.Confidence, "probabilities": probs}
+		default:
+			out[id] = map[string]any{"type": "score", "score": a.Score, "confidence": a.Confidence, "legend": a.Legend, "probabilities": probs}
+		}
+	}
+	return out
+}

package/extensions/jev/ask_test.go

@@ -0,0 +1,218 @@
+package jev_test
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+)
+
+// jev_ask (src/index.ts registerTool, toQuestion, renderAnswers).
+
+func askHost(t *testing.T, body any, extra map[string]any) (*Host, *fakeJev) {
+	t.Helper()
+	e := newEnv(t)
+	t.Setenv("TYPESAFE_API_KEY", testKey)
+	srv := newFakeJev(t, always(body))
+	e.writeGlobal(t, jevConfig(srv, extra))
+	return start(t, e, newHostState(), HostOptions{}), srv
+}
+
+func askResult(t *testing.T, h *Host, params map[string]any) (string, map[string]any) {
+	t.Helper()
+	h.adoptDynamicTools()
+	raw, failure := h.Tool("jev_ask", params)
+	if failure != "" {
+		t.Fatalf("jev_ask failed: %s", failure)
+	}
+	var r struct {
+		Content json.RawMessage `json:"content"`
+		Details map[string]any  `json:"details"`
+	}
+	if err := json.Unmarshal(raw, &r); err != nil {
+		t.Fatalf("result %s: %v", raw, err)
+	}
+	var s string
+	if json.Unmarshal(r.Content, &s) != nil {
+		var blocks []struct {
+			Text string `json:"text"`
+		}
+		_ = json.Unmarshal(r.Content, &blocks)
+		for _, b := range blocks {
+			s += b.Text
+		}
+	}
+	return s, r.Details
+}
+
+func TestAsk_RegisteredOnlyWhenEnabledWithAKey(t *testing.T) {
+	e := newEnv(t)
+	h := start(t, e, newHostState(), HostOptions{})
+	if len(h.CallsTo("registerTool")) != 0 {
+		t.Error("jev_ask registered while Jev is off")
+	}
+}
+
+func TestAsk_RendersTypedAnswers(t *testing.T) {
+	body := map[string]any{"model": "jev-test", "usage": map[string]any{"input_tokens": 12, "output_tokens": 3}, "answers": map[string]any{
+		"relevant": noul(0.93),
+		"label": map[string]any{"type": "choice", "choice": "bug", "confidence": 0.9,
+			"probabilities": map[string]any{"feature": 0.1, "bug": 0.9}},
+		"quality": score(1.75, 0.8),
+	}}
+	h, srv := askHost(t, body, nil)
+	got, details := askResult(t, h, map[string]any{
+		"state": "the diff",
+		"questions": []any{
+			map[string]any{"id": "relevant", "type": "noul", "instructions": "Is this relevant?"},
+			map[string]any{"id": "label", "type": "choice", "instructions": "Which bucket?",
+				"options": []any{map[string]any{"name": "bug", "description": "Defect"}, map[string]any{"name": "feature"}}},
+			map[string]any{"id": "quality", "type": "score", "instructions": "How thorough?", "levels": []any{"Superficial", "Adequate", "Thorough"}},
+		},
+	})
+	want := strings.Join([]string{
+		"model jev-test",
+		"relevant: yes 0.93  <- Is this relevant?",
+		"label: bug (conf 0.90) [bug 0.90, feature 0.10]  <- Which bucket?",
+		"quality: 1.75/3 (conf 0.80)  <- How thorough?",
+		"tokens 12 in / 3 out",
+	}, "\n")
+	// Note: the legend in the score() fixture has four entries, so levels = 3.
+	if got != want {
+		t.Errorf("rendered:\n%s\nwant:\n%s", got, want)
+	}
+	if details["ok"] != true {
+		t.Errorf("details = %v", details)
+	}
+	req := srv.first(t)
+	if req.Body["state"] != "the diff" {
+		t.Errorf("state = %v", req.Body["state"])
+	}
+	qs := req.Body["questions"].(map[string]any)
+	label := qs["label"].(map[string]any)
+	crit := label["criteria"].(map[string]any)
+	if crit["bug"] != "Defect" || crit["feature"] != nil {
+		t.Errorf("choice criteria = %v (option without description must be null)", crit)
+	}
+	if _, has := crit["feature"]; !has {
+		t.Error("option without description must be sent as null, not omitted")
+	}
+	if lv := qs["quality"].(map[string]any)["criteria"].([]any); len(lv) != 3 {
+		t.Errorf("levels = %v", lv)
+	}
+	noulQ := qs["relevant"].(map[string]any)
+	if _, has := noulQ["criteria"]; has {
+		t.Errorf("noul question sent criteria: %v", noulQ)
+	}
+	if got := strings.Join(questionOrder(req.Raw), ","); got != "relevant,label,quality" {
+		t.Errorf("order = %s", got)
+	}
+}
+
+func TestAsk_InvalidQuestionShapesAreExplainedWithoutARequest(t *testing.T) {
+	h, srv := askHost(t, clearGate(), nil)
+	cases := map[string]struct {
+		q    map[string]any
+		want string
+	}{
+		"choice without options": {map[string]any{"id": "c", "type": "choice", "instructions": "x"}, `jev_ask: question "c": choice needs at least one option`},
+		"choice empty options":   {map[string]any{"id": "c", "type": "choice", "instructions": "x", "options": []any{}}, `jev_ask: question "c": choice needs at least one option`},
+		"score one level":        {map[string]any{"id": "s", "type": "score", "instructions": "x", "levels": []any{"only"}}, `jev_ask: question "s": score needs at least two levels`},
+		"score no levels":        {map[string]any{"id": "s", "type": "score", "instructions": "x"}, `jev_ask: question "s": score needs at least two levels`},
+	}
+	for name, c := range cases {
+		got, details := askResult(t, h, map[string]any{"state": "s", "questions": []any{c.q}})
+		if got != c.want || details["ok"] != false {
+			t.Errorf("%s: got %q details %v, want %q", name, got, details, c.want)
+		}
+	}
+	if srv.count() != 0 {
+		t.Errorf("requests = %d", srv.count())
+	}
+}
+
+func TestAsk_BlankInstructionsAndNoQuestionsAreRefused(t *testing.T) {
+	h, srv := askHost(t, clearGate(), nil)
+	got, _ := askResult(t, h, map[string]any{"state": "s", "questions": []any{map[string]any{"id": "a", "type": "noul", "instructions": "  "}}})
+	if got != `jev_ask: question "a": instructions are required` {
+		t.Errorf("blank instructions: %q", got)
+	}
+	got, _ = askResult(t, h, map[string]any{"state": "s", "questions": []any{}})
+	if got != "jev_ask: no questions provided" {
+		t.Errorf("no questions: %q", got)
+	}
+	if srv.count() != 0 {
+		t.Errorf("requests = %d", srv.count())
+	}
+}
+
+// C8: the original let a duplicate id silently replace the earlier question.
+func TestCorrection_DuplicateQuestionIdIsRefused(t *testing.T) {
+	h, srv := askHost(t, clearGate(), nil)
+	q := map[string]any{"id": "a", "type": "noul", "instructions": "x"}
+	got, _ := askResult(t, h, map[string]any{"state": "s", "questions": []any{q, q}})
+	if got != `jev_ask: duplicate question id "a"` || srv.count() != 0 {
+		t.Errorf("got %q, requests %d", got, srv.count())
+	}
+}
+
+func TestAsk_ServerErrorIsReportedNotThrown(t *testing.T) {
+	h, _ := askHost(t, "x", nil)
+	e := newEnv(t)
+	t.Setenv("TYPESAFE_API_KEY", testKey)
+	srv := newFakeJev(t, func(int, recordedRequest) jevReply { return jevReply{status: 401, body: "denied " + testKey} })
+	e.writeGlobal(t, jevConfig(srv, nil))
+	h = start(t, e, newHostState(), HostOptions{})
+	got, details := askResult(t, h, map[string]any{"state": "s", "questions": []any{map[string]any{"id": "a", "type": "noul", "instructions": "x"}}})
+	if !strings.HasPrefix(got, "jev_ask: ") || !strings.Contains(got, "401") || strings.Contains(got, testKey) || !strings.Contains(got, "[redacted]") || details["ok"] != false {
+		t.Errorf("got %q %v", got, details)
+	}
+}
+
+func TestAsk_MissingAnswerIsAnErrorNotAVerdict(t *testing.T) {
+	h, _ := askHost(t, map[string]any{"model": "m", "answers": map[string]any{}}, nil)
+	got, details := askResult(t, h, map[string]any{"state": "s", "questions": []any{map[string]any{"id": "a", "type": "noul", "instructions": "x"}}})
+	if !strings.HasPrefix(got, "jev_ask: ") || !strings.Contains(got, `did not answer "a"`) || details["ok"] != false {
+		t.Errorf("got %q %v", got, details)
+	}
+}
+
+func TestAsk_AnswerForAnotherTypeIsAnError(t *testing.T) {
+	h, _ := askHost(t, map[string]any{"model": "m", "answers": map[string]any{"a": score(1, 0.5)}}, nil)
+	got, _ := askResult(t, h, map[string]any{"state": "s", "questions": []any{map[string]any{"id": "a", "type": "noul", "instructions": "x"}}})
+	if !strings.Contains(got, `"a" is not a noul`) {
+		t.Errorf("got %q", got)
+	}
+}
+
+func TestAsk_HonoursOff(t *testing.T) {
+	h, srv := askHost(t, clearGate(), nil)
+	if failure := h.Command("jev", "off"); failure != "" {
+		t.Fatal(failure)
+	}
+	got, details := askResult(t, h, map[string]any{"state": "s", "questions": []any{map[string]any{"id": "a", "type": "noul", "instructions": "x"}}})
+	if srv.count() != 0 || details["ok"] != false || !strings.Contains(got, "off") {
+		t.Errorf("jev_ask sent content while Jev is off: %q %v (%d requests)", got, details, srv.count())
+	}
+}
+
+func TestAsk_ToolMetadata(t *testing.T) {
+	h, _ := askHost(t, clearGate(), nil)
+	calls := h.CallsTo("registerTool")
+	if len(calls) != 1 {
+		t.Fatalf("registerTool calls = %d", len(calls))
+	}
+	a := calls[0].Args
+	if a["name"] != "jev_ask" || a["label"] != "Jev Ask" {
+		t.Errorf("tool = %v", a)
+	}
+	mustContain(t, "description", a["description"].(string), "typed questions", "calibrated answers")
+}
+
+func TestCorrection_AskStateIsCappedAtMaxStateChars(t *testing.T) {
+	h, srv := askHost(t, map[string]any{"model": "m", "answers": map[string]any{"a": noul(0.5)}}, map[string]any{"maxStateChars": 100})
+	askResult(t, h, map[string]any{"state": strings.Repeat("s", 500), "questions": []any{map[string]any{"id": "a", "type": "noul", "instructions": "x"}}})
+	got, _ := srv.first(t).Body["state"].(string)
+	if got != strings.Repeat("s", 100)+"…[400 chars elided]" {
+		t.Errorf("state = %q", got)
+	}
+}