dotclaude-jev

1// The hooks module of dotclaude-jev.
2// It acts on the session note in `hooks/session-start/second-opinion.md`:
3// Jev picks before the user answers a question with options.
4// On each `AskUserQuestion`, the hook runs `jev.mjs ask` once. Jev sorts each
5// question into preference or facts, and picks from its options. A facts
6// question shows the pick of Jev and its confidence to the user. A question
7// about a goal, a preference, or an approval stays as it is. The hook never
8// denies, so Claude has no reason to ask in plain text instead. Without
9// `TYPESAFE_API_KEY`, or when Jev fails, the question passes unchanged.
10
11/** Under this confidence, the TypeSafe docs treat an answer as uncertain. */
12const MIN_CONFIDENCE = 0.5;
13const JEV_TIMEOUT_MS = 45000;
14
15const KIND = {
16  type: "choice",
17  instructions:
18    "Only the user can answer some questions. Facts decide others. Which is this question?",
19  criteria: {
20    preference:
21      "A goal, a preference, an approval, or a choice that reasonable engineers make either way",
22    facts:
23      "Correctness, security, data loss, performance, or maintenance cost decide the answer",
24  },
25};
26
27/** The Jev request for the questions that have 2 or more options. */
28export function jevRequest(questions) {
29  const asked = {};
30  const state = [];
31  questions.forEach((q, i) => {
32    const options = Array.isArray(q?.options) ? q.options : [];
33    if (options.length < 2) return;
34    state.push(
35      `Question ${i}: ${q.question}`,
36      ...options.map((o) => `- ${o.label}: ${o.description ?? ""}`),
37    );
38    asked[`kind_${i}`] = {
39      ...KIND,
40      instructions: `${KIND.instructions} (question ${i})`,
41    };
42    asked[`pick_${i}`] = {
43      type: "choice",
44      instructions: `Which option is the best answer to question ${i}?`,
45      criteria: Object.fromEntries(
46        options.map((o) => [o.label, o.description || o.label]),
47      ),
48    };
49  });
50  return Object.keys(asked).length
51    ? { state: state.join("\n"), questions: asked }
52    : null;
53}
54
55/** The questions with the pick of Jev added to each facts question. */
56export function withPicks(questions, answers) {
57  return questions.map((q, i) => {
58    const kind = answers?.[`kind_${i}`];
59    const pick = answers?.[`pick_${i}`];
60    if (
61      kind?.choice !== "facts" ||
62      !(kind.confidence >= MIN_CONFIDENCE) ||
63      !(pick?.confidence >= MIN_CONFIDENCE) ||
64      !q.options.some((o) => o.label === pick.choice)
65    )
66      return q;
67    const note = `Jev picks "${pick.choice}" (confidence ${pick.confidence.toFixed(2)}).`;
68    return { ...q, question: `${q.question}\n\n${note}` };
69  });
70}
71
72export function register(on) {
73  on("tool.call", async ($, e, next) => {
74    if (e.tool !== "AskUserQuestion" || !Array.isArray(e.questions))
75      return next(e);
76    try {
77      if (!(await $.env.get("TYPESAFE_API_KEY"))) return next(e);
78      const request = jevRequest(e.questions);
79      if (!request) return next(e);
80      const run = await $.process.run(
81        [
82          "node",
83          `${$.plugin.root}/skills/second-opinion/scripts/jev.mjs`,
84          "ask",
85          "--state",
86          request.state,
87        ],
88        {
89          stdin: JSON.stringify({ questions: request.questions }),
90          timeoutMs: JEV_TIMEOUT_MS,
91        },
92      );
93      if (run.exitCode !== 0) return next(e);
94      const questions = withPicks(e.questions, JSON.parse(run.stdout));
95      return next({ ...e, questions });
96    } catch {
97      // Jev is missing, slow, or gave output that is not valid.
98      return next(e);
99    }
100  });
101}
102