sdd-forge 0.1.0-alpha.622 → 0.1.0-alpha.650

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdd-forge",
-  "version": "0.1.0-alpha.622",
+  "version": "0.1.0-alpha.650",
   "description": "Spec-Driven Development tooling for automated documentation generation",
   "repository": {
     "type": "git",

package/src/docs/commands/agents.js

@@ -12,7 +12,7 @@ import path from "path";
 import { runIfDirect } from "../../lib/entrypoint.js";
 import { parseArgs } from "../../lib/cli.js";
 import { sddOutputDir } from "../../lib/config.js";
-import { callAgent, loadAgentConfig } from "../../lib/agent.js";
+import { callAgentAwaitLog, loadAgentConfig } from "../../lib/agent.js";
 import { translate } from "../../lib/i18n.js";
 import { createResolver } from "../lib/resolver-factory.js";
 import { createLogger } from "../../lib/progress.js";
@@ -201,7 +201,7 @@ async function main(ctx) {
     const prompt = buildRefinePrompt(projectContent, combinedDocs, config, srcRoot, sddContent);
 
     try {
-      const result = callAgent(agent, prompt, agent.timeoutMs, undefined, { systemPrompt });
+      const result = await callAgentAwaitLog(agent, prompt, agent.timeoutMs, undefined, { systemPrompt });
 
       let refined = result.trim();
 

package/src/docs/commands/enrich.js

@@ -14,7 +14,7 @@ import path from "path";
 import { runIfDirect } from "../../lib/entrypoint.js";
 import { parseArgs } from "../../lib/cli.js";
 import { sddOutputDir, resolveConcurrency } from "../../lib/config.js";
-import { resolveAgent, callAgentAsync, DEFAULT_AGENT_TIMEOUT_MS, resolveWorkDir } from "../../lib/agent.js";
+import { resolveAgent, callAgentAsyncWithLog, DEFAULT_AGENT_TIMEOUT_MS, resolveWorkDir } from "../../lib/agent.js";
 import { minify } from "../lib/minify.js";
 import { mapWithConcurrency } from "../lib/concurrency.js";
 import { resolveCommandContext, loadFullAnalysis } from "../lib/command-context.js";
@@ -454,7 +454,7 @@ async function main(ctx) {
 
     let response;
     try {
-      response = await callAgentAsync(agent, prompt, timeoutMs, root, {
+      response = await callAgentAsyncWithLog(agent, prompt, timeoutMs, root, {
         retryCount,
       });
     } catch (err) {

package/src/docs/commands/forge.js

@@ -22,7 +22,7 @@ import { PKG_DIR, repoRoot, parseArgs } from "../../lib/cli.js";
 import { loadConfig, resolveConcurrency } from "../../lib/config.js";
 import { loadFullAnalysis, loadAnalysisData, getChapterFiles, readText } from "../lib/command-context.js";
 import { createResolver } from "../lib/resolver-factory.js";
-import { callAgentAsync, DEFAULT_AGENT_TIMEOUT_MS, resolveAgent } from "../../lib/agent.js";
+import { callAgentAsyncWithLog, DEFAULT_AGENT_TIMEOUT_MS, resolveAgent } from "../../lib/agent.js";
 import { translate } from "../../lib/i18n.js";
 import { EXIT_ERROR } from "../../lib/exit-codes.js";
 import {
@@ -144,7 +144,7 @@ async function invokeAgent(agent, prompt, { cwd, timeoutMs, systemPrompt, verbos
     : null;
 
   try {
-    return await callAgentAsync(agent, prompt, timeout, cwd, {
+    return await callAgentAsyncWithLog(agent, prompt, timeout, cwd, {
       systemPrompt,
       onStdout: verbose ? (chunk) => process.stderr.write(chunk) : undefined,
       onStderr: verbose ? (chunk) => process.stderr.write(chunk) : undefined,

package/src/docs/commands/init.js

@@ -13,7 +13,7 @@ import path from "path";
 import { runIfDirect } from "../../lib/entrypoint.js";
 import { repoRoot, parseArgs } from "../../lib/cli.js";
 import { loadPackageField } from "../../lib/config.js";
-import { callAgent } from "../../lib/agent.js";
+import { callAgentWithLog } from "../../lib/agent.js";
 import { resolveTemplates, mergeResolved, resolveChaptersOrder, translateTemplate } from "../lib/template-merger.js";
 import { summaryToText } from "../lib/forge-prompts.js";
 import { createLogger } from "../../lib/progress.js";
@@ -81,7 +81,7 @@ function aiFilterChapters(chapters, analysis, agent, root, purpose) {
 
   let response;
   try {
-    response = callAgent(agent, prompt, 60000, root);
+    response = callAgentWithLog(agent, prompt, 60000, root);
   } catch (err) {
     logger.log(`[init] WARN: AI chapter selection failed: ${err.message}`);
     return chapters;

package/src/docs/commands/text.js

@@ -28,7 +28,7 @@ import {
 import { repoRoot, parseArgs } from "../../lib/cli.js";
 import { loadConfig, resolveConcurrency, DEFAULT_CONCURRENCY } from "../../lib/config.js";
 import { createLogger } from "../../lib/progress.js";
-import { callAgent as callAgentBase, callAgentAsync as callAgentAsyncBase, ensureAgentWorkDir, loadAgentConfig, DEFAULT_AGENT_TIMEOUT_MS } from "../../lib/agent.js";
+import { callAgentWithLog, callAgentAsyncWithLog, ensureAgentWorkDir, loadAgentConfig, DEFAULT_AGENT_TIMEOUT_MS } from "../../lib/agent.js";
 import { translate } from "../../lib/i18n.js";
 import { resolveCommandContext, getChapterFiles, loadFullAnalysis } from "../lib/command-context.js";
 import { repairJson } from "../../lib/json-parse.js";
@@ -263,12 +263,12 @@ async function processTemplateFileBatch(text, analysis, fileName, agent, timeout
 // エージェント呼び出し
 // ---------------------------------------------------------------------------
 function callAgent(agent, prompt, timeoutMs, cwd, preamblePatterns, systemPrompt) {
-  const result = callAgentBase(agent, prompt, timeoutMs, cwd, { systemPrompt });
+  const result = callAgentWithLog(agent, prompt, timeoutMs, cwd, { systemPrompt });
   return stripPreamble(result, preamblePatterns);
 }
 
 async function callAgentAsync(agent, prompt, timeoutMs, cwd, preamblePatterns, systemPrompt, extraOptions) {
-  const result = await callAgentAsyncBase(agent, prompt, timeoutMs, cwd, { systemPrompt, ...extraOptions });
+  const result = await callAgentAsyncWithLog(agent, prompt, timeoutMs, cwd, { systemPrompt, ...extraOptions });
   return stripPreamble(result, preamblePatterns);
 }
 

package/src/docs/commands/translate.js

@@ -15,7 +15,7 @@ import { runIfDirect } from "../../lib/entrypoint.js";
 import { parseArgs } from "../../lib/cli.js";
 import { resolveOutputConfig } from "../../lib/types.js";
 import { resolveConcurrency } from "../../lib/config.js";
-import { callAgentAsync } from "../../lib/agent.js";
+import { callAgentAsyncWithLog } from "../../lib/agent.js";
 import { createLogger } from "../../lib/progress.js";
 import { resolveCommandContext, getChapterFiles, stripResponsePreamble } from "../lib/command-context.js";
 import { mapWithConcurrency } from "../lib/concurrency.js";
@@ -71,7 +71,7 @@ async function translateDocument(content, fromLang, toLang, agent, root, documen
 
   const prompt = content;
 
-  const result = await callAgentAsync(agent, prompt, agent.timeoutMs, root, {
+  const result = await callAgentAsyncWithLog(agent, prompt, agent.timeoutMs, root, {
     systemPrompt,
   });
 

package/src/docs/lib/template-merger.js

@@ -13,7 +13,7 @@ import fs from "fs";
 import path from "path";
 import { parseBlocks, BLOCK_START_RE, BLOCK_END_RE } from "./directive-parser.js";
 import { resolveChainSafe, resolveMultiChains } from "../../lib/presets.js";
-import { callAgent } from "../../lib/agent.js";
+import { callAgentWithLog } from "../../lib/agent.js";
 
 const SPECIAL_FILES = new Set(["README.md", "AGENTS.sdd.md", "layout.md"]);
 
@@ -430,7 +430,7 @@ export function translateTemplate(content, fromLang, toLang, agent, root) {
   ].join("\n");
 
   try {
-    return callAgent(agent, prompt, 60000, root);
+    return callAgentWithLog(agent, prompt, 60000, root);
   } catch (err) {
     // Translation failed — return original
     return content;

package/src/flow/commands/review.js

@@ -14,8 +14,16 @@ import path from "path";
 import { runIfDirect } from "../../lib/entrypoint.js";
 import { repoRoot, parseArgs } from "../../lib/cli.js";
 import { loadConfig } from "../../lib/config.js";
-import { loadFlowState } from "../../lib/flow-state.js";
-import { loadAgentConfig, callAgent, resolveAgent, ensureAgentWorkDir } from "../../lib/agent.js";
+import { loadFlowState, getSpecName } from "../../lib/flow-state.js";
+import { loadAgentConfig, callAgentAwaitLog, resolveAgent, ensureAgentWorkDir } from "../../lib/agent.js";
+
+/**
+ * Local helper for review-phase agent invocations. All review calls use the
+ * same default timeout and pass `root` as cwd, so this collapses the repeated
+ * `(agent, prompt, undefined, root, { systemPrompt })` boilerplate.
+ */
+const callReviewAgent = (agent, prompt, root, systemPrompt) =>
+  callAgentAwaitLog(agent, prompt, undefined, root, { systemPrompt });
 import { runCmd } from "../../lib/process.js";
 import { EXIT_ERROR } from "../../lib/exit-codes.js";
 import { VALID_PHASES } from "../lib/phases.js";
@@ -496,12 +504,10 @@ async function runTestReview(root, flow, config, dryRun) {
 
   // Step 1: Generate test design
   console.error("  [test-review] Generating test design...");
-  const testDesign = await callAgent(
-    agent,
-    buildTestDesignPrompt(requirements),
-    undefined,
-    root,
-    { systemPrompt: "You are a test design expert. Output a structured test design." },
+  const testDesignPrompt = buildTestDesignPrompt(requirements);
+  const testDesign = await callReviewAgent(
+    agent, testDesignPrompt, root,
+    "You are a test design expert. Output a structured test design.",
   );
   // Save test design as tests/spec.md
   const testsDir = path.resolve(root, specDir, "tests");
@@ -518,22 +524,18 @@ async function runTestReview(root, flow, config, dryRun) {
     label: "test-review",
     dryRun,
     async detect() {
-      const raw = await callAgent(
-        agent,
-        buildGapAnalysisPrompt(testDesign, testFiles),
-        undefined,
-        root,
-        { systemPrompt: "You are a test quality reviewer. Identify gaps between test design and test code." },
+      const detectPrompt = buildGapAnalysisPrompt(testDesign, testFiles);
+      const raw = await callReviewAgent(
+        agent, detectPrompt, root,
+        "You are a test quality reviewer. Identify gaps between test design and test code.",
       );
       return { issues: parseGaps(raw), raw };
     },
     async fix(raw) {
-      const fixResult = await callAgent(
-        agent,
-        buildTestFixPrompt(raw, testFiles),
-        undefined,
-        root,
-        { systemPrompt: "You are a test engineer. Fix test gaps by writing complete updated test files." },
+      const fixPrompt = buildTestFixPrompt(raw, testFiles);
+      const fixResult = await callReviewAgent(
+        agent, fixPrompt, root,
+        "You are a test engineer. Fix test gaps by writing complete updated test files.",
       );
       const written = applyTestFixes(fixResult, root);
       if (written.length > 0) {
@@ -700,12 +702,10 @@ async function runSpecReview(root, flow, config, dryRun) {
           contextEntries = analysisData.ctxSearch(analysisData.entries, analysisData.analysis, searchQuery, root);
         }
       }
-      const raw = await callAgent(
-        agent,
-        buildSpecReviewPrompt(specText, contextEntries),
-        undefined,
-        root,
-        { systemPrompt: "You are a spec completeness reviewer. Identify oversights in the spec." },
+      const detectPrompt = buildSpecReviewPrompt(specText, contextEntries);
+      const raw = await callReviewAgent(
+        agent, detectPrompt, root,
+        "You are a spec completeness reviewer. Identify oversights in the spec.",
       );
       if (raw.includes("NO_PROPOSALS")) return { issues: [], raw };
       const issues = parseProposals(raw);
@@ -714,19 +714,16 @@ async function runSpecReview(root, flow, config, dryRun) {
     async fix(raw) {
       const specText = fs.readFileSync(specPath, "utf8");
       const proposals = parseProposals(raw);
-      const validationResult = await callAgent(
-        validationAgent,
-        [
-          "Validate these spec improvement proposals:",
-          "",
-          raw,
-          "",
-          "## Current spec for context:",
-          specText,
-        ].join("\n"),
-        undefined,
-        root,
-        { systemPrompt: buildFinalSystemPrompt() },
+      const validationPrompt = [
+        "Validate these spec improvement proposals:",
+        "",
+        raw,
+        "",
+        "## Current spec for context:",
+        specText,
+      ].join("\n");
+      const validationResult = await callReviewAgent(
+        validationAgent, validationPrompt, root, buildFinalSystemPrompt(),
       );
       const results = mergeVerdicts(validationResult, proposals);
       const approved = results.filter((r) => r.verdict === "APPROVED");
@@ -739,12 +736,10 @@ async function runSpecReview(root, flow, config, dryRun) {
       console.error(`  [spec-review] ${approved.length} proposal(s) approved. Applying to spec...`);
 
       const approvedText = approved.map((p, i) => `### ${i + 1}. ${p.title}\n${p.body}`).join("\n\n");
-      const fixResult = await callAgent(
-        agent,
-        buildSpecFixPrompt(specText, approvedText),
-        undefined,
-        root,
-        { systemPrompt: "You are a spec writer. Apply the approved proposals to produce an updated spec." },
+      const specFixPrompt = buildSpecFixPrompt(specText, approvedText);
+      const fixResult = await callReviewAgent(
+        agent, specFixPrompt, root,
+        "You are a spec writer. Apply the approved proposals to produce an updated spec.",
       );
 
       // Strip preamble and markdown fences from AI output
@@ -836,13 +831,7 @@ async function main() {
   console.error("  [draft] Generating proposals...");
   const draftAgent = loadAgentConfig(config, "flow.review.draft");
   ensureAgentWorkDir(draftAgent, root);
-  const draftResult = await callAgent(
-    draftAgent,
-    diff,
-    undefined,
-    root,
-    { systemPrompt: buildDraftSystemPrompt() },
-  );
+  const draftResult = await callReviewAgent(draftAgent, diff, root, buildDraftSystemPrompt());
 
   if (draftResult.includes("NO_PROPOSALS")) {
     console.log("No improvement proposals found. Code looks good.");
@@ -874,13 +863,7 @@ async function main() {
     diff,
   ].join("\n");
 
-  const finalResult = await callAgent(
-    finalAgent,
-    finalPrompt,
-    undefined,
-    root,
-    { systemPrompt: buildFinalSystemPrompt() },
-  );
+  const finalResult = await callReviewAgent(finalAgent, finalPrompt, root, buildFinalSystemPrompt());
 
   const results = mergeVerdicts(finalResult, proposals);
   const approved = results.filter((r) => r.verdict === "APPROVED");

package/src/flow/lib/get-context.js

@@ -15,7 +15,7 @@ import path from "path";
 import { sddOutputDir, loadConfig } from "../../lib/config.js";
 import { FlowCommand } from "./base-command.js";
 import { ANALYSIS_META_KEYS } from "../../docs/lib/analysis-entry.js";
-import { resolveAgent, callAgent } from "../../lib/agent.js";
+import { resolveAgent, callAgentWithLog } from "../../lib/agent.js";
 
 const EXCLUDE_FIELDS = new Set(["hash", "mtime", "lines", "id", "enrich", "detail"]);
 
@@ -221,7 +221,7 @@ function aiSearch(allEntries, analysis, query, root) {
   const prompt = buildKeywordSelectionPrompt(allKeywords, query);
   let response;
   try {
-    response = callAgent(agent, prompt, 30000, root);
+    response = callAgentWithLog(agent, prompt, 30000, root);
   } catch (_) {
     return fallbackSearch(allEntries, query);
   }

package/src/flow/lib/run-finalize.js

@@ -27,9 +27,7 @@ import { FLOW_COMMANDS } from "../registry.js";
 export function finalizeOnError(stepName, trigger) {
   return (ctx, err) => {
     try {
-      // Use mainRoot in worktree mode so issue-log persists after cleanup
-      const logRoot = ctx.mainRoot || ctx.root;
-      const issueLog = loadIssueLog(logRoot, ctx.flowState.spec);
+      const issueLog = loadIssueLog(ctx.root, ctx.flowState.spec);
       const entry = {
         step: stepName,
         reason: err.message || String(err),
@@ -37,7 +35,7 @@ export function finalizeOnError(stepName, trigger) {
       };
       if (trigger) entry.trigger = trigger;
       issueLog.entries.push(entry);
-      saveIssueLog(logRoot, ctx.flowState.spec, issueLog);
+      saveIssueLog(ctx.root, ctx.flowState.spec, issueLog);
     } catch (e) { console.error("[issue-log hook]", e.message); }
   };
 }

package/src/flow/lib/run-gate.js

@@ -13,8 +13,9 @@
 import fs from "fs";
 import path from "path";
 import { runCmd } from "../../lib/process.js";
-import { callAgent, resolveAgent } from "../../lib/agent.js";
+import { callAgentWithLog, resolveAgent } from "../../lib/agent.js";
 import { filterByPhase, loadMergedGuardrails } from "../../lib/guardrail.js";
+import { getSpecName } from "../../lib/flow-state.js";
 import { FlowCommand } from "./base-command.js";
 
 // ---------------------------------------------------------------------------
@@ -225,7 +226,7 @@ function checkGuardrail(root, targetText, config, phase, role) {
   const prompt = buildGuardrailPrompt(targetText, guardrails, phase, role);
   if (!prompt) return { passed: true, results: [] };
 
-  const response = callAgent(agent, prompt);
+  const response = callAgentWithLog(agent, prompt);
   const results = parseGuardrailResponse(response);
   const passed = results.length > 0 && results.every((r) => r.passed);
 
@@ -426,7 +427,7 @@ export class RunGateCommand extends FlowCommand {
     if (!agent) throw new Error("no agent configured for spec.gate");
 
     const reqPrompt = buildImplCheckPrompt(specText, diff);
-    const reqResponse = callAgent(agent, reqPrompt);
+    const reqResponse = callAgentWithLog(agent, reqPrompt);
     const reqResults = parseGuardrailResponse(reqResponse);
 
     const reasons = reqResults.map((r) => ({

package/src/flow/lib/run-retro.js

@@ -8,8 +8,9 @@
 import fs from "fs";
 import path from "path";
 import { runCmd } from "../../lib/process.js";
-import { callAgent, resolveAgent } from "../../lib/agent.js";
+import { callAgentAwaitLog, resolveAgent } from "../../lib/agent.js";
 import { repairJson } from "../../lib/json-parse.js";
+import { getSpecName } from "../../lib/flow-state.js";
 import { FlowCommand } from "./base-command.js";
 
 /**
@@ -192,7 +193,7 @@ export class RunRetroCommand extends FlowCommand {
 
     let response;
     try {
-      response = callAgent(agent, prompt);
+      response = await callAgentAwaitLog(agent, prompt);
     } catch (e) {
       throw new Error(`AI agent call failed: ${e.message}`);
     }

package/src/flow/registry.js

@@ -270,8 +270,7 @@ export const FLOW_COMMANDS = {
         // Auto-record issue-log on gate FAIL
         if (result?.result !== "pass") {
           try {
-            const logRoot = ctx.mainRoot || ctx.root;
-            const issueLog = loadIssueLog(logRoot, ctx.flowState?.spec);
+            const issueLog = loadIssueLog(ctx.root, ctx.flowState?.spec);
             const reasons = result?.artifacts?.issues?.length
               ? result.artifacts.issues.join("; ")
               : (result?.artifacts?.reasons || []).map(r => r.detail || r).join("; ");
@@ -281,21 +280,20 @@ export const FLOW_COMMANDS = {
               trigger: "gate post hook (auto)",
               timestamp: new Date().toISOString(),
             });
-            saveIssueLog(logRoot, ctx.flowState?.spec, issueLog);
+            saveIssueLog(ctx.root, ctx.flowState?.spec, issueLog);
           } catch (e) { console.error("[gate issue-log hook]", e.message); }
         }
       },
       onError(ctx, err) {
         try {
-          const logRoot = ctx.mainRoot || ctx.root;
-          const issueLog = loadIssueLog(logRoot, ctx.flowState?.spec);
+          const issueLog = loadIssueLog(ctx.root, ctx.flowState?.spec);
           issueLog.entries.push({
             step: resolveGateStepId(ctx.phase),
             reason: err.message || String(err),
             trigger: "gate onError hook (auto)",
             timestamp: new Date().toISOString(),
           });
-          saveIssueLog(logRoot, ctx.flowState?.spec, issueLog);
+          saveIssueLog(ctx.root, ctx.flowState?.spec, issueLog);
         } catch (e) { console.error("[gate issue-log hook]", e.message); }
       },
     },

package/src/lib/agent.js

@@ -9,6 +9,8 @@ import crypto from "crypto";
 import fs from "fs";
 import path from "path";
 import { execFileSync, spawn } from "child_process";
+import { Logger, generateRequestId } from "./log.js";
+
 
 /** Default agent timeout in seconds. */
 export const DEFAULT_AGENT_TIMEOUT = 300;
@@ -109,7 +111,6 @@ export function callAgent(agent, prompt, timeoutMs, cwd, options) {
     env,
     ...(stdinContent != null ? { input: stdinContent } : {}),
   });
-
   return result.trim();
 }
 
@@ -134,10 +135,145 @@ export function callAgent(agent, prompt, timeoutMs, cwd, options) {
  */
 export function callAgentAsync(agent, prompt, timeoutMs, cwd, options) {
   const { retryCount = 0, retryDelayMs = 3000, ...restOptions } = options || {};
-  if (retryCount <= 0) {
-    return callAgentAsyncOnce(agent, prompt, timeoutMs, cwd, restOptions);
+  return retryCount <= 0
+    ? callAgentAsyncOnce(agent, prompt, timeoutMs, cwd, restOptions)
+    : callAgentAsyncWithRetry(agent, prompt, timeoutMs, cwd, restOptions, retryCount, retryDelayMs);
+}
+
+/**
+ * Build a Logger.agent() end-event payload from a callAgent invocation.
+ */
+function buildAgentLogPayload(agent, prompt, options, response, exitCode, error, startedAt) {
+  return {
+    agentKey: agent?.command ?? null,
+    model: agent?.model ?? null,
+    prompt: {
+      system: options?.systemPrompt ?? null,
+      user: prompt,
+    },
+    response: {
+      text: response,
+      exitCode,
+      error,
+    },
+    durationSec: (Date.now() - startedAt) / 1000,
+  };
+}
+
+const STDERR_LOG = (e) => process.stderr.write(`[sdd-forge] Logger.agent failed: ${e.message}\n`);
+
+/**
+ * Async runner that wraps an agent invocation in Logger.agent start/end
+ * events. Used by both `callAgentAwaitLog` (sync inner call, awaited
+ * Logger I/O) and `callAgentAsyncWithLog` (async inner call).
+ *
+ * The two callers differ only in:
+ *   - whether the inner invoke is awaited (`asyncInvoke`)
+ *   - which property of the thrown error holds the exit code (`errCodeKey`)
+ *
+ * For the truly synchronous variant (`callAgentWithLog`), use
+ * `runWithAgentLoggingSync` below — sync mode cannot await Logger I/O,
+ * so its control flow differs enough to keep it as a separate small helper.
+ *
+ * @param {Object}   spec
+ * @param {boolean}  spec.asyncInvoke    — true if invoke returns a Promise
+ * @param {()=>any}  spec.invoke
+ * @param {Object}   spec.agent
+ * @param {string}   spec.prompt
+ * @param {Object}   [spec.options]
+ * @param {string}   spec.errCodeKey     — "status" (execFileSync) or "code" (spawn)
+ */
+async function runWithAgentLogging({ asyncInvoke, invoke, agent, prompt, options, errCodeKey }) {
+  const requestId = generateRequestId();
+  const startedAt = Date.now();
+  const logger = Logger.getInstance();
+  await logger.agent({ phase: "start", requestId });
+
+  let result = null;
+  let err = null;
+  try {
+    result = asyncInvoke ? await invoke() : invoke();
+    return result;
+  } catch (e) {
+    err = e;
+    throw e;
+  } finally {
+    const payload = buildAgentLogPayload(
+      agent,
+      prompt,
+      options,
+      result,
+      err ? (err[errCodeKey] ?? 1) : 0,
+      err ? err.message : null,
+      startedAt,
+    );
+    await logger.agent({ phase: "end", requestId, ...payload });
+  }
+}
+
+/**
+ * Sync callAgent wrapped with Logger.agent start/end events.
+ * End-event Logger.log() is fire-and-forget.
+ */
+export function callAgentWithLog(agent, prompt, timeoutMs, cwd, options) {
+  return runWithAgentLoggingSync({
+    invoke: () => callAgent(agent, prompt, timeoutMs, cwd, options),
+    agent, prompt, options,
+    errCodeKey: "status",
+  });
+}
+
+/** Sync variant — runs invoke synchronously, fires Logger calls without awaiting. */
+function runWithAgentLoggingSync({ invoke, agent, prompt, options, errCodeKey }) {
+  const requestId = generateRequestId();
+  const startedAt = Date.now();
+  const logger = Logger.getInstance();
+  logger.agent({ phase: "start", requestId }).catch(STDERR_LOG);
+  let result = null;
+  let err = null;
+  try {
+    result = invoke();
+    return result;
+  } catch (e) {
+    err = e;
+    throw e;
+  } finally {
+    const payload = buildAgentLogPayload(
+      agent,
+      prompt,
+      options,
+      result,
+      err ? (err[errCodeKey] ?? 1) : 0,
+      err ? err.message : null,
+      startedAt,
+    );
+    logger.agent({ phase: "end", requestId, ...payload }).catch(STDERR_LOG);
   }
-  return callAgentAsyncWithRetry(agent, prompt, timeoutMs, cwd, restOptions, retryCount, retryDelayMs);
+}
+
+/**
+ * Sync callAgent wrapped with Logger.agent start/end events, awaited.
+ * Use in async function contexts where the existing code uses sync callAgent.
+ */
+export async function callAgentAwaitLog(agent, prompt, timeoutMs, cwd, options) {
+  return runWithAgentLogging({
+    asyncInvoke: false,
+    invoke: () => callAgent(agent, prompt, timeoutMs, cwd, options),
+    agent, prompt, options,
+    errCodeKey: "status",
+  });
+}
+
+/**
+ * Async callAgentAsync (spawn-based) wrapped with Logger.agent start/end events.
+ */
+export async function callAgentAsyncWithLog(agent, prompt, timeoutMs, cwd, options) {
+  return runWithAgentLogging({
+    asyncInvoke: true,
+    invoke: () => callAgentAsync(agent, prompt, timeoutMs, cwd, options),
+    agent, prompt, options,
+    errCodeKey: "code",
+  });
 }
 
 async function callAgentAsyncWithRetry(agent, prompt, timeoutMs, cwd, options, retryCount, retryDelayMs) {

package/src/lib/flow-state.js

@@ -15,6 +15,18 @@ import { isInsideWorktree, getMainRepoPath } from "./cli.js";
 const STATE_FILE = "flow.json";
 const ACTIVE_FLOW_FILE = ".active-flow";
 
+/**
+ * Extract the spec name (e.g. "152-add-logger-to-callsites") from a flow object or state.
+ * Both `flow.spec` and `state.spec` hold a relative path like "specs/152-.../spec.md".
+ *
+ * @param {{ spec?: string }|null|undefined} flowOrState
+ * @returns {string|null}
+ */
+export function getSpecName(flowOrState) {
+  if (!flowOrState?.spec) return null;
+  return path.basename(path.dirname(flowOrState.spec));
+}
+
 /** SDD workflow step IDs in order. */
 export const FLOW_STEPS = [
   "approach", "branch", "prepare-spec", "draft", "gate-draft", "spec",