@standardagents/skill 0.43.1 → 0.44.0

package/README.md

@@ -35,6 +35,15 @@ guidance into a supported coding agent. Currently:
 - Codex gets a skill folder in `$CODEX_HOME/skills` or `~/.codex/skills`
 - Claude Code gets a user subagent in `~/.claude/agents/agentbuilder.md`
 
+The implementation-agnostic specification guidance is a separate skill:
+
+```bash
+npx skills add standardagents/skills@spec
+```
+
+The `agentbuilder` skill defers to `spec` for what the specification requires,
+and it reads the published specification directly when `spec` is not installed.
+
 Package install:
 
 ```bash

package/package.json

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

package/skills/agentbuilder/SKILL.md

@@ -30,6 +30,14 @@ 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.
 
+## The specification comes first
+
+This skill covers how to build with AgentBuilder. The `spec` skill covers what the Standard Agent Specification requires, and it reads the published specification each time it runs.
+
+- Use the `spec` skill for questions about what the specification requires or whether an agent is portable.
+- If the `spec` skill is not available, read https://standardagentspec.org/llms.txt and the pages it lists. Tell the user once that `npx skills add standardagents/skills@spec` installs the skill.
+- If this skill and the published specification disagree, the specification is correct. Report the disagreement to the user.
+
 ## Keeping this skill up to date
 
 <!-- installed-skill-version: __SKILL_VERSION__ -->
@@ -407,7 +415,7 @@ When the new agent is a child in a graph, creating the agent file is half the jo
 - [ ] The session tools pass the [three-places check](#session-tools-must-exist-in-three-places)
 - [ ] The **owning parent side's `subagents` array** has the `SubagentRelationship` — an agent nobody declares is unreachable, and the declaration is the grant. Never put the relationship in a prompt's `tools` array (definition-time error). Declare it on the side whose turns should receive the child's traffic
 - [ ] `blocking` and `maxInstances` are chosen deliberately ([waiting style vs. lifetime](#subprompts-vs-subagents-vs-handoffs)), and `initUserMessageProperty` (and `initAttachmentsProperty` for files) are mapped so the child starts with real context instead of an empty first turn
-- [ ] The relationship name (`as`, defaulting to `agent`) doesn't collide with any tool name or the reserved lifecycle names (`subagents`, `subagent_create`, `subagent_message`), and appears on only one side
+- [ ] The relationship name (`as`, defaulting to the unqualified part of `agent`) doesn't collide with any tool name or the reserved lifecycle names (`subagents`, `subagent_create`, `subagent_message`), and appears on only one side
 - [ ] The **parent prompt text** (for prompt-backed owning sides) says when to delegate to this child and explains `subagent_create` vs `subagent_message`
 - [ ] Side B reviewers use a model from a *different provider* than side A ([why](#session-boundary-discipline))
 - [ ] Run the dev server and check the composition view: the parent→child edge should be visible, and creating a test thread should show the child spawn and the completion payload arrive back on the owning side
@@ -684,6 +692,12 @@ This is the single biggest gap in most coding-agent-built tools. **Do not write
 
 ### Method cheat sheet
 
+`state.loadModel`, `state.loadPrompt`, and `state.loadAgent` enforce package
+visibility. Global code can load unpacked definitions and packed entry agents.
+Packed code can load its own definitions and other packages' entry agents.
+A packed model cannot fall back to a host model with the same short name.
+A refused load returns the same not-found error as a missing definition.
+
 Discoverability reference. For full signatures, read the spec types from `node_modules/@standardagents/spec/dist/` (or browse `packages/spec/src/` on GitHub). Worked examples live in `agents/tools/AGENTS.md`.
 
 ```
@@ -720,7 +734,7 @@ await state.setValue('invocation_count', count + 1);
 
 ### Agent Skills library
 
-`state.skills` is the instance-GLOBAL Agent Skills library (agentskills.io SKILL.md format) — the deliberate exception to per-thread scoping: skills install once and every thread sees them. `list()` returns metadata (name + description), `get(name)` loads a SKILL.md body on demand (progressive disclosure), `readFile(name, path)` opens bundled files, and `install(files)` / `setEnabled` / `remove` manage the library. Identity always comes from SKILL.md frontmatter (`name`, `description`), validated on install.
+`state.skills` uses the agentskills.io SKILL.md format. A thread sees its owner's skills and enabled skills in the admin-reviewed shared library. Owner skills shadow shared skills with the same name. `list()` returns metadata. `get(name)` loads a SKILL.md body. `readFile(name, path)` reads bundled files. `install(files)`, `setEnabled`, and `remove` require an instance admin and change that admin's private skills. Skill identity comes from SKILL.md frontmatter (`name`, `description`), validated on install.
 
 ### Sandboxed code execution
 
