agent-dealer 0.1.4 → 0.1.5

package/bundle/server/dist/queue/plan-delegation.js

@@ -0,0 +1,27 @@
+import { addArtifact, getLatestArtifact } from "../repository/runs.js";
+/**
+ * Human approved a plan whose triage questions are still open.
+ * Record the delegation so the executor sees the questions it must decide itself.
+ * Call BEFORE markPlanTriageConsumed — a consumed triage has nothing to delegate.
+ */
+export function recordPlanDelegation(runId) {
+    const triageArt = getLatestArtifact(runId, "plan_triage");
+    if (!triageArt?.contentJson)
+        return false;
+    let triage;
+    try {
+        triage = JSON.parse(triageArt.contentJson);
+    }
+    catch {
+        return false;
+    }
+    if (triage.consumed || triage.questions.length === 0)
+        return false;
+    // >= not >: createdAt has millisecond precision, and answers for this triage
+    // round can tie with it. Answers can never legitimately predate their triage.
+    const answers = getLatestArtifact(runId, "plan_answers");
+    if (answers && answers.createdAt >= triageArt.createdAt)
+        return false;
+    addArtifact(runId, "plan_answers", { answers: [], outcome: "delegated", answeredAt: new Date().toISOString() }, "human");
+    return true;
+}

package/bundle/server/dist/queue/plan-delegation.test.js

@@ -0,0 +1,61 @@
+import { test, before } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+process.env.AGENT_DEALER_HOME = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-delegate-"));
+process.env.MAX_CONCURRENT_RUNS = "0";
+const { migrate } = await import("../db/index.js");
+const { BUILTIN_AGENT_CLAUDE_ID } = await import("@agent-dealer/shared");
+const { updateAgent } = await import("../repository/agents.js");
+const { addArtifact, createRun, getLatestArtifact, markPlanTriageConsumed } = await import("../repository/runs.js");
+const { recordPlanDelegation } = await import("./plan-delegation.js");
+const QUESTIONS = [{ id: "q1", question: "Which backend?", options: [{ label: "SQLite" }, { label: "Postgres" }] }];
+before(() => {
+    migrate();
+    updateAgent(BUILTIN_AGENT_CLAUDE_ID, { workspaceRoot: process.env.AGENT_DEALER_HOME });
+});
+function seedRun(triage) {
+    const run = createRun({
+        title: "Delegate test",
+        taskCategory: "other",
+        status: "plan_pending",
+        agentId: BUILTIN_AGENT_CLAUDE_ID,
+    });
+    addArtifact(run.id, "draft_plan", { markdown: "# Plan" }, "agent");
+    if (triage)
+        addArtifact(run.id, "plan_triage", triage, "agent");
+    return run;
+}
+test("open questions produce a delegated plan_answers record", () => {
+    const run = seedRun({ verdict: "needs_review", rationale: "r", questions: QUESTIONS, parseFallback: false, consumed: false });
+    assert.equal(recordPlanDelegation(run.id), true);
+    const art = getLatestArtifact(run.id, "plan_answers");
+    const content = JSON.parse(art.contentJson);
+    assert.equal(content.outcome, "delegated");
+    assert.deepEqual(content.answers, []);
+    assert.equal(art.author, "human");
+});
+test("no triage means nothing to delegate", () => {
+    const run = seedRun();
+    assert.equal(recordPlanDelegation(run.id), false);
+    assert.equal(getLatestArtifact(run.id, "plan_answers"), null);
+});
+test("triage without questions means nothing to delegate", () => {
+    const run = seedRun({ verdict: "trivial", rationale: "r", questions: [], parseFallback: false, consumed: false });
+    assert.equal(recordPlanDelegation(run.id), false);
+});
+test("consumed triage means nothing to delegate", () => {
+    const run = seedRun({ verdict: "needs_review", rationale: "r", questions: QUESTIONS, parseFallback: false, consumed: false });
+    markPlanTriageConsumed(run.id);
+    assert.equal(recordPlanDelegation(run.id), false);
+});
+test("already-answered questions are not delegated", () => {
+    const run = seedRun({ verdict: "needs_review", rationale: "r", questions: QUESTIONS, parseFallback: false, consumed: false });
+    addArtifact(run.id, "plan_answers", {
+        answers: [{ questionId: "q1", selectedLabel: "SQLite" }],
+        outcome: "approved",
+        answeredAt: new Date().toISOString(),
+    }, "human");
+    assert.equal(recordPlanDelegation(run.id), false);
+});

