@polygraph/claude-plugin 0.5.0 → 0.5.2

package/hooks/capture-cli.mjs

@@ -0,0 +1,294 @@
+import { spawn as spawnChild, spawnSync } from 'node:child_process';
+import { closeSync, mkdirSync, openSync, renameSync, statSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+
+const JS_CLI_ENTRY = /\.[cm]?js$/i;
+export const HOOK_WORKER_LOG_MAX_BYTES = 5 * 1024 * 1024;
+
+export function nonEmptyString(value) {
+  return typeof value === 'string' && value.trim() ? value : undefined;
+}
+
+export function isManagedChildEnvironment(env) {
+  return Boolean(env && Object.hasOwn(env, 'POLYGRAPH_CHILD_AGENT'));
+}
+
+export function captureCommandEnvironment(env = process.env) {
+  const commandEnv = { ...env };
+  delete commandEnv.POLYGRAPH_SESSION_ID;
+  delete commandEnv.POLYGRAPH_CAPTURE_TOKEN;
+  return commandEnv;
+}
+
+/**
+ * The directory a capture process is launched from. A claim carries the
+ * harness working directory, but that directory can be gone by the time a
+ * delayed hook or detached worker runs (an archived session worktree, a
+ * removed temp dir), and a spawn from a missing cwd fails with ENOENT before
+ * the CLI ever starts. Working-directory evidence reaches the CLI as an
+ * explicit `--cwd` argument where it matters, so the launch itself only
+ * needs a directory that exists: the claim's own when it does, else the home
+ * directory, else the temp directory.
+ */
+export function resolveLaunchDirectory(preferred, env = process.env) {
+  const candidates = [preferred, nonEmptyString(env?.HOME) ?? homedir(), tmpdir()];
+  for (const candidate of candidates) {
+    const directory = nonEmptyString(candidate);
+    if (!directory) continue;
+    try {
+      if (statSync(directory).isDirectory()) return directory;
+    } catch {
+      // Missing or unreadable: try the next candidate.
+    }
+  }
+  return undefined;
+}
+
+/**
+ * The hook process's own working directory, or undefined when it no longer
+ * has one. A harness can start a hook in a directory removed moments earlier
+ * or remove it while the hook runs, and `process.cwd()` then throws
+ * `uv_cwd`. Callers use this only as the last-resort claim directory, so a
+ * missing answer degrades to the launch fallback instead of a crash.
+ */
+export function processWorkingDirectory() {
+  try {
+    return process.cwd();
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The working directory a claim may record when the payload carries none.
+ * Claude and Codex run command hooks in the session's own directory, so the
+ * hook process's cwd is genuine harness evidence there. Cursor runs plugin
+ * hooks from the plugin root, which is never the repository: a Cursor claim
+ * without workspace_roots records no directory at all, and the launch
+ * fallback (home, then temp) stays a spawn detail rather than evidence.
+ */
+export function fallbackClaimDirectory(agentType, hookCwd) {
+  if (agentType === 'cursor') return undefined;
+  return nonEmptyString(hookCwd) ?? processWorkingDirectory();
+}
+
+/**
+ * A hook-captured observation time: a positive epoch-millisecond integer, or
+ * undefined for anything else. Wakes and finalizations both carry one, and
+ * neither ever substitutes a worker's own clock for it.
+ */
+export function observedAtValue(value) {
+  return Number.isSafeInteger(value) && value > 0 ? value : undefined;
+}
+
+function nodeRuntime(execPath) {
+  const base = basename(execPath).toLowerCase();
+  return base === 'node' || base === 'node.exe' ? execPath : 'node';
+}
+
+function portableReexec(env, platform) {
+  const raw = nonEmptyString(env.POLYGRAPH_CLI_REEXEC);
+  if (!raw || platform !== 'win32') return undefined;
+
+  try {
+    const parsed = JSON.parse(raw);
+    if (
+      Array.isArray(parsed) &&
+      parsed.length > 0 &&
+      parsed.every((part) => nonEmptyString(part))
+    ) {
+      return parsed;
+    }
+  } catch {
+    // An invalid portability hint is ignored in favor of the normal launch.
+  }
+  return undefined;
+}
+
+function deadlineExceededResult() {
+  const error = new Error('Polygraph capture command timed out before launch');
+  error.code = 'ETIMEDOUT';
+  return { error, status: null, signal: 'SIGTERM' };
+}
+
+function withRemainingTimeout(options, deadline, now) {
+  if (deadline === undefined) return options;
+  const remaining = Math.floor(deadline - now());
+  if (remaining < 1) return undefined;
+  const configured = Number.isFinite(options.timeout) ? options.timeout : remaining;
+  return { ...options, timeout: Math.min(configured, remaining) };
+}
+
+function runBeforeDeadline(spawn, command, args, options, deadline, now) {
+  const boundedOptions = withRemainingTimeout(options, deadline, now);
+  if (!boundedOptions) return deadlineExceededResult();
+  // Some runtimes hosting these hooks in-process (OpenCode runs under Bun)
+  // THROW launch errors from spawnSync instead of returning them in
+  // result.error. Both shapes must land in the same error path.
+  try {
+    return spawn(command, args, boundedOptions);
+  } catch (error) {
+    return { error, status: null, signal: null };
+  }
+}
+
+export function runCaptureCliSync(
+  args,
+  {
+    env = process.env,
+    spawn = spawnSync,
+    options = {},
+    cwd,
+    deadline,
+    now = Date.now,
+    platform = process.platform,
+    execPath = process.execPath,
+  } = {}
+) {
+  const command = nonEmptyString(env.POLYGRAPH_CLI) ?? 'polygraph';
+  const reexec = portableReexec(env, platform);
+  const launchDirectory = resolveLaunchDirectory(cwd, env);
+  const spawnOptions = {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    ...options,
+    ...(launchDirectory ? { cwd: launchDirectory } : {}),
+    env: captureCommandEnvironment(env),
+    shell: false,
+    windowsHide: true,
+  };
+
+  // A plain JavaScript CLI entry (a local package install, a dev build without
+  // the executable bit) is never executed directly: direct execution fails
+  // EACCES/ENOEXEC on most platforms and Bun surfaces that as a synchronous
+  // throw. Running it through Node up front means exactly one process ever
+  // launches per wake — there is no ambiguity about which attempt ran.
+  let executable;
+  let prefixArgs;
+  if (reexec) {
+    [executable, ...prefixArgs] = reexec;
+  } else if (JS_CLI_ENTRY.test(command)) {
+    executable = nodeRuntime(execPath);
+    prefixArgs = [command];
+  } else {
+    executable = command;
+    prefixArgs = [];
+  }
+
+  return runBeforeDeadline(
+    spawn,
+    executable,
+    [...prefixArgs, ...args],
+    spawnOptions,
+    deadline,
+    now
+  );
+}
+
+function reportWorkerLaunchFailure(onFailure, error) {
+  try {
+    const pending = onFailure(error);
+    if (pending && typeof pending.catch === 'function') {
+      pending.catch(() => {});
+    }
+  } catch {
+    // A detached handoff must never turn diagnostics into a hook failure.
+  }
+}
+
+// A worker's inherited stdout/stderr land in one append-only log per worker
+// kind, rotated to `.1` past the same bound as hooks.log so a chatty CLI can
+// never grow it without limit.
+export function openHookWorkerLog(env, logName) {
+  const home = nonEmptyString(env?.HOME) ?? homedir();
+  const logsDir = join(home, '.polygraph', 'logs');
+  mkdirSync(logsDir, { recursive: true });
+  const logFile = join(logsDir, logName);
+
+  try {
+    if (statSync(logFile).size > HOOK_WORKER_LOG_MAX_BYTES) {
+      renameSync(logFile, `${logFile}.1`);
+    }
+  } catch {
+    // There may be no prior log, and rotation must stay best-effort.
+  }
+
+  return openSync(logFile, 'a', 0o600);
+}
+
+/**
+ * Hand a serialized claim to a detached Node worker and return immediately.
+ * The worker owns the complete CLI invocation and its durable failure
+ * logging; the short-lived parent hook observes launch errors only, because
+ * it cannot outlive the harness event that spawned it.
+ *
+ * The worker is a plain JS module, so it always launches through a Node
+ * runtime: process.execPath is the host binary, and under OpenCode that is
+ * the compiled Bun executable rather than Node.
+ */
+export function launchDetachedHookWorker({
+  workerPath,
+  claim,
+  logName,
+  spawn = spawnChild,
+  env = process.env,
+  execPath = process.execPath,
+  onFailure = () => {},
+  openLog = openHookWorkerLog,
+  closeLog = closeSync,
+}) {
+  // The log is diagnostic only. If it cannot be opened (unwritable home,
+  // exhausted descriptors) the worker still launches with its output
+  // discarded; its own durable hooks.log write does not depend on it.
+  let logFd;
+  try {
+    logFd = openLog(env, logName);
+  } catch (error) {
+    reportWorkerLaunchFailure(onFailure, error);
+  }
+  const output = logFd === undefined ? 'ignore' : logFd;
+
+  // The serialized claim keeps the harness cwd as evidence even when the
+  // launch has to happen elsewhere.
+  const launchDirectory = resolveLaunchDirectory(claim.cwd, env);
+
+  let child;
+  try {
+    child = spawn(nodeRuntime(execPath), [workerPath, JSON.stringify(claim)], {
+      ...(launchDirectory ? { cwd: launchDirectory } : {}),
+      detached: true,
+      env: captureCommandEnvironment(env),
+      shell: false,
+      stdio: ['ignore', output, output],
+      windowsHide: true,
+    });
+  } finally {
+    if (logFd !== undefined) {
+      try {
+        closeLog(logFd);
+      } catch (error) {
+        reportWorkerLaunchFailure(onFailure, error);
+      }
+    }
+  }
+
+  child.once('error', (error) => reportWorkerLaunchFailure(onFailure, error));
+  child.unref();
+
+  return true;
+}
+
+export function cliFailure(commandName, result) {
+  if (result?.error) return result.error;
+  const stderr = nonEmptyString(result?.stderr);
+  const stdout = nonEmptyString(result?.stdout);
+  const detail = stderr ?? stdout;
+  const outcome = result?.signal
+    ? `terminated by signal ${result.signal}`
+    : `exited with status ${String(result?.status)}`;
+  return new Error(
+    `polygraph ${commandName} ${outcome}` +
+      (detail ? `: ${detail}` : '')
+  );
+}

package/hooks/ensure-agent-session-capture-worker.mjs

@@ -0,0 +1,63 @@
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+import { ensureAgentSessionCapture } from './agent-session-capture.mjs';
+import { logHookFailure } from './agent-session-link.mjs';
+
+function writeWorkerFailure(error, claim) {
+  try {
+    const entry = {
+      time: new Date().toISOString(),
+      hook: `${claim?.agentType ?? 'unknown'}:ensure-agent-session-capture-worker`,
+      pid: process.pid,
+      agentSessionId: claim?.agentSessionId,
+      error: error instanceof Error ? error.message : String(error),
+      ...(error instanceof Error && error.stack ? { stack: error.stack } : {}),
+    };
+    process.stderr.write(JSON.stringify(entry) + '\n');
+  } catch {
+    // The inherited log stream is diagnostic only.
+  }
+}
+
+export function main({
+  serializedClaim = process.argv[2],
+  env = process.env,
+  spawn,
+  logFailure = logHookFailure,
+  writeFailure = writeWorkerFailure,
+} = {}) {
+  let claim;
+  try {
+    claim = JSON.parse(serializedClaim);
+    return ensureAgentSessionCapture(claim, spawn, env);
+  } catch (error) {
+    writeFailure(error, claim);
+    try {
+      logFailure(
+        `${claim?.agentType ?? 'unknown'}:ensure-agent-session-capture-worker`,
+        error,
+        {
+          agentSessionId: claim?.agentSessionId,
+          cli: env.POLYGRAPH_CLI || 'polygraph',
+        }
+      );
+    } catch {
+      // The worker is already detached; diagnostics cannot be allowed to crash it.
+    }
+    return false;
+  }
+}
+
+function isMainModule() {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+if (isMainModule()) {
+  process.exitCode = main() ? 0 : 1;
+}

package/hooks/ensure-agent-session-capture.mjs

@@ -0,0 +1,79 @@
+import { readFileSync, realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+import {
+  buildCommandHookEnsureCapture,
+  ensureAgentSessionCapture,
+  launchAgentSessionCaptureWake,
+} from './agent-session-capture.mjs';
+import { hookPayloadSessionId, logHookFailure } from './agent-session-link.mjs';
+import { fallbackClaimDirectory } from './capture-cli.mjs';
+
+function readPayload() {
+  try {
+    const raw = readFileSync(0, 'utf8');
+    return raw ? JSON.parse(raw) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function main({
+  payload = readPayload(),
+  agentType = process.argv[2],
+  // Harness manifests without an async hook flag pass --detach so the hook
+  // returns immediately; a detached worker then owns the bounded wake. This
+  // matters most for cursor's blocking beforeSubmitPrompt, which would
+  // otherwise stall every prompt on a slow CLI.
+  detach = process.argv.includes('--detach'),
+  env = process.env,
+  spawn,
+  logFailure = logHookFailure,
+  // The hook's own directory is read lazily, inside the protected path, and
+  // only when the payload carries none and the harness runs hooks in the
+  // session directory: a default evaluated at entry would throw uv_cwd from
+  // an already-deleted cwd before any fallback could run, and Cursor's hook
+  // cwd is the plugin root rather than the repository.
+  cwd,
+  launcherOptions = {},
+  now = Date.now,
+} = {}) {
+  const reportFailure = (error) =>
+    logFailure(`${agentType || 'unknown'}:ensure-agent-session-capture`, error, {
+      hookEventName: payload?.hook_event_name,
+      agentSessionId: hookPayloadSessionId(payload),
+    });
+
+  try {
+    const built = buildCommandHookEnsureCapture(payload, agentType, env, now);
+    if (!built) return false;
+
+    const claim = {
+      ...built,
+      cwd: built.cwd ?? fallbackClaimDirectory(agentType, cwd),
+    };
+    if (detach) {
+      return launchAgentSessionCaptureWake(claim, spawn, env, {
+        ...launcherOptions,
+        onFailure: reportFailure,
+      });
+    }
+    return ensureAgentSessionCapture(claim, spawn, env);
+  } catch (error) {
+    reportFailure(error);
+    return false;
+  }
+}
+
+function isMainModule() {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+if (isMainModule()) {
+  main();
+}

package/hooks/finalize-agent-session-worker.mjs

@@ -0,0 +1,63 @@
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+import { finalizeAgentSession } from './agent-session-finalize.mjs';
+import { logHookFailure } from './agent-session-link.mjs';
+
+function writeWorkerFailure(error, claim) {
+  try {
+    const entry = {
+      time: new Date().toISOString(),
+      hook: `${claim?.agentType ?? 'unknown'}:finalize-agent-session-worker`,
+      pid: process.pid,
+      agentSessionId: claim?.agentSessionId,
+      error: error instanceof Error ? error.message : String(error),
+      ...(error instanceof Error && error.stack ? { stack: error.stack } : {}),
+    };
+    process.stderr.write(JSON.stringify(entry) + '\n');
+  } catch {
+    // The inherited log stream is diagnostic only.
+  }
+}
+
+export function main({
+  serializedClaim = process.argv[2],
+  env = process.env,
+  spawn,
+  logFailure = logHookFailure,
+  writeFailure = writeWorkerFailure,
+} = {}) {
+  let claim;
+  try {
+    claim = JSON.parse(serializedClaim);
+    return finalizeAgentSession(claim, spawn, env);
+  } catch (error) {
+    writeFailure(error, claim);
+    try {
+      logFailure(
+        `${claim?.agentType ?? 'unknown'}:finalize-agent-session-worker`,
+        error,
+        {
+          agentSessionId: claim?.agentSessionId,
+          cli: env.POLYGRAPH_CLI || 'polygraph',
+        }
+      );
+    } catch {
+      // The worker is already detached; diagnostics cannot be allowed to crash it.
+    }
+    return false;
+  }
+}
+
+function isMainModule() {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+if (isMainModule()) {
+  process.exitCode = main() ? 0 : 1;
+}

package/hooks/finalize-agent-session.mjs

@@ -3,9 +3,10 @@ import { fileURLToPath } from 'node:url';
 
 import {
   buildCommandHookFinalize,
-  finalizeAgentSession,
+  launchAgentSessionFinalize,
 } from './agent-session-finalize.mjs';
-import { logHookFailure } from './agent-session-link.mjs';
+import { hookPayloadSessionId, logHookFailure } from './agent-session-link.mjs';
+import { fallbackClaimDirectory } from './capture-cli.mjs';
 
 function readPayload() {
   try {
@@ -21,23 +22,36 @@ export function main({
   agentType = process.argv[2],
   env = process.env,
   spawn,
+  logFailure = logHookFailure,
+  // The hook's own directory is read lazily, inside the protected path, and
+  // only when the payload carries none and the harness runs hooks in the
+  // session directory: a default evaluated at entry would throw uv_cwd from
+  // an already-deleted cwd before any fallback could run, and Cursor's hook
+  // cwd is the plugin root rather than the repository.
+  cwd,
+  launcherOptions = {},
+  now = Date.now,
 } = {}) {
+  const reportFailure = (error) =>
+    logFailure(`${agentType || 'unknown'}:finalize-agent-session`, error, {
+      hookEventName: payload?.hook_event_name,
+      agentSessionId: hookPayloadSessionId(payload),
+    });
+
   try {
-    const finalize = buildCommandHookFinalize(payload, agentType, env);
+    const finalize = buildCommandHookFinalize(payload, agentType, env, now);
     if (!finalize) return false;
-    return finalizeAgentSession(
+    return launchAgentSessionFinalize(
       {
         ...finalize,
-        cwd: finalize.cwd ?? process.cwd(),
+        cwd: finalize.cwd ?? fallbackClaimDirectory(agentType, cwd),
       },
       spawn,
-      env
+      env,
+      { ...launcherOptions, onFailure: reportFailure }
     );
   } catch (error) {
-    logHookFailure(`${agentType || 'unknown'}:finalize-agent-session`, error, {
-      hookEventName: payload?.hook_event_name,
-      agentSessionId: payload?.session_id,
-    });
+    reportFailure(error);
     return false;
   }
 }

package/hooks/hooks.json

@@ -25,7 +25,7 @@
     ],
     "SessionStart": [
       {
-        "matcher": "startup|resume|compact",
+        "matcher": "startup|resume|clear|compact|fork",
         "hooks": [
           {
             "type": "command",
@@ -39,6 +39,28 @@
         ]
       }
     ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/ensure-agent-session-capture.mjs claude",
+            "async": true
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/ensure-agent-session-capture.mjs claude",
+            "async": true
+          }
+        ]
+      }
+    ],
     "SessionEnd": [
       {
         "hooks": [

package/hooks/record-session-mapping.mjs

@@ -3,9 +3,11 @@ import { fileURLToPath } from 'node:url';
 
 import {
   buildCommandHookLink,
+  hookPayloadSessionId,
   linkAgentSession,
   logHookFailure,
 } from './agent-session-link.mjs';
+import { fallbackClaimDirectory } from './capture-cli.mjs';
 
 function readPayload() {
   try {
@@ -20,29 +22,29 @@ export function main({
   payload = readPayload(),
   agentType = process.argv[2],
   env = process.env,
-  pid = process.ppid,
   spawn,
+  logFailure = logHookFailure,
 } = {}) {
   try {
     const link = buildCommandHookLink(payload, agentType, env);
     if (!link) return false;
 
-    const claim = {
-      ...link,
-      cwd: link.cwd ?? process.cwd(),
-    };
-    // Claude lifecycle hooks deliberately forward only the exact harness
-    // identity, transcript, cwd, and hook source. PID is not identity and can
-    // be stale by the time an asynchronous SessionStart hook runs.
-    if (!(agentType === 'claude' && payload?.hook_event_name === 'SessionStart')) {
-      claim.pid = pid;
-    }
-
-    return linkAgentSession(claim, spawn, env);
+    // Claude and Codex run this hook in the session directory, so the hook's
+    // own cwd stands in when the payload carries none; Cursor's hook cwd is
+    // the plugin root and is never recorded. Read lazily, inside the
+    // protected path, because a deleted cwd makes process.cwd() throw.
+    return linkAgentSession(
+      {
+        ...link,
+        cwd: link.cwd ?? fallbackClaimDirectory(agentType),
+      },
+      spawn,
+      env
+    );
   } catch (error) {
-    logHookFailure(`${agentType || 'unknown'}:link-agent-session`, error, {
+    logFailure(`${agentType || 'unknown'}:link-agent-session`, error, {
       hookEventName: payload?.hook_event_name,
-      agentSessionId: payload?.session_id,
+      agentSessionId: hookPayloadSessionId(payload),
     });
     return false;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polygraph/claude-plugin",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "AI agent skills and subagents for Polygraph sessions, repository context, and coordination",
   "license": "UNLICENSED",
   "private": false,

package/skills/polygraph/SKILL.md

@@ -35,6 +35,7 @@ Polygraph functionality is available via both MCP tools and CLI commands. Use wh
 | `stop_agent` | — | Cancel an in-progress child by delegation id; its session is preserved for later read-only context restoration. |
 | `push_branch` | — | Push a local git branch to the remote repository. For the repo you are in, this pushes from your current checkout. Requires a session description. |
 | `create_pr` | — | Create draft PRs with session metadata linking related PRs |
+| `update_pr` | — | Update title, user-authored body, labels, or assignees on one PR associated with a session |
 | `show_session` | `polygraph session show <id> [--details]` | Query status of the current session. Use details when session summary, repo IDs, PR URLs, and PR descriptions are needed. |
 | `update_session` | `polygraph session update --session <id> [--title] [--description]` | Update the session title and/or description (at least one required); metadata only, independent of PR creation or mark-ready. |
 | `link_reference` | — | Link an external reference to a session. |
@@ -211,9 +212,9 @@ The `allow_agent` and `deny_agent` tools exist for parents whose MCP clients do
 
 ### Publish Changes (Push Branches, Create PRs, Mark Ready)
 
-Publishing covers the branch-to-PR flow: `push_branch` (push local commits; must precede PR creation), `create_pr` (linked draft PRs, including fork PRs via `targetRepository`), `mark_pr_ready` (transition drafts to OPEN), and `associate_pr` (link PRs created outside Polygraph).
+Publishing covers the branch-to-PR flow: `push_branch` (push local commits; must precede PR creation), `create_pr` (linked draft PRs, including fork PRs via `targetRepository`), `mark_pr_ready` (transition drafts to OPEN), `associate_pr` (link PRs created outside Polygraph), and `update_pr` (update metadata on an associated PR).
 
-**Whenever you push a branch, create or associate a PR, or mark PRs ready, read [`reference/publish-changes.md`](reference/publish-changes.md) first.** That reference file holds the full flow.
+**Whenever you push a branch, create, associate, or update a PR, or mark PRs ready, read [`reference/publish-changes.md`](reference/publish-changes.md) first.** That reference file holds the full flow.
 
 ### Session Description Policy
 
@@ -295,6 +296,7 @@ If the session has a description timeline, also display:
 1. **Wait in background subagents** — `spawn_agent` is fine to call directly, but every waited `show_agent` poll belongs in a `Task(run_in_background: true)`; inline polling floods the context with status noise.
    
 1. **Read each result once** — when a poller exits, read that child with a single unwaited `show_agent(sessionId, id)`; `result.text` is the child's final message. Only reach for an explicit `tail` if that is not enough.
+1. **State the output in every brief** — children are told to be concise, so the instruction must say what to return: the shape, a cap where one makes sense, and the exact token for "nothing to report". See [`reference/delegation.md`](reference/delegation.md).
 1. **Poll child status before proceeding** — Always verify child agents have reached a terminal `child.status` (`'completed'`, `'failed'`, or `'cancelled'`) before pushing branches or creating PRs
 1. **Link PRs in descriptions** - Reference related PRs in each PR body
 1. **Keep PRs as drafts** until all repos are ready