@standardagents/skill 0.17.0 → 0.17.1

package/package.json

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

package/skills/agentbuilder/SKILL.md

@@ -493,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 |
@@ -515,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
@@ -579,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
@@ -746,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)
@@ -764,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`.