package/bundle/server/dist/queue/result-qa.js

@@ -0,0 +1,66 @@
+import { randomUUID } from "node:crypto";
+import { addArtifact, getRun } from "../repository/runs.js";
+import { hasPendingQaExchange, latestExecuteSessionId } from "../repository/result-qa.js";
+import { runQa } from "../runners/qa.js";
+const ASKABLE_STATUSES = new Set(["review", "done"]);
+const QA_RUNTIMES = new Set(["claude_code", "cursor_local"]);
+/** Ask the run's agent about its finished result. Read-only; never changes run status. */
+export function askResultQuestion(runId, question, opts) {
+    // An empty question would persist a result_qa artifact that ResultQaContent then
+    // refuses to parse — invisible in the thread, and hasPendingQaExchange would miss
+    // it, defeating the one-pending-question lock. Reject before spending anything.
+    const trimmed = question.trim();
+    if (!trimmed)
+        return { ok: false, code: 400, error: "Question cannot be empty" };
+    const run = getRun(runId);
+    if (!run)
+        return { ok: false, code: 404, error: "Not found" };
+    if (!ASKABLE_STATUSES.has(run.status)) {
+        return { ok: false, code: 409, error: `Can only ask about a finished result — run is ${run.status}` };
+    }
+    const runtime = run.runtime ?? "claude_code";
+    if (!QA_RUNTIMES.has(runtime)) {
+        return { ok: false, code: 409, error: `Q&A is unsupported for runtime ${runtime}` };
+    }
+    // The pending check and the insert below must stay in one synchronous block: every
+    // call here is sync (better-sqlite3), so no other request can interleave between them.
+    // Do not introduce an `await` before addArtifact — that would open a double-ask window.
+    if (hasPendingQaExchange(runId)) {
+        return { ok: false, code: 409, error: "A question is already being answered" };
+    }
+    const resumeSessionId = latestExecuteSessionId(runId);
+    const exchange = {
+        exchangeId: randomUUID(),
+        question: trimmed,
+        status: "pending",
+        sessionResumed: Boolean(resumeSessionId),
+        askedAt: new Date().toISOString(),
+    };
+    addArtifact(runId, "result_qa", exchange, "human");
+    void answerExchange(run, exchange, resumeSessionId, opts?.runner ?? runQa);
+    return { ok: true, exchange };
+}
+async function answerExchange(run, exchange, resumeSessionId, runner) {
+    let result;
+    try {
+        result = await runner(run, exchange.question, resumeSessionId);
+    }
+    catch (e) {
+        appendExchange(run.id, { ...exchange, status: "failed", error: String(e) });
+        return;
+    }
+    addArtifact(run.id, "usage", result.usage, "agent");
+    if (!result.ok) {
+        appendExchange(run.id, { ...exchange, status: "failed", error: result.error ?? "Q&A failed" });
+        return;
+    }
+    appendExchange(run.id, {
+        ...exchange,
+        status: "answered",
+        answer: result.answer,
+        answeredAt: new Date().toISOString(),
+    });
+}
+function appendExchange(runId, exchange) {
+    addArtifact(runId, "result_qa", exchange, "agent");
+}

package/bundle/server/dist/queue/result-qa.test.js