@@ -753,6 +767,8 @@ const run = state.runCode(
 const result = await run;
 ```
 
+In a thread endpoint, `runCode` forwards functions in imports, globals, and execution arguments as callable proxies. Call `run.terminate(reason)` to stop the sandbox. A caller disconnect also stops the run. When `report` is supplied, the host receives reports during the run and `run.reports` updates as reports arrive.
+
 By default, `runCode()` executes the `default` export with no args. Use `execute: { fn, args }` to call a named export or pass arguments; `fn: 'default'` calls the default export with args. Use `modules` to provide local relative ES modules. The result is a status object: successful runs return `status: 'success'`, `result`, `logs`, `reports`, and `durationMs`; failed runs return an error status and an `error` object. Call `run.terminate(reason)` from your own timeout budget when needed.
 
 ### Notes on a few that are easy to misuse
@@ -842,12 +858,16 @@ PromptDefinition
   recentImageThreshold   number (default 10)             how many recent messages keep real images
   historyLimit           number                          load only the newest messages (at least N, under 2N,
                                                          the cut moving N at a time); unset loads all
-  providerOptions        Record<string, unknown>         passthrough to the provider (overrides model defaults)
+  providerOptions        Record<string, unknown>         provider-specific request options
   hooks                  HookId[]                        prompt-scoped hooks (overrides agent hooks)
 ```
 
+Provider options merge from model defaults to prompt overrides. Later values win. A prompt can set `reasoning.level` from 0 to 100.
+
 ### Composable prompts: the `tone` pattern
 
+A circular prompt include raises an error that names the include chain. A prompt can include the same partial through different paths.
+
 `prompt` can be a string or an array of parts. Use parts to compose a shared "tone" or "persona" across many prompts so changes flow through one place.
 
 ```ts
@@ -928,7 +948,7 @@ PromptSide
   subagents         SubagentRelationship[]       side-owned child relationships (see cheat sheet below)
   stopOnResponse    boolean (default true)       stop side turn on text response without tool calls
   stopTool          string                       stop side turn when this tool is called
-  stopToolResponseProperty  string               extracted property for stop tool outcomes
+  stopToolResponseProperty  string (optional)    extracted property for stop tool outcomes
   maxSteps          number                       per-side step cap within one turn
   sessionStop       { name, messageProperty?, attachmentsProperty? }   ends session with a result
   sessionFail       { name, messageProperty?, attachmentsProperty? }   ends session with a failure
@@ -956,7 +976,7 @@ SubagentRelationship — entry in a side's `subagents` array
                                                          eligible; exposeAsTool: true marks it as designed
                                                          for composition and supplies the default description
   as                         string                      relationship name — tool-surface name, registry
-                                                         identity, reference name; defaults to `agent`.
+                                                         identity, reference name; defaults to the unqualified part of `agent`.
                                                          Two relationships may target the same agent under
                                                          different `as` names (aliases), each with its own
                                                          config — e.g. work_calendar / personal_calendar
@@ -1042,6 +1062,9 @@ Hooks extend agent behavior without modifying core logic. Defined via `defineHoo
 | `before_store_tool_result` | Before tool result storage | Transform tool results |
 | `after_tool_call_success` | After successful tool call | Post-process success results |
 | `after_tool_call_failure` | After failed tool call | Handle/recover from errors |
+| `user_client_attached` | After a user client attaches | Handle an attached client |
+| `user_client_detached` | After a user client detaches | Handle a detached client |
+| `user_value_changed` | After a user value changes | Handle a durable user value change |
 
 > **Caution:** Hooks that filter or truncate messages must keep matching tool calls and tool results together. Separating them produces hard-to-debug failures in many models.
 
@@ -1071,7 +1094,7 @@ Two value types are supported:
 - **`text`** — simple string. Safe to render in prompts.
 - **`secret`** — encrypted; **MUST only be used inside tools**. Never reference a secret in prompt text and never return it to the model. A `GMAIL_API_KEY` is `secret`; a `LOCATION` is `text`.
 
-When a thread is created, all required variables in the agent graph must be provided. The instance of a variable on a thread is called an "environment variable" or `env`. Resolution precedence (low → high): prompt → tool → agent → thread.
+When a thread is created, all required variables in the agent graph must be provided. The instance of a variable on a thread is called an "environment variable" or `env`. Resolution precedence (high → low): thread → agent → prompt → user → instance.
 
 Scoped variables (`scoped: true`) do not inherit from parent thread env — they reset for the declaring agent's subtree. Use this when a subagent must run with different config from its parent (e.g., a per-instance Slack channel ID).