switchroom 0.13.9 → 0.13.10

package/telegram-plugin/hooks/subagent-tracker-posttool.mjs

@@ -249,6 +249,58 @@ function updateRow(dbPath, { id, status, resultSummary, now }, done) {
   })
 }
 
+// ---------------------------------------------------------------------------
+// Foreground handback nudge (conversational-pacing beat 4)
+// ---------------------------------------------------------------------------
+
+/**
+ * Synchronously read the `background` flag for a subagent row. Returns
+ * 0 (foreground), 1 (background), or null (unknown — sync SQLite
+ * unavailable, or row not found). Used to gate the foreground handback
+ * nudge: a background sub-agent's PostToolUse fires on the ~10s launch
+ * ACK, not on completion, so it must NOT be nudged here (the gateway's
+ * subagent-watcher handles the background handback via inject_inbound).
+ */
+function readBackgroundFlagSync(dbPath, id) {
+  const DatabaseSync = resolveSyncSqlite()
+  if (DatabaseSync == null) return null
+  try {
+    const db = new DatabaseSync(dbPath)
+    const row = db.prepare('SELECT background FROM subagents WHERE id = ?').get(id)
+    db.close()
+    if (row == null) return null
+    return row.background === 1 ? 1 : 0
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Emit a PostToolUse `additionalContext` nudge. For a foreground
+ * sub-agent this fires at real completion, mid-parent-turn, with the
+ * result already in the parent's context — the nudge steers the parent
+ * to synthesise a user-facing handback (beat 4) instead of dumping the
+ * raw report or moving on silently. Same channel `sandbox-hint-posttool`
+ * uses; capped well under Claude Code's 10k hook-output limit.
+ */
+function emitForegroundHandbackNudge() {
+  const out = {
+    hookSpecificOutput: {
+      hookEventName: 'PostToolUse',
+      additionalContext:
+        'A sub-agent you dispatched just returned. Beat 4 — the handback: '
+        + 'before you move on, send the user a reply in your own voice that '
+        + 'synthesises what the sub-agent found and your next step. Do not '
+        + 'paste its raw report and do not go silent.',
+    },
+  }
+  try {
+    process.stdout.write(JSON.stringify(out) + '\n')
+  } catch {
+    /* stdout write failures never block the tool flow */
+  }
+}
+
 // ---------------------------------------------------------------------------
 // main
 // ---------------------------------------------------------------------------
@@ -292,6 +344,23 @@ function main() {
   if (!existsSync(dbPath)) process.exit(0)
 
   const toolResponse = event.tool_response ?? null
+
+  // conversational-pacing beat 4 (foreground half). A foreground
+  // sub-agent's PostToolUse fires at real completion, mid-parent-turn,
+  // with its result in tool_response — nudge the parent to synthesise a
+  // user-facing handback. Background sub-agents are gated OUT: their
+  // PostToolUse fires on the launch ACK (BACKGROUND_SQL leaves status
+  // untouched for that reason), and their handback is driven by the
+  // gateway's subagent-watcher onFinish path instead. Fail-silent: an
+  // unknown background flag (null) skips the nudge.
+  if (
+    process.env.SWITCHROOM_SUBAGENT_HANDBACK !== '0'
+    && detectStatus(toolResponse) === 'completed'
+    && readBackgroundFlagSync(dbPath, id) === 0
+  ) {
+    emitForegroundHandbackNudge()
+  }
+
   updateRow(
     dbPath,
     {

package/telegram-plugin/subagent-watcher.ts

@@ -105,6 +105,15 @@ export interface WorkerEntry {
   stallTerminalSynthesised: boolean
   /** Short summary from last completed tool / narrative, for completion message. */
   lastSummaryLine: string
+  /**
+   * Full text (capped at SUBAGENT_RESULT_TEXT_MAX) of the most recent
+   * `sub_agent_text` emission. For a worker the final such line before
+   * `turn_end` is its result summary. Carried to the gateway via
+   * `onFinish` so a background sub-agent's result can be handed back to
+   * the user (conversational-pacing beat 4). Empty until the first
+   * narrative line.
+   */
+  lastResultText: string
   /**
    * Most recent tool call observed on this sub-agent's JSONL tail —
    * tool name + sanitised arg for fleet-row display (P0 of #662). Null
@@ -270,6 +279,12 @@ export interface SubagentWatcherConfig {
     outcome: 'completed' | 'failed' | 'orphan'
     toolCount: number
     durationMs: number
+    /** Dispatch-time task description, for the handback envelope. */
+    description: string
+    /** The worker's final narrative emission (capped). May be empty if
+     *  no `sub_agent_text` line was ever observed. Feeds the
+     *  `subagent_handback` inbound. */
+    resultText: string
   }) => void
   /** `Date.now` override for tests. */
   now?: () => number
@@ -321,6 +336,15 @@ const DEFAULT_SILENT_SYNTHESIS_STALL_THRESHOLD_MS = 300_000
  */
 const DEFAULT_SILENT_STALL_TERMINAL_MS = 300_000
 
+/**
+ * Cap on the result text retained per sub-agent (`entry.lastResultText`)
+ * and carried to the gateway via `onFinish`. The gateway feeds this into
+ * the `subagent_handback` inbound; the model synthesises a fresh
+ * user-facing summary from it, so the full transcript is never needed
+ * and an unbounded retain would bloat the parent's context.
+ */
+const SUBAGENT_RESULT_TEXT_MAX = 3000
+
 /**
  * Resolve a threshold-knob env var (e.g.
  * `SWITCHROOM_SUBAGENT_STALL_TERMINAL_MS`) to a positive integer ms
@@ -580,6 +604,16 @@ function readSubTail(
           // and must remain stable. Overwriting it with the sub-agent's first
           // narrative line caused a race-condition-dependent display (issue #352).
           entry.lastSummaryLine = ev.text.split('\n')[0].trim().slice(0, 120)
+          // Retain the full text of the most recent narrative emission —
+          // for a worker the final such line before turn_end IS its
+          // result summary (the worker prompt asks it to "return a
+          // concise summary"). Carried to the gateway via onFinish so a
+          // *background* sub-agent's result can be handed back to the
+          // user (conversational-pacing beat 4). Replace-on-write +
+          // capped: this is the worker's intended output, never tool
+          // args or file content — consistent with the watcher's
+          // "descriptions only" privacy posture.
+          entry.lastResultText = ev.text.trim().slice(0, SUBAGENT_RESULT_TEXT_MAX)
         } else if (ev.kind === 'sub_agent_turn_end') {
           if (entry.state === 'running') {
             entry.state = 'done'
@@ -750,6 +784,7 @@ export function startSubagentWatcher(config: SubagentWatcherConfig): SubagentWat
       completionNotified: false,
       stallTerminalSynthesised: false,
       lastSummaryLine: '',
+      lastResultText: '',
       lastTool: null,
       historical: isHistorical,
     }
@@ -850,6 +885,8 @@ export function startSubagentWatcher(config: SubagentWatcherConfig): SubagentWat
             outcome: entry.historical ? 'orphan' : 'completed',
             toolCount: entry.toolCount,
             durationMs: nowFn() - entry.dispatchedAt,
+            description: entry.description,
+            resultText: entry.lastResultText,
           })
         } catch (cbErr) {
           log?.(`subagent-watcher: onFinish callback error ${agentId}: ${(cbErr as Error).message}`)
@@ -869,6 +906,8 @@ export function startSubagentWatcher(config: SubagentWatcherConfig): SubagentWat
             outcome: 'failed',
             toolCount: entry.toolCount,
             durationMs: nowFn() - entry.dispatchedAt,
+            description: entry.description,
+            resultText: entry.lastResultText,
           })
         } catch (cbErr) {
           log?.(`subagent-watcher: onFinish callback error ${agentId}: ${(cbErr as Error).message}`)

package/telegram-plugin/tests/subagent-handback-inbound-builder.test.ts

@@ -0,0 +1,105 @@
+/**
+ * Pin the InboundMessage shape the gateway synthesizes when a
+ * *background* sub-agent finishes (conversational-pacing beat 4 — the
+ * handback). The `meta.source` string is load-bearing: the MCP channel
+ * notification wraps it as `<channel source="subagent_handback">`, and
+ * the agent prompt's beat 4 keys on exactly that tag. A regression that
+ * changes the source string silently breaks the wake-up — the model
+ * wouldn't recognise the turn as a handback cue.
+ */
+
+import { describe, it, expect } from 'vitest'
+import {
+  buildSubagentHandbackInbound,
+  HANDBACK_RESULT_MAX,
+  HANDBACK_DESC_MAX,
+} from '../gateway/subagent-handback-inbound-builder.js'
+
+const FIXED_NOW = 1_700_000_000_000
+
+describe('buildSubagentHandbackInbound', () => {
+  it('builds a completed-worker handback with the load-bearing meta.source', () => {
+    const inbound = buildSubagentHandbackInbound({
+      ctx: {
+        chatId: '12345',
+        taskDescription: 'Refactor the auth module',
+        resultText: 'Done — refactored, 4 tests added, all green.',
+        outcome: 'completed',
+      },
+      nowMs: FIXED_NOW,
+    })
+    expect(inbound.type).toBe('inbound')
+    expect(inbound.chatId).toBe('12345')
+    expect(inbound.userId).toBe(0)
+    expect(inbound.user).toBe('subagent-watcher')
+    expect(inbound.ts).toBe(FIXED_NOW)
+    expect(inbound.messageId).toBe(FIXED_NOW)
+    // The wake-up contract: bridge renders <channel source="subagent_handback">.
+    expect(inbound.meta.source).toBe('subagent_handback')
+    expect(inbound.meta.outcome).toBe('completed')
+    // Text carries the task, the result, and the beat-4 steer.
+    expect(inbound.text).toContain('Refactor the auth module')
+    expect(inbound.text).toContain('4 tests added, all green')
+    expect(inbound.text).toContain('beat 4')
+    expect(inbound.text).toMatch(/synthesise|synthesize/i)
+  })
+
+  it('builds a failed-worker handback that steers an honest report', () => {
+    const inbound = buildSubagentHandbackInbound({
+      ctx: {
+        chatId: '99',
+        taskDescription: 'Migrate the DB',
+        resultText: 'Hit a lock timeout on step 3.',
+        outcome: 'failed',
+      },
+      nowMs: FIXED_NOW,
+    })
+    expect(inbound.meta.source).toBe('subagent_handback')
+    expect(inbound.meta.outcome).toBe('failed')
+    expect(inbound.text).toContain('FAILED')
+    expect(inbound.text).toContain('lock timeout on step 3')
+    expect(inbound.text).toMatch(/did not complete|did not/i)
+  })
+
+  it('tolerates an empty result text (worker emitted no narrative)', () => {
+    const inbound = buildSubagentHandbackInbound({
+      ctx: {
+        chatId: '99',
+        taskDescription: 'Quiet task',
+        resultText: '',
+        outcome: 'completed',
+      },
+      nowMs: FIXED_NOW,
+    })
+    expect(inbound.meta.source).toBe('subagent_handback')
+    expect(inbound.text).toContain('left no summary')
+    // Still steers a handback even with no result text.
+    expect(inbound.text).toContain('beat 4')
+  })
+
+  it('caps an over-long result text and description', () => {
+    const inbound = buildSubagentHandbackInbound({
+      ctx: {
+        chatId: '99',
+        taskDescription: 'D'.repeat(HANDBACK_DESC_MAX + 500),
+        resultText: 'R'.repeat(HANDBACK_RESULT_MAX + 5000),
+        outcome: 'completed',
+      },
+      nowMs: FIXED_NOW,
+    })
+    // Body stays bounded — cap + the surrounding steer prose, well under
+    // Claude Code's hook/context limits.
+    expect(inbound.text.length).toBeLessThan(
+      HANDBACK_RESULT_MAX + HANDBACK_DESC_MAX + 800,
+    )
+    expect(inbound.text).toContain('…')
+  })
+
+  it('falls back to a placeholder when the description is blank', () => {
+    const inbound = buildSubagentHandbackInbound({
+      ctx: { chatId: '99', taskDescription: '   ', resultText: 'x', outcome: 'completed' },
+      nowMs: FIXED_NOW,
+    })
+    expect(inbound.text).toContain('(no description)')
+  })
+})

package/telegram-plugin/tests/subagent-tracker-hooks.test.ts

@@ -210,6 +210,67 @@ describe('subagent-tracker-posttool', () => {
       | undefined
     expect(row?.status).toBe('failed')
   })
+
+  it('emits a foreground handback nudge for a foreground sub-agent', () => {
+    // conversational-pacing beat 4: a FOREGROUND sub-agent's PostToolUse
+    // fires at real completion, mid-parent-turn — emit an
+    // additionalContext nudge steering the parent to synthesise a
+    // handback.
+    runHook(PRETOOL_SCRIPT, {
+      session_id: 's-fg',
+      tool_name: 'Agent',
+      tool_use_id: 'toolu_fg001',
+      tool_input: { description: 'A foreground task', run_in_background: false },
+    })
+    const postResult = runHook(POSTTOOL_SCRIPT, {
+      tool_name: 'Agent',
+      tool_use_id: 'toolu_fg001',
+      tool_response: { result: 'Foreground work complete.', is_error: false },
+    })
+    expect(postResult.status).toBe(0)
+    expect(postResult.stdout).toContain('additionalContext')
+    expect(postResult.stdout).toContain('handback')
+    expect(postResult.stdout).toContain('PostToolUse')
+  })
+
+  it('does NOT emit a handback nudge for a background sub-agent', () => {
+    // A background sub-agent's PostToolUse fires on the launch ACK, not
+    // on completion — nudging "synthesise the handback" there is wrong.
+    // The gateway's subagent-watcher onFinish path owns background.
+    runHook(PRETOOL_SCRIPT, {
+      session_id: 's-bg',
+      tool_name: 'Agent',
+      tool_use_id: 'toolu_bg001',
+      tool_input: { description: 'A background task', run_in_background: true },
+    })
+    const postResult = runHook(POSTTOOL_SCRIPT, {
+      tool_name: 'Agent',
+      tool_use_id: 'toolu_bg001',
+      tool_response: { result: 'launched', is_error: false },
+    })
+    expect(postResult.status).toBe(0)
+    expect(postResult.stdout).not.toContain('additionalContext')
+  })
+
+  it('does NOT emit a handback nudge when SWITCHROOM_SUBAGENT_HANDBACK=0', () => {
+    runHook(PRETOOL_SCRIPT, {
+      session_id: 's-off',
+      tool_name: 'Agent',
+      tool_use_id: 'toolu_off001',
+      tool_input: { description: 'A foreground task', run_in_background: false },
+    })
+    const postResult = runHook(
+      POSTTOOL_SCRIPT,
+      {
+        tool_name: 'Agent',
+        tool_use_id: 'toolu_off001',
+        tool_response: { result: 'done', is_error: false },
+      },
+      { SWITCHROOM_SUBAGENT_HANDBACK: '0' },
+    )
+    expect(postResult.status).toBe(0)
+    expect(postResult.stdout).not.toContain('additionalContext')
+  })
 })
 
 describe('agent-dir resolution (RFC §Bug 2)', () => {

package/telegram-plugin/tests/subagent-watcher.test.ts

@@ -367,7 +367,10 @@ describe('startSubagentWatcher', () => {
       return { agentDir, jsonlPath }
     }
 
-    function startWatcherSync(opts: { agentDir: string }): {
+    function startWatcherSync(opts: {
+      agentDir: string
+      onFinish?: Parameters<typeof startSubagentWatcher>[0]['onFinish']
+    }): {
       notifications: string[]
       poll: () => void
       watcher: ReturnType<typeof startSubagentWatcher>
@@ -380,6 +383,7 @@ describe('startSubagentWatcher', () => {
       const watcher = startSubagentWatcher({
         agentDir: opts.agentDir,
         sendNotification: (text) => notifications.push(text),
+        ...(opts.onFinish ? { onFinish: opts.onFinish } : {}),
         stallThresholdMs: 60_000,
         rescanMs: 500,
         now: () => Date.now(),
@@ -465,6 +469,68 @@ describe('startSubagentWatcher', () => {
       expect(entry?.toolCount).toBe(3)
     })
 
+    it('captures the full last narrative line into lastResultText (handback)', () => {
+      // lastSummaryLine keeps only the first line, 120 chars — a progress
+      // preview. lastResultText keeps the full last narrative emission:
+      // for a worker that IS its result summary, fed to the gateway's
+      // subagent_handback inbound (conversational-pacing beat 4).
+      const fullResult =
+        'Done. I refactored the auth module, added 4 tests, and all green.\n' +
+        'One caveat: the legacy token path still needs a follow-up.'
+      const content = buildJSONL(
+        subAgentUserMsg('Refactor auth'),
+        subAgentAssistantText(fullResult),
+      )
+      const { agentDir } = setupRealFs(content, 'deadbeef')
+      const h = startWatcherSync({ agentDir })
+      h.poll()
+      const entry = h.watcher.getRegistry().get('deadbeef')
+      expect(entry).toBeDefined()
+      // lastSummaryLine is the truncated first line only.
+      expect(entry?.lastSummaryLine).not.toMatch(/follow-up/)
+      // lastResultText keeps the whole thing — multi-line, both sentences.
+      expect(entry?.lastResultText).toContain('refactored the auth module')
+      expect(entry?.lastResultText).toContain('legacy token path still needs a follow-up')
+    })
+
+    it('onFinish carries description + resultText for the handback', () => {
+      // onFinish fires only on a POST-boot transition (a file already
+      // done at startup is historical and short-circuits). So: register
+      // the running sub-agent first, then append turn_duration.
+      const finishes: Array<{ description: string; resultText: string; outcome: string }> = []
+      const agentDir = join(tmpRoot, 'agent')
+      const subagentsDir = join(agentDir, '.claude', 'projects', 'p1', 'session-abc', 'subagents')
+      mkdirSync(subagentsDir, { recursive: true })
+      const jsonlPath = join(subagentsDir, 'agent-deadbeef.jsonl')
+
+      const h = startWatcherSync({
+        agentDir,
+        onFinish: ({ description, resultText, outcome }) => {
+          finishes.push({ description, resultText, outcome })
+        },
+      })
+      // Register the sub-agent as running (post-boot, not historical).
+      writeFileSync(
+        jsonlPath,
+        buildJSONL(
+          subAgentUserMsg('Run a long task'),
+          subAgentAssistantText('All set — migration applied cleanly, 0 rows dropped.'),
+        ),
+      )
+      h.poll()
+      expect(h.watcher.getRegistry().get('deadbeef')?.state).toBe('running')
+
+      // Now it finishes — onFinish must carry the result text.
+      appendFileSync(jsonlPath, buildJSONL(subAgentTurnDuration()))
+      h.poll()
+
+      expect(finishes.length).toBe(1)
+      expect(finishes[0].outcome).toBe('completed')
+      expect(finishes[0].resultText).toContain('migration applied cleanly')
+      // description stays the dispatch description, never the narrative.
+      expect(finishes[0].description).not.toMatch(/migration applied/)
+    })
+
     it('does NOT emit completion notification for a file already done at startup', () => {
       // File pre-exists with turn_end already written — agent was done before
       // the watcher started. No completion notification should fire.

package/telegram-plugin/uat/scenarios/jtbd-subagent-handback-dm.test.ts

@@ -0,0 +1,95 @@
+/**
+ * JTBD: "talking to my agent feels like talking to a capable person."
+ * Conversational-pacing beat 4 — the sub-agent handback.
+ *
+ * The gap this closes: a *background* sub-agent finishes decoupled from
+ * any turn boundary. The parent agent is idle when it completes, with no
+ * turn to receive the result — so without a deterministic nudge the user
+ * never hears back until they send the next message themselves. The
+ * agent looks like it dropped the delegated work on the floor.
+ *
+ * The fix (Option B): the gateway's subagent-watcher `onFinish` fires a
+ * `subagent_handback` inbound carrying the worker's result; the idle
+ * agent wakes and synthesises a user-facing handback in its own voice.
+ *
+ * What this scenario asserts: after the parent dispatches a background
+ * worker and ends its turn, a SECOND, unprompted bot message arrives —
+ * the handback — without the driver sending anything further. That
+ * second message is the whole point: proactive "the worker's done,
+ * here's what it found".
+ *
+ * Prompt strategy: explicit tool-naming (Option 1, mirroring
+ * `bg-sub-agent-dispatch-dm.test.ts`) — the scenario verifies the
+ * handback INFRA, not the model's delegation judgment, so the dispatch
+ * is pinned deterministic.
+ *
+ * Requires the standard DM-scenario env (see uat/SETUP.md §3-6). The
+ * test-harness override `SWITCHROOM_SUBAGENT_STALL_*` (switchroom.yaml)
+ * compresses the watcher's terminal-synthesis window so a background
+ * worker that never writes an explicit `turn_end` still terminates
+ * (and hands back) within the scenario budget instead of 5 min.
+ */
+
+import { describe, expect, it } from "vitest";
+import { spinUp } from "../harness.js";
+
+const BG_DISPATCH_PROMPT =
+  `Use the Agent tool with subagent_type "general-purpose" and ` +
+  `run_in_background: true to dispatch a worker with this exact task: ` +
+  `"Run \`echo HANDBACK-PROBE-OK\` via the Bash tool, then return a ` +
+  `one-line summary of what you did." After dispatching, send me a ` +
+  `brief one-line reply saying you have kicked off the background ` +
+  `worker, then END YOUR TURN — do NOT wait for the worker and do NOT ` +
+  `do the echo yourself.`;
+
+describe("uat: sub-agent handback — proactive beat-4 communication", () => {
+  it(
+    "delivers an unprompted handback message after a background worker finishes",
+    async () => {
+      const sc = await spinUp({ agent: "test-harness" });
+      try {
+        await sc.sendDM(BG_DISPATCH_PROMPT);
+
+        // Beat 1/5 of the dispatch turn: the parent acks that it kicked
+        // off the worker, then ends its turn. Generous timeout — a cold
+        // first turn plus the Agent dispatch can run long.
+        const ack = await sc.expectMessage(/.+/, {
+          from: "bot",
+          timeout: 60_000,
+        });
+        expect(ack.messageId).toBeGreaterThan(0);
+
+        // THE TEST: a second, distinct bot message arrives — the
+        // handback — WITHOUT the driver sending anything further. This
+        // is the deterministic beat-4 win: the watcher's onFinish fired
+        // a `subagent_handback` inbound, the idle agent woke, and it
+        // synthesised a user-facing report.
+        //
+        // Match: a bot message that is NOT the ack and reads like a
+        // completion report. The handback inbound steers the model to
+        // report what the worker found; we accept any of the natural
+        // wordings rather than pinning exact prose (the model owns the
+        // words — determinism contract).
+        const handback = await sc.expectMessage(
+          (m) =>
+            m.messageId !== ack.messageId &&
+            /\b(done|finished|complete|completed|wrapped up|worker|back|result)\b/i.test(
+              m.text,
+            ),
+          { from: "bot", timeout: 180_000 },
+        );
+
+        expect(handback.messageId).not.toBe(ack.messageId);
+        // The handback must be a real synthesised message, not an echo
+        // of the raw `<channel source="subagent_handback">` envelope or
+        // the steering text verbatim.
+        expect(handback.text).not.toMatch(/<channel/i);
+        expect(handback.text).not.toMatch(/source="subagent_handback"/i);
+        expect(handback.text.length).toBeGreaterThan(0);
+      } finally {
+        await sc.tearDown();
+      }
+    },
+    240_000,
+  );
+});