@standardagents/skill 0.17.0-next.a4b7340 → 0.17.1

package/dist/index.d.ts

@@ -17,9 +17,10 @@ declare function listSkills(): SkillDefinition[];
 declare function getSkill(name: SkillName): SkillDefinition;
 declare function resolveSkillDir(name: SkillName): string;
 declare function resolveSkillFile(name: SkillName, ...segments: string[]): string;
+declare function skillPackageVersion(): Promise<string>;
 declare function readSkillFile(name: SkillName, ...segments: string[]): Promise<string>;
 declare function copySkill(name: SkillName, destinationRoot: string, options?: CopySkillOptions): Promise<string>;
 declare const skillPackageRoot: string;
 declare const skillsRoot: string;
 
-export { type CopySkillOptions, type SkillDefinition, type SkillName, copySkill, getSkill, listSkills, readSkillFile, resolveSkillDir, resolveSkillFile, skillPackageRoot, skillsRoot };
+export { type CopySkillOptions, type SkillDefinition, type SkillName, copySkill, getSkill, listSkills, readSkillFile, resolveSkillDir, resolveSkillFile, skillPackageRoot, skillPackageVersion, skillsRoot };

package/dist/index.js

@@ -1,9 +1,10 @@
 // src/index.ts
-import { cp, mkdir, readFile } from "fs/promises";
+import { cp, mkdir, readFile, writeFile } from "fs/promises";
 import { fileURLToPath } from "url";
 import { isAbsolute, relative, resolve } from "path";
 var PACKAGE_ROOT = fileURLToPath(new URL("../", import.meta.url));
 var SKILLS_ROOT = resolve(PACKAGE_ROOT, "skills");
