From 3170b2c86b016c5357f613ff47cdb7d98c6d4532 Mon Sep 17 00:00:00 2001
From: vivekchand <vivekchand19@gmail.com>
Date: Sun, 30 Aug 2026 02:29:51 +0200
Subject: [PATCH 1/2] =?UTF-8?q?feat(approvals):=20question-set=20approvals?=
 =?UTF-8?q?=20=E2=80=94=20decisions=20beyond=20yes/no=20(WO-52=20phase=201?=
 =?UTF-8?q?)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Approvals were strictly binary approve/deny. This adds "question set"
approvals end-to-end for the LOCAL product, with Claude Code's
AskUserQuestion tool as the first source:

* clawmetry/question_sets.py (new) — shared vocabulary: sanitize the
  1-4-question set from the PreToolUse payload, strictly validate
  structured answers against it (unknown question / unknown option label
  are rejected; multiSelect takes label arrays; free text only when the
  question set says so), merge winning answers into updatedInput, and the
  shared decision-wall core (answers land in args["_cm_answers"] BEFORE
  the row flips to decision='answered', so a waiting hook never sees the
  status without the answers). Storage is migration-free: the set rides
  in args["_cm_questions"] (the _cm_risk precedent).

* routes/hooks.py — the PreToolUse receiver intercepts AskUserQuestion
  before policy matching, parks a question-set row (on_timeout="ask"),
  and answers an 'answered' row with permissionDecision=allow +
  hookSpecificOutput.updatedInput = tool_input + answers. Every failure
  mode — window elapsed, expired row, malformed payload, unreadable
  answers, store down — falls back to "ask" (the terminal prompt), NEVER
  the binary on_timeout=deny default and NEVER a fabricated answer.
  CLAWMETRY_QUESTION_GATE=0 kills the intercept;
  CLAWMETRY_QUESTION_WINDOW_S overrides the window (default: the mirror
  window, 180 s). The hook client already forwards hookSpecificOutput
  verbatim, so no client change was needed.

* routes/policy.py + routes/hitl.py — both local decision walls accept
  decision='answer' carrying the answers map (validated → 400 on unknown
  labels/questions; first-click-wins preserved via
  update_approval_decision). GET /api/approvals now serves the full
  question set per row; the audit summary counts 'answered'.

* clawmetry/claude_code_gate.py — the installed PreToolUse matcher also
  watches AskUserQuestion whenever the gate is armed, and the hook
  timeout is floored at the question window + buffer so Claude Code
  never cancels the hook before the receiver's "ask" fallback lands.

* clawmetry/templates/tabs/approvals.html — pending question rows render
  full fidelity (radios / checkboxes / free-text when flagged, count +
  headers chip) with a single "Send answers" button posting
  decision='answer'; binary rows are untouched.

* tests/test_question_set_approvals.py (23 tests) — validation 400s,
  multiSelect round-trip, first-click-wins on structured answers, binary
  regression through both walls, gate intercept → updatedInput, expiry →
  "ask". Two exact-matcher assertions in
  tests/test_runtime_gates_and_hooks.py updated for the widened matcher.

Excluded from this phase: cloud/pro decision walls, Telegram/phone
question fidelity (phase 2).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017VCaSBpV1wBCKrU4z9MKKZ
---
 clawmetry/claude_code_gate.py           |  35 ++
 clawmetry/question_sets.py              | 231 ++++++++++
 clawmetry/templates/tabs/approvals.html | 111 ++++-
 routes/hitl.py                          |  46 +-
 routes/hooks.py                         | 246 +++++++++--
 routes/policy.py                        |  59 ++-
 tests/test_question_set_approvals.py    | 540 ++++++++++++++++++++++++
 tests/test_runtime_gates_and_hooks.py   |  14 +-
 8 files changed, 1232 insertions(+), 50 deletions(-)
 create mode 100644 clawmetry/question_sets.py
 create mode 100644 tests/test_question_set_approvals.py

diff --git a/clawmetry/claude_code_gate.py b/clawmetry/claude_code_gate.py
index 93cd5fd810..6fcb0df0c2 100644
--- a/clawmetry/claude_code_gate.py
+++ b/clawmetry/claude_code_gate.py
@@ -168,6 +168,27 @@ def _add(fragment: str) -> None:
     return "|".join(parts) if parts else "Bash"
 
 
+def _question_gate_enabled() -> bool:
+    """Question-set approvals (WO-52): on by default, one env var off."""
+    return os.environ.get("CLAWMETRY_QUESTION_GATE", "1").strip() != "0"
+
+
+def _question_window_s() -> int:
+    """Mirror of routes.hooks._question_window_s (stdlib-only fast path
+    must not import Flask modules): env override → mirror window → 180 s."""
+    raw = os.environ.get("CLAWMETRY_QUESTION_WINDOW_S", "").strip()
+    if raw:
+        try:
+            return max(10, int(raw))
+        except ValueError:
+            pass
+    try:
+        from clawmetry import approval_events as _ae
+        return int(_ae.mirror_window_s("claude_code"))
+    except Exception:
+        return 180
+
+
 def _timeout_from_policies(policies) -> int:
     """Hook timeout: the longest matching policy window + buffer, so the
     receiver's own on_timeout mapping always answers first."""
@@ -544,6 +565,20 @@ def _install(policies) -> None:
     command = _hook_command(base)
     matcher = _matcher_from_policies(policies)
     timeout = _timeout_from_policies(policies)
