@prismer/runtime 2.2.55 → 2.2.63

package/built-in-skills/agent-coordination/SKILL.md

@@ -43,14 +43,22 @@ For peer-agent delegation, the canonical paths are **`cloud task create --assign
 cloud discover --workspace-id "$PRISMER_WORKSPACE_ID"                                  # all agents in this workspace
 cloud discover --workspace-id "$PRISMER_WORKSPACE_ID" --capability code-review         # filter by capability
 cloud discover --workspace-id "$PRISMER_WORKSPACE_ID" --online-only                    # only online agents
-cloud im contacts                                 # your contact list
+cloud im contacts                                 # users you've chatted with (conversation-derived)
+cloud im contacts --external --workspace-id "$PRISMER_WORKSPACE_ID"  # your cross-workspace contact edges
 ```
 
 `cloud discover` is a workspace-scoped Agent Registry contract: every result
 is backed by an AgentCard in the requested workspace and carries its routing
-`userId`. Human accounts and agents from other workspaces are contract
-violations. When the target is already in the current conversation, prefer the
-conversation members listing below instead of searching the wider workspace.
+`userId`. Agents from other workspaces are NOT in this directory — the only
+legitimate cross-workspace targets are your **external contact edges**
+(`cloud im contacts --external`, built by the owner's 「添加外部联系人」+ 双侧
+approval): each entry carries the peer's `imUserId` (use it as the send
+target), its workspace name, and its lifecycle. If the user asks you to reach
+an agent outside this workspace, check that list first — if the peer is there,
+message it directly; if not, say plainly that no external contact edge exists
+and the owner must add the contact first. When the target is already in the
+current conversation, prefer the conversation members listing below instead
+of searching.
 
 ### List participants in a conversation (scoped)
 
@@ -73,8 +81,17 @@ cloud im groups send <groupId> "Team update: feature shipped"
 
 # With routing metadata
 cloud send <to-username> "Need approval" --conversation-id <convId> --by-username --workspace-id "$PRISMER_WORKSPACE_ID"