@@ -0,0 +1,146 @@
+import { test, before } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+process.env.AGENT_DEALER_HOME = fs.mkdtempSync(path.join(os.tmpdir(), "dealer-qa-"));
+process.env.MAX_CONCURRENT_RUNS = "0";
+const { migrate } = await import("../db/index.js");
+const { BUILTIN_AGENT_CLAUDE_ID } = await import("@agent-dealer/shared");
+const { updateAgent } = await import("../repository/agents.js");
+const { addArtifact, createRun, getLatestArtifact, getRun, transitionRun, updateRunFields } = await import("../repository/runs.js");
+const { listQaExchanges, hasPendingQaExchange } = await import("../repository/result-qa.js");
+const { askResultQuestion } = await import("./result-qa.js");
+const USAGE = { phase: "qa", runtime: "claude_code", totalCostUsd: 0.02 };
+before(() => {
+    migrate();
+    updateAgent(BUILTIN_AGENT_CLAUDE_ID, { workspaceRoot: process.env.AGENT_DEALER_HOME });
+});
+function seedReviewRun(opts) {
+    const run = createRun({
+        title: "QA test",
+        taskCategory: "other",
+        status: "plan_approved",
+        agentId: BUILTIN_AGENT_CLAUDE_ID,
+    });
+    if (opts?.session) {
+        addArtifact(run.id, "agent_session", { phase: "execute", runtime: "claude_code", sessionId: opts.session }, "agent");
+    }
+    transitionRun(run.id, "running");
+    transitionRun(run.id, "review");
+    return getRun(run.id);
+}
+/** Resolves the async answer job before asserting. */
+async function settle() {
+    await new Promise((r) => setTimeout(r, 10));
+}
+test("asking persists a pending exchange, then an answered one with the same exchangeId", async () => {
+    const run = seedReviewRun({ session: "sess-exec" });
+    let sawSession = "unset";
+    const res = askResultQuestion(run.id, "Why SQLite?", {
+        runner: async (_run, _q, resumeSessionId) => {
+            sawSession = resumeSessionId;
+            return { ok: true, answer: "Single-process.", usage: USAGE };
+        },
+    });
+    assert.equal(res.ok, true);
+    assert.equal(res.ok && res.exchange.status, "pending");
+    assert.equal(listQaExchanges(run.id)[0].status, "pending");
+    await settle();
+    assert.equal(sawSession, "sess-exec");
+    const thread = listQaExchanges(run.id);
+    assert.equal(thread.length, 1, "append-only exchanges collapse by exchangeId");
+    assert.equal(thread[0].status, "answered");
+    assert.equal(thread[0].answer, "Single-process.");
+    assert.equal(thread[0].sessionResumed, true);
+    assert.ok(thread[0].answeredAt);
+    assert.equal(getLatestArtifact(run.id, "usage").contentJson.includes('"phase":"qa"'), true);
+});
+test("missing execute session answers ungrounded and flags sessionResumed false", async () => {
+    const run = seedReviewRun();
+    askResultQuestion(run.id, "What did you check?", {
+        runner: async () => ({ ok: true, answer: "The tests.", usage: USAGE }),
+    });
+    await settle();
+    const thread = listQaExchanges(run.id);
+    assert.equal(thread[0].sessionResumed, false);
+    assert.equal(thread[0].status, "answered");
+});
+test("runner failure records a failed exchange and never changes run status", async () => {
+    const run = seedReviewRun({ session: "sess-exec" });
+    askResultQuestion(run.id, "Why?", {
+        runner: async () => ({ ok: false, answer: "", error: "qa exited 1", usage: USAGE }),
+    });
+    await settle();
+    const thread = listQaExchanges(run.id);
+    assert.equal(thread[0].status, "failed");
+    assert.equal(thread[0].error, "qa exited 1");
+    assert.equal(getRun(run.id).status, "review");
+});
+test("runner throwing records a failed exchange", async () => {
+    const run = seedReviewRun({ session: "sess-exec" });
+    askResultQuestion(run.id, "Why?", {
+        runner: async () => { throw new Error("spawn ENOENT"); },
+    });
+    await settle();
+    assert.match(listQaExchanges(run.id)[0].error, /spawn ENOENT/);
+});
+test("a second question while one is pending returns 409", () => {
+    const run = seedReviewRun({ session: "sess-exec" });
+    askResultQuestion(run.id, "First?", { runner: () => new Promise(() => { }) });
+    const second = askResultQuestion(run.id, "Second?", { runner: async () => ({ ok: true, answer: "x", usage: USAGE }) });
+    assert.equal(!second.ok && second.code, 409);
+});
+test("asking a done run is allowed", async () => {
+    const run = seedReviewRun({ session: "sess-exec" });
+    transitionRun(run.id, "done");
+    const res = askResultQuestion(run.id, "Post-hoc?", {
+        runner: async () => ({ ok: true, answer: "Sure.", usage: USAGE }),
+    });
+    assert.equal(res.ok, true);
+    await settle();
+    assert.equal(listQaExchanges(run.id)[0].status, "answered");
+});
+test("asking a running run returns 409", () => {
+    const run = createRun({
+        title: "Still running",
+        taskCategory: "other",
+        status: "plan_approved",
+        agentId: BUILTIN_AGENT_CLAUDE_ID,
+    });
+    transitionRun(run.id, "running");
+    const res = askResultQuestion(run.id, "Why?", { runner: async () => ({ ok: true, answer: "x", usage: USAGE }) });
+    assert.equal(!res.ok && res.code, 409);
+});
+test("whitespace-only question is rejected before spending anything", async () => {
+    const run = seedReviewRun({ session: "sess-exec" });
+    let runnerCalled = false;
+    const res = askResultQuestion(run.id, "   ", {
+        runner: async () => { runnerCalled = true; return { ok: true, answer: "x", usage: USAGE }; },
+    });
+    assert.equal(!res.ok && res.code, 400);
+    await settle();
+    assert.equal(runnerCalled, false, "no paid agent call");
+    assert.equal(listQaExchanges(run.id).length, 0, "no artifact persisted");
+    assert.equal(hasPendingQaExchange(run.id), false, "pending lock not corrupted");
+});
+test("a persisted exchange always round-trips through the content schema", async () => {
+    const run = seedReviewRun({ session: "sess-exec" });
+    askResultQuestion(run.id, "  Why SQLite?  ", {
+        runner: async () => ({ ok: true, answer: "Single-process.", usage: USAGE }),
+    });
+    await settle();
+    const thread = listQaExchanges(run.id);
+    assert.equal(thread.length, 1, "exchange is visible, i.e. it parsed");
+    assert.equal(thread[0].question, "Why SQLite?", "stored trimmed");
+});
+test("unknown run returns 404", () => {
+    const res = askResultQuestion("00000000-0000-4000-a000-0000000000ff", "Why?");
+    assert.equal(!res.ok && res.code, 404);
+});
+test("cursor runtime is allowed", () => {
+    const run = seedReviewRun({ session: "sess-exec" });
+    updateRunFields(run.id, { runtime: "cursor_local" });
+    const res = askResultQuestion(run.id, "Why?", { runner: async () => ({ ok: true, answer: "x", usage: USAGE }) });
+    assert.equal(res.ok, true);
+});