+    # Question-set approvals (WO-52 phase 1): whenever the gate is armed,
+    # also watch AskUserQuestion so the receiver can mirror the runtime's
+    # structured questions to the dashboard, which answers with the actual
+    # option labels (hookSpecificOutput.updatedInput). No answer inside the
+    # question window → the receiver replies "ask" and the terminal prompt
+    # takes over, exactly today's flow. CLAWMETRY_QUESTION_GATE=0 opts out.
+    if _question_gate_enabled():
+        if "AskUserQuestion" not in matcher.split("|"):
+            matcher = f"{matcher}|AskUserQuestion"
+        # The hook timeout must outlive the question window, or Claude Code
+        # cancels the hook before our own "ask" fallback lands and the
+        # parked row is left pending with nobody waiting on it.
+        timeout = max(timeout, hook_ownership.clamp_hook_timeout(
+            _question_window_s() + _HOOK_TIMEOUT_BUFFER_S))
     desired = {
         "matcher": matcher,
         "hooks": [{"type": "command", "command": command,
diff --git a/clawmetry/question_sets.py b/clawmetry/question_sets.py
new file mode 100644
index 0000000000..cfbf944e5b
--- /dev/null
+++ b/clawmetry/question_sets.py
@@ -0,0 +1,231 @@
+"""Question-set approvals — decisions beyond yes/no (WO-52, phase 1).
+
+Approvals were strictly binary (approve/deny). Claude Code's
+``AskUserQuestion`` tool carries a structured question set — 1-4 questions,
+each with a short ``header``, 2-4 labelled ``options`` and an optional
+``multiSelect`` flag — and its PreToolUse hook is allowed to answer with
+``hookSpecificOutput.updatedInput`` = the original ``tool_input`` plus
+``answers: {"<question text>": "<option label>"}`` (a list of labels for
+multiSelect questions); the session then resumes with those answers as if
+the human had picked them in the terminal.
+
+This module is the shared vocabulary for that flow:
+
+* the hook receiver (``routes/hooks.py``) sanitizes and parks the set,
+* the decision walls (``routes/policy.py`` ``/api/approvals/<id>/decide``
+  and ``routes/hitl.py`` ``/api/hitl/decide``) validate structured answers
+  against the stored set and flip the row,
+* the receiver merges the winning answers back into the tool input.
+
+Storage is migration-free: everything rides in the approvals row's ``args``
+BLOB under namespaced keys (the ``_cm_risk`` precedent):
+
+  ``args["_cm_questions"]`` — the sanitized question set (list of dicts:
+      ``question`` / ``header`` / ``options: [{label, description}]`` /
+      ``multiSelect`` / optional ``allow_free_text``).
+  ``args["_cm_answers"]``   — the structured answers map, written by the
+      decision wall immediately BEFORE it flips the row to
+      ``decision='answered'`` (status ``answered``), so a hook waiting on
+      the row never observes the answered status without the answers.
+
+Validation is strict by design: an answered question must exist in the
+stored set and every selected label must be one of that question's option
+labels — unless the question itself carries a truthy free-text flag
+(``allow_free_text`` / ``allowFreeText``), in which case any non-empty
+string is accepted ("a free-text input when the question set says so").
+
+Safety contract (mirrors the receiver's): a question-set approval that
+expires or fails NEVER fabricates or defaults an answer and never follows
+the binary ``on_timeout=deny`` default — the fallback is always ``ask``,
+i.e. the runtime's own terminal prompt, exactly today's behaviour.
+"""
+from __future__ import annotations
+
+MAX_QUESTIONS = 4
+MAX_OPTIONS = 4
+
+_FREE_TEXT_KEYS = ("allow_free_text", "allowFreeText", "free_text",
+                   "freeText", "allowOther")
+
+
+def _free_text_allowed(question: dict) -> bool:
+    return any(bool(question.get(k)) for k in _FREE_TEXT_KEYS)
+
+
+def sanitize_question_set(tool_input) -> "list[dict] | None":
+    """Normalise an AskUserQuestion ``tool_input`` into the stored shape.
+
+    Returns a list of clean question dicts, or ``None`` when the payload
+    carries nothing usable (the caller then answers ``ask`` — the terminal
+    prompt handles whatever we could not understand). Lenient on extras,
+    strict on shape: unknown keys are dropped, questions without text are
+    skipped, options are capped at ``MAX_OPTIONS`` with non-string /
+    unlabelled entries discarded.
+    """
+    if not isinstance(tool_input, dict):
+        return None
+    raw = tool_input.get("questions")
+    if not isinstance(raw, list) or not raw:
+        return None
+    out: list[dict] = []
+    for q in raw[:MAX_QUESTIONS]:
+        if not isinstance(q, dict):
+            continue
+        text = str(q.get("question") or "").strip()
+        if not text:
+            continue
+        options: list[dict] = []
+        raw_opts = q.get("options")
+        if isinstance(raw_opts, list):
+            for o in raw_opts[:MAX_OPTIONS]:
+                if isinstance(o, dict):
+                    label = str(o.get("label") or "").strip()
+                    if not label:
+                        continue
+                    options.append({
+                        "label": label,
+                        "description": str(o.get("description") or ""),
+                    })
+                elif isinstance(o, str) and o.strip():
+                    options.append({"label": o.strip(), "description": ""})
+        entry = {
+            "question": text,
+            "header": str(q.get("header") or "").strip(),
+            "options": options,
+            "multiSelect": bool(q.get("multiSelect")),
+        }
+        if _free_text_allowed(q):
+            entry["allow_free_text"] = True
+        out.append(entry)
+    return out or None
+
+
+def question_summary(questions: list) -> str:
+    """One-line preview for the row's ``action`` string and pending chip."""
+    heads = []
+    for q in questions or []:
+        if not isinstance(q, dict):
+            continue
+        head = str(q.get("header") or q.get("question") or "").strip()
+        if head:
+            heads.append(head[:40])
+    n = len(questions or [])
+    label = "question" if n == 1 else "questions"
+    return f"{n} {label}" + (f" — {'; '.join(heads)}" if heads else "")
+
+
+def validate_answers(questions, answers) -> "str | None":
+    """Validate a structured answers map against the stored question set.
+
+    Returns an error string (the decision wall turns it into a 400), or
+    ``None`` when the answers are acceptable. Rules:
+
+    * ``answers`` must be a non-empty object keyed by question text;
+    * every answered question must exist in the stored set;
+    * a single-choice question takes one string; a multiSelect question
+      takes a string or a non-empty list of strings;
+    * every selected label must exist among that question's options,
+      unless the question allows free text.
+
+    Partial answer maps are allowed (only what is answered is validated) —
+    the UI enforces completeness before submitting; the wall enforces
+    correctness of what arrives.
+    """
+    if not isinstance(questions, list) or not questions:
+        return "no stored question set to validate against"
+    if not isinstance(answers, dict) or not answers:
+        return "answers must be a non-empty object keyed by question text"
+    by_text = {str(q.get("question")): q for q in questions
+               if isinstance(q, dict) and q.get("question")}
+    for qtext, value in answers.items():
+        q = by_text.get(str(qtext))
+        if q is None:
+            return f"unknown question: {str(qtext)[:80]!r}"
+        labels = {o.get("label") for o in (q.get("options") or [])
+                  if isinstance(o, dict) and o.get("label")}
+        free = _free_text_allowed(q)
+        if isinstance(value, list):
+            if not q.get("multiSelect"):
+                return (f"question {str(qtext)[:60]!r} is single-choice — "
+                        "the answer must be a string, not a list")
+            if not value:
+                return f"question {str(qtext)[:60]!r}: empty selection"
+            picked = value
+        else:
+            picked = [value]
+        for label in picked:
+            if not isinstance(label, str) or not label.strip():
+                return (f"question {str(qtext)[:60]!r}: every answer must "
+                        "be a non-empty string")
+            if label not in labels and not free:
+                return (f"unknown option {label[:60]!r} for question "
+                        f"{str(qtext)[:60]!r}")
+    return None
+
+
+def merge_answers_into_input(tool_input, answers) -> dict:
+    """The ``updatedInput`` the hook replies with: original tool input plus
+    the ``answers`` map (labels as strings, multiSelect as lists)."""
+    merged = dict(tool_input) if isinstance(tool_input, dict) else {}
+    merged["answers"] = {
+        str(k): (list(v) if isinstance(v, list) else str(v))
+        for k, v in dict(answers).items()
+    }
+    return merged
+
+
+def answers_summary(questions, answers) -> str:
+    """Human-readable one-liner for ``decision_reason`` / audit log."""
+    parts = []
+    for q in questions or []:
+        if not isinstance(q, dict):
+            continue
+        value = (answers or {}).get(q.get("question"))
+        if value is None:
+            continue
+        head = str(q.get("header") or q.get("question") or "").strip()[:40]
+        text = ", ".join(str(v) for v in value) if isinstance(value, list) \
+            else str(value)
+        parts.append(f"{head}: {text[:80]}" if head else text[:80])
+    return ("answered — " + "; ".join(parts))[:290] if parts else "answered"
+
+
+def apply_answer_decision(approval_id, row, answers, *, resolver,
+                          reason, write) -> "tuple[bool, str, int]":
+    """Shared decision-wall core for ``decision='answer'``.
+
+    ``write(method_name, **kwargs) -> bool`` is the caller's store writer
+    (daemon-proxy first — e.g. ``routes.hooks._ls_write``). Returns
+    ``(ok, status_or_error, http_code)``.
+
+    Write order matters: the answers are merged into ``args`` while the row
+    is still pending, and only then is the row flipped to ``answered`` via
+    ``update_approval_decision`` (first-click-wins). A hook polling the row
+    therefore never sees the answered status without ``_cm_answers``. The
+    flip only ever transitions a *pending* row, so a racing binary decision
+    keeps its result; callers re-read the row afterwards to report what
+    actually stands.
+    """
+    args = row.get("args") if isinstance(row.get("args"), dict) else {}
+    questions = args.get("_cm_questions")
+    if not isinstance(questions, list) or not questions:
+        return (False,
+                "not a question-set approval (no stored question set)", 400)
+    err = validate_answers(questions, answers)
+    if err:
+        return False, err, 400
+    merged = dict(args)
+    merged["_cm_answers"] = {
+        str(k): (list(v) if isinstance(v, list) else str(v))
+        for k, v in answers.items()
+    }
+    # Answers land in args BEFORE the status flips (see docstring). The
+    # upsert re-states the pre-checked 'pending' status; the authoritative
+    # transition is the update_approval_decision below.
+    if not write("ingest_approval", approval={
+            "id": str(approval_id), "args": merged, "status": "pending"}):
+        return False, "answer write failed (approval store unavailable)", 500
+    summary = str(reason or answers_summary(questions, answers))[:300]
+    write("update_approval_decision", approval_id=str(approval_id),
+          decision="answered", resolver=resolver, reason=summary)
+    return True, "answered", 200
diff --git a/clawmetry/templates/tabs/approvals.html b/clawmetry/templates/tabs/approvals.html
index ba590cd14b..9c54f1d1bd 100644
--- a/clawmetry/templates/tabs/approvals.html
+++ b/clawmetry/templates/tabs/approvals.html
@@ -439,6 +439,78 @@
     } catch(e) { alert('Failed: ' + e); }
   };
 
+  /* ── Question-set approvals (WO-52 phase 1) ──
+   * A row whose args carry _cm_questions (served as `questions` by
+   * /api/approvals) is a structured question from the runtime — Claude
+   * Code's AskUserQuestion tool first. Render it full-fidelity and post
+   * decision='answer' with an answers map keyed by question text; the
+   * blocked PreToolUse hook resumes the session with those answers.
+   */
+  var _questionSets = {};   // approval id -> question set (rebuilt per render)
+
+  function _escAttr(s) { return escHtml(s).replace(/"/g, '&quot;'); }
+
+  function _renderQuestion(id, q, qi) {
+    var name = 'qa-' + escHtml(id) + '-' + qi;
+    var html = '<div style="margin-top:8px;padding:10px 12px;background:var(--bg-primary);border:1px solid var(--border-secondary);border-radius:8px;">';
+    html += '<div style="font-size:12px;font-weight:700;color:var(--text-primary);margin-bottom:6px;">'
+      + (q.header ? '<span style="background:rgba(59,130,246,0.15);color:#60a5fa;border-radius:4px;padding:1px 6px;font-size:10px;margin-right:6px;">' + escHtml(q.header) + '</span>' : '')
+      + escHtml(q.question)
+      + (q.multiSelect ? ' <span style="font-size:10px;color:var(--text-muted);font-weight:400;">(select all that apply)</span>' : '')
+      + '</div>';
+    var type = q.multiSelect ? 'checkbox' : 'radio';
+    (q.options || []).forEach(function(o) {
+      html += '<label style="display:flex;align-items:flex-start;gap:8px;margin:4px 0;cursor:pointer;">'
+        + '<input type="' + type + '" name="' + name + '" value="' + _escAttr(o.label) + '" style="margin-top:3px;cursor:pointer;">'
+        + '<span><span style="font-size:12px;color:var(--text-primary);">' + escHtml(o.label) + '</span>'
+        + (o.description ? '<span style="display:block;font-size:11px;color:var(--text-muted);">' + escHtml(o.description) + '</span>' : '')
+        + '</span></label>';
+    });
+    if (q.allow_free_text) {
+      html += '<input type="text" id="qa-ft-' + escHtml(id) + '-' + qi + '" placeholder="Or type your own answer…" style="width:100%;box-sizing:border-box;margin-top:6px;padding:6px 10px;border:1px solid var(--border-secondary);border-radius:6px;background:var(--bg-secondary);color:var(--text-primary);font-size:12px;">';
+    }
+    return html + '</div>';
+  }
+
+  window.sendQuestionAnswers = async function(id) {
+    var qs = _questionSets[id] || [];
+    if (!qs.length) { alert('Question set is no longer available — refresh.'); return; }
+    var answers = {};
+    for (var qi = 0; qi < qs.length; qi++) {
+      var q = qs[qi];
+      var name = 'qa-' + id + '-' + qi;
+      var ft = document.getElementById('qa-ft-' + id + '-' + qi);
+      var ftVal = ft && ft.value ? ft.value.trim() : '';
+      if (q.multiSelect) {
+        var picked = [].slice.call(document.querySelectorAll('input[name="' + name + '"]:checked'))
+          .map(function(el){ return el.value; });
+        if (ftVal) picked.push(ftVal);
+        if (!picked.length) { alert('Please answer: ' + q.question); return; }
+        answers[q.question] = picked;
+      } else {
+        var sel = document.querySelector('input[name="' + name + '"]:checked');
+        var val = sel ? sel.value : ftVal;
+        if (!val) { alert('Please answer: ' + q.question); return; }
+        answers[q.question] = val;
+      }
+    }
+    var reasonEl = document.getElementById('dec-reason-' + id);
+    var reason = reasonEl && reasonEl.value ? reasonEl.value.trim() : '';
+    try {
+      var body = {decision: 'answer', answers: answers};
+      if (reason) body.reason = reason;
+      var r = await fetch('/api/approvals/' + encodeURIComponent(id) + '/decide', {
+        method: 'POST', headers: {'Content-Type': 'application/json'},
+        body: JSON.stringify(body)
+      });
+      var d = await r.json();
+      if (!r.ok) throw new Error(d.error || ('HTTP ' + r.status));
+      loadApprovalsTab();
+    } catch (e) {
+      alert('Sending answers failed: ' + e);
+    }
+  };
+
   /* ── Approval row renderer ──
    * Phase 1.2 (#1343): richer per-row context.
    *   - Pretty-printed args (2-space indent, capped at 800 chars vs old 200)
@@ -447,8 +519,13 @@
    */
   function _renderRow(r, pending) {
     var statusColors = {pending:'#f59e0b', approved:'#22c55e', denied:'#ef4444',
-                        timeout:'#6b7280', expired:'#6b7280'};
+                        answered:'#3b82f6', timeout:'#6b7280', expired:'#6b7280'};
     var c = statusColors[r.status] || '#6b7280';
+    // Question-set rows (WO-52): the runtime asked a structured question;
+    // pending ones render the actual options + a "Send answers" submit.
+    var qSet = (r.questions && r.questions.length) ? r.questions : null;
+    var isQuestionRow = !!(qSet && pending);
+    if (isQuestionRow) _questionSets[r.id] = qSet;
     var argsPretty = '';
     try {
       if (r.args === undefined && r.args_preview) {
@@ -476,6 +553,13 @@
       // Not one of the user's rules: the runtime itself stopped to ask.
       html += '<span style="background:rgba(139,92,246,0.15);color:#a78bfa;border:1px solid rgba(139,92,246,0.35);padding:1px 8px;border-radius:99px;font-size:10px;font-weight:700;">asked by the agent</span>';
     }
+    if (qSet) {
+      // Pending chip: question count + headers, so the queue scans well.
+      var qHeads = qSet.map(function(q){return q.header || '';}).filter(Boolean).join(' · ');
+      html += '<span style="background:rgba(59,130,246,0.15);color:#60a5fa;border:1px solid rgba(59,130,246,0.35);padding:1px 8px;border-radius:99px;font-size:10px;font-weight:700;">'
+        + qSet.length + (qSet.length === 1 ? ' question' : ' questions')
+        + (qHeads ? ' · ' + escHtml(qHeads).slice(0, 60) : '') + '</span>';
+    }
     if (r.risk && r.risk.level) {
       var riskColors = {low:'#6b7280', medium:'#f59e0b', high:'#f97316', critical:'#ef4444'};
       var rc = riskColors[r.risk.level] || '#6b7280';
@@ -496,8 +580,26 @@
     if (r.context) {
       html += '<div style="font-size:12px;color:var(--text-secondary);margin-bottom:6px;" data-i18n="app.eschtml_r_context">' + escHtml(r.context) + '</div>';
     }
-    html += '<pre style="margin:0;padding:8px 10px;font-size:11px;background:var(--bg-primary);border:1px solid var(--border-secondary);border-radius:6px;overflow:auto;max-height:200px;color:var(--text-secondary);white-space:pre-wrap;word-break:break-word;">' + escHtml(argsPretty) + '</pre>';
-    if (pending) {
+    if (isQuestionRow) {
+      // Full-fidelity question form: radios for single-choice, checkboxes
+      // for multiSelect, a free-text input when the question set says so.
+      html += qSet.map(function(q, qi){ return _renderQuestion(r.id, q, qi); }).join('');
+    } else {
+      html += '<pre style="margin:0;padding:8px 10px;font-size:11px;background:var(--bg-primary);border:1px solid var(--border-secondary);border-radius:6px;overflow:auto;max-height:200px;color:var(--text-secondary);white-space:pre-wrap;word-break:break-word;">' + escHtml(argsPretty) + '</pre>';
+    }
+    if (pending && isQuestionRow) {
+      html += '<div style="margin-top:10px;">';
+      html += '<input type="text" id="dec-reason-' + escHtml(r.id) + '" placeholder="Note (optional — recorded in audit log)" style="width:100%;box-sizing:border-box;padding:6px 10px;border:1px solid var(--border-secondary);border-radius:6px;background:var(--bg-primary);color:var(--text-primary);font-size:12px;">';
+      html += '</div>';
+      html += '<div style="display:flex;gap:8px;margin-top:8px;flex-wrap:wrap;">';
+      html += '<button onclick="sendQuestionAnswers(\'' + escHtml(r.id) + '\')" style="background:#3b82f6;color:#fff;border:0;padding:7px 16px;border-radius:6px;font-weight:600;font-size:12px;cursor:pointer;">Send answers</button>';
+      html += '<button onclick="decideApproval(\'' + escHtml(r.id) + '\',\'approve\')" title="Skip answering here — the question appears in the terminal instead" style="background:var(--bg-primary);color:var(--text-secondary);border:1px solid var(--border-secondary);padding:7px 12px;border-radius:6px;font-weight:600;font-size:12px;cursor:pointer;">Answer in terminal</button>';
+      html += '<button onclick="decideApproval(\'' + escHtml(r.id) + '\',\'deny\')" style="background:transparent;color:#ef4444;border:1px solid #ef444444;padding:7px 12px;border-radius:6px;font-weight:600;font-size:12px;cursor:pointer;" data-i18n="app.deny">Deny</button>';
+      if (r.expires_at) {
+        html += '<span style="color:var(--text-muted);font-size:11px;align-self:center;margin-left:6px;">expires ' + escHtml((r.expires_at||'').slice(11,19)) + '</span>';
+      }
+      html += '</div>';
+    } else if (pending) {
       html += '<div style="margin-top:10px;">';
       html += '<input type="text" id="dec-reason-' + escHtml(r.id) + '" placeholder="Reason (optional — recorded in audit log)" style="width:100%;box-sizing:border-box;padding:6px 10px;border:1px solid var(--border-secondary);border-radius:6px;background:var(--bg-primary);color:var(--text-primary);font-size:12px;">';
       html += '</div>';
@@ -540,7 +642,8 @@
       session_id: r.requestor_session_id,
       args_preview: r.args_preview,
       risk: r.risk,
-      kind: r.kind
+      kind: r.kind,
+      questions: r.questions
     };
   }
   function _mapLocalDecision(r) {
diff --git a/routes/hitl.py b/routes/hitl.py
index c94fd7652e..c9777bc672 100644
--- a/routes/hitl.py
+++ b/routes/hitl.py
@@ -136,13 +136,55 @@ def hitl_decide():
 
     if not session_id:
         return jsonify({"error": "session_id required"}), 400
-    if decision not in ("approve", "reject"):
-        return jsonify({"error": "decision must be 'approve' or 'reject'"}), 400
+    if decision not in ("approve", "reject", "answer"):
+        return jsonify({"error": "decision must be 'approve', 'reject' "
+                                 "or 'answer'"}), 400
 
     flag = _flag_path(session_id)
     if not flag.exists():
         return jsonify({"error": "session not flagged for HITL"}), 404
 
+    # ── question-set answers (WO-52 phase 1) ─────────────────────────────
+    # decision='answer' carries a structured ``answers`` map validated
+    # against the question set stored in the approval row's args
+    # (default row id: hitl_<session_id>; unknown question / option → 400).
+    # An accepted answer unblocks the session exactly like an approve.
+    if decision == "answer":
+        approval_id = (data.get("approval_id")
+                       or f"hitl_{session_id}").strip()
+        rows = _try_store_call("query_approvals", limit=500)
+        if isinstance(rows, dict):
+            rows = rows.get("result") or rows.get("rows") or []
+        rows = rows if isinstance(rows, list) else []
+        row = next((r for r in rows if r.get("id") == approval_id), None)
+        if row is None:
+            return jsonify({"error": "unknown approval id"}), 404
+        from clawmetry import question_sets as qsets
+        from routes.hooks import _ls_write as _writer
+        ok, msg, code = qsets.apply_answer_decision(
+            approval_id, row, data.get("answers"), resolver=operator,
+            reason=(reason or None), write=_writer)
+        if not ok:
+            return jsonify({"error": msg}), code
+        flag.unlink()
+        log.info("HITL answer: session=%s approval=%s operator=%s",
+                 session_id, approval_id, operator)
+        try:
+            from clawmetry import audit as _audit
+            _audit.audit_event(
+                "hitl.resume", actor=operator, target=session_id,
+                result="answered", source="hitl",
+                metadata={"decision": "answer", "approval_id": approval_id},
+            )
+        except Exception:
+            pass
+        return jsonify({
+            "decided": True,
+            "session_id": session_id,
+            "decision": "answer",
+            "operator": operator,
+        })
+
     flag.unlink()
     log.info(
         "HITL decision: session=%s decision=%s operator=%s reason=%r",
diff --git a/routes/hooks.py b/routes/hooks.py
index a7650d1425..c28accc28a 100644
--- a/routes/hooks.py
+++ b/routes/hooks.py
@@ -189,18 +189,24 @@ def _find_approval(approval_id: str):
 
 # ── response helpers ───────────────────────────────────────────────────────
 
-def _hso(decision: str, reason: str) -> dict:
-    return {
-        "hookSpecificOutput": {
-            "hookEventName": "PreToolUse",
-            "permissionDecision": decision,
-            "permissionDecisionReason": reason,
-        },
+def _hso(decision: str, reason: str,
+         updated_input: "dict | None" = None) -> dict:
+    out = {
+        "hookEventName": "PreToolUse",
+        "permissionDecision": decision,
+        "permissionDecisionReason": reason,
     }
+    if updated_input is not None:
+        # Question-set answers (WO-52): allow + updatedInput = the original
+        # tool_input plus the human's structured answers — the session
+        # resumes as if they had been picked in the terminal.
+        out["updatedInput"] = updated_input
+    return {"hookSpecificOutput": out}
 
 
-def _decided(decision: str, reason: str, approval_id: "str | None" = None):
-    body = _hso(decision, reason)
+def _decided(decision: str, reason: str, approval_id: "str | None" = None,
+             updated_input: "dict | None" = None):
+    body = _hso(decision, reason, updated_input)
     body["status"] = "decided"
     if approval_id:
         body["approval_id"] = approval_id
@@ -246,6 +252,37 @@ def _args_meta(row) -> dict:
     return args if isinstance(args, dict) else {}
 
 
+# ── question-set approvals (WO-52 phase 1) ─────────────────────────────────
+# Claude Code's AskUserQuestion tool is a question addressed to the human,
+# so it never needs a protection rule to be worth mirroring: when the gate
+# hook sees it, the question set is parked as an approval row the dashboard
+# renders full-fidelity, and an "answer" decision resumes the session with
+# the picked labels (hookSpecificOutput.updatedInput). Every failure mode —
+# window elapsed, malformed payload, unreadable answers, store down — falls
+# back to "ask" (the runtime's own terminal prompt). NEVER "deny" and NEVER
+# a fabricated answer: the worst case must be exactly today's behaviour.
+
+def _question_gate_enabled() -> bool:
+    return os.environ.get("CLAWMETRY_QUESTION_GATE", "1").strip() != "0"
+
+
+def _question_window_s() -> int:
+    """How long the dashboard/phone gets before the terminal prompt takes
+    over. Env override first, then the mirror window (same concept: a
+    bounded head start for the remote surface), then 180 s."""
+    raw = os.environ.get("CLAWMETRY_QUESTION_WINDOW_S", "").strip()
+    if raw:
+        try:
+            return max(10, int(raw))
+        except ValueError:
+            pass
+    try:
+        from clawmetry import approval_events as _ae
+        return int(_ae.mirror_window_s("claude_code"))
+    except Exception:
+        return 180
+
+
 # ── the receiver ───────────────────────────────────────────────────────────
 
 # URL slug -> the runtime name stamped on approval rows. Each gated runtime
@@ -312,6 +349,14 @@ def _pretooluse_impl(runtime: str):
     if not tool_name:
         return _decided("allow", "no tool_name in hook payload")
 
+    # ── AskUserQuestion: question-set approval (WO-52 phase 1) ───────────
+    # Intercepted BEFORE policy matching: the runtime is already asking its
+    # human a structured question, so no protection rule is required for
+    # the dashboard to be allowed to answer it.
+    if tool_name == "AskUserQuestion" and _question_gate_enabled():
+        return _park_question_set(runtime, session_id, cwd, tool_use_id,
+                                  tool_input)
+
     # ── fresh call: policy match ─────────────────────────────────────────
     try:
         from clawmetry import approvals as ap
@@ -365,34 +410,10 @@ def _pretooluse_impl(runtime: str):
         pass
 
     # ── park a pending row in the local queue ────────────────────────────
-    # Dedup: a client whose first POST timed out client-side retries without
-    # approval_id.  Primary key: tool_use_id.  Fallback (tool_use_id absent):
-    # (session_id, tool_name, md5(tool_input)) within a 30 s window.
-    if tool_use_id:
-        for r in _rows(_ls_read("query_approvals", status="pending",
-                                limit=100)):
-            if _args_meta(r).get("tool_use_id") == tool_use_id:
-                return _wait_on_row(str(r.get("id")), r, tool_name)
-    elif session_id:
-        ih = _input_hash(tool_input)
-        req_sid = f"{runtime}:{session_id}"
-        cutoff_ms = int(time.time() * 1000) - 30_000
-        for r in _rows(_ls_read("query_approvals", status="pending",
-                                limit=100)):
-            m = _args_meta(r)
-            if (m.get("tool_use_id") is None
-                    and m.get("input_hash") == ih
-                    and m.get("tool_name") == tool_name
-                    and r.get("requestor_session_id") == req_sid):
-                try:
-                    import datetime as _dt
-                    row_ms = int(_dt.datetime.fromisoformat(
-                        (r.get("created_at") or "").replace("Z", "+00:00")
-                    ).timestamp() * 1000)
-                except Exception:
-                    row_ms = 0
-                if row_ms >= cutoff_ms:
-                    return _wait_on_row(str(r.get("id")), r, tool_name)
+    dupe = _find_pending_dupe(runtime, session_id, tool_name, tool_input,
+                              tool_use_id)
+    if dupe is not None:
+        return _wait_on_row(str(dupe.get("id")), dupe, tool_name)
 
     approval_id = uuid.uuid4().hex
     now_ms = int(time.time() * 1000)
@@ -451,6 +472,143 @@ def _pretooluse_impl(runtime: str):
     return _wait_on_row(approval_id, row, tool_name)
 
 
+def _find_pending_dupe(runtime: str, session_id: str, tool_name: str,
+                       tool_input: dict, tool_use_id: str):
+    """Existing pending row for this exact call, or None.
+
+    Dedup: a client whose first POST timed out client-side retries without
+    approval_id.  Primary key: tool_use_id.  Fallback (tool_use_id absent):
+    (session_id, tool_name, md5(tool_input)) within a 30 s window.
+    """
+    if tool_use_id:
+        for r in _rows(_ls_read("query_approvals", status="pending",
+                                limit=100)):
+            if _args_meta(r).get("tool_use_id") == tool_use_id:
+                return r
+        return None
+    if session_id:
+        ih = _input_hash(tool_input)
+        req_sid = f"{runtime}:{session_id}"
+        cutoff_ms = int(time.time() * 1000) - 30_000
+        for r in _rows(_ls_read("query_approvals", status="pending",
+                                limit=100)):
+            m = _args_meta(r)
+            if (m.get("tool_use_id") is None
+                    and m.get("input_hash") == ih
+                    and m.get("tool_name") == tool_name
+                    and r.get("requestor_session_id") == req_sid):
+                try:
+                    import datetime as _dt
+                    row_ms = int(_dt.datetime.fromisoformat(
+                        (r.get("created_at") or "").replace("Z", "+00:00")
+                    ).timestamp() * 1000)
+                except Exception:
+                    row_ms = 0
+                if row_ms >= cutoff_ms:
+                    return r
+    return None
+
+
+def _park_question_set(runtime: str, session_id: str, cwd: str,
+                       tool_use_id: str, tool_input: dict):
+    """Park an AskUserQuestion call as a question-set approval row and wait.
+
+    The row carries the sanitized set in ``args["_cm_questions"]`` and
+    ``on_timeout="ask"`` — a question that nobody answers in the window
+    falls back to the runtime's own terminal prompt, NEVER the binary
+    deny default, and NEVER a fabricated answer.
+    """
+    from clawmetry import question_sets as qsets
+    questions = qsets.sanitize_question_set(tool_input)
+    if questions is None:
+        return _decided("ask", "AskUserQuestion payload not understood — "
+                               "falling back to the terminal prompt")
+
+    dupe = _find_pending_dupe(runtime, session_id, "AskUserQuestion",
+                              tool_input, tool_use_id)
+    if dupe is not None:
+        return _wait_on_row(str(dupe.get("id")), dupe, "AskUserQuestion")
+
+    approval_id = uuid.uuid4().hex
+    now_ms = int(time.time() * 1000)
+    window_s = _question_window_s()
+    summary = qsets.question_summary(questions)
+    ok = _ls_write("ingest_approval", approval={
+        "id": approval_id,
+        "requestor_session_id": f"{runtime}:{session_id}" if session_id
+                                else None,
+        "action": f"AskUserQuestion: {summary[:140]}",
+        "args": {
+            "source": "pretooluse-hook",
+            "runtime": runtime,
+            "kind": "question_set",
+            "tool_name": "AskUserQuestion",
+            "tool_input": tool_input,
+            "cwd": cwd,
+            "tool_use_id": tool_use_id or None,
+            "input_hash": None if tool_use_id else _input_hash(tool_input),
+            "policy": "AskUserQuestion",
+            "timeout": window_s,
+            "on_timeout": "ask",
+            "deadline_ms": now_ms + window_s * 1000,
+            "_cm_questions": questions,
+        },
+        "status": "pending",
+        "created_at": _utcnow(),
+    })
+    if not ok:
+        return _decided("ask", "approval store unavailable — falling back "
+                               "to the terminal prompt")
+    _audit("pending", "AskUserQuestion", {"approval_id": approval_id,
+                                          "kind": "question_set",
+                                          "session_id": session_id,
+                                          "questions": len(questions)})
+    _page_human({"id": approval_id, "runtime": runtime,
+                 "kind": "question_set", "tool_name": "AskUserQuestion",
+                 "command": summary[:140], "cwd": cwd,
+                 "policy": "AskUserQuestion",
+                 "requestor_session_id": session_id})
+    row = _find_approval(approval_id) or {"status": "pending", "args": {
+        "on_timeout": "ask",
+        "deadline_ms": now_ms + window_s * 1000,
+        "policy": "AskUserQuestion",
+        "tool_input": tool_input,
+        "_cm_questions": questions,
+    }}
+    return _wait_on_row(approval_id, row, "AskUserQuestion")
+
+
+def _answered_reply(approval_id: str, row: dict, tool_name: str):
+    """Turn an ``answered`` row into allow + updatedInput.
+
+    Re-validates the stored answers against the stored set before replying;
+    anything unreadable degrades to "ask" (the terminal prompt) — a broken
+    answer must never become a fabricated one.
+    """
+    meta = _args_meta(row)
+    try:
+        from clawmetry import question_sets as qsets
+        questions = meta.get("_cm_questions")
+        answers = meta.get("_cm_answers")
+        err = qsets.validate_answers(questions, answers)
+        if err:
+            raise ValueError(err)
+        updated = qsets.merge_answers_into_input(
+            meta.get("tool_input") or {}, answers)
+    except Exception as e:
+        _audit("answered:unreadable", tool_name,
+               {"approval_id": approval_id, "error": str(e)[:200]})
+        return _decided("ask", f"answers recorded but unreadable ({e}) — "
+                               "falling back to the terminal prompt",
+                        approval_id)
+    _audit("answered", tool_name, {"approval_id": approval_id})
+    return _decided(
+        "allow",
+        "Answered by the human via ClawMetry approvals — resuming with "
+        "their answers.",
+        approval_id, updated_input=updated)
+
+
 def _wait_on_row(approval_id: str, row: dict, tool_name: str):
     """Poll the approvals row for up to one wait slice; final answer or
     ``pending``. All state is in the row — safe under concurrent calls
@@ -470,7 +628,12 @@ def _wait_on_row(approval_id: str, row: dict, tool_name: str):
     slice_end = time.time() + _WAIT_SLICE_S
     status = str(row.get("status") or "pending").strip()
     reason = row.get("decision_reason")
+    is_question = bool(meta.get("_cm_questions"))
     while True:
+        if status == "answered":
+            # Question-set decision (WO-52): allow + updatedInput carrying
+            # the human's structured answers.
+            return _answered_reply(approval_id, row, tool_name)
         if status in ("approved", "auto_approved"):
             _audit("approved", tool_name, {"approval_id": approval_id,
                                            "policy": policy_name})
@@ -480,6 +643,13 @@ def _wait_on_row(approval_id: str, row: dict, tool_name: str):
                 f"(policy '{policy_name}')."
                 + (f" Reason: {reason}" if reason else ""),
                 approval_id)
+        if status == "expired" and is_question:
+            # A question that expired is NOT a refusal: hand the decision
+            # back to the runtime's own prompt (never the binary deny).
+            _audit("expired:ask", tool_name, {"approval_id": approval_id})
+            return _decided("ask", "question-set approval expired with no "
+                                   "answer — falling back to the terminal "
+                                   "prompt", approval_id)
         if status in ("denied", "expired"):
             _audit("denied", tool_name, {"approval_id": approval_id,
                                          "policy": policy_name})
@@ -526,6 +696,8 @@ def _wait_on_row(approval_id: str, row: dict, tool_name: str):
     # resolver == "timeout" is our own on_timeout write above).
     fresh = _find_approval(approval_id)
     final = str((fresh or {}).get("status") or "timeout").strip()
+    if final == "answered" and (fresh or {}).get("resolver") != "timeout":
+        return _answered_reply(approval_id, fresh or row, tool_name)
     if final in ("approved", "auto_approved") \
             and (fresh or {}).get("resolver") != "timeout":
         _audit("approved", tool_name, {"approval_id": approval_id,
diff --git a/routes/policy.py b/routes/policy.py
index 57861a457e..7df93105a8 100644
--- a/routes/policy.py
+++ b/routes/policy.py
@@ -205,6 +205,18 @@ def _approval_kind(row) -> str:
     return "policy"
 
 
+def _row_questions(row) -> "list | None":
+    """The question set stored on a question-set approval row (WO-52),
+    full-fidelity — the dashboard renders the actual options, not a
+    preview. None on binary rows so their rendering is untouched."""
+    args = row.get("args")
+    if isinstance(args, dict):
+        q = args.get("_cm_questions")
+        if isinstance(q, list) and q:
+            return q
+    return None
+
+
 @bp_policy.route("/api/approvals")
 @gate("approval_queue")
 def api_approvals_queue():
@@ -236,6 +248,9 @@ def api_approvals_queue():
             # (the runtime itself stopped to ask) — the UI says which,
             # because they mean different things to the person deciding.
             "kind":                 _approval_kind(r),
+            # Question-set rows (WO-52) carry the full set so the UI can
+            # render radios/checkboxes and post decision='answer'.
+            "questions":            _row_questions(r),
         }
         for r in rows
     ]
@@ -251,7 +266,7 @@ def _approvals_audit_payload(status=None, limit=100, runtime=None):
     rows = _filter_rows_by_runtime(rows, runtime)
 
     decisions = []
-    pending = approved = denied = simulated = 0
+    pending = approved = denied = simulated = answered = 0
     for r in rows:
         st = (r.get("status") or "pending")
         dec = (r.get("decision") or "")
@@ -260,6 +275,10 @@ def _approvals_audit_payload(status=None, limit=100, runtime=None):
             simulated += 1
         elif st == "pending":
             pending += 1
+        elif st == "answered" or dec == "answered":
+            # Question-set decision (WO-52): the human answered with
+            # structured options — neither an approve nor a deny.
+            answered += 1
         elif st in ("approved", "allow", "allowed") or dec in ("approve", "allow"):
             approved += 1
         elif st in ("denied", "deny", "blocked", "rejected") or dec in ("deny", "block"):
@@ -284,6 +303,7 @@ def _approvals_audit_payload(status=None, limit=100, runtime=None):
         "pending": pending,
         "approved": approved,
         "denied": denied,
+        "answered": answered,
         "simulated": simulated,
     }
     return {"decisions": decisions, "summary": summary, "_source": "local_store"}
@@ -667,10 +687,10 @@ def api_approval_decide(approval_id: str):
     (grace mode preserves today's behaviour for free users)."""
     body = request.get_json(silent=True) or {}
     decision = str(body.get("decision") or "").strip().lower()
-    if decision not in ("approve", "deny"):
+    if decision not in ("approve", "deny", "answer"):
         return jsonify({
             "ok":    False,
-            "error": "decision must be 'approve' or 'deny'",
+            "error": "decision must be 'approve', 'deny' or 'answer'",
         }), 400
     reason = body.get("reason")
     if reason is not None:
@@ -694,11 +714,42 @@ def api_approval_decide(approval_id: str):
     if row is None:
         return jsonify({"ok": False, "error": "unknown approval id"}), 404
     existing = str(row.get("status") or "pending").strip()
-    if existing in ("approved", "denied", "timeout", "expired"):
+    if existing in ("approved", "denied", "answered", "timeout", "expired"):
         # Already decided — return the frozen status (idempotent). This is
         # the same "first click wins" the store method enforces.
         return jsonify({"ok": True, "status": existing, "already": True})
 
+    # ── question-set answers (WO-52 phase 1) ─────────────────────────────
+    # decision='answer' carries a structured ``answers`` map validated
+    # against the question set stored in the row's args (unknown question
+    # or unknown option label → 400). The shared core merges the answers
+    # into args BEFORE flipping the row to 'answered', so the hook waiting
+    # on it never sees the status without the answers.
+    if decision == "answer":
+        from clawmetry import question_sets as qsets
+        from routes.hooks import _ls_write as _writer
+        reason = body.get("reason")
+        ok, msg, code = qsets.apply_answer_decision(
+            aid, row, body.get("answers"), resolver="local",
+            reason=(str(reason)[:300] if reason else None), write=_writer)
+        if not ok:
+            return jsonify({"ok": False, "error": msg}), code
+        # First-click-wins: the flip only ever transitions a pending row —
+        # re-read to report what actually stands (a racing binary decision
+        # keeps its result).
+        rows2 = _coerce_rows(_ls_call("query_approvals", limit=500))
+        row2 = next((r for r in rows2 if r.get("id") == aid), None)
+        final = str((row2 or {}).get("status") or "answered").strip()
+        try:
+            from clawmetry import approval_events as _ae
+            _ae.notify_resolved(aid, "answered", "dashboard")
+        except Exception:
+            pass
+        resp = {"ok": True, "status": final}
+        if final != "answered":
+            resp["already"] = True
+        return jsonify(resp)
+
     # Flip the row. Prefer the daemon proxy (owns the DuckDB writer lock
     # — same pattern the cloud-relay decision path uses); fall back to a
     # direct writable open when the daemon isn't running (tests, dev
diff --git a/tests/test_question_set_approvals.py b/tests/test_question_set_approvals.py
new file mode 100644
index 0000000000..9d5cef38fe
--- /dev/null
+++ b/tests/test_question_set_approvals.py
@@ -0,0 +1,540 @@
+"""Question-set approvals — decisions beyond yes/no (WO-52, phase 1).
+
+Approvals were strictly binary. Claude Code's ``AskUserQuestion`` tool is
+the first non-binary source: its PreToolUse hook payload carries 1-4
+structured questions, and the hook may answer with
+``hookSpecificOutput.updatedInput`` = tool_input + ``answers`` so the
+session resumes with the human's actual choices.
+
+Pins, in order:
+
+  1. ``clawmetry.question_sets`` — sanitize + strict answer validation
+     (unknown label → error, unknown question → error, multiSelect arrays,
+     free text only when the set says so).
+  2. The local decision wall (``POST /api/approvals/<id>/decide``) —
+     ``decision='answer'`` round-trip, 400s, first-click-wins, and the
+     binary approve/deny regression.
+  3. The HITL wall (``POST /api/hitl/decide``) — same ``answer`` decision,
+     plus the binary reject regression.
+  4. The gate receiver (``POST /api/hooks/claude-code/pretooluse``) —
+     an AskUserQuestion call parks a question-set row; an answered row
+     yields allow + updatedInput; expiry yields "ask" (the terminal
+     prompt), NEVER the binary deny default, NEVER a fabricated answer.
+
+Fixture shape follows ``tests/test_mirror_gate.py``: real tmp HOME +
+isolated CLAWMETRY_LOCAL_STORE_PATH, ``clawmetry.local_store`` popped and
+reloaded FIRST so every late import in the routes resolves against the
+fresh module (the reload-stales-your-import trap), daemon proxy pinned
+offline, one-second wait slices.
+"""
+from __future__ import annotations
+
+import importlib
+import json
+import os
+import sys
+import time
+
+import pytest
+from flask import Flask
+
+_REPO_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+if _REPO_ROOT not in sys.path:
+    sys.path.insert(0, _REPO_ROOT)
+
+from clawmetry import question_sets as qsets  # noqa: E402
+
+
+# ── fixtures ───────────────────────────────────────────────────────────────
+
+
+@pytest.fixture
+def fresh_store(tmp_path, monkeypatch):
+    monkeypatch.setenv("HOME", str(tmp_path))
+    monkeypatch.delenv("CLAWMETRY_ENFORCE", raising=False)
+    monkeypatch.setenv("CLAWMETRY_LOCAL_STORE_PATH",
+                       str(tmp_path / "events.duckdb"))
+    monkeypatch.setenv("CLAWMETRY_LOCAL_FLUSH_SECS", "0.05")
+    monkeypatch.setenv("CLAWMETRY_LOCAL_FLUSH_BATCH", "1")
+    sys.modules.pop("clawmetry.local_store", None)
+    import clawmetry.local_store as ls
+    importlib.reload(ls)
+    yield ls
+    try:
+        ls.get_store().stop(flush=False)
+    except Exception:
+        pass
+
+
+def _pin_entitlement(monkeypatch):
+    import clawmetry.entitlements as ent
+    e = ent.Entitlement(tier="pro", source="test", grace=False,
+                        features=frozenset(("approval_queue",
+                                            "approval_routing",
+                                            "approval_mirror")),
+                        runtimes=frozenset())
+    monkeypatch.setattr(ent, "get_entitlement", lambda force=False: e)
+
+
+@pytest.fixture
+def app(fresh_store, monkeypatch, tmp_path):
+    """One Flask app carrying all three surfaces under test: the hook
+    receiver, the local decide wall, and the HITL wall."""
+    _pin_entitlement(monkeypatch)
+    import routes.local_query as lq
+    monkeypatch.setattr(lq, "local_store_via_daemon", lambda *a, **k: None)
+    import routes.hooks as rh
+    monkeypatch.setattr(rh, "_WAIT_SLICE_S", 1.0)
+    # _HITL_DIR is bound at import time from Path.home(); repin it to THIS
+    # test's HOME so flag files land (and are asserted) in the right place.
+    import routes.hitl as rhitl
+    from pathlib import Path
+    monkeypatch.setattr(rhitl, "_HITL_DIR",
+                        Path(str(tmp_path)) / ".clawmetry" / "hitl")
+    from routes.hooks import bp_hooks
+    from routes.policy import bp_policy
+    from routes.hitl import bp_hitl
+    flask_app = Flask(__name__)
+    flask_app.register_blueprint(bp_hooks)
+    flask_app.register_blueprint(bp_policy)
+    flask_app.register_blueprint(bp_hitl)
+    return flask_app.test_client(), fresh_store
+
+
+_QUESTIONS_INPUT = {
+    "questions": [
+        {"question": "Which database should the cache use?",
+         "header": "Cache",
+         "options": [{"label": "Redis", "description": "in-memory"},
+                     {"label": "DuckDB", "description": "embedded"}],
+         "multiSelect": False},
+        {"question": "Which environments should this ship to?",
+         "header": "Envs",
+         "options": [{"label": "staging", "description": ""},
+                     {"label": "prod", "description": ""},
+                     {"label": "dev", "description": ""}],
+         "multiSelect": True},
+    ],
+}
+
+_GOOD_ANSWERS = {
+    "Which database should the cache use?": "DuckDB",
+    "Which environments should this ship to?": ["staging", "dev"],
+}
+
+
+def _seed_question_row(ls, row_id="q-row-1", session="claude_code:s1",
+                       deadline_offset_ms=60_000):
+    """Park a question-set row exactly the way the receiver does."""
+    store = ls.get_store()
+    questions = qsets.sanitize_question_set(_QUESTIONS_INPUT)
+    store.ingest_approval({
+        "id": row_id,
+        "requestor_session_id": session,
+        "action": f"AskUserQuestion: {qsets.question_summary(questions)}",
+        "args": {
+            "source": "pretooluse-hook",
+            "runtime": "claude_code",
+            "kind": "question_set",
+            "tool_name": "AskUserQuestion",
+            "tool_input": _QUESTIONS_INPUT,
+            "policy": "AskUserQuestion",
+            "on_timeout": "ask",
+            "deadline_ms": int(time.time() * 1000) + deadline_offset_ms,
+            "_cm_questions": questions,
+        },
+        "status": "pending",
+        "created_at": "2026-08-30T00:00:00Z",
+    })
+    return store
+
+
+def _row(store, row_id):
+    return next((r for r in store.query_approvals(limit=50)
+                 if r["id"] == row_id), None)
+
+
+# ── 1. question_sets: sanitize + validation ────────────────────────────────
+
+
+def test_sanitize_normalises_and_caps():
+    qs = qsets.sanitize_question_set(_QUESTIONS_INPUT)
+    assert len(qs) == 2
+    assert qs[0]["question"] == "Which database should the cache use?"
+    assert qs[0]["multiSelect"] is False
+    assert [o["label"] for o in qs[1]["options"]] == ["staging", "prod",
+                                                      "dev"]
+    # Garbage shapes come back None (the receiver answers "ask").
+    assert qsets.sanitize_question_set({}) is None
+    assert qsets.sanitize_question_set({"questions": []}) is None
+    assert qsets.sanitize_question_set({"questions": "nope"}) is None
+    assert qsets.sanitize_question_set(None) is None
+    # Question without text is skipped; options without labels dropped.
+    qs2 = qsets.sanitize_question_set({"questions": [
+        {"question": "", "options": [{"label": "x"}]},
+        {"question": "ok?", "options": [{"label": ""}, {"label": "yes"},
+                                        7]},
+    ]})
+    assert len(qs2) == 1
+    assert qs2[0]["options"] == [{"label": "yes", "description": ""}]
+
+
+def test_validate_answers_strictness():
+    qs = qsets.sanitize_question_set(_QUESTIONS_INPUT)
+    assert qsets.validate_answers(qs, _GOOD_ANSWERS) is None
+    # Unknown option label → error.
+    err = qsets.validate_answers(qs, {
+        "Which database should the cache use?": "Postgres"})
+    assert err and "unknown option" in err
+    # Unknown question → error.
+    err = qsets.validate_answers(qs, {"Wat?": "Redis"})
+    assert err and "unknown question" in err
+    # A list against a single-choice question → error.
+    err = qsets.validate_answers(qs, {
+        "Which database should the cache use?": ["Redis", "DuckDB"]})
+    assert err and "single-choice" in err
+    # Unknown label inside a multiSelect array → error.
+    err = qsets.validate_answers(qs, {
+        "Which environments should this ship to?": ["staging", "moon"]})
+    assert err and "unknown option" in err
+    # Empty / wrong-shape answer maps → error.
+    assert qsets.validate_answers(qs, {}) is not None
+    assert qsets.validate_answers(qs, "Redis") is not None
+    assert qsets.validate_answers(qs, {
+        "Which database should the cache use?": ""}) is not None
+
+
+def test_free_text_only_when_the_set_says_so():
+    with_free = qsets.sanitize_question_set({"questions": [
+        {"question": "Name the branch?", "header": "Branch",
+         "options": [{"label": "main"}, {"label": "dev"}],
+         "allowFreeText": True},
+    ]})
+    assert with_free[0]["allow_free_text"] is True
+    assert qsets.validate_answers(with_free,
+                                  {"Name the branch?": "my-feature"}) is None
+    without = qsets.sanitize_question_set({"questions": [
+        {"question": "Name the branch?",
+         "options": [{"label": "main"}, {"label": "dev"}]},
+    ]})
+    err = qsets.validate_answers(without, {"Name the branch?": "my-feature"})
+    assert err and "unknown option" in err
+
+
+def test_merge_answers_into_input_shape():
+    updated = qsets.merge_answers_into_input(_QUESTIONS_INPUT, _GOOD_ANSWERS)
+    assert updated["questions"] == _QUESTIONS_INPUT["questions"]
+    assert updated["answers"] == _GOOD_ANSWERS
+    # A fresh dict — the stored tool_input is never mutated.
+    assert "answers" not in _QUESTIONS_INPUT
+
+
+# ── 2. local decide wall: /api/approvals/<id>/decide ───────────────────────
+
+
+def test_wall_answer_round_trip_multiselect(app):
+    client, ls = app
+    store = _seed_question_row(ls)
+    r = client.post("/api/approvals/q-row-1/decide",
+                    json={"decision": "answer", "answers": _GOOD_ANSWERS})
+    assert r.status_code == 200
+    assert r.get_json() == {"ok": True, "status": "answered"}
+    row = _row(store, "q-row-1")
+    assert row["status"] == "answered"
+    assert row["decision"] == "answered"
+    # Structured answers ride in args (multiSelect array round-trips).
+    assert row["args"]["_cm_answers"] == _GOOD_ANSWERS
+    # decision_reason carries the human-readable summary for the audit feed.
+    assert "answered" in row["decision_reason"]
+
+
+def test_wall_answer_unknown_label_is_400(app):
+    client, ls = app
+    store = _seed_question_row(ls)
+    r = client.post("/api/approvals/q-row-1/decide",
+                    json={"decision": "answer", "answers": {
+                        "Which database should the cache use?": "Postgres"}})
+    assert r.status_code == 400
+    assert "unknown option" in r.get_json()["error"]
+    # The row is untouched — a rejected answer decides nothing.
+    assert _row(store, "q-row-1")["status"] == "pending"
+
+
+def test_wall_answer_unknown_question_is_400(app):
+    client, ls = app
+    _seed_question_row(ls)
+    r = client.post("/api/approvals/q-row-1/decide",
+                    json={"decision": "answer",
+                          "answers": {"Not a question": "Redis"}})
+    assert r.status_code == 400
+    assert "unknown question" in r.get_json()["error"]
+
+
+def test_wall_answer_on_binary_row_is_400(app):
+    client, ls = app
+    ls.get_store().ingest_approval({
+        "id": "bin-1", "requestor_session_id": "claude_code:s1",
+        "action": "Bash: rm -rf /tmp/x",
+        "args": {"source": "pretooluse-hook", "tool_name": "Bash",
+                 "tool_input": {"command": "rm -rf /tmp/x"}},
+        "status": "pending", "created_at": "2026-08-30T00:00:00Z"})
+    r = client.post("/api/approvals/bin-1/decide",
+                    json={"decision": "answer",
+                          "answers": {"q": "a"}})
+    assert r.status_code == 400
+    assert "question-set" in r.get_json()["error"]
+
+
+def test_wall_first_click_wins_on_structured_answers(app):
+    client, ls = app
+    store = _seed_question_row(ls)
+    first = client.post("/api/approvals/q-row-1/decide",
+                        json={"decision": "answer",
+                              "answers": _GOOD_ANSWERS})
+    assert first.get_json() == {"ok": True, "status": "answered"}
+    # Second structured answer: idempotent, the first one stands.
+    second = client.post("/api/approvals/q-row-1/decide",
+                         json={"decision": "answer", "answers": {
+                             "Which database should the cache use?":
+                                 "Redis"}})
+    assert second.status_code == 200
+    assert second.get_json() == {"ok": True, "status": "answered",
+                                 "already": True}
+    assert _row(store, "q-row-1")["args"]["_cm_answers"] == _GOOD_ANSWERS
+    # A late binary click doesn't overwrite the answers either.
+    late = client.post("/api/approvals/q-row-1/decide",
+                       json={"decision": "deny"})
+    assert late.get_json() == {"ok": True, "status": "answered",
+                               "already": True}
+
+
+def test_wall_deny_beats_a_late_answer(app):
+    client, ls = app
+    _seed_question_row(ls)
+    assert client.post("/api/approvals/q-row-1/decide",
+                       json={"decision": "deny"}).status_code == 200
+    late = client.post("/api/approvals/q-row-1/decide",
+                       json={"decision": "answer",
+                             "answers": _GOOD_ANSWERS})
+    assert late.status_code == 200
+    assert late.get_json() == {"ok": True, "status": "denied",
+                               "already": True}
+
+
+def test_wall_binary_regression(app):
+    """Plain approve/deny rows behave exactly as before."""
+    client, ls = app
+    store = ls.get_store()
+    for rid, decision, status in (("b-appr", "approve", "approved"),
+                                  ("b-deny", "deny", "denied")):
+        store.ingest_approval({
+            "id": rid, "requestor_session_id": "claude_code:s1",
+            "action": "Bash: ls",
+            "args": {"source": "pretooluse-hook", "tool_name": "Bash",
+                     "tool_input": {"command": "ls"}},
+            "status": "pending", "created_at": "2026-08-30T00:00:00Z"})
+        r = client.post(f"/api/approvals/{rid}/decide",
+                        json={"decision": decision, "reason": "because"})
+        assert r.status_code == 200
+        assert r.get_json()["status"] == status
+        assert _row(store, rid)["status"] == status
+    # Unknown decision word still rejected.
+    r = client.post("/api/approvals/b-appr/decide",
+                    json={"decision": "maybe"})
+    assert r.status_code == 400
+
+
+def test_queue_payload_carries_the_question_set(app):
+    client, ls = app
+    _seed_question_row(ls)
+    d = client.get("/api/approvals").get_json()
+    row = next(a for a in d["approvals"] if a["id"] == "q-row-1")
+    assert row["kind"] == "question_set"
+    assert [q["question"] for q in row["questions"]] == [
+        "Which database should the cache use?",
+        "Which environments should this ship to?"]
+    assert [o["label"] for o in row["questions"][0]["options"]] == [
+        "Redis", "DuckDB"]
+
+
+# ── 3. HITL wall: /api/hitl/decide ─────────────────────────────────────────
+
+
+def _flag_session(client, sid="hitl-s1"):
+    r = client.post("/api/hitl/flag", json={"session_id": sid,
+                                            "reason": "loop suspected",
+                                            "operator": "op"})
+    assert r.status_code == 200
+    return sid
+
+
+def _attach_questions(ls, sid):
+    store = ls.get_store()
+    questions = qsets.sanitize_question_set(_QUESTIONS_INPUT)
+    store.ingest_approval({
+        "id": f"hitl_{sid}",
+        "args": {"tool_input": _QUESTIONS_INPUT,
+                 "_cm_questions": questions},
+        "status": "pending",
+    })
+    return store
+
+
+def test_hitl_answer_round_trip(app, tmp_path):
+    client, ls = app
+    sid = _flag_session(client)
+    store = _attach_questions(ls, sid)
+    r = client.post("/api/hitl/decide",
+                    json={"session_id": sid, "decision": "answer",
+                          "operator": "op", "answers": _GOOD_ANSWERS})
+    assert r.status_code == 200
+    assert r.get_json()["decision"] == "answer"
+    row = _row(store, f"hitl_{sid}")
+    assert row["status"] == "answered"
+    assert row["args"]["_cm_answers"] == _GOOD_ANSWERS
+    # The pause flag is lifted — an answer unblocks like an approve.
+    assert not (tmp_path / ".clawmetry" / "hitl" / f"pause_{sid}").exists()
+
+
+def test_hitl_answer_unknown_label_is_400_and_keeps_the_flag(app, tmp_path):
+    client, ls = app
+    sid = _flag_session(client, "hitl-s2")
+    _attach_questions(ls, sid)
+    r = client.post("/api/hitl/decide",
+                    json={"session_id": sid, "decision": "answer",
+                          "operator": "op", "answers": {
+                              "Which database should the cache use?":
+                                  "Postgres"}})
+    assert r.status_code == 400
+    assert (tmp_path / ".clawmetry" / "hitl" / f"pause_{sid}").exists()
+
+
+def test_hitl_binary_regression(app, tmp_path):
+    client, _ls = app
+    sid = _flag_session(client, "hitl-s3")
+    r = client.post("/api/hitl/decide",
+                    json={"session_id": sid, "decision": "reject",
+                          "operator": "op", "reason": "no"})
+    assert r.status_code == 200
+    assert r.get_json()["decision"] == "reject"
+    assert not (tmp_path / ".clawmetry" / "hitl" / f"pause_{sid}").exists()
+    # Unknown decision word still rejected.
+    _flag_session(client, "hitl-s4")
+    r = client.post("/api/hitl/decide",
+                    json={"session_id": "hitl-s4", "decision": "maybe"})
+    assert r.status_code == 400
+
+
+# ── 4. the gate receiver ───────────────────────────────────────────────────
+
+
+def _ask_event(**over):
+    return {"tool_name": "AskUserQuestion",
+            "tool_input": _QUESTIONS_INPUT,
+            "session_id": "s1", "cwd": "/tmp", "tool_use_id": "tu-q1",
+            **over}
+
+
+def test_gate_parks_a_question_row_and_answer_yields_updated_input(app):
+    """The end-to-end loop: park → pending → wall answers → allow +
+    updatedInput carrying the structured answers."""
+    client, ls = app
+    first = client.post("/api/hooks/claude-code/pretooluse",
+                        json=_ask_event()).get_json()
+    assert first["status"] == "pending"
+    aid = first["approval_id"]
+    row = _row(ls.get_store(), aid)
+    assert row["args"]["kind"] == "question_set"
+    assert row["args"]["on_timeout"] == "ask"
+    assert len(row["args"]["_cm_questions"]) == 2
+
+    # The human answers through the real decision wall.
+    r = client.post(f"/api/approvals/{aid}/decide",
+                    json={"decision": "answer", "answers": _GOOD_ANSWERS})
+    assert r.status_code == 200
+
+    # The hook client re-POSTs with approval_id, like the real fast path.
+    done = client.post("/api/hooks/claude-code/pretooluse",
+                       json=_ask_event(approval_id=aid)).get_json()
+    hso = done["hookSpecificOutput"]
+    assert hso["permissionDecision"] == "allow"
+    assert hso["updatedInput"]["answers"] == _GOOD_ANSWERS
+    assert hso["updatedInput"]["questions"] == _QUESTIONS_INPUT["questions"]
+
+
+def test_gate_dedups_on_tool_use_id(app):
+    client, ls = app
+    client.post("/api/hooks/claude-code/pretooluse", json=_ask_event())
+    client.post("/api/hooks/claude-code/pretooluse", json=_ask_event())
+    rows = [r for r in ls.get_store().query_approvals(limit=50)
+            if (r.get("args") or {}).get("kind") == "question_set"]
+    assert len(rows) == 1
+
+
+def test_gate_plain_approve_allows_without_updated_input(app):
+    """Approve ('answer in the terminal') → allow with the input UNCHANGED,
+    so Claude Code renders its own question UI."""
+    client, ls = app
+    first = client.post("/api/hooks/claude-code/pretooluse",
+                        json=_ask_event()).get_json()
+    aid = first["approval_id"]
+    client.post(f"/api/approvals/{aid}/decide", json={"decision": "approve"})
+    done = client.post("/api/hooks/claude-code/pretooluse",
+                       json=_ask_event(approval_id=aid)).get_json()
+    hso = done["hookSpecificOutput"]
+    assert hso["permissionDecision"] == "allow"
+    assert "updatedInput" not in hso
+
+
+def test_gate_deny_denies_with_reason(app):
+    client, ls = app
+    first = client.post("/api/hooks/claude-code/pretooluse",
+                        json=_ask_event()).get_json()
+    aid = first["approval_id"]
+    client.post(f"/api/approvals/{aid}/decide",
+                json={"decision": "deny", "reason": "not now"})
+    done = client.post("/api/hooks/claude-code/pretooluse",
+                       json=_ask_event(approval_id=aid)).get_json()
+    assert done["hookSpecificOutput"]["permissionDecision"] == "deny"
+
+
+def test_gate_expiry_falls_back_to_ask_never_deny(app):
+    """THE safety pin: an expired question-set approval answers "ask" (the
+    terminal prompt takes over) — never the binary on_timeout=deny default,
+    never a fabricated answer."""
+    client, ls = app
+    _seed_question_row(ls, row_id="q-exp", deadline_offset_ms=-1000)
+    done = client.post("/api/hooks/claude-code/pretooluse",
+                       json=_ask_event(approval_id="q-exp")).get_json()
+    assert done["hookSpecificOutput"]["permissionDecision"] == "ask"
+    # …and the row records the timeout, closing the loop for the queue.
+    assert _row(ls.get_store(), "q-exp")["status"] == "timeout"
+
+
+def test_gate_expired_status_falls_back_to_ask(app):
+    """A question row someone else already marked 'expired' must also come
+    back as "ask" — the binary path maps expired to deny."""
+    client, ls = app
+    store = _seed_question_row(ls, row_id="q-expired")
+    store.ingest_approval({"id": "q-expired", "status": "expired"})
+    done = client.post("/api/hooks/claude-code/pretooluse",
+                       json=_ask_event(approval_id="q-expired")).get_json()
+    assert done["hookSpecificOutput"]["permissionDecision"] == "ask"
+
+
+def test_gate_malformed_question_payload_asks(app):
+    client, _ls = app
+    done = client.post("/api/hooks/claude-code/pretooluse",
+                       json=_ask_event(tool_input={"nope": 1})).get_json()
+    assert done["hookSpecificOutput"]["permissionDecision"] == "ask"
+
+
+def test_gate_question_gate_env_kill_switch(app, monkeypatch):
+    """CLAWMETRY_QUESTION_GATE=0 restores the pre-WO-52 behaviour: no
+    policies match AskUserQuestion, so the receiver has no opinion."""
+    client, _ls = app
+    monkeypatch.setenv("CLAWMETRY_QUESTION_GATE", "0")
+    done = client.post("/api/hooks/claude-code/pretooluse",
+                       json=_ask_event()).get_json()
+    assert done["hookSpecificOutput"]["permissionDecision"] == "allow"
+    assert "updatedInput" not in done["hookSpecificOutput"]
diff --git a/tests/test_runtime_gates_and_hooks.py b/tests/test_runtime_gates_and_hooks.py
index bc3b59df69..272bea7a80 100644
--- a/tests/test_runtime_gates_and_hooks.py
+++ b/tests/test_runtime_gates_and_hooks.py
@@ -430,7 +430,10 @@ def test_cc_gate_install_merges_and_uninstall_removes_only_ours(cc_gate):
     assert len(pre) == 2
     assert pre[0]["hooks"][0]["command"] == "my-linter"  # foreign preserved
     ours = pre[1]
-    assert ours["matcher"] == "Bash"
+    # WO-52: the installed matcher always also watches AskUserQuestion so
+    # the receiver can mirror question sets (the derivation helper itself
+    # stays policy-only — pinned below in the matcher-derivation test).
+    assert ours["matcher"] == "Bash|AskUserQuestion"
     cmd = ours["hooks"][0]["command"]
     assert ccg.HOOK_CMD_MARKER in cmd
     assert "--base http://127.0.0.1:8900" in cmd
@@ -438,7 +441,11 @@ def test_cc_gate_install_merges_and_uninstall_removes_only_ours(cc_gate):
     # hook never flashes (or parks) a console window under the desktop app.
     assert cmd.startswith(
         ccg._windowless_python(sys.executable, os.name == "nt"))
-    assert ours["hooks"][0]["timeout"] == 120 + 60  # policy + buffer
+    # Policy window (120) + buffer (60) = 180, raised to the question-set
+    # floor: question window (180 default) + buffer (60) = 240, so Claude
+    # Code never cancels the hook before the receiver's "ask" fallback for
+    # an unanswered AskUserQuestion lands (WO-52).
+    assert ours["hooks"][0]["timeout"] == 240
     assert s["model"] == "opus"                     # rest of file untouched
     st = json.loads(open(ccg._STATE_PATH).read())
     assert st["installed"] is True
@@ -461,7 +468,8 @@ def test_cc_gate_install_merges_and_uninstall_removes_only_ours(cc_gate):
     ours = [e for e in s["hooks"]["PreToolUse"]
             if ccg._entry_is_ours(e)]
     assert len(ours) == 1
-    assert ours[0]["matcher"] == "Write|Edit|MultiEdit|NotebookEdit"
+    assert ours[0]["matcher"] == \
+        "Write|Edit|MultiEdit|NotebookEdit|AskUserQuestion"
 
     # No policy wants the gate → only ours removed; foreign + Stop intact.
     ccg.gate_handler(False, [])

From e5d77657b8a90d48cf22fa494f4ccc69768cf27d Mon Sep 17 00:00:00 2001
From: vivekchand <vivekchand19@gmail.com>
Date: Sun, 30 Aug 2026 02:38:53 +0200
Subject: [PATCH 2/2] ci: re-run after check group was cancelled by a PR-body
 edit

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017VCaSBpV1wBCKrU4z9MKKZ