+var VERSION_STAMP_PATTERN = /<!--\s*installed-skill-version:\s*__SKILL_VERSION__\s*-->/g;
 var SKILL_CATALOG = {
   agentbuilder: {
     description: "Compose Standard Agents from models, prompts, tools, hooks, APIs, and subagents using markdown-authored guidance."
@@ -44,9 +45,26 @@ function resolveSkillDir(name) {
 function resolveSkillFile(name, ...segments) {
   return resolveInside(resolveSkillDir(name), segments);
 }
+var cachedVersion = null;
+function skillPackageVersion() {
+  cachedVersion ??= readFile(resolve(PACKAGE_ROOT, "package.json"), "utf8").then(
+    (manifest) => JSON.parse(manifest).version
+  );
+  return cachedVersion;
+}
+async function stampSkillVersion(content) {
+  if (!content.includes("__SKILL_VERSION__")) {
+    return content;
+  }
+  const version = await skillPackageVersion();
+  return content.replace(
+    VERSION_STAMP_PATTERN,
+    `<!-- installed-skill-version: ${version} -->`
+  );
+}
 async function readSkillFile(name, ...segments) {
   const target = segments.length === 0 ? resolveSkillFile(name, "SKILL.md") : resolveSkillFile(name, ...segments);
-  return readFile(target, "utf8");
+  return stampSkillVersion(await readFile(target, "utf8"));
 }
 async function copySkill(name, destinationRoot, options = {}) {
   const sourceDir = resolveSkillDir(name);
@@ -58,6 +76,9 @@ async function copySkill(name, destinationRoot, options = {}) {
     force: options.overwrite ?? false,
     errorOnExist: !(options.overwrite ?? false)
   });
+  const entryFile = resolve(targetDir, "SKILL.md");
+  const entryContent = await readFile(entryFile, "utf8");
+  await writeFile(entryFile, await stampSkillVersion(entryContent), "utf8");
   return targetDir;
 }
 var skillPackageRoot = PACKAGE_ROOT;
@@ -70,6 +91,7 @@ export {
   resolveSkillDir,
   resolveSkillFile,
   skillPackageRoot,
+  skillPackageVersion,
   skillsRoot
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import { cp, mkdir, readFile } from 'node:fs/promises'\nimport { fileURLToPath } from 'node:url'\nimport { isAbsolute, relative, resolve } from 'node:path'\n\nconst PACKAGE_ROOT = fileURLToPath(new URL('../', import.meta.url))\nconst SKILLS_ROOT = resolve(PACKAGE_ROOT, 'skills')\n\nconst SKILL_CATALOG = {\n  agentbuilder: {\n    description:\n      'Compose Standard Agents from models, prompts, tools, hooks, APIs, and subagents using markdown-authored guidance.',\n  },\n} as const\n\nexport type SkillName = keyof typeof SKILL_CATALOG\n\nexport interface SkillDefinition {\n  name: SkillName\n  description: string\n  directory: string\n  entryFile: string\n}\n\nexport interface CopySkillOptions {\n  overwrite?: boolean\n}\n\nfunction assertSkillName(name: string): asserts name is SkillName {\n  if (!(name in SKILL_CATALOG)) {\n    throw new Error(\n      `Unknown Standard Agents skill \"${name}\". Expected one of: ${Object.keys(SKILL_CATALOG).join(', ')}.`\n    )\n  }\n}\n\nfunction resolveInside(baseDir: string, segments: readonly string[]): string {\n  const candidate = resolve(baseDir, ...segments)\n  const relativePath = relative(baseDir, candidate)\n\n  if (relativePath.startsWith('..') || isAbsolute(relativePath)) {\n    throw new Error('Skill paths must stay within the skill directory.')\n  }\n\n  return candidate\n}\n\nexport function listSkills(): SkillDefinition[] {\n  return (Object.keys(SKILL_CATALOG) as SkillName[]).map((name) => getSkill(name))\n}\n\nexport function getSkill(name: SkillName): SkillDefinition {\n  const definition = SKILL_CATALOG[name]\n  const directory = resolveSkillDir(name)\n\n  return {\n    name,\n    description: definition.description,\n    directory,\n    entryFile: resolveSkillFile(name, 'SKILL.md'),\n  }\n}\n\nexport function resolveSkillDir(name: SkillName): string {\n  assertSkillName(name)\n  return resolve(SKILLS_ROOT, name)\n}\n\nexport function resolveSkillFile(name: SkillName, ...segments: string[]): string {\n  return resolveInside(resolveSkillDir(name), segments)\n}\n\nexport async function readSkillFile(\n  name: SkillName,\n  ...segments: string[]\n): Promise<string> {\n  const target = segments.length === 0\n    ? resolveSkillFile(name, 'SKILL.md')\n    : resolveSkillFile(name, ...segments)\n\n  return readFile(target, 'utf8')\n}\n\nexport async function copySkill(\n  name: SkillName,\n  destinationRoot: string,\n  options: CopySkillOptions = {}\n): Promise<string> {\n  const sourceDir = resolveSkillDir(name)\n  const targetRoot = resolve(destinationRoot)\n  const targetDir = resolve(targetRoot, name)\n\n  await mkdir(targetRoot, { recursive: true })\n  await cp(sourceDir, targetDir, {\n    recursive: true,\n    force: options.overwrite ?? false,\n    errorOnExist: !(options.overwrite ?? false),\n  })\n\n  return targetDir\n}\n\nexport const skillPackageRoot = PACKAGE_ROOT\nexport const skillsRoot = SKILLS_ROOT\n"],"mappings":";AAAA,SAAS,IAAI,OAAO,gBAAgB;AACpC,SAAS,qBAAqB;AAC9B,SAAS,YAAY,UAAU,eAAe;AAE9C,IAAM,eAAe,cAAc,IAAI,IAAI,OAAO,YAAY,GAAG,CAAC;AAClE,IAAM,cAAc,QAAQ,cAAc,QAAQ;AAElD,IAAM,gBAAgB;AAAA,EACpB,cAAc;AAAA,IACZ,aACE;AAAA,EACJ;AACF;AAeA,SAAS,gBAAgB,MAAyC;AAChE,MAAI,EAAE,QAAQ,gBAAgB;AAC5B,UAAM,IAAI;AAAA,MACR,kCAAkC,IAAI,uBAAuB,OAAO,KAAK,aAAa,EAAE,KAAK,IAAI,CAAC;AAAA,IACpG;AAAA,EACF;AACF;AAEA,SAAS,cAAc,SAAiB,UAAqC;AAC3E,QAAM,YAAY,QAAQ,SAAS,GAAG,QAAQ;AAC9C,QAAM,eAAe,SAAS,SAAS,SAAS;AAEhD,MAAI,aAAa,WAAW,IAAI,KAAK,WAAW,YAAY,GAAG;AAC7D,UAAM,IAAI,MAAM,mDAAmD;AAAA,EACrE;AAEA,SAAO;AACT;AAEO,SAAS,aAAgC;AAC9C,SAAQ,OAAO,KAAK,aAAa,EAAkB,IAAI,CAAC,SAAS,SAAS,IAAI,CAAC;AACjF;AAEO,SAAS,SAAS,MAAkC;AACzD,QAAM,aAAa,cAAc,IAAI;AACrC,QAAM,YAAY,gBAAgB,IAAI;AAEtC,SAAO;AAAA,IACL;AAAA,IACA,aAAa,WAAW;AAAA,IACxB;AAAA,IACA,WAAW,iBAAiB,MAAM,UAAU;AAAA,EAC9C;AACF;AAEO,SAAS,gBAAgB,MAAyB;AACvD,kBAAgB,IAAI;AACpB,SAAO,QAAQ,aAAa,IAAI;AAClC;AAEO,SAAS,iBAAiB,SAAoB,UAA4B;AAC/E,SAAO,cAAc,gBAAgB,IAAI,GAAG,QAAQ;AACtD;AAEA,eAAsB,cACpB,SACG,UACc;AACjB,QAAM,SAAS,SAAS,WAAW,IAC/B,iBAAiB,MAAM,UAAU,IACjC,iBAAiB,MAAM,GAAG,QAAQ;AAEtC,SAAO,SAAS,QAAQ,MAAM;AAChC;AAEA,eAAsB,UACpB,MACA,iBACA,UAA4B,CAAC,GACZ;AACjB,QAAM,YAAY,gBAAgB,IAAI;AACtC,QAAM,aAAa,QAAQ,eAAe;AAC1C,QAAM,YAAY,QAAQ,YAAY,IAAI;AAE1C,QAAM,MAAM,YAAY,EAAE,WAAW,KAAK,CAAC;AAC3C,QAAM,GAAG,WAAW,WAAW;AAAA,IAC7B,WAAW;AAAA,IACX,OAAO,QAAQ,aAAa;AAAA,IAC5B,cAAc,EAAE,QAAQ,aAAa;AAAA,EACvC,CAAC;AAED,SAAO;AACT;AAEO,IAAM,mBAAmB;AACzB,IAAM,aAAa;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import { cp, mkdir, readFile, writeFile } from 'node:fs/promises'\nimport { fileURLToPath } from 'node:url'\nimport { isAbsolute, relative, resolve } from 'node:path'\n\nconst PACKAGE_ROOT = fileURLToPath(new URL('../', import.meta.url))\nconst SKILLS_ROOT = resolve(PACKAGE_ROOT, 'skills')\nconst VERSION_STAMP_PATTERN = /<!--\\s*installed-skill-version:\\s*__SKILL_VERSION__\\s*-->/g\n\nconst SKILL_CATALOG = {\n  agentbuilder: {\n    description:\n      'Compose Standard Agents from models, prompts, tools, hooks, APIs, and subagents using markdown-authored guidance.',\n  },\n} as const\n\nexport type SkillName = keyof typeof SKILL_CATALOG\n\nexport interface SkillDefinition {\n  name: SkillName\n  description: string\n  directory: string\n  entryFile: string\n}\n\nexport interface CopySkillOptions {\n  overwrite?: boolean\n}\n\nfunction assertSkillName(name: string): asserts name is SkillName {\n  if (!(name in SKILL_CATALOG)) {\n    throw new Error(\n      `Unknown Standard Agents skill \"${name}\". Expected one of: ${Object.keys(SKILL_CATALOG).join(', ')}.`\n    )\n  }\n}\n\nfunction resolveInside(baseDir: string, segments: readonly string[]): string {\n  const candidate = resolve(baseDir, ...segments)\n  const relativePath = relative(baseDir, candidate)\n\n  if (relativePath.startsWith('..') || isAbsolute(relativePath)) {\n    throw new Error('Skill paths must stay within the skill directory.')\n  }\n\n  return candidate\n}\n\nexport function listSkills(): SkillDefinition[] {\n  return (Object.keys(SKILL_CATALOG) as SkillName[]).map((name) => getSkill(name))\n}\n\nexport function getSkill(name: SkillName): SkillDefinition {\n  const definition = SKILL_CATALOG[name]\n  const directory = resolveSkillDir(name)\n\n  return {\n    name,\n    description: definition.description,\n    directory,\n    entryFile: resolveSkillFile(name, 'SKILL.md'),\n  }\n}\n\nexport function resolveSkillDir(name: SkillName): string {\n  assertSkillName(name)\n  return resolve(SKILLS_ROOT, name)\n}\n\nexport function resolveSkillFile(name: SkillName, ...segments: string[]): string {\n  return resolveInside(resolveSkillDir(name), segments)\n}\n\nlet cachedVersion: Promise<string> | null = null\n\nexport function skillPackageVersion(): Promise<string> {\n  cachedVersion ??= readFile(resolve(PACKAGE_ROOT, 'package.json'), 'utf8').then(\n    (manifest) => JSON.parse(manifest).version as string\n  )\n\n  return cachedVersion\n}\n\nasync function stampSkillVersion(content: string): Promise<string> {\n  if (!content.includes('__SKILL_VERSION__')) {\n    return content\n  }\n\n  const version = await skillPackageVersion()\n\n  return content.replace(\n    VERSION_STAMP_PATTERN,\n    `<!-- installed-skill-version: ${version} -->`\n  )\n}\n\nexport async function readSkillFile(\n  name: SkillName,\n  ...segments: string[]\n): Promise<string> {\n  const target = segments.length === 0\n    ? resolveSkillFile(name, 'SKILL.md')\n    : resolveSkillFile(name, ...segments)\n\n  return stampSkillVersion(await readFile(target, 'utf8'))\n}\n\nexport async function copySkill(\n  name: SkillName,\n  destinationRoot: string,\n  options: CopySkillOptions = {}\n): Promise<string> {\n  const sourceDir = resolveSkillDir(name)\n  const targetRoot = resolve(destinationRoot)\n  const targetDir = resolve(targetRoot, name)\n\n  await mkdir(targetRoot, { recursive: true })\n  await cp(sourceDir, targetDir, {\n    recursive: true,\n    force: options.overwrite ?? false,\n    errorOnExist: !(options.overwrite ?? false),\n  })\n\n  const entryFile = resolve(targetDir, 'SKILL.md')\n  const entryContent = await readFile(entryFile, 'utf8')\n  await writeFile(entryFile, await stampSkillVersion(entryContent), 'utf8')\n\n  return targetDir\n}\n\nexport const skillPackageRoot = PACKAGE_ROOT\nexport const skillsRoot = SKILLS_ROOT\n"],"mappings":";AAAA,SAAS,IAAI,OAAO,UAAU,iBAAiB;AAC/C,SAAS,qBAAqB;AAC9B,SAAS,YAAY,UAAU,eAAe;AAE9C,IAAM,eAAe,cAAc,IAAI,IAAI,OAAO,YAAY,GAAG,CAAC;AAClE,IAAM,cAAc,QAAQ,cAAc,QAAQ;AAClD,IAAM,wBAAwB;AAE9B,IAAM,gBAAgB;AAAA,EACpB,cAAc;AAAA,IACZ,aACE;AAAA,EACJ;AACF;AAeA,SAAS,gBAAgB,MAAyC;AAChE,MAAI,EAAE,QAAQ,gBAAgB;AAC5B,UAAM,IAAI;AAAA,MACR,kCAAkC,IAAI,uBAAuB,OAAO,KAAK,aAAa,EAAE,KAAK,IAAI,CAAC;AAAA,IACpG;AAAA,EACF;AACF;AAEA,SAAS,cAAc,SAAiB,UAAqC;AAC3E,QAAM,YAAY,QAAQ,SAAS,GAAG,QAAQ;AAC9C,QAAM,eAAe,SAAS,SAAS,SAAS;AAEhD,MAAI,aAAa,WAAW,IAAI,KAAK,WAAW,YAAY,GAAG;AAC7D,UAAM,IAAI,MAAM,mDAAmD;AAAA,EACrE;AAEA,SAAO;AACT;AAEO,SAAS,aAAgC;AAC9C,SAAQ,OAAO,KAAK,aAAa,EAAkB,IAAI,CAAC,SAAS,SAAS,IAAI,CAAC;AACjF;AAEO,SAAS,SAAS,MAAkC;AACzD,QAAM,aAAa,cAAc,IAAI;AACrC,QAAM,YAAY,gBAAgB,IAAI;AAEtC,SAAO;AAAA,IACL;AAAA,IACA,aAAa,WAAW;AAAA,IACxB;AAAA,IACA,WAAW,iBAAiB,MAAM,UAAU;AAAA,EAC9C;AACF;AAEO,SAAS,gBAAgB,MAAyB;AACvD,kBAAgB,IAAI;AACpB,SAAO,QAAQ,aAAa,IAAI;AAClC;AAEO,SAAS,iBAAiB,SAAoB,UAA4B;AAC/E,SAAO,cAAc,gBAAgB,IAAI,GAAG,QAAQ;AACtD;AAEA,IAAI,gBAAwC;AAErC,SAAS,sBAAuC;AACrD,oBAAkB,SAAS,QAAQ,cAAc,cAAc,GAAG,MAAM,EAAE;AAAA,IACxE,CAAC,aAAa,KAAK,MAAM,QAAQ,EAAE;AAAA,EACrC;AAEA,SAAO;AACT;AAEA,eAAe,kBAAkB,SAAkC;AACjE,MAAI,CAAC,QAAQ,SAAS,mBAAmB,GAAG;AAC1C,WAAO;AAAA,EACT;AAEA,QAAM,UAAU,MAAM,oBAAoB;AAE1C,SAAO,QAAQ;AAAA,IACb;AAAA,IACA,iCAAiC,OAAO;AAAA,EAC1C;AACF;AAEA,eAAsB,cACpB,SACG,UACc;AACjB,QAAM,SAAS,SAAS,WAAW,IAC/B,iBAAiB,MAAM,UAAU,IACjC,iBAAiB,MAAM,GAAG,QAAQ;AAEtC,SAAO,kBAAkB,MAAM,SAAS,QAAQ,MAAM,CAAC;AACzD;AAEA,eAAsB,UACpB,MACA,iBACA,UAA4B,CAAC,GACZ;AACjB,QAAM,YAAY,gBAAgB,IAAI;AACtC,QAAM,aAAa,QAAQ,eAAe;AAC1C,QAAM,YAAY,QAAQ,YAAY,IAAI;AAE1C,QAAM,MAAM,YAAY,EAAE,WAAW,KAAK,CAAC;AAC3C,QAAM,GAAG,WAAW,WAAW;AAAA,IAC7B,WAAW;AAAA,IACX,OAAO,QAAQ,aAAa;AAAA,IAC5B,cAAc,EAAE,QAAQ,aAAa;AAAA,EACvC,CAAC;AAED,QAAM,YAAY,QAAQ,WAAW,UAAU;AAC/C,QAAM,eAAe,MAAM,SAAS,WAAW,MAAM;AACrD,QAAM,UAAU,WAAW,MAAM,kBAAkB,YAAY,GAAG,MAAM;AAExE,SAAO;AACT;AAEO,IAAM,mBAAmB;AACzB,IAAM,aAAa;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@standardagents/skill",
-  "version": "0.17.0-next.a4b7340",
+  "version": "0.17.1",
   "private": false,
   "publishConfig": {
     "access": "public",

package/skills/agentbuilder/SKILL.md

@@ -29,6 +29,21 @@ For deeper reference material that this skill links to, see:
 
 > If the `agents/*/AGENTS.md` files don't exist in your project yet, run `pnpm exec agents scaffold` to create them.
 
+## Keeping this skill up to date
+
+<!-- installed-skill-version: __SKILL_VERSION__ -->
+
+This skill ships as `@standardagents/skill` on npm, and the version installed here is stamped in the HTML comment above. The first time you use this skill in a conversation, verify it is current:
+
+1. If the stamp above still reads `__SKILL_VERSION__`, this is an unstamped development copy — skip this check.
+2. Run `npm view @standardagents/skill version`. If the command fails (offline, no npm, no shell access), skip silently. This check must never block, retry, or interrupt real work.
+3. If the published version is newer than the stamp, tell the user in one short line and offer to update. Updating overwrites this file — including any local edits — so get the user's OK before running:
+   - Codex install (file lives under `.codex/skills/`): `npx @standardagents/cli@latest skill --force --agent codex`
+   - Claude Code install (file lives under `.claude/agents/`): `npx @standardagents/cli@latest skill --force --agent claude`
+4. After updating, re-read the new file before continuing.
+
+Do this at most once per conversation, then move on to the task at hand.
+
 ---
 
 ## Before you write any code
@@ -478,7 +493,7 @@ This is the single biggest gap in most coding-agent-built tools. **Do not write
 | Read/write config and secrets | `state.env` / `state.envType` / `state.setEnv` | `process.env`, `.env` files |
 | Run isolated deterministic code | `state.runCode` with explicit bridges | `eval`, child processes, implicit runtime access |
 | Search files the thread has seen | `state.grepFiles` / `state.findFiles` | Reimplementing search |
-| Escalate / report status to the parent | `state.notifyParent` / `state.setStatus` | Custom message bus |
+| Escalate / report status to the parent | `state.notifyParent` / `state.setStatus` / `state.stopSession` | Custom message bus |
 | Load a sibling prompt / agent / model | `state.loadPrompt` / `state.loadAgent` / `state.loadModel` | Duplicating the definition |
 | Inspect or message a child thread | `state.children` / `state.getChildThread` | External orchestration |
 | Inject context the model should see | `state.injectMessage` / `state.queueMessage` | Stuffing the system prompt |
@@ -500,7 +515,7 @@ Resources    loadModel, loadPrompt, loadAgent,
              getChildThread, getParentThread,
              getPromptNames, getAgentNames, getModelNames
 Env          env, envType, setEnv
-Parent       notifyParent, setStatus
+Parent       notifyParent, setStatus, stopSession
 Tools        queueTool, invokeTool
 Effects      scheduleEffect, getScheduledEffects, removeScheduledEffect
 Events       emit
@@ -564,7 +579,8 @@ By default, `runCode()` executes the `default` export with no args. Use `execute
 - **`state.runCode`** runs JavaScript or TypeScript in an isolated Dynamic Worker sandbox. The sandbox does not receive `ThreadState`, env, files, network, or host globals implicitly. Pass exact capabilities through `imports`, `globals`, `modules`, and `execute`. It executes exported values/functions; code such as `console.log(fibonacci(5))` can log, but it must still `export default ...` or export a named function/value for the host to receive a result.
 - **`state.scheduleEffect`** runs a named effect after a delay. It survives restarts. This is your cron, your queue, and your retry timer all in one.
 - **`state.invokeTool` vs `state.queueTool`** — `invokeTool` runs synchronously and returns the result; `queueTool` schedules the call to run later in the normal tool-call flow. Prefer `queueTool` when the model should see the result as a regular tool call.
-- **`state.notifyParent`** — for resumable subagents with `parentCommunication: 'explicit'`, this is the only way the child talks to the parent. Use it sparingly; every notification interrupts the parent.
+- **`state.notifyParent`** — for resumable subagents with `parentCommunication: 'explicit'`, this is the main way the child talks to the parent. Use it sparingly; every delivered notification interrupts the parent. If there is no parent, nothing is queued externally.
+- **`state.stopSession`** — terminally ends the active agent session. Use `state.stopSession({ result, notifyParent, status })` when a tool should return a blocking result, optionally notify the parent, and mark the child status without requiring a session tool call.
 - **File attachments** use the path convention `/attachments/{filename}.{ext}`. Always use this path when passing files between agents — the runtime copies them across thread filesystems automatically.
 
 ### Sandboxed code env bridge pattern
@@ -731,7 +747,9 @@ SubagentToolConfig — entry on a parent prompt's `tools` array
     maxInstances               number                    cap on concurrent instances; when reached the tool
                                                          is hidden and new messages route to existing instances
     parentCommunication        'implicit' | 'explicit'   implicit (default) auto-queues completion to parent
-                                                         explicit requires state.notifyParent() in code
+                                                         explicit requires state.notifyParent(),
+                                                         state.setStatus(), or state.stopSession()
+                                                         in code
   initUserMessageProperty    schema field name           tool arg used as child's first user message
   initAttachmentsProperty    schema field name           tool arg holding /attachments/* paths to copy to child
   initAgentNameProperty      schema field name           tool arg used to tag the child thread (UI label)
@@ -749,7 +767,7 @@ These are correct as written in the spec — internalize them.
    - Implicitly via `immediate: { ... }` — the child spawns the moment the parent prompt activates, before any LLM step.
 2. **Children only communicate back to their parents.** Two flavors:
    - **Implicit**: the child auto-queues a message to the parent when the session ends (via `sessionStop`, `sessionFail`, or `maxSessionTurns`). Default for all subagents.
-   - **Explicit**: only when `state.notifyParent()` is called. Set with `resumable.parentCommunication: 'explicit'`. Use for high-traffic resumables (e.g., a Slack monitor) where you want control over when the parent is interrupted.
+   - **Explicit**: only when code calls `state.notifyParent()`, `state.setStatus()`, or `state.stopSession({ result, notifyParent, status })`. Set with `resumable.parentCommunication: 'explicit'`. Use for high-traffic resumables (e.g., a Slack monitor) where you want control over when the parent is interrupted.
 3. **Resumable subagents can receive messages from their parents.** `resumable.receives_messages` chooses which side hears them.
 4. **When a child sends back to the parent, it MUST indicate whether it needs a response** — in plain English, e.g. "After researching, you must respond so I can continue with the email." A research subagent providing FYI info doesn't need a response; a gmail subagent waiting on guidance does.
 5. **File attachments use path strings.** `/attachments/{filename}.{ext}`. Use this convention everywhere — the runtime copies attachments across thread filesystems automatically when listed in `initAttachmentsProperty`.