package/bundle/server/dist/repository/result-qa.js

@@ -0,0 +1,37 @@
+import { ResultQaContent as ResultQaContentSchema, latestQaExchanges } from "@agent-dealer/shared";
+import { listArtifacts } from "./runs.js";
+/** Collapsed Q&A thread for a run — latest artifact per exchangeId, oldest ask first. */
+export function listQaExchanges(runId) {
+    const parsed = [];
+    for (const art of listArtifacts(runId)) {
+        if (art.kind !== "result_qa" || !art.contentJson)
+            continue;
+        try {
+            parsed.push(ResultQaContentSchema.parse(JSON.parse(art.contentJson)));
+        }
+        catch {
+            // skip malformed
+        }
+    }
+    return latestQaExchanges(parsed);
+}
+export function hasPendingQaExchange(runId) {
+    return listQaExchanges(runId).some((e) => e.status === "pending");
+}
+/** Session id of the most recent execute phase — what a Q&A resumes into. */
+export function latestExecuteSessionId(runId) {
+    const sessions = listArtifacts(runId).filter((a) => a.kind === "agent_session");
+    for (let i = sessions.length - 1; i >= 0; i--) {
+        if (!sessions[i].contentJson)
+            continue;
+        try {
+            const parsed = JSON.parse(sessions[i].contentJson);
+            if (parsed.phase === "execute" && parsed.sessionId)
+                return parsed.sessionId;
+        }
+        catch {
+            // skip
+        }
+    }
+    return null;
+}

