switchroom 0.13.8 → 0.13.10

package/dist/cli/switchroom.js

@@ -47314,8 +47314,8 @@ var {
 } = import__.default;
 
 // src/build-info.ts
-var VERSION = "0.13.8";
-var COMMIT_SHA = "bb713414";
+var VERSION = "0.13.10";
+var COMMIT_SHA = "e0fd6617";
 
 // src/cli/agent.ts
 init_source();
@@ -48766,11 +48766,13 @@ function buildWorkspaceContext(args) {
 There is a real person on the other end. Every turn should feel like
 messaging a capable colleague \u2014 not a tool emitting output. Five beats:
 
-1. **Acknowledge first.** On any turn that needs real work \u2014 a file
-   read, a search, a command \u2014 your FIRST action is a short \`reply\`
-   in your own voice ("on it \u2014 checking now"), before you start. Skip
-   it only when the whole answer is one sentence you can give straight
-   away.
+1. **Acknowledge first.** Unless your whole reply is a single short
+   sentence you can send right now, your FIRST action this turn is a
+   brief \`reply\` in your own voice \u2014 "on it", "good question, one
+   sec", "let me dig in" \u2014 before any tool call and before you
+   compose the full answer. This holds even for a pure-thinking
+   answer: if it will run to a paragraph, ack first. It is the line
+   between a colleague and a black box.
 2. **Then go quiet and work.** Heads-down is correct \u2014 do NOT narrate
    every tool call. A typing indicator runs automatically while you
    work; you do not maintain it.
@@ -48780,7 +48782,10 @@ messaging a capable colleague \u2014 not a tool emitting output. Five beats:
    \`disable_notification: true\`.
 4. **Hand back delegations with synthesis.** When a sub-agent / worker
    returns, re-enter in YOUR voice \u2014 what it found, and what you are
-   doing next. Never let its raw report stand as your reply.
+   doing next. Never let its raw report stand as your reply. A
+   *background* worker finishes after your turn ends; its result
+   arrives as a fresh \`<channel source="subagent_handback">\` turn \u2014
+   treat that turn as the cue to do exactly this.
 5. **Deliver the answer** as a final \`reply\`.
 
 The one thing to avoid is *spam*: a reply on every tool call, on a
@@ -49485,7 +49490,7 @@ function buildSettingsHooksBlock(p) {
     }
   ] : [];
   const useHotReloadStable = agentConfig.channels?.telegram?.hotReloadStable === true;
-  const turnPacingDirective = "<turn-pacing>You are messaging a human. First action this turn: if " + "answering needs any tool call (a file read, a search, a command), " + "send a SHORT acknowledgement via the reply tool with " + "disable_notification true BEFORE the first tool call. Then work; " + "surface meaningful progress in human prose at real milestones; hand " + "back any sub-agent findings in your own voice; deliver the answer. " + "Skip the opening ack only for a one-sentence answer you can give " + "immediately.</turn-pacing>";
+  const turnPacingDirective = "<turn-pacing>You are messaging a human in a chat. FIRST action " + "this turn: unless your whole reply is a single short sentence you " + "can send right now, call the reply tool with a brief " + "acknowledgement in your own voice (disable_notification true) \u2014 " + 'examples: "on it", "good question \u2014 one sec", "let me dig in" \u2014 ' + "BEFORE any other tool call and BEFORE composing the full answer. " + "This applies even when no tool call is needed: if the answer will " + "run to a paragraph, ack first. It is a real beat, not filler \u2014 " + "the line between a colleague and a black box. Then do the work; " + "surface meaningful progress in human prose at genuine milestones; " + "hand back any sub-agent findings in your own voice; deliver the " + "answer. Do not acknowledge a trivial one-liner, and never " + "acknowledge twice.</turn-pacing>";
   const switchroomUserPromptSubmit = [
     ...useHotReloadStable ? [
       {
@@ -49663,7 +49668,7 @@ function reconcileAgent(name, agentConfigRaw, agentsDir, telegramConfig, switchr
   const hindsightRecallCacheTtlSecs = agentConfig.memory?.recall?.cache_ttl_secs;
   const hindsightRecallMinOverlap = agentConfig.memory?.recall?.min_overlap;
   const startShPath = join8(agentDir, "start.sh");
-  {
+  if (!options.skipProfileTemplates) {
     const basePath = getBaseProfilePath();
     const startShContext = {
       name,
@@ -49710,11 +49715,13 @@ function reconcileAgent(name, agentConfigRaw, agentsDir, telegramConfig, switchr
 There is a real person on the other end. Every turn should feel like
 messaging a capable colleague \u2014 not a tool emitting output. Five beats:
 
-1. **Acknowledge first.** On any turn that needs real work \u2014 a file
-   read, a search, a command \u2014 your FIRST action is a short \`reply\`
-   in your own voice ("on it \u2014 checking now"), before you start. Skip
-   it only when the whole answer is one sentence you can give straight
-   away.
+1. **Acknowledge first.** Unless your whole reply is a single short
+   sentence you can send right now, your FIRST action this turn is a
+   brief \`reply\` in your own voice \u2014 "on it", "good question, one
+   sec", "let me dig in" \u2014 before any tool call and before you
+   compose the full answer. This holds even for a pure-thinking
+   answer: if it will run to a paragraph, ack first. It is the line
+   between a colleague and a black box.
 2. **Then go quiet and work.** Heads-down is correct \u2014 do NOT narrate
    every tool call. A typing indicator runs automatically while you
    work; you do not maintain it.
@@ -49724,7 +49731,10 @@ messaging a capable colleague \u2014 not a tool emitting output. Five beats:
    \`disable_notification: true\`.
 4. **Hand back delegations with synthesis.** When a sub-agent / worker
    returns, re-enter in YOUR voice \u2014 what it found, and what you are
-   doing next. Never let its raw report stand as your reply.
+   doing next. Never let its raw report stand as your reply. A
+   *background* worker finishes after your turn ends; its result
+   arrives as a fresh \`<channel source="subagent_handback">\` turn \u2014
+   treat that turn as the cue to do exactly this.
 5. **Deliver the answer** as a final \`reply\`.
 
 The one thing to avoid is *spam*: a reply on every tool call, on a
@@ -49797,7 +49807,7 @@ Don't wait for a slash command. Don't ask permission. Memory work is table stake
       changes.push(startShPath);
     }
   }
-  if (!options.preserveClaudeMd) {
+  if (!options.preserveClaudeMd && !options.skipProfileTemplates) {
     const profilePath = getProfilePath(agentConfig.extends ?? DEFAULT_PROFILE);
     const claudeMdSrc = join8(profilePath, "CLAUDE.md.hbs");
     const claudeMdDest = join8(agentDir, "CLAUDE.md");
@@ -73396,13 +73406,31 @@ defaults:
     PreToolUse:
       - command: "/opt/switchroom-audit.sh"
         timeout: 5
-  # Bundled skills that ship with switchroom. \`humanizer\` removes AI-writing
-  # patterns from agent replies before they reach Telegram (29 patterns from
-  # Wikipedia's "Signs of AI writing" guide). \`humanizer-calibrate\` is its
-  # companion that builds a personal voice template from your message history.
-  # Remove from this list to disable. Per-agent \`skills:\` is unioned with
-  # this default \u2014 don't repeat shared skills in each agent.
-  skills: [humanizer, humanizer-calibrate]
+  # Bundled skills that ship with switchroom \u2014 general-purpose capabilities
+  # every agent gets by default. Per-agent \`skills:\` is unioned with this
+  # list; don't repeat shared skills in each agent. Remove an entry here to
+  # disable it fleet-wide.
+  #
+  #   docx / pdf / pptx / xlsx \u2014 Office + PDF document handling (read,
+  #                              extract, generate). Pairs with the
+  #                              pandoc/imagemagick bins in the base image.
+  #   webapp-testing           \u2014 Playwright-driven UI checks (browsers are
+  #                              baked into the agent image at
+  #                              /opt/playwright/browsers).
+  #   mcp-builder              \u2014 scaffold + iterate on MCP servers.
+  #   skill-creator            \u2014 author new Claude Code skills.
+  #   file-bug                 \u2014 structured issue filing into the operator's
+  #                              tracker.
+  #   humanizer                \u2014 strips AI-writing patterns from replies
+  #                              before they reach Telegram (29 patterns
+  #                              from Wikipedia's "Signs of AI writing").
+  #   humanizer-calibrate      \u2014 builds a personal voice template from your
+  #                              message history; feeds humanizer.
+  #
+  # Job-specific / dev-only skills (buildkite-*, telegram-test-harness,
+  # token-helpers, switchroom-*) are intentionally NOT in this default
+  # list \u2014 opt in per-agent where they apply.
+  skills: [docx, pdf, pptx, xlsx, webapp-testing, mcp-builder, skill-creator, file-bug, humanizer, humanizer-calibrate]
   # Optional: point the humanizer at a voice template generated by
   # \`/humanizer-calibrate\`. Without this, falls back to generic rules.
   # humanizer_voice_file: ~/.switchroom/voice.md
@@ -75454,7 +75482,7 @@ function reconcileAgentCronOnly(agent) {
       return { ok: false, error: `agent "${agent}" not in switchroom.yaml` };
     }
     const agentsDir = resolveAgentsDir(config);
-    const result = reconcileAgent(agent, agentConfig, agentsDir, config.telegram, config, undefined, {});
+    const result = reconcileAgent(agent, agentConfig, agentsDir, config.telegram, config, undefined, { skipProfileTemplates: true });
     const changes = [...result.changes];
     const nonCron = changes.filter((p) => classifyChangeKind(p) !== "cron");
     if (nonCron.length > 0) {

package/dist/host-control/main.js

@@ -9666,6 +9666,8 @@ var init_secretlint_source = __esm(() => {
 
 // src/host-control/main.ts
 import { homedir as homedir3 } from "node:os";
+import { existsSync as existsSync7 } from "node:fs";
+import { join as join4, resolve as resolve6 } from "node:path";
 
 // src/config/loader.ts
 import { readFileSync as readFileSync2, existsSync as existsSync3 } from "node:fs";
@@ -14702,9 +14704,11 @@ import {
   readFileSync as readFileSync4,
   writeFileSync as writeFileSync2,
   renameSync,
-  mkdirSync
+  mkdirSync,
+  unlinkSync
 } from "node:fs";
 import { join as join3, dirname as dirname2, resolve as resolve5 } from "node:path";
+import { randomUUID, randomBytes } from "node:crypto";
 
 // src/host-control/protocol.ts
 var MAX_FRAME_BYTES = 64 * 1024;
@@ -15634,7 +15638,7 @@ function validateConfigEdit(opts) {
   const leakErr = secretLeakGuard(beforeData, parsedAfter.data);
   if (leakErr)
     return leakErr;
-  return { ok: true };
+  return { ok: true, postApplyContent: applied.after };
 }
 
 // src/host-control/server.ts
@@ -15688,6 +15692,15 @@ function readCachedInstallType(bindRoot) {
   } catch {}
   return payload;
 }
+var CONFIG_APPROVAL_TIMEOUT_MS = 10 * 60 * 1000;
+function defaultApprovalId() {
+  return randomBytes(4).toString("hex");
+}
+function unlinkSyncBestEffort(path2) {
+  try {
+    unlinkSync(path2);
+  } catch {}
+}
 var STATUS_RETENTION_MS = 10 * 60 * 1000;
 var STATUS_MAX_ENTRIES = 256;
 var TAIL_BYTES = 4096;
@@ -15916,7 +15929,7 @@ class HostdServer {
           resp = await this.handleAgentSmoke(req, started);
           break;
         case "config_propose_edit":
-          resp = this.handleConfigProposeEdit(req, started);
+          resp = await this.handleConfigProposeEdit(req, caller, started);
           break;
       }
     } catch (err) {
@@ -16213,7 +16226,7 @@ class HostdServer {
       stderr_tail: tail(res.stderr)
     };
   }
-  handleConfigProposeEdit(req, started) {
+  async handleConfigProposeEdit(req, caller, started) {
     const enabled = this.opts.config.hostd?.config_edit_enabled === true;
     if (!enabled) {
       return errorResponse(req.request_id, "E_CONFIG_EDIT_DISABLED: config_propose_edit is disabled; " + "operator must set hostd.config_edit_enabled=true in " + "switchroom.yaml to opt in", Date.now() - started);
@@ -16227,7 +16240,96 @@ class HostdServer {
     if (!verdict.ok) {
       return errorResponse(req.request_id, `${verdict.code}: ${verdict.detail}`, Date.now() - started);
     }
-    return errorResponse(req.request_id, "E_NOT_IMPLEMENTED_APPLY_PATH: validation passed (apply path " + "not yet implemented — pending PR 1c)", Date.now() - started);
+    if (!this.opts.approvalGateway) {
+      return errorResponse(req.request_id, "E_NO_APPROVAL_GATEWAY: validation passed but hostd was " + "started without an approval-gateway wiring; the operator " + "build is missing the telegram-plugin link", Date.now() - started);
+    }
+    const callerName = caller.kind === "agent" ? caller.name : "operator";
+    const approvalId = (this.opts.generateApprovalId ?? defaultApprovalId)();
+    const approval = await this.opts.approvalGateway.requestApproval({
+      requestId: approvalId,
+      agentName: callerName,
+      reason: req.args.reason,
+      unifiedDiff: req.args.unified_diff,
+      timeoutMs: CONFIG_APPROVAL_TIMEOUT_MS
+    });
+    if (approval.verdict === "deny") {
+      return errorResponse(req.request_id, `E_DENIED: operator denied config_propose_edit (approval_id=${approvalId})`, Date.now() - started);
+    }
+    if (approval.verdict === "timeout") {
+      return errorResponse(req.request_id, `E_APPROVAL_TIMEOUT: operator approval card expired without a tap (approval_id=${approvalId})`, Date.now() - started);
+    }
+    const release = await this.acquireConfigApplyLock();
+    try {
+      let snapshot;
+      try {
+        snapshot = readFileSync4(configPath, "utf-8");
+      } catch (err) {
+        await approval.finalize({
+          outcome: "reconcile_failed_rolled_back",
+          detail: `pre-write snapshot read failed: ${err.message}`
+        });
+        return errorResponse(req.request_id, `E_RECONCILE_FAILED_ROLLED_BACK: snapshot read failed: ${err.message}`, Date.now() - started);
+      }
+      const postApply = verdict.postApplyContent;
+      const tmp = configPath + ".tmp";
+      try {
+        writeFileSync2(tmp, postApply);
+        renameSync(tmp, configPath);
+      } catch (err) {
+        unlinkSyncBestEffort(tmp);
+        await approval.finalize({
+          outcome: "reconcile_failed_rolled_back",
+          detail: `atomic write failed: ${err.message}`
+        });
+        return errorResponse(req.request_id, `E_RECONCILE_FAILED_ROLLED_BACK: write failed: ${err.message}`, Date.now() - started);
+      }
+      const runner = this.opts.runReconcile ?? (async () => this.runSwitchroom(["apply"]));
+      const recRes = await runner({ requestId: approvalId });
+      if (recRes.exit_code === 0) {
+        await approval.finalize({ outcome: "applied" });
+        return {
+          v: 1,
+          request_id: req.request_id,
+          result: "completed",
+          exit_code: 0,
+          duration_ms: Date.now() - started,
+          stdout_tail: tail(recRes.stdout),
+          stderr_tail: tail(recRes.stderr)
+        };
+      }
+      let rollbackDetail = "";
+      try {
+        writeFileSync2(tmp, snapshot);
+        renameSync(tmp, configPath);
+      } catch (err) {
+        rollbackDetail = `snapshot restore failed: ${err.message}`;
+        await approval.finalize({
+          outcome: "reconcile_failed_rolled_back",
+          detail: rollbackDetail
+        });
+        return errorResponse(req.request_id, `E_RECONCILE_FAILED_ROLLED_BACK: ${rollbackDetail}`, Date.now() - started);
+      }
+      const recRes2 = await runner({ requestId: approvalId });
+      const recoveryNote = recRes2.exit_code === 0 ? "rolled back successfully" : `rolled back but recovery reconcile also failed (exit ${recRes2.exit_code})`;
+      await approval.finalize({
+        outcome: "reconcile_failed_rolled_back",
+        detail: recoveryNote
+      });
+      return errorResponse(req.request_id, `E_RECONCILE_FAILED_ROLLED_BACK: reconcile exit ${recRes.exit_code}; ${recoveryNote}`, Date.now() - started);
+    } finally {
+      release();
+    }
+  }
+  configApplyLock = Promise.resolve();
+  async acquireConfigApplyLock() {
+    let release;
+    const next = new Promise((r) => {
+      release = r;
+    });
+    const prior = this.configApplyLock;
+    this.configApplyLock = prior.then(() => next);
+    await prior;
+    return release;
   }
   async handleAgentSmoke(req, started) {
     const container = `switchroom-${req.args.name}`;
@@ -16529,6 +16631,104 @@ function isSafeExecArgvElement(s) {
   return !/[\u0000-\u001f\u007f]/.test(s);
 }
 
+// src/host-control/approval-gateway.ts
+import { connect } from "node:net";
+
+class SocketApprovalGateway {
+  opts;
+  constructor(opts) {
+    this.opts = opts;
+  }
+  async requestApproval(req) {
+    const sockPath = this.opts.resolveGatewaySocket(req.agentName);
+    if (sockPath === null) {
+      return {
+        verdict: "deny",
+        finalize: async () => {}
+      };
+    }
+    return await new Promise((resolve6) => {
+      const client = connect({ path: sockPath });
+      let buffer = "";
+      let resolved = false;
+      const log = this.opts.log ?? (() => {});
+      const finalize = async (outcome) => {
+        if (client.destroyed)
+          return;
+        try {
+          client.write(JSON.stringify({
+            type: "request_config_finalize",
+            requestId: req.requestId,
+            outcome: outcome.outcome,
+            ...outcome.detail ? { detail: outcome.detail } : {}
+          }) + `
+`);
+          client.end();
+        } catch (err) {
+          log(`finalize write failed (requestId=${req.requestId}): ${err.message}`);
+        }
+      };
+      client.on("connect", () => {
+        try {
+          client.write(JSON.stringify({
+            type: "request_config_approval",
+            requestId: req.requestId,
+            agentName: req.agentName,
+            reason: req.reason,
+            unifiedDiff: req.unifiedDiff,
+            timeoutMs: req.timeoutMs
+          }) + `
+`);
+        } catch (err) {
+          if (resolved)
+            return;
+          resolved = true;
+          log(`request_config_approval write failed (requestId=${req.requestId}): ${err.message}`);
+          resolve6({ verdict: "deny", finalize: async () => {} });
+        }
+      });
+      client.on("data", (chunk2) => {
+        buffer += chunk2.toString("utf8");
+        const lines = buffer.split(`
+`);
+        buffer = lines.pop() ?? "";
+        for (const line of lines) {
+          if (!line.trim())
+            continue;
+          let parsed;
+          try {
+            parsed = JSON.parse(line);
+          } catch {
+            log(`bad JSON from gateway: ${line.slice(0, 200)}`);
+            continue;
+          }
+          const obj = parsed;
+          if (obj.type === "config_approval_resolved" && obj.requestId === req.requestId && (obj.verdict === "approve" || obj.verdict === "deny" || obj.verdict === "timeout") && !resolved) {
+            resolved = true;
+            resolve6({
+              verdict: obj.verdict,
+              finalize
+            });
+          }
+        }
+      });
+      client.on("error", (err) => {
+        if (resolved)
+          return;
+        resolved = true;
+        log(`gateway socket error (requestId=${req.requestId}): ${err.message}`);
+        resolve6({ verdict: "deny", finalize: async () => {} });
+      });
+      client.on("close", () => {
+        if (resolved)
+          return;
+        resolved = true;
+        resolve6({ verdict: "deny", finalize: async () => {} });
+      });
+    });
+  }
+}
+
 // src/host-control/main.ts
 async function main() {
   const config = loadConfig();
@@ -16547,12 +16747,27 @@ async function main() {
     process.stderr.write("hostd: no admin-flagged agents — nothing to serve. Set `admin: true` on at least one agent.\n");
     process.exit(2);
   }
+  const agentsDir = process.env.SWITCHROOM_AGENTS_DIR ?? join4(homedir3(), ".switchroom", "agents");
+  const approvalGateway = new SocketApprovalGateway({
+    resolveGatewaySocket: (agentName) => {
+      const sock = resolve6(agentsDir, agentName, "telegram", "gateway.sock");
+      return existsSync7(sock) ? sock : null;
+    },
+    log: (m) => process.stderr.write(`hostd: approval-gateway — ${m}
+`)
+  });
   const server = new HostdServer({
     homeDir: homedir3(),
     agentUids,
     config: {
-      agents: Object.fromEntries(Object.entries(config.agents).map(([n, a]) => [n, { admin: a.admin === true }]))
-    }
+      agents: Object.fromEntries(Object.entries(config.agents).map(([n, a]) => [n, { admin: a.admin === true }])),
+      ...config.hostd ? {
+        hostd: {
+          ...config.hostd.config_edit_enabled !== undefined ? { config_edit_enabled: config.hostd.config_edit_enabled } : {}
+        }
+      } : {}
+    },
+    approvalGateway
   });
   await server.start();
   const paths = server.getBoundPaths();

package/examples/switchroom.yaml

@@ -71,13 +71,31 @@ defaults:
     PreToolUse:
       - command: "/opt/switchroom-audit.sh"
         timeout: 5
-  # Bundled skills that ship with switchroom. `humanizer` removes AI-writing
-  # patterns from agent replies before they reach Telegram (29 patterns from
-  # Wikipedia's "Signs of AI writing" guide). `humanizer-calibrate` is its
-  # companion that builds a personal voice template from your message history.
-  # Remove from this list to disable. Per-agent `skills:` is unioned with
-  # this default — don't repeat shared skills in each agent.
-  skills: [humanizer, humanizer-calibrate]
+  # Bundled skills that ship with switchroom — general-purpose capabilities
+  # every agent gets by default. Per-agent `skills:` is unioned with this
+  # list; don't repeat shared skills in each agent. Remove an entry here to
+  # disable it fleet-wide.
+  #
+  #   docx / pdf / pptx / xlsx — Office + PDF document handling (read,
+  #                              extract, generate). Pairs with the
+  #                              pandoc/imagemagick bins in the base image.
+  #   webapp-testing           — Playwright-driven UI checks (browsers are
+  #                              baked into the agent image at
+  #                              /opt/playwright/browsers).
+  #   mcp-builder              — scaffold + iterate on MCP servers.
+  #   skill-creator            — author new Claude Code skills.
+  #   file-bug                 — structured issue filing into the operator's
+  #                              tracker.
+  #   humanizer                — strips AI-writing patterns from replies
+  #                              before they reach Telegram (29 patterns
+  #                              from Wikipedia's "Signs of AI writing").
+  #   humanizer-calibrate      — builds a personal voice template from your
+  #                              message history; feeds humanizer.
+  #
+  # Job-specific / dev-only skills (buildkite-*, telegram-test-harness,
+  # token-helpers, switchroom-*) are intentionally NOT in this default
+  # list — opt in per-agent where they apply.
+  skills: [docx, pdf, pptx, xlsx, webapp-testing, mcp-builder, skill-creator, file-bug, humanizer, humanizer-calibrate]
   # Optional: point the humanizer at a voice template generated by
   # `/humanizer-calibrate`. Without this, falls back to generic rules.
   # humanizer_voice_file: ~/.switchroom/voice.md

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switchroom",
-  "version": "0.13.8",
+  "version": "0.13.10",
   "description": "Run Claude Code 24/7 on your Claude Pro/Max subscription over Telegram. Open-source alternative to OpenClaw and NanoClaw — no API keys.",
   "type": "module",
   "bin": {

package/profiles/_shared/telegram-style.md.hbs

@@ -5,10 +5,10 @@ Telegram is a chat — replies should feel like one, not a terminal dump or a tr
 **Every turn that responds to a user message MUST end with a `reply` (or `stream_reply` with `done=true`).** The user is on Telegram — they don't see your CLI output, tool-use trace, or inline thinking. The ONLY path for words to reach them is an MCP tool call. If you have a final answer, send it via `reply`. The text in your terminal is not the conversation.
 
 **Conversational pacing — a human is on the other side.** Match the rhythm of a capable colleague messaging you back. Five beats:
-- **1 · Acknowledge first.** Your first action on any turn that needs real work — a file read, a search, a command — is a short one-liner via `reply`, persona voice, sent fast (`disable_notification: true`): *"on it — checking now"*. Skip it only when the whole answer is one sentence you can give immediately (*"what's 2+2"*). This is a beat, not filler — it's the line between a colleague and a black box.
+- **1 · Acknowledge first.** Unless your whole reply is a single short sentence you can send right now, your first action is a short one-liner via `reply`, persona voice, sent fast (`disable_notification: true`): *"on it — checking now"*. This holds whether the work ahead is a tool call or a paragraph of pure reasoning — if the answer will run long, ack *before* you compose it. Skip the ack only for an immediate one-sentence answer (*"what's 2+2"*). This is a beat, not filler — it's the line between a colleague and a black box.
 - **2 · Then go quiet and work.** Heads-down is right — do **not** narrate every tool call. A typing indicator runs for you automatically; you don't keep it alive.
 - **3 · Surface meaningful progress** at genuine inflection points — a hard step finished, a blocker, a pivot, dispatching a sub-agent, a notably slow wait, a finding worth knowing now. One short `reply`, `disable_notification: true` (no mid-turn ping).
-- **4 · Hand back delegations with synthesis.** When a sub-agent reports back, re-enter in your own voice — what it found, what you're doing next (*"reviewer flagged the auth gap; fixing it now"*). Never let its raw report stand as your reply.
+- **4 · Hand back delegations with synthesis.** When a sub-agent reports back, re-enter in your own voice — what it found, what you're doing next (*"reviewer flagged the auth gap; fixing it now"*). Never let its raw report stand as your reply. A *background* worker finishes after your turn has ended — its result is delivered to you as a fresh `<channel source="subagent_handback">` turn. That turn IS your cue: synthesise it for the user right then; don't treat it as noise and don't stay silent.
 - **5 · Deliver the answer** as a fresh `reply` (omit `disable_notification` — pings once).
 
 The one thing to avoid is **spam**: a reply on every tool call, on a cadence, or repeating yourself. Responsive and human, never a flood. A `<system-reminder>` containing `[silence-poke]` means you've gone quiet too long — send one short `reply` and carry on; skip it only if you're within ~5s of finishing.