+
+# Cross-workspace external contact (must appear in `cloud im contacts --external`)
+cloud im send <peer-imUserId> "hello across workspaces"
 ```
 
+**Deferred (202 ACTION_DEFERRED):** a cross-workspace send without an active
+contact edge does NOT deliver — it returns `deferred` with an `approvalId` and
+the message waits for contact approval (both-side owner approval). Report that
+plainly to the user: "已发起联系人请求，等待对方台审批（approvalId: …）；
+批准后重新发送。" Never report such a send as sent.
+
 ### Send with attached file
 
 > **决定怎么交付文件 — 先读这条:**

package/built-in-skills/agent-meta/SKILL.md

@@ -11,6 +11,17 @@ metadata:
 
 # Agent Meta
 
+## Skill self-check
+
+Start from the current Runtime's effective skill list (Hermes skills_list or
+the registered skill surface), not a recursive disk count. Distinguish installed
+files, registered capabilities, and actual smoke-tested operations. Platform or
+session filtering is expected, not a damaged skill or a question for the user.
+For a full disk audit, classify excluded entries as informational and missing
+commands/credentials as not ready. Check prerequisites without printing secrets;
+command presence does not prove authentication. Report only actionable defects,
+and never claim all functions passed from frontmatter parsing alone.
+
 Use this skill when the user asks you to inspect, save, restore, publish, or fork a Prismer long-running agent.
 
 ## Commands

package/built-in-skills/assets/SKILL.md

@@ -75,7 +75,7 @@ cloud asset sync                                          # refresh local cache
 - **Always describe before reading.** Metadata tells you whether reading is safe (text vs binary, size, encoding).
 - Don't treat metadata as proof of file contents — title and MIME can lie. The content hash is the only authoritative identity.
 - If multiple locators disagree (e.g. filename matches two assets with different hashes), **stop and re-search** rather than reading the wrong file.
-- Avoid reading binary or image-heavy assets directly. For images, use `cloud parse` (OCR) or a vision-capable downstream tool; for PDFs, use `cloud parse`.
+- Avoid reading binary or image-heavy assets as text. Use the `liteparse` local `lit` workflow for supported parsing/OCR, `office-artifacts` for document-specific operations, or an available vision tool for images. Do not invoke `cloud parse`: the cloud heavy-format parser is not available.
 
 ### Read
 

package/built-in-skills/canvas-design/SKILL.md

@@ -134,7 +134,7 @@ To create museum or magazine quality work, use the design philosophy as the foun
 
 **Text as a contextual element**: Text is always minimal and visual-first, but let context guide whether that means whisper-quiet labels or bold typographic gestures. A punk venue poster might have larger, more aggressive type than a minimalist ceramics studio identity. Most of the time, font should be thin. All use of fonts must be design-forward and prioritize visual communication. Regardless of text scale, nothing falls off the page and nothing overlaps. Every element must be contained within the canvas boundaries with proper margins. Check carefully that all text, graphics, and visual elements have breathing room and clear separation. This is non-negotiable for professional execution. **IMPORTANT: Use different fonts if writing text. Search the `./canvas-fonts` directory. Regardless of approach, sophistication is non-negotiable.**
 
-Download and use whatever fonts are needed to make this a reality. Get creative by making the typography actually part of the art itself -- if the art is abstract, bring the font onto the canvas, not typeset digitally.
+Use fonts with a verified redistribution/embedding license. Bundled `canvas-fonts` TTFs do not cover Chinese; check the cmap for all requested characters and select an installed licensed CJK fallback when needed (for example an available Noto CJK family). Never silently render missing-glyph boxes. Inspect the rendered output and retain each font's OFL/copyright notice when distributing it. Download additional fonts only from a trusted source with its license, not arbitrary font mirrors.
 
 To push boundaries, follow design instinct/intuition while using the philosophy as a guiding principle. Embrace ultimate design freedom and choice. Push aesthetics and design to the frontier. 
 
@@ -146,7 +146,7 @@ Output the final result as a single, downloadable .pdf or .png file, alongside t
 
 ## FINAL STEP
 
-**IMPORTANT**: The user ALREADY said "It isn't perfect enough. It must be pristine, a masterpiece if craftsmanship, as if it were about to be displayed in a museum."
+**IMPORTANT**: Perform a final quality pass against the user's actual brief. Do not invent user feedback or override requested content, style, accessibility, or scope.
 
 **CRITICAL**: To refine the work, avoid adding more graphics; instead refine what has been created and make it extremely crisp, respecting the design philosophy and the principles of minimalism entirely. Rather than adding a fun filter or refactoring a font, consider how to make the existing composition more cohesive with the art. If the instinct is to call a new function or draw a new shape, STOP and instead ask: "How can I make what's already here more of a piece of art?"
 
@@ -154,4 +154,4 @@ Take a second pass. Go back to the code and refine/polish further to make this a
 
 ## MULTI-PAGE OPTION
 
-To create additional pages when requested, create more creative pages along the same lines as the design philosophy but distinctly different as well. Bundle those pages in the same .pdf or many .pngs. Treat the first page as just a single page in a whole coffee table book waiting to be filled. Make the next pages unique twists and memories of the original. Have them almost tell a story in a very tasteful way. Exercise full creative freedom.
+To create additional pages when requested, create more creative pages along the same lines as the design philosophy but distinctly different as well. Bundle those pages in the same .pdf or many .pngs. Treat the first page as just a single page in a whole coffee table book waiting to be filled. Make the next pages unique twists and memories of the original. Have them almost tell a story in a very tasteful way. Exercise full creative freedom.

package/built-in-skills/canvas-design/canvas-fonts/IBMPlexSerif-OFL.txt

@@ -0,0 +1,93 @@
+Copyright © 2017 IBM Corp. with Reserved Font Name "Plex"
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+
+This license is copied below, and is also available with a FAQ at: http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/built-in-skills/canvas-design/canvas-fonts/InstrumentSerif-OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2022 The Instrument Serif Project Authors (https://github.com/Instrument/instrument-serif)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/built-in-skills/canvas-design/canvas-fonts/LICENSE-SOURCES.md

@@ -0,0 +1,16 @@
+# Serif Font Notices
+
+All font binaries remain unchanged. Font licenses are separate from the canvas
+skill's Apache-2.0 license.
+
+- `IBMPlexSerif-{Regular,Italic,Bold,BoldItalic}.ttf`: embedded name ID 0 is
+  `Copyright 2020 IBM Corp. All rights reserved.`; name ID 13 declares OFL 1.1.
+  `IBMPlexSerif-OFL.txt` retains the upstream 2017 IBM notice and Reserved Font
+  Name Plex, from https://raw.githubusercontent.com/google/fonts/main/ofl/ibmplexserif/OFL.txt.
+  Retain both this embedded-binary notice and the upstream OFL notice.
+- `InstrumentSerif-{Regular,Italic}.ttf`: embedded name ID 0 matches
+  `Copyright 2022 The Instrument Serif Project Authors (https://github.com/Instrument/instrument-serif)`;
+  name ID 13 declares OFL 1.1. `InstrumentSerif-OFL.txt` is from
+  https://raw.githubusercontent.com/google/fonts/main/ofl/instrumentserif/OFL.txt.
+
+Sources retrieved 2026-09-23; these added notices do not modify or relicense fonts.

package/built-in-skills/claim-agent-ownership/SKILL.md

@@ -8,8 +8,6 @@ description: |
   so subsequent dispatches route deterministically. Implements Gap G-2-⑤ on top of the
   Wave 2-B2 `/api/im/agent-bindings/:agentImUserId/rebind` endpoint.
 applies_to: [hermes, claude-code, openclaw, codex]
-requires:
-  - aip-identity
 phaseModel:
   defaultPhase: tool_use
 version: 1
@@ -52,12 +50,18 @@ authoritative rebind endpoint, which atomically:
 ## API
 
 There is **no generic `cloud im get` / `cloud im post`** subcommand in the
-runtime CLI today (release 201 audit, `sdk/prismer-cloud/runtime/src/cli/`).
+runtime CLI contract described here (`sdk/cloud/` and `sdk/prismer/`).
 A dedicated `cloud agent rebind` verb is not landed either. The skill calls
 the cloud HTTP endpoint directly via `curl` (or the equivalent fetch from the
 orchestrator's MCP runtime), authenticating with the daemon API key already
 present in the environment as `$PRISMER_API_KEY`:
 
+Before a write, resolve the actual workspace, agent ID, target daemon ID and
+authorized identity from the current runtime. `aip-identity` is not a bundled
+prerequisite; use the available identity/read-only binding interface. Missing
+identity or unavailable endpoint is a stop condition, not permission to invent
+IDs or switch accounts. Confirm migration impact and drain in-flight work.
+
 ```bash
 # Inspect the current bindings first.
 curl -fsS \

package/built-in-skills/claude-api/SKILL.md

@@ -28,7 +28,7 @@ Never mix the two — don't reach for `requests`/`fetch` in a Python or TypeScri
 
 Unless the user requests otherwise:
 
-For the Claude model version, please use Claude Opus 4.7, which you can access via the exact model string `claude-opus-4-7`. Please default to using adaptive thinking (`thinking: {type: "adaptive"}`) for anything remotely complicated. And finally, please default to streaming for any request that may involve long input, long output, or high `max_tokens` — it prevents hitting request timeouts. Use the SDK's `.get_final_message()` / `.finalMessage()` helper to get the complete response if you don't need to handle individual stream events
+Use the model and provider configuration authorized by the user and project. The model IDs and limits in this cached reference are examples: verify availability and supported thinking parameters against the deployed provider or official Models API before changing them. Never replace Prismer gateway configuration or perform a provider migration just because this reference mentions an Anthropic model. For long outputs prefer streaming, using the SDK's `.get_final_message()` / `.finalMessage()` helper when a complete response is needed.
 
 ---
 

package/built-in-skills/claude-api/python/claude-api/README.md

@@ -242,7 +242,7 @@ class ConversationManager:
 
         response = self.client.messages.create(
             model=self.model,
-            max_tokens=kwargs.get("max_tokens", 16000),
+            max_tokens=kwargs.pop("max_tokens", 16000),
             system=self.system,
             messages=self.messages,
             **kwargs
@@ -251,7 +251,7 @@ class ConversationManager:
         assistant_message = next(
             (b.text for b in response.content if b.type == "text"), ""
         )
-        self.messages.append({"role": "assistant", "content": assistant_message})
+        self.messages.append({"role": "assistant", "content": response.content})
 
         return assistant_message
 

package/built-in-skills/claude-api/python/claude-api/tool-use.md

@@ -140,7 +140,7 @@ tools = [...]  # Your tool definitions
 messages = [{"role": "user", "content": user_input}]
 
 # Agentic loop: keep going until Claude stops calling tools
-while True:
+for turn in range(20):
     response = client.messages.create(
         model="claude-opus-4-7",
         max_tokens=16000,
@@ -154,14 +154,16 @@ while True:
 
     # Server-side tool hit iteration limit; re-send to continue
     if response.stop_reason == "pause_turn":
-        messages = [
-            {"role": "user", "content": user_input},
-            {"role": "assistant", "content": response.content},
-        ]
+        messages.append({"role": "assistant", "content": response.content})
         continue
 
+    if response.stop_reason != 'tool_use':
+        raise RuntimeError(f'Incomplete response: {response.stop_reason}')
+
     # Extract tool use blocks from the response
     tool_use_blocks = [b for b in response.content if b.type == "tool_use"]
+    if not tool_use_blocks:
+        raise RuntimeError('tool_use response has no tool blocks')
 
     # Append assistant's response (including tool_use blocks)
     messages.append({"role": "assistant", "content": response.content})
@@ -178,6 +180,8 @@ while True:
 
     # Append tool results as a user message
     messages.append({"role": "user", "content": tool_results})
+else:
+    raise RuntimeError('Tool turn budget exceeded')
 
 # Final response text
 final_text = next(b.text for b in response.content if b.type == "text")

package/built-in-skills/claude-api/python/managed-agents/README.md

@@ -270,6 +270,11 @@ session = client.beta.sessions.create(
 List files the agent wrote to `/mnt/session/outputs/` during a session, then download them.
 
 ```python
+from pathlib import Path
+import tempfile
+
+# Use a new private directory; treat server filenames as untrusted.
+output_dir = Path(tempfile.mkdtemp(prefix='agent-output-'))
 # List files associated with a session
 files = client.beta.files.list(
     scope_id=session.id,
@@ -279,7 +284,12 @@ for f in files.data:
     print(f.filename, f.size_bytes)
     # Download each file and save to disk
     file_content = client.beta.files.download(f.id)
-    file_content.write_to_file(f.filename)
+    name = f.filename
+    if not name or name in ('.', '..') or '/' in name or '\\' in name:
+        raise ValueError('Unsafe output filename')
+    with (output_dir / name).open('xb') as out:
+        for chunk in file_content.iter_bytes():
+            out.write(chunk)
 ```
 
 > 💡 There's a brief indexing lag (~1–3s) between `session.status_idle` and output files appearing in `files.list`. Retry once or twice if the list is empty.

package/built-in-skills/claude-api/shared/error-codes.md

@@ -25,7 +25,7 @@ This file documents HTTP error codes returned by the Claude API, their common ca
 - Missing required parameters (`model`, `max_tokens`, `messages`)
 - Invalid parameter types (e.g., string where integer expected)
 - Empty messages array
-- Messages not alternating user/assistant
+- Invalid message roles or missing tool-result counterparts
 
 **Example error:**
 
@@ -34,7 +34,7 @@ This file documents HTTP error codes returned by the Claude API, their common ca
   "type": "error",
   "error": {
     "type": "invalid_request_error",
-    "message": "messages: roles must alternate between \"user\" and \"assistant\""
+    "message": "messages: invalid request structure (illustrative example)"
   },
   "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
 }
@@ -44,7 +44,7 @@ This file documents HTTP error codes returned by the Claude API, their common ca
 
 - `model` is a valid model ID
 - `max_tokens` is a positive integer
-- `messages` array is non-empty and alternates correctly
+- `messages` array is non-empty and uses valid roles; consecutive same-role messages are combined into one turn, not inherently a 400 (Python SDK 1.8.0 request type documentation)
 
 ---
 
@@ -171,7 +171,7 @@ thinking: budget_tokens=10000, max_tokens=16000
 | `budget_tokens` >= `max_tokens` (older models) | 400 | Ensure `budget_tokens` < `max_tokens`                  |
 | Typo in model ID                | 404              | Use valid model ID like `claude-opus-4-7`               |
 | First message is `assistant`    | 400              | First message must be `user`                            |
-| Consecutive same-role messages  | 400              | Alternate `user` and `assistant`                        |
+| Missing/mismatched tool results | 400              | Match all tool_use IDs with corresponding tool_result blocks |
 | API key in code                 | 401 (leaked key) | Use environment variable                                |
 | Custom retry needs              | 429/5xx          | SDK retries automatically; customize with `max_retries` |
 

package/built-in-skills/claude-api/shared/managed-agents-client-patterns.md

@@ -159,7 +159,8 @@ await client.beta.sessions.events.send(session.id, {
 for await (const event of stream) { /* ... */ }
 ```
 
-The `Promise.all([stream, send])` shape works too, but stream-first is simpler and has the same effect — the stream starts buffering the moment it's opened.
+Do not use `Promise.all([stream, send])` as a readiness barrier: the send can
+finish before the connection opens. Await stream establishment before sending.
 
 ---
 
@@ -196,7 +197,8 @@ for await (const event of stream) {
   if (event.type === 'agent.custom_tool_use' && event.name === 'linear_graphql') {
     const result = await linear.request(event.input.query, event.input.vars) // host's key
     await client.beta.sessions.events.send(session.id, {
-      events: [{ type: 'user.custom_tool_result', tool_use_id: event.id, result }],
+      events: [{ type: 'user.custom_tool_result', custom_tool_use_id: event.id,
+        content: [{ type: 'text', text: JSON.stringify(result) }] }],
     })
   }
 }

package/built-in-skills/claude-api/shared/managed-agents-core.md

@@ -58,7 +58,7 @@ rescheduling → running ↔ idle → terminated
 | Operation | Notes |
 |---|---|
 | List / fetch | Paginated list or single resource by ID |
-| Update | Only `title` is updatable |
+| Update | `title`, `metadata`, `budget`, session-local `agent` configuration and `vault_ids`; see the update section (Python SDK 1.8.0) |
 | Archive | Session becomes **read-only**. Not reversible. |
 | Delete | Permanently deletes session, event history, container, and checkpoints. |
 
@@ -235,4 +235,3 @@ client.beta.sessions.update(
     vault_ids=["vlt_..."],
 )
 ```
-

package/built-in-skills/claude-api/shared/managed-agents-events.md

@@ -67,11 +67,9 @@ Practical patterns for driving a session via the events surface.
 **Open the stream before sending events.** The stream only delivers events that occur *after* it's opened — it does not replay current state or historical events. If you send a message first and open the stream second, early events (including fast status transitions) arrive buffered in a single batch and you lose the ability to react to them in real time.
 
 ```ts
-// ✅ Correct — stream and send concurrently
-const [response] = await Promise.all([
-  streamEvents(sessionId),   // opens SSE connection
-  sendMessage(sessionId, text),
-]);
+// Wait until the SSE connection is established, then send.
+const response = await streamEvents(sessionId);
+await sendMessage(sessionId, text);
 
 // ❌ Wrong — events before stream opens arrive as a single buffered batch
 await sendMessage(sessionId, text);
@@ -87,26 +85,49 @@ const response = await streamEvents(sessionId);
 **The consolidation pattern:** on every (re)connect, overlap the stream with a history fetch and dedupe by event ID:
 
 ```python
-def connect_with_consolidation(client, session_id):
+def connect_with_consolidation(client, session_id, max_events=10000):
+    import time
+    deadline = time.monotonic() + 300
     # 1. Open the SSE stream first
-    stream = client.beta.sessions.events.stream(session_id=session_id)
+    stream = client.beta.sessions.events.stream(session_id=session_id, timeout=30)
 
     # 2. Fetch history to cover any gap
-    history = client.beta.sessions.events.list(
-        session_id=session_id,
-    )
-
-    # 3. Yield history first, then stream — dedupe by event.id
+    # SDK page iteration follows all pages, not only history.data.
+    history = client.beta.sessions.events.list(session_id=session_id, timeout=30)
     seen = set()
-    for ev in history.data:
-        seen.add(ev.id)
-        yield ev
-    for ev in stream:
-        if ev.id not in seen:
-            seen.add(ev.id)
-            yield ev
+    count = 0
+    try:
+        for source, replay in ((history, True), (stream, False)):
+            for ev in source:
+                count += 1
+                if count > max_events or time.monotonic() >= deadline:
+                    raise TimeoutError('Consolidation budget exceeded; persist cursor and resume')
+                key = (ev.id, ev.processed_at)
+                if ev.id and key in seen:
+                    continue
+                if ev.id:
+                    seen.add(key)
+                # Historical terminal events must not terminate a later turn.
+                yield ev, replay
+                if not replay and ev.type == 'session.status_terminated':
+                    return
+                if not replay and ev.type == 'session.status_idle' and ev.stop_reason.type != 'requires_action':
+                    return
+            if replay:
+                state = client.beta.sessions.retrieve(session_id, timeout=30)
+                if state.status != 'running':
+                    return  # caller reconciles pending actions from history/state
+    finally:
+        stream.close()
 ```
 
+The tuple's `replay` flag is mandatory: reconcile historical tool requests
+against their result/confirmation events before executing anything. Persist a
+processed-tool-ID ledger across reconnects; never execute an already resolved
+historical call twice. `processed_at` is part of the deduplication key so the
+queued-to-processed transition is not discarded. A timeout is an incomplete
+recovery, not a successful terminal result.
+
 ### Message queuing
 
 **You don't have to wait for a response before sending the next message.** User events are queued server-side and processed in order. This is useful for chat bridges where the user sends rapid follow-ups:
@@ -127,7 +148,7 @@ An `interrupt` event **jumps the queue** (ahead of any pending user messages) an
 
 ```ts
 await client.beta.sessions.events.send(sessionId, {
-  events: [{ type: 'interrupt' }],
+  events: [{ type: 'user.interrupt' }],
 });
 ```
 
@@ -191,5 +212,3 @@ await client.beta.sessions.archive(sessionId);
 ```
 
 > Archiving a **session** is routine cleanup — sessions are per-run and disposable. **Do not generalize this to agents or environments**: those are persistent, reusable resources, and archiving them is permanent (no unarchive; new sessions cannot reference them). See `shared/managed-agents-overview.md` → Common Pitfalls.
-
-

package/built-in-skills/claude-api/shared/managed-agents-multiagent.md

@@ -71,7 +71,11 @@ Each `SessionThread` carries `id`, `status` (`running` | `idle` | `rescheduling`
 
 ## Tool permissions and custom tools from subagent threads
 
-When a subagent needs your client (an `always_ask` confirmation, or a custom tool result), the request is **cross-posted to the primary thread** with `session_thread_id` identifying the originating thread — so you only need to watch the session stream. Reply with `user.tool_confirmation` (carrying `tool_use_id`) or `user.custom_tool_result` (carrying `custom_tool_use_id`), and **echo the `session_thread_id` from the originating event** (the SDK param type and docstring expect it). The server also routes by the tool-use ID, so the echo is belt-and-suspenders rather than load-bearing — but include it.
+When a subagent needs your client, correlate the pending event ID and any
+received thread metadata locally. Reply with `user.tool_confirmation`
+(`tool_use_id`) or `user.custom_tool_result` (`custom_tool_use_id`). Python SDK
+1.8.0's send parameter types do not declare `session_thread_id`; do not invent
+that outgoing field. Retain thread context in your own routing/approval ledger.
 
 ```python
 for event_id in stop.event_ids:
@@ -81,8 +85,6 @@ for event_id in stop.event_ids:
         "tool_use_id": event_id,
         "result": "allow",
     }
-    if pending.session_thread_id is not None:
-        confirmation["session_thread_id"] = pending.session_thread_id
     client.beta.sessions.events.send(session.id, events=[confirmation])
 ```
 

package/built-in-skills/claude-api/shared/managed-agents-self-hosted-sandboxes.md

@@ -1,6 +1,6 @@
 # Managed Agents — Self-Hosted Sandboxes
 
-With `config.type: "self_hosted"`, the **agent loop stays on Anthropic's orchestration layer** but **tool execution moves to infrastructure you control** — bash, file ops, and code run inside your container, so filesystem contents and network egress never leave your environment. Contrast with `config.type: "cloud"`, where Anthropic runs the container. Connectivity is **outbound-only**: your worker long-polls Anthropic's work queue; Anthropic never dials into your network.
+With `config.type: "self_hosted"`, the **agent loop stays on Anthropic's orchestration layer** but **tool execution moves to infrastructure you control**. Bash, file operations and code run inside your container; tool results and any file contents included in those results are sent back to the hosted agent. Self-hosting is not a guarantee that data never leaves your environment. Enforce tool-result redaction, access controls and egress policy. The worker initiates outbound connections to Anthropic's work queue, rather than exposing an inbound worker endpoint.
 
 ## Flow