package/bundle/server/dist/routes/index.js

@@ -1,11 +1,13 @@
 import fs from "node:fs";
-import { CreateRunInput, AgentConfigInput, AgentDeckConfigPatch, CreateAgentInput, UpdateAgentInput, DraftPlanInput, KickRunInput, PlanAnswersInput, LinearIntakeConfigPatch, PromoteLinearInput, RetryRunInput, Runtime, UpdatePlanInput, PlaybookPatchContent, BUILTIN_AGENT_CLAUDE_ID, } from "@agent-dealer/shared";
+import { CreateRunInput, AgentConfigInput, AgentDeckConfigPatch, CreateAgentInput, UpdateAgentInput, DraftPlanInput, KickRunInput, PlanAnswersInput, ResultQaInput, LinearIntakeConfigPatch, PromoteLinearInput, RetryRunInput, Runtime, UpdatePlanInput, PlaybookPatchContent, BUILTIN_AGENT_CLAUDE_ID, } from "@agent-dealer/shared";
 import { parseRunBudget } from "@agent-dealer/shared";
 import { addArtifact, createRun, findActiveByExternalId, getRun, listArtifacts, listEvents, listRuns, updateRunFields, updateArtifactContent, transitionRun, getLatestArtifact, markPlanTriageConsumed, patchRunPhaseBudget, updateRunBudget, } from "../repository/runs.js";
 import { createAgent, deleteAgent, getAgent, listAgents, updateAgent, } from "../repository/agents.js";
 import { listAgentsWithHealth } from "../adapters/agent-health.js";
 import { forceDispatch, getSnapshotAsync, kickRun, schedulePlanDraft, scheduleRedraft, scheduleReflect, submitPlanAnswers, subscribe, } from "../queue/dispatcher.js";
 import { approveRunWithDeliver } from "../queue/approve-deliver.js";
+import { recordPlanDelegation } from "../queue/plan-delegation.js";
+import { askResultQuestion } from "../queue/result-qa.js";
 import { rejectPendingOutboundDrafts } from "../repository/outbound-drafts.js";
 import { fetchAgentDeckDecks, updatePlaybookBody } from "../adapters/agent-deck.js";
 import { testAgentDeckConnection } from "../adapters/agent-deck.js";
@@ -302,6 +304,7 @@ export async function registerRoutes(app) {
             if (input.executeBudget !== undefined) {
                 patchRunPhaseBudget(id, "execute", input.executeBudget);
             }
+            recordPlanDelegation(id);
             markPlanTriageConsumed(id);
             try {
                 transitionRun(id, "plan_approved");
@@ -336,6 +339,20 @@ export async function registerRoutes(app) {
             return reply.status(result.code).send({ error: result.error });
         return { run: result.run, outcome: result.outcome };
     });
+    app.post("/api/runs/:id/qa", async (req, reply) => {
+        const { id } = req.params;
+        let input;
+        try {
+            input = ResultQaInput.parse(req.body);
+        }
+        catch (e) {
+            return reply.status(400).send({ error: String(e) });
+        }
+        const result = askResultQuestion(id, input.question);
+        if (!result.ok)
+            return reply.status(result.code).send({ error: result.error });
+        return reply.status(202).send({ exchange: result.exchange });
+    });
     app.post("/api/runs/:id/kick", async (req, reply) => {
         const { id } = req.params;
         const run = getRun(id);

package/bundle/server/dist/runners/claude-args.js

@@ -2,6 +2,8 @@ import { getTemporalOutputDir } from "../paths.js";
 export const DENY_SEND_TOOL = "mcp__agent-deck__call_service_tool";
 const DECK_READ_TOOLS = "mcp__agent-deck__get_playbook,mcp__agent-deck__get_bound_deck,mcp__agent-deck__bind_workspace,mcp__agent-deck__list_service_tools";
 const PLAN_REFLECT_TOOLS = `Read,Glob,Grep,Skill,${DECK_READ_TOOLS}`;
+/** Q&A about a finished result — read-only, no deck writes, no workspace mutation. */
+const QA_TOOLS = "Read,Glob,Grep,Skill";
 function executeToolsForCategory(category) {
     const base = ["Read", "Write", "Edit", "Glob", "Grep", "Skill", DECK_READ_TOOLS];
     if (category !== "communication" && category !== "email") {
@@ -12,7 +14,10 @@ function executeToolsForCategory(category) {
 /** Build claude -p CLI args for a phase (excluding prompt, model, resume, mcp-config, budget). */
 export function buildClaudePhaseArgs(run, mode) {
     const args = ["--output-format", "stream-json", "--verbose"];
-    if (mode === "plan" || mode === "reflect") {
+    if (mode === "qa") {
+        args.push("--allowedTools", QA_TOOLS);
+    }
+    else if (mode === "plan" || mode === "reflect") {
         args.push("--allowedTools", PLAN_REFLECT_TOOLS);
     }
     else {

package/bundle/server/dist/runners/claude.js

@@ -6,7 +6,7 @@ import { humanFeedbackText, lineageParentExecuteSessionId } from "./run-context.
 import { getTemporalLogsDir } from "../paths.js";
 import { resolveClaudeBin, resolveCursorBin } from "../cli-env.js";
 import { resolveBudgetForPhase, resolveModelForPhase, getRun } from "../repository/runs.js";
-import { budgetCliArgs } from "@agent-dealer/shared";
+import { budgetCliArgs, QA_PHASE_BUDGET } from "@agent-dealer/shared";
 import { buildClaudePhaseArgs } from "./claude-args.js";
 async function spawnCli(cmd, args, cwd) {
     return new Promise((resolve, reject) => {
@@ -31,7 +31,10 @@ export async function runClaude(run, mode = "execute", model, opts) {
     if (!fs.existsSync(mcpConfig)) {
         throw new Error(`MCP config not found: ${mcpConfig}. Set CLAUDE_MCP_CONFIG.`);
     }
-    const phaseBudget = resolveBudgetForPhase(run, mode);
+    if (mode === "qa" && !opts?.promptOverride) {
+        throw new Error("qa mode requires a promptOverride");
+    }
+    const phaseBudget = mode === "qa" ? { ...QA_PHASE_BUDGET } : resolveBudgetForPhase(run, mode);
     const resumeSessionId = opts?.resumeSessionId ??
         (mode === "execute" && humanFeedbackText(run) ? lineageParentExecuteSessionId(run) : null);
     const prompt = opts?.promptOverride ??
@@ -42,7 +45,7 @@ export async function runClaude(run, mode = "execute", model, opts) {
                 : resumeSessionId
                     ? buildExecutionContinuationPrompt(run)
                     : buildExecutionPrompt(run));
-    const logPath = logPathFor(run, mode === "reflect" ? "reflect" : mode);
+    const logPath = logPathFor(run, mode);
     const args = [
         ...(model ? ["--model", model] : []),
         ...(resumeSessionId ? ["--resume", resumeSessionId] : []),
@@ -58,8 +61,11 @@ export async function runClaude(run, mode = "execute", model, opts) {
         fs.writeFileSync(logPath, transcript);
     return { exitCode, transcript, logPath };
 }
-export async function runCursor(run, mode = "execute", model) {
-    const prompt = mode === "plan" ? buildPlanPrompt(run) : buildExecutionPrompt(run);
+export async function runCursor(run, mode = "execute", model, opts) {
+    if (mode === "qa" && !opts?.promptOverride) {
+        throw new Error("qa mode requires a promptOverride");
+    }
+    const prompt = opts?.promptOverride ?? (mode === "plan" ? buildPlanPrompt(run) : buildExecutionPrompt(run));
     const logPath = logPathFor(run, mode);
     const args = [
         "agent",
@@ -68,6 +74,8 @@ export async function runCursor(run, mode = "execute", model) {
         "--output-format",
         "stream-json",
         "--stream-partial-output",
+        ...(mode === "qa" ? ["--mode", "ask"] : []),
+        ...(opts?.resumeSessionId ? ["--resume", opts.resumeSessionId] : []),
         ...(model ? ["--model", model] : []),
         prompt,
     ];

package/bundle/server/dist/runners/claude.test.js

@@ -34,11 +34,28 @@ function hasDisallowSend(args) {
     return i >= 0 && args[i + 1] === DENY_SEND_TOOL;
 }
 test("all phases deny call_service_tool", () => {
-    for (const mode of ["plan", "execute", "reflect"]) {
+    for (const mode of ["plan", "execute", "reflect", "qa"]) {
         const args = buildClaudePhaseArgs(runWithCategory("code"), mode);
         assert.equal(hasDisallowSend(args), true, mode);
     }
 });
+test("qa allowlist is read-only", () => {
+    const args = buildClaudePhaseArgs(runWithCategory("code"), "qa");
+    const i = args.indexOf("--allowedTools");
+    assert.equal(args[i + 1], "Read,Glob,Grep,Skill");
+});
+test("qa forbids mutation tools even for code tasks", () => {
+    const args = buildClaudePhaseArgs(runWithCategory("code"), "qa");
+    const i = args.indexOf("--allowedTools");
+    for (const tool of ["Write", "Edit", "Bash"]) {
+        assert.doesNotMatch(args[i + 1], new RegExp(`\\b${tool}\\b`), tool);
+    }
+    assert.equal(hasDisallowSend(args), true);
+});
+test("qa does not add the deliverable output dir", () => {
+    const args = buildClaudePhaseArgs(runWithCategory("content"), "qa");
+    assert.equal(args.includes("--add-dir"), false);
+});
 test("execute allowlist includes list_service_tools", () => {
     const args = buildClaudePhaseArgs(runWithCategory("code"), "execute");
     const i = args.indexOf("--allowedTools");

package/bundle/server/dist/runners/persist.js

@@ -53,7 +53,7 @@ export function persistRunOutput(input) {
     const blocker = detectExecutionBlocker(resultText);
     const isError = exitCode !== 0 || streamError || blocker.detected;
     const usage = extractUsage(events, phase, runtime);
-    const caps = resolveBudgetForPhase(run, phase);
+    const caps = phase === "qa" ? null : resolveBudgetForPhase(run, phase);
     if (caps?.maxTurns != null)
         usage.maxTurns = caps.maxTurns;
     if (caps?.maxBudgetUsd != null)

package/bundle/server/dist/runners/prompts.js

@@ -1,6 +1,6 @@
 import { getLatestArtifact } from "../repository/runs.js";
 import { documentOutputHint } from "./persist.js";
-import { humanFeedbackText, appendPlanRetrySections, appendExecutionRetrySections, retryContext, } from "./run-context.js";
+import { humanFeedbackText, appendPlanRetrySections, appendExecutionRetrySections, retryContext, reviewQaPairs, } from "./run-context.js";
 export function workspaceForRun(run) {
     return run.repo ?? run.artifactWorkspace ?? process.cwd();
 }
@@ -45,6 +45,13 @@ function outboundDraftContractSection() {
         "- Do not perform the send — the human approves and the server delivers verbatim.",
     ].join("\n");
 }
+function reviewQaSections(run) {
+    const pairs = reviewQaPairs(run);
+    if (pairs.length === 0)
+        return [];
+    const lines = pairs.flatMap((p) => [`Q: ${p.question}`, `A: ${p.answer}`, ``]);
+    return [`## Review Q&A`, `The human asked about the prior result. Honor these answers.`, ...lines];
+}
 export function buildExecutionContinuationPrompt(run) {
     const ctx = retryContext(run);
     const parts = [
@@ -64,6 +71,7 @@ export function buildExecutionContinuationPrompt(run) {
             parts.push(`## Human feedback`, feedback, ``);
         }
     }
+    parts.push(...reviewQaSections(run));
     if (run.deckId) {
         parts.push(`Use Agent Deck: bind_workspace({ deckId: "${run.deckId}", workspaceRoot: "${workspaceForRun(run)}" })`);
         if (run.playbookId) {
@@ -104,6 +112,8 @@ export function buildExecutionPrompt(run) {
         }
     }
     parts.push(...planAnswersSections(run));
+    parts.push(...planDelegationSections(run));
+    parts.push(...reviewQaSections(run));
     if (run.taskCategory === "content" || run.taskCategory === "research") {
         parts.push(`## Deliverable`, documentOutputHint(run), `You MUST write the file using your Write/edit tool — do not only print markdown in chat.`, ``);
     }
@@ -155,6 +165,35 @@ export function buildReflectPrompt(run, opts) {
     }
     return parts.join("\n");
 }
+export function buildQaPrompt(run, question, opts) {
+    const parts = [
+        `The human reviewing your finished work has a question about it.`,
+        ``,
+        `IMPORTANT:`,
+        `- Answer the question. Do NOT modify anything — no files, no edits, no commands, no sends.`,
+        `- You may read files to check your own work.`,
+        `- Answer concisely in markdown. No preamble, no restating the question.`,
+        `- If you do not know, say so plainly rather than guessing.`,
+        ``,
+    ];
+    if (opts.grounded) {
+        parts.push(`## Task`, taskText(run), ``);
+    }
+    else {
+        parts.push(`Your original session is gone, so the relevant context is reproduced below.`, ``, `## Task`, taskText(run), ``);
+        const plan = artifactMarkdown("approved_plan", run.id);
+        if (plan)
+            parts.push(`## Approved plan`, plan, ``);
+        const result = artifactMarkdown("execution_result", run.id);
+        if (result)
+            parts.push(`## Execution outcome`, result, ``);
+        const doc = artifactMarkdown("document", run.id);
+        if (doc)
+            parts.push(`## Deliverable`, doc, ``);
+    }
+    parts.push(`## Question`, question);
+    return parts.join("\n");
+}
 function hasOutboundSendGate(category) {
     return category === "communication" || category === "email";
 }
@@ -200,6 +239,35 @@ function planAnswersSections(run) {
         return [];
     }
 }
+function planDelegationSections(run) {
+    const ansArt = getLatestArtifact(run.id, "plan_answers");
+    if (!ansArt?.contentJson)
+        return [];
+    try {
+        const ans = JSON.parse(ansArt.contentJson);
+        if (ans.outcome !== "delegated")
+            return [];
+        const triArt = getLatestArtifact(run.id, "plan_triage");
+        const questions = triArt?.contentJson
+            ? JSON.parse(triArt.contentJson).questions
+            : [];
+        if (questions.length === 0)
+            return [];
+        const lines = questions.map((q) => {
+            const options = q.options.map((o) => o.label).join(" | ");
+            return `- ${q.question} (options: ${options})`;
+        });
+        return [
+            "## Unanswered plan questions",
+            "The reviewer chose to proceed without answering these. Use your best judgment.",
+            ...lines,
+            "",
+        ];
+    }
+    catch {
+        return [];
+    }
+}
 export function buildPlanRevisePrompt(run, questions, answers) {
     const qa = answers.map((a) => {
         const q = questions.find((x) => x.id === a.questionId);