@tekyzinc/gsd-t 3.18.13 → 3.18.17

package/scripts/gsd-t-transcript.html

@@ -45,6 +45,27 @@
     .spawn-panel .empty { color: var(--fg-xdim); font-style: italic; padding: 4px 0; font-size: 11px; }
     .spawn-panel .wave-group { border-top: 1px dashed var(--border); padding-top: 4px; margin-top: 4px; }
     .spawn-panel .wave-group:first-child { border-top: none; padding-top: 0; margin-top: 0; }
+    /* M44 D9 — parallelism panel (additive; scoped to its own class). */
+    .parallelism-panel { margin-top: 14px; border: 1px solid var(--border); border-radius: 4px; padding: 10px 12px; background: var(--bg); transition: border-color 200ms ease; }
+    .parallelism-panel.color-green { border-color: #10b981; }
+    .parallelism-panel.color-yellow { border-color: #f59e0b; }
+    .parallelism-panel.color-red { border-color: #ef4444; }
+    .parallelism-panel.color-dimmed { border-color: #374151; opacity: 0.5; }
+    .parallelism-panel h3 { margin: 0 0 6px 0; font-size: 11px; text-transform: uppercase; color: var(--fg-xdim); letter-spacing: 0.08em; display: flex; justify-content: space-between; align-items: baseline; }
+    .parallelism-panel h3 .pp-dot { display: inline-block; width: 8px; height: 8px; border-radius: 50%; background: currentColor; margin-right: 6px; vertical-align: middle; }
+    .parallelism-panel .pp-dot.dot-green { color: #10b981; }
+    .parallelism-panel .pp-dot.dot-yellow { color: #f59e0b; }
+    .parallelism-panel .pp-dot.dot-red { color: #ef4444; }
+    .parallelism-panel .pp-dot.dot-dimmed { color: #374151; }
+    .parallelism-panel .pp-row { display: flex; justify-content: space-between; font-size: 11px; padding: 2px 0; font-family: var(--mono); }
+    .parallelism-panel .pp-row .pp-k { color: var(--fg-xdim); }
+    .parallelism-panel .pp-row .pp-v { color: var(--fg); }
+    .parallelism-panel .pp-gates { margin-top: 6px; padding-top: 6px; border-top: 1px dashed var(--border); font-size: 11px; font-family: var(--mono); color: var(--fg-dim); }
+    .parallelism-panel .pp-gates span { margin-right: 8px; }
+    .parallelism-panel .pp-actions { display: flex; gap: 6px; margin-top: 8px; }
+    .parallelism-panel .pp-actions button { flex: 1; padding: 4px 8px; font-size: 11px; background: var(--bg-raised); color: var(--fg); border: 1px solid var(--border); border-radius: 3px; cursor: pointer; font-family: var(--sans); }
+    .parallelism-panel .pp-actions button:hover { border-color: var(--accent); }
+    .parallelism-panel .pp-actions button.danger:hover { border-color: #ef4444; color: #ef4444; }
     .spawn-panel .wave-label { font-size: 10px; color: var(--fg-xdim); font-family: var(--mono); text-transform: uppercase; letter-spacing: 0.05em; margin: 4px 0 2px 0; }
     aside h3 { margin: 0 12px 8px 12px; font-size: 11px; text-transform: uppercase; color: var(--fg-xdim); letter-spacing: 0.08em; }
     aside .tree { font-size: 13px; }
@@ -76,6 +97,10 @@
     aside .tool-row .tool-tokens { color: var(--fg-dim); flex: 0 0 auto; }
     aside .tool-empty { color: var(--fg-xdim); font-size: 11px; font-style: italic; }
     aside .tool-error { color: var(--yellow); font-size: 11px; font-style: italic; }
+    /* M45 D2 — in-session conversation left-rail badge */
+    aside .node.in-session .name { color: var(--yellow); }
+    aside .node.in-session.active .name { color: var(--accent-warm, var(--yellow)); }
+    aside .node .label-in-session { color: var(--yellow); margin-right: 4px; }
     @keyframes pulse { 0%, 100% { opacity: 1; } 50% { opacity: 0.5; } }
     /* 10s attention-pulse for a freshly-arrived spawn — fires once when
        auto-follow snaps focus to a new session, then self-removes. */
@@ -170,6 +195,20 @@
       <div class="sec-totals" id="active-totals">—</div>
       <div id="active-tasks"><div class="empty">no active spawn plan</div></div>
     </section>
+    <!-- M44 D9 — parallelism panel (additive). Reads /api/parallelism every 5s.
+         Color border reflects color_state (green/yellow/red/dimmed). -->
+    <div class="parallelism-panel color-dimmed" id="parallelism-panel">
+      <h3><span><span class="pp-dot dot-dimmed" id="pp-dot"></span>Parallelism</span><span id="pp-mode" style="font-size:10px;color:var(--fg-xdim);">idle</span></h3>
+      <div class="pp-row"><span class="pp-k">active workers</span><span class="pp-v" id="pp-active">—</span></div>
+      <div class="pp-row"><span class="pp-k">ready tasks</span><span class="pp-v" id="pp-ready">—</span></div>
+      <div class="pp-row"><span class="pp-k">parallelism factor</span><span class="pp-v" id="pp-factor">—</span></div>
+      <div class="pp-row"><span class="pp-k">oldest spawn</span><span class="pp-v" id="pp-oldest">—</span></div>
+      <div class="pp-gates" id="pp-gates"><span>dep: —</span><span>disj: —</span><span>eco: —</span></div>
+      <div class="pp-actions">
+        <button id="pp-report-btn" title="Download full parallelism post-mortem for the current wave">📄 Full Report</button>
+        <button id="pp-stop-btn" class="danger" title="Write .gsd-t/.unattended/stop sentinel to halt an active supervisor">Stop Supervisor</button>
+      </div>
+    </div>
   </aside>
   <button class="jump-to-live" id="jump-btn">↓ Jump to live</button>
 
@@ -483,14 +522,33 @@
           return;
         }
         const currentId = (location.hash || '#').slice(1) || spawnId;
+        // M45 D2: in-session conversation NDJSONs are distinguished by the
+        // `in-session-` spawn-id prefix. The viewer labels them with
+        // `💬 conversation` instead of the default `▶ spawn`. This is a
+        // front-end-only discriminator — no server-side type field is
+        // required; the filename prefix (== spawn-id) is the contract.
+        function isInSession(node) {
+          return typeof node.spawnId === 'string' && node.spawnId.indexOf('in-session-') === 0;
+        }
         function render(node, depth) {
           const el = document.createElement('div');
           el.className = 'node ' + statusClass(node);
+          if (isInSession(node)) el.classList.add('in-session');
           if (node.spawnId === currentId) el.classList.add('active');
           el.style.paddingLeft = (12 + depth * 14) + 'px';
           const dot = document.createElement('span'); dot.className = 'dot';
           const name = document.createElement('span'); name.className = 'name';
-          name.textContent = (node.command || 'spawn') + ' · ' + node.spawnId.slice(-8);
+          if (isInSession(node)) {
+            const badge = document.createElement('span');
+            badge.className = 'label-in-session';
+            badge.textContent = '💬 conversation';
+            name.appendChild(badge);
+            const tail = document.createElement('span');
+            tail.textContent = ' · ' + node.spawnId.slice(-8);
+            name.appendChild(tail);
+          } else {
+            name.textContent = (node.command || 'spawn') + ' · ' + node.spawnId.slice(-8);
+          }
           name.title = (node.description || node.spawnId) + '\n' + (node.startedAt || '');
           const kill = document.createElement('button');
           kill.className = 'kill';
@@ -919,6 +977,99 @@
       subscribePlanUpdates();
       // Light poll every 10s as a safety net if SSE is disconnected.
       setInterval(fetchInitialPlans, 10000);
+
+      // ── M44 D9 — Parallelism panel ─────────────────────────────────────────
+      // Polls /api/parallelism every 5s. Color border reflects color_state.
+      // Full Report button fetches /api/parallelism/report and downloads the
+      // markdown. Stop Supervisor POSTs /api/unattended-stop (writes sentinel).
+      (function wireParallelismPanel() {
+        const panel = document.getElementById('parallelism-panel');
+        if (!panel) return;
+        const dot = document.getElementById('pp-dot');
+        const modeEl = document.getElementById('pp-mode');
+        const activeEl = document.getElementById('pp-active');
+        const readyEl = document.getElementById('pp-ready');
+        const factorEl = document.getElementById('pp-factor');
+        const oldestEl = document.getElementById('pp-oldest');
+        const gatesEl = document.getElementById('pp-gates');
+        const reportBtn = document.getElementById('pp-report-btn');
+        const stopBtn = document.getElementById('pp-stop-btn');
+
+        function fmtAge(s) {
+          if (s == null || !isFinite(s)) return '—';
+          if (s < 60) return s + 's';
+          const m = Math.floor(s / 60), rs = s % 60;
+          if (m < 60) return m + 'm ' + rs + 's';
+          const h = Math.floor(m / 60), rm = m % 60;
+          return h + 'h ' + rm + 'm';
+        }
+
+        function applyColor(state) {
+          const colors = ['color-green', 'color-yellow', 'color-red', 'color-dimmed'];
+          const dots = ['dot-green', 'dot-yellow', 'dot-red', 'dot-dimmed'];
+          for (const c of colors) panel.classList.remove(c);
+          for (const d of dots) dot.classList.remove(d);
+          const cls = 'color-' + (state || 'dimmed');
+          const dcls = 'dot-' + (state || 'dimmed');
+          panel.classList.add(cls);
+          dot.classList.add(dcls);
+        }
+
+        function renderGates(g) {
+          if (!g) { gatesEl.textContent = 'gates: —'; return; }
+          const dep = g.dep_gate_veto || { count: 0 };
+          const dis = g.disjointness_fallback || { count: 0 };
+          const eco = g.economics_decision || { count: 0 };
+          function tally(c) { return c === 0 ? '✓ 0' : (c <= 3 ? '⚠ ' + c : '❌ ' + c); }
+          gatesEl.innerHTML = '<span>dep: ' + tally(dep.count) + '</span>' +
+                              '<span>disj: ' + tally(dis.count) + '</span>' +
+                              '<span>eco: ' + eco.count + '</span>';
+        }
+
+        async function poll() {
+          try {
+            const r = await fetch('/api/parallelism');
+            if (!r.ok) return;
+            const m = await r.json();
+            applyColor(m.color_state);
+            modeEl.textContent = m.parallelism_factor_mode || 'idle';
+            activeEl.textContent = String(m.activeWorkers);
+            readyEl.textContent = String(m.readyTasks);
+            factorEl.textContent = (typeof m.parallelism_factor === 'number' ? m.parallelism_factor.toFixed(1) : '—') + '×';
+            const oldest = (m.activeSpawnAges_s && m.activeSpawnAges_s.length) ? m.activeSpawnAges_s[0] : null;
+            oldestEl.textContent = fmtAge(oldest);
+            renderGates(m.gate_decisions);
+          } catch { /* keep last state on transient failure */ }
+        }
+
+        async function downloadReport() {
+          try {
+            const r = await fetch('/api/parallelism/report');
+            if (!r.ok) return;
+            const md = await r.text();
+            const blob = new Blob([md], { type: 'text/markdown' });
+            const url = URL.createObjectURL(blob);
+            const a = document.createElement('a');
+            a.href = url;
+            a.download = 'parallelism-report-' + new Date().toISOString().slice(0, 19).replace(/:/g, '-') + '.md';
+            document.body.appendChild(a); a.click(); document.body.removeChild(a);
+            setTimeout(() => URL.revokeObjectURL(url), 1000);
+          } catch { /* swallow */ }
+        }
+
+        async function stopSupervisor() {
+          if (!confirm('Write .gsd-t/.unattended/stop sentinel? Active supervisor will exit on next poll.')) return;
+          try {
+            const r = await fetch('/api/unattended-stop', { method: 'POST' });
+            if (r.ok) { stopBtn.textContent = 'Stop sent ✓'; setTimeout(() => { stopBtn.textContent = 'Stop Supervisor'; }, 3000); }
+          } catch { /* swallow */ }
+        }
+
+        if (reportBtn) reportBtn.addEventListener('click', downloadReport);
+        if (stopBtn) stopBtn.addEventListener('click', stopSupervisor);
+        poll();
+        setInterval(poll, 5000);
+      })();
     })();
   </script>
 </body>

package/scripts/hooks/gsd-t-conversation-capture.js

@@ -0,0 +1,258 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * GSD-T Conversation Capture Hook (M45 D2)
+ *
+ * Captures the orchestrator session's conversational turns into
+ * `.gsd-t/transcripts/in-session-{sessionId}.ndjson` so the visualizer
+ * left rail can list the in-session conversation alongside spawn entries.
+ *
+ * Installed into `~/.claude/settings.json` (SessionStart, UserPromptSubmit,
+ * Stop, optional PostToolUse). Reads the hook payload from stdin, dispatches
+ * on `hook_event_name`, appends a typed NDJSON frame. Writes content-level
+ * data (not just tokens — that's the job of `gsd-t-in-session-usage-hook.js`).
+ *
+ * Safety:
+ * - Never throws to the caller — catches all errors, logs to stderr, exits 0.
+ * - `content` is capped at 16 KB per frame; over-cap writes `truncated: true`.
+ * - Append-only; never overwrites an existing in-session NDJSON file.
+ * - Project-dir discovery: prefers `GSD_T_PROJECT_DIR`, then `payload.cwd`,
+ *   then walks up from `process.cwd()` looking for `.gsd-t/progress.md`.
+ *   Silent no-op if no project dir found.
+ *
+ * Contract: .gsd-t/contracts/conversation-capture-contract.md v1.0.0
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const DEFAULT_SCRIPT_GUARD_MS = 5000;
+const CONTENT_CAP_BYTES = 16 * 1024; // 16 KB
+const MAX_STDIN = 1024 * 1024; // 1 MiB defense-in-depth
+const started = Date.now();
+
+function _readStdin() {
+  return new Promise((resolve) => {
+    let buf = '';
+    let aborted = false;
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => {
+      if (aborted) return;
+      buf += chunk;
+      if (buf.length > MAX_STDIN) {
+        aborted = true;
+        try { process.stdin.destroy(); } catch (_) { /* noop */ }
+        resolve('');
+      }
+    });
+    process.stdin.on('end', () => { if (!aborted) resolve(buf); });
+    process.stdin.on('error', () => resolve(buf));
+    setTimeout(() => resolve(buf), DEFAULT_SCRIPT_GUARD_MS).unref();
+  });
+}
+
+function _parsePayload(raw) {
+  try { return JSON.parse(raw || '{}'); } catch (_) { return null; }
+}
+
+function _walkUpForProject(startDir) {
+  try {
+    let dir = path.resolve(startDir || '.');
+    for (let i = 0; i < 10; i++) {
+      if (fs.existsSync(path.join(dir, '.gsd-t', 'progress.md'))) return dir;
+      const parent = path.dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+  } catch (_) { /* swallow */ }
+  return null;
+}
+
+function _resolveProjectDir(payload) {
+  const env = process.env.GSD_T_PROJECT_DIR;
+  if (env && fs.existsSync(path.join(env, '.gsd-t'))) return env;
+  if (payload && typeof payload.cwd === 'string' && path.isAbsolute(payload.cwd)
+      && fs.existsSync(path.join(payload.cwd, '.gsd-t'))) {
+    return payload.cwd;
+  }
+  const walked = _walkUpForProject(process.cwd());
+  if (walked) return walked;
+  return null;
+}
+
+function _resolveSessionId(payload) {
+  if (payload && typeof payload.session_id === 'string' && payload.session_id.length > 0
+      && !/[\/\\\0]|\.\./.test(payload.session_id)) {
+    return payload.session_id;
+  }
+  // Fallback: deterministic-ish per-process hash. Stable within one process,
+  // different across processes. Keeps the filename non-empty when Claude Code
+  // omits session_id (shouldn't happen in practice but we must not explode).
+  // Also used as defense-in-depth for malformed session_ids containing path
+  // separators / `..` that would let path.join collapse the `in-session-`
+  // prefix (protects the filename-prefix discriminator contract with the
+  // viewer + compact-detector).
+  const seed = String(process.pid) + ':' + String(started);
+  return 'pid-' + crypto.createHash('sha1').update(seed).digest('hex').slice(0, 12);
+}
+
+function _capContent(raw) {
+  if (raw == null) return { content: null, truncated: false };
+  let str;
+  if (typeof raw === 'string') str = raw;
+  else {
+    try { str = JSON.stringify(raw); } catch (_) { str = String(raw); }
+  }
+  const byteLen = Buffer.byteLength(str, 'utf8');
+  if (byteLen <= CONTENT_CAP_BYTES) return { content: str, truncated: false };
+  // Truncate by bytes; slice then re-decode to avoid breaking a multi-byte char.
+  const buf = Buffer.from(str, 'utf8').subarray(0, CONTENT_CAP_BYTES);
+  return { content: buf.toString('utf8'), truncated: true };
+}
+
+function _appendFrame(projectDir, sessionId, frame) {
+  const transcriptsDir = path.join(projectDir, '.gsd-t', 'transcripts');
+  try { fs.mkdirSync(transcriptsDir, { recursive: true }); } catch (_) { /* noop */ }
+  const outPath = path.join(transcriptsDir, 'in-session-' + sessionId + '.ndjson');
+  // Path-traversal guard: resolved path must stay under transcriptsDir.
+  const resolvedOut = path.resolve(outPath);
+  const resolvedDir = path.resolve(transcriptsDir) + path.sep;
+  if (!resolvedOut.startsWith(resolvedDir)) return;
+  fs.appendFileSync(outPath, JSON.stringify(frame) + '\n', 'utf8');
+}
+
+function _extractUserContent(payload) {
+  // Claude Code UserPromptSubmit payload carries the prompt text.
+  if (payload && typeof payload.prompt === 'string') return payload.prompt;
+  if (payload && payload.message && typeof payload.message.content === 'string') {
+    return payload.message.content;
+  }
+  if (payload && payload.user_message && typeof payload.user_message === 'string') {
+    return payload.user_message;
+  }
+  return null;
+}
+
+function _extractAssistantContent(payload) {
+  // Stop hook payloads vary. Try the common shapes; fall back to null so we
+  // still emit a stub frame (ts + session_id only).
+  if (payload && typeof payload.assistant_message === 'string') return payload.assistant_message;
+  if (payload && payload.message && typeof payload.message.content === 'string') {
+    return payload.message.content;
+  }
+  if (payload && typeof payload.content === 'string') return payload.content;
+  return null;
+}
+
+function _buildUserFrame(payload, sessionId, ts) {
+  const { content, truncated } = _capContent(_extractUserContent(payload));
+  const frame = {
+    type: 'user_turn',
+    ts,
+    session_id: sessionId,
+  };
+  if (content != null) frame.content = content;
+  if (truncated) frame.truncated = true;
+  if (payload && typeof payload.message_id === 'string') frame.message_id = payload.message_id;
+  return frame;
+}
+
+function _buildAssistantFrame(payload, sessionId, ts) {
+  const { content, truncated } = _capContent(_extractAssistantContent(payload));
+  const frame = {
+    type: 'assistant_turn',
+    ts,
+    session_id: sessionId,
+  };
+  if (content != null) frame.content = content;
+  if (truncated) frame.truncated = true;
+  if (payload && typeof payload.message_id === 'string') frame.message_id = payload.message_id;
+  return frame;
+}
+
+function _buildSessionStartFrame(sessionId, ts) {
+  return { type: 'session_start', ts, session_id: sessionId };
+}
+
+function _buildToolUseFrame(payload, sessionId, ts) {
+  const frame = {
+    type: 'tool_use',
+    ts,
+    session_id: sessionId,
+  };
+  if (payload && typeof payload.tool_name === 'string') frame.name = payload.tool_name;
+  else if (payload && payload.tool && typeof payload.tool.name === 'string') frame.name = payload.tool.name;
+  if (payload && typeof payload.tool_use_id === 'string') frame.tool_use_id = payload.tool_use_id;
+  if (payload && typeof payload.duration_ms === 'number') frame.duration_ms = payload.duration_ms;
+  return frame;
+}
+
+function _handle(payload) {
+  if (!payload || typeof payload !== 'object') return;
+  const event = payload.hook_event_name;
+  if (!event) return;
+
+  const projectDir = _resolveProjectDir(payload);
+  if (!projectDir) return; // not a GSD-T project — silent no-op
+
+  const sessionId = _resolveSessionId(payload);
+  const ts = new Date().toISOString();
+
+  switch (event) {
+    case 'SessionStart': {
+      _appendFrame(projectDir, sessionId, _buildSessionStartFrame(sessionId, ts));
+      return;
+    }
+    case 'UserPromptSubmit': {
+      _appendFrame(projectDir, sessionId, _buildUserFrame(payload, sessionId, ts));
+      return;
+    }
+    case 'Stop': {
+      _appendFrame(projectDir, sessionId, _buildAssistantFrame(payload, sessionId, ts));
+      return;
+    }
+    case 'PostToolUse': {
+      // Opt-in: guarded to keep default writes small.
+      if (process.env.GSD_T_CAPTURE_TOOL_USES !== '1') return;
+      _appendFrame(projectDir, sessionId, _buildToolUseFrame(payload, sessionId, ts));
+      return;
+    }
+    default:
+      return;
+  }
+}
+
+async function main() {
+  try {
+    const raw = await _readStdin();
+    const payload = _parsePayload(raw);
+    if (!payload) return;
+    _handle(payload);
+  } catch (err) {
+    try { process.stderr.write('gsd-t-conversation-capture: ' + (err && err.message || err) + '\n'); } catch (_) { /* noop */ }
+  } finally {
+    const elapsed = Date.now() - started;
+    if (elapsed > DEFAULT_SCRIPT_GUARD_MS) process.exitCode = 0;
+  }
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  _internal: {
+    _parsePayload,
+    _resolveProjectDir,
+    _resolveSessionId,
+    _capContent,
+    _buildUserFrame,
+    _buildAssistantFrame,
+    _buildSessionStartFrame,
+    _buildToolUseFrame,
+    _appendFrame,
+    _handle,
+    CONTENT_CAP_BYTES,
+  },
+};

package/templates/CLAUDE-global.md

@@ -253,6 +253,60 @@ This gives the user real-time visibility into which model is handling each opera
 
 **Context Meter (M34/M38, v3.12.10+)** — The real context-window measurement feeding the headless-default spawn decision. A PostToolUse hook (`scripts/gsd-t-context-meter.js`) runs after every tool call, uses local token estimation to write the current input-token count into `.gsd-t/.context-meter-state.json`. `getSessionStatus()` reads that state file (fresh window = 5 minutes) with a historical heuristic fallback when the file is missing or stale. Command files consume the signal via a small bash shim (`CTX_PCT=$(node -e "…tb.getSessionStatus('.').pct")`). **Single-band model** (context-meter-contract v1.3.0): there's one threshold (default 85%) and one action — hand off to a detached headless spawn. No three-band routing, no silent downgrades, no MANDATORY STOP prose. The meter exists to inform spawn-time routing, not to pause work in-flight.
 
+## In-Session Conversation Capture (M45 D2)
+
+The orchestrator session's user↔assistant dialog is captured into
+`.gsd-t/transcripts/in-session-{sessionId}.ndjson` via a dedicated hook
+script (`scripts/hooks/gsd-t-conversation-capture.js`). The viewer's left
+rail labels these entries `💬 conversation` (front-end-only discriminator
+— the `in-session-` filename prefix is the contract).
+
+This hook captures **content** (user prompts + assistant replies). It is
+complementary to `scripts/hooks/gsd-t-in-session-usage-hook.js` (M43 D1),
+which captures per-turn **token usage** into
+`.gsd-t/metrics/token-usage.jsonl`. Both hooks coexist on the same events.
+
+**Install block** (append to `~/.claude/settings.json` alongside the existing
+context-meter, version-check, compact-detector, and in-session-usage hooks):
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      { "matcher": "",
+        "hooks": [{ "type": "command",
+                    "command": "node \"$HOME/.claude/scripts/hooks/gsd-t-conversation-capture.js\"",
+                    "async": true }] }
+    ],
+    "UserPromptSubmit": [
+      { "matcher": "",
+        "hooks": [{ "type": "command",
+                    "command": "node \"$HOME/.claude/scripts/hooks/gsd-t-conversation-capture.js\"",
+                    "async": true }] }
+    ],
+    "Stop": [
+      { "matcher": "",
+        "hooks": [{ "type": "command",
+                    "command": "node \"$HOME/.claude/scripts/hooks/gsd-t-conversation-capture.js\"",
+                    "async": true }] }
+    ],
+    "PostToolUse": [
+      { "matcher": "",
+        "hooks": [{ "type": "command",
+                    "command": "GSD_T_CAPTURE_TOOL_USES=1 node \"$HOME/.claude/scripts/hooks/gsd-t-conversation-capture.js\"",
+                    "async": true }] }
+    ]
+  }
+}
+```
+
+The `PostToolUse` entry is **opt-in** via `GSD_T_CAPTURE_TOOL_USES=1`. Leave it
+unset unless you want per-tool frames in the NDJSON (full tool payloads are
+already recorded in `events/*.jsonl`).
+
+Contract: `.gsd-t/contracts/conversation-capture-contract.md` v1.0.0. Frame
+schema, file-naming, and session-id resolution rules are locked there.
+
 ## Observability Logging (MANDATORY)
 
 Every command that spawns a Task subagent, invokes `claude -p`, or calls `spawn('claude', ...)` MUST route the spawn through `bin/gsd-t-token-capture.cjs` so the real token-usage envelope is parsed and recorded. This is the M41 canonical pattern — the pre-M41 bash block that wrote `| N/A |` is retired.