@prismer/runtime 2.0.8 → 2.2.63

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

@@ -1,5 +1,6 @@
 ---
 name: claim-agent-ownership
+scope: common
 description: |
   Orchestrator skill for resolving multi-daemon binding contention. Use when you (the
   orchestrator) detect an `agent.binding.contested` sync event indicating two daemons
@@ -7,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
@@ -51,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 \
@@ -73,7 +78,7 @@ curl -fsS \
 ```
 
 `PRISMER_CLOUD_BASE` defaults to the cloud the daemon paired with
-(`https://prismer.cloud` in prod, `http://127.0.0.1:3000` in local dev).
+(`https://prod.docbrew.cn` in prod, `http://127.0.0.1:3000` in local dev).
 
 For pure-API use (orchestrator runtime, MCP tool, etc.), the underlying call is:
 
@@ -209,7 +214,7 @@ Action:
     "$PRISMER_CLOUD_BASE/api/im/agent-bindings/u_agent_ceo/rebind"
 
 Response: boundDaemonId='daemon-mac-studio-01', inFlightTaskCount=2
-Orchestrator messages user: "Pinned CEO agent to your Mac Studio. 2 tasks finishing on
+Orchestrator messages user: "Pinned Team Manager agent to your Mac Studio. 2 tasks finishing on
                             the cloud pod first."
 ```
 

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

@@ -1,5 +1,6 @@
 ---
 name: claude-api
+scope: coding
 description: "Build, debug, and optimize Claude API / Anthropic SDK apps. Apps built with this skill should include prompt caching. Also handles migrating existing Claude API code between Claude model versions (4.5 → 4.6, 4.6 → 4.7, retired-model replacements). TRIGGER when: code imports `anthropic`/`@anthropic-ai/sdk`; user asks for the Claude API, Anthropic SDK, or Managed Agents; user adds/modifies/tunes a Claude feature (caching, thinking, compaction, tool use, batch, files, citations, memory) or model (Opus/Sonnet/Haiku) in a file; questions about prompt caching / cache hit rate in an Anthropic SDK project. SKIP: file imports `openai`/other-provider SDK, filename like `*-openai.py`/`*-generic.py`, provider-neutral code, general programming/ML."
 license: Complete terms in LICENSE.txt
 ---
@@ -27,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
 

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

@@ -88,8 +88,8 @@ Control when server-executed tools (agent toolset + MCP) run automatically vs wa
 **Responding to `always_ask`:** Send a `user.tool_confirmation` event with `tool_use_id` from the triggering `agent_tool_use`/`mcp_tool_use` event:
 
 ```json
-{ "type": "tool_confirmation", "tool_use_id": "sevt_abc123", "result": "allow" }
-{ "type": "tool_confirmation", "tool_use_id": "sevt_def456", "result": "deny", "message": "Read .env.example instead" }
+{ "type": "user.tool_confirmation", "tool_use_id": "sevt_abc123", "result": "allow" }
+{ "type": "user.tool_confirmation", "tool_use_id": "sevt_def456", "result": "deny", "deny_message": "Read .env.example instead" }
 ```
 
 The optional `message` on a deny is delivered to the agent so it can adjust its approach.
@@ -318,4 +318,3 @@ agent = client.beta.agents.create(
 | List Versions         | `GET`    | `/v1/skills/{id}/versions`                      |
 | Get Version           | `GET`    | `/v1/skills/{id}/versions/{version}`            |
 | Delete Version        | `DELETE` | `/v1/skills/{id}/versions/{version}`            |
-

package/built-in-skills/claude-api/shared/model-migration.md

@@ -50,7 +50,7 @@ Then wait for the answer. The same applies to *"Migrate to Opus 4.7"* and bare *
 rg -l "<old-model-id>" --type-not md | cut -d/ -f1 | sort | uniq -c | sort -rn
 ```
 
-Present the breakdown in your scope question (e.g. *"Found 217 references across 3 directories: api/ (130), api-go/ (62), routing/ (25). Which to migrate?"*). Also confirm `git status` is clean before surveying — unexpected modifications mean a concurrent process; stop and investigate before proceeding.
+Present the breakdown in your scope question (e.g. *"Found 217 references across 3 directories: api/ (130), api-go/ (62), routing/ (25). Which to migrate?"*). Inspect `git status` before editing and preserve all existing changes. A dirty tree alone is not a blocker; stop only when an overlapping change prevents safe scoped work. Never restore or discard unrelated files.
 
 ---
 
@@ -488,7 +488,7 @@ Every item is tagged: **`[BLOCKS]`** items cause a 400 error, infinite loop, sil
 For each file that calls `messages.create()` / equivalent SDK method:
 
 - [ ] **[BLOCKS]** Update the `model=` string to the new alias
-- [ ] **[BLOCKS]** Replace `budget_tokens` with `thinking={"type": "adaptive"}` (deprecated on Opus 4.6 / Sonnet 4.6)
+- [ ] **[TUNE]** Prefer `thinking={"type": "adaptive"}` on Opus 4.6 / Sonnet 4.6; deprecation alone is not proof that an existing `budget_tokens` call fails. Verify the selected model's contract before removing working configuration.
 - [ ] **[BLOCKS]** Move `format` from top-level `output_format` into `output_config.format`
 - [ ] **[BLOCKS]** Remove any assistant-turn prefills if targeting Opus 4.6 or Sonnet 4.6 (see the prefill replacement table)
 - [ ] **[BLOCKS]** Switch to streaming if `max_tokens > ~16000` (otherwise SDK HTTP timeout)
@@ -517,7 +517,7 @@ For cached prompts: the render order and hash inputs did not change, so existing
 
 ## Migrating to Opus 4.7
 
-> **Model ID `claude-opus-4-7` is authoritative as written here.** When the user asks to migrate to Opus 4.7, write `model="claude-opus-4-7"` exactly. Do **not** WebFetch to verify — this guide is the source of truth for migration target IDs. The corresponding entry exists in `shared/models.md`.
+> Model IDs in this cached guide are examples, not authority over the deployed provider. Verify the requested target using the provider's current Models API or official documentation from `shared/live-sources.md`; preserve explicit user/runtime model policy. Do not make a paid request merely to probe availability.
 
 Claude Opus 4.7 is our most capable generally available model to date. It is highly autonomous and performs exceptionally well on long-horizon agentic work, knowledge work, vision tasks, and memory tasks. This section summarizes everything new at launch. It is layered on top of the 4.6 migration above — if the caller is jumping from Opus 4.5 or older, apply the 4.6 changes first, then apply this section.
 

package/built-in-skills/claude-api/shared/models.md

@@ -41,7 +41,7 @@ curl https://api.anthropic.com/v1/models/claude-opus-4-7 \
 {
   "id": "claude-opus-4-7",
   "display_name": "Claude Opus 4.7",
-  "max_input_tokens": 200000,
+  "max_input_tokens": 1000000,
   "max_tokens": 128000,
   "capabilities": {
     "image_input": {"supported": true},

package/built-in-skills/claude-api/typescript/claude-api/batches.md

@@ -79,7 +79,7 @@ for await (const result of await client.messages.batches.results(
   switch (result.result.type) {
     case "succeeded":
       console.log(
-        `[${result.custom_id}] ${result.result.message.content[0].text.slice(0, 100)}`,
+        `[${result.custom_id}] ${result.result.message.content.filter(b => b.type === 'text').map(b => b.text).join('\n').slice(0, 100)}`,
       );
       break;
     case "errored":

package/built-in-skills/claude-api/typescript/claude-api/files-api.md

@@ -60,7 +60,9 @@ const response = await client.beta.messages.create({
   betas: ["files-api-2025-04-14"],
 });
 
-console.log(response.content[0].text);
+for (const block of response.content) {
+  if (block.type === 'text') console.log(block.text);
+}
 ```
 
 ---

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

@@ -59,7 +59,8 @@ const client = new Anthropic();
 const tools: Anthropic.Tool[] = [...]; // Your tool definitions
 let messages: Anthropic.MessageParam[] = [{ role: "user", content: userInput }];
 
-while (true) {
+for (let turn = 0; ; turn++) {
+  if (turn >= 20) throw new Error("Tool turn budget exceeded");
   const response = await client.messages.create({
     model: "claude-opus-4-7",
     max_tokens: 16000,
@@ -75,6 +76,7 @@ while (true) {
     continue;
   }
 
+  if (response.stop_reason !== "tool_use") throw new Error(`Incomplete response: ${response.stop_reason}`);
   const toolUseBlocks = response.content.filter(
     (b): b is Anthropic.ToolUseBlock => b.type === "tool_use",
   );
@@ -91,6 +93,7 @@ while (true) {
     });
   }
 
+  if (!toolResults.length) throw new Error("Missing tool results");
   messages.push({ role: "user", content: toolResults });
 }
 ```
@@ -106,7 +109,8 @@ const client = new Anthropic();
 const tools: Anthropic.Tool[] = [...];
 let messages: Anthropic.MessageParam[] = [{ role: "user", content: userInput }];
 
-while (true) {
+for (let turn = 0; ; turn++) {
+  if (turn >= 20) throw new Error("Tool turn budget exceeded");
   const stream = client.messages.stream({
     model: "claude-opus-4-7",
     max_tokens: 64000,
@@ -131,6 +135,7 @@ while (true) {
     continue;
   }
 
+  if (message.stop_reason !== "tool_use") throw new Error(`Incomplete response: ${message.stop_reason}`);
   const toolUseBlocks = message.content.filter(
     (b): b is Anthropic.ToolUseBlock => b.type === "tool_use",
   );
@@ -147,6 +152,7 @@ while (true) {
     });
   }
 
+  if (!toolResults.length) throw new Error("Missing tool results");
   messages.push({ role: "user", content: toolResults });
 }
 ```

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

@@ -225,7 +225,7 @@ async function runSession(client: Anthropic, sessionId: string) {
       sessionId,
     );
 
-    const toolCalls: Array<{ custom_tool_use_id: string; tool_name: string; input: unknown }> = [];
+    const toolCalls: Array<{ id: string; tool_name: string; input: unknown }> = [];
 
     for await (const event of stream) {
       if (event.type === "agent.message") {
@@ -270,6 +270,9 @@ async function runSession(client: Anthropic, sessionId: string) {
 
 ```typescript
 import fs from "fs";
+import os from "node:os";
+import path from "node:path";
+const outputDir = fs.mkdtempSync(path.join(os.tmpdir(), "agent-output-"));
 
 const file = await client.beta.files.upload({
   file: fs.createReadStream("data.csv"),
@@ -305,7 +308,10 @@ for (const f of files.data) {
   // Download and save to disk
   const resp = await client.beta.files.download(f.id);
   const buffer = Buffer.from(await resp.arrayBuffer());
-  fs.writeFileSync(f.filename, buffer);
+  if (!f.filename || [".", ".."].includes(f.filename) || /[/\\]/.test(f.filename)) {
+    throw new Error("Unsafe output filename");
+  }
+  fs.writeFileSync(path.join(outputDir, f.filename), buffer, { flag: "wx", mode: 0o600 });
 }
 ```
 

package/built-in-skills/codebase-design/DEEPENING.md

@@ -0,0 +1,37 @@
+# Deepening
+
+How to deepen a cluster of shallow modules safely, given its dependencies. Assumes the vocabulary in [SKILL.md](SKILL.md) — **module**, **interface**, **seam**, **adapter**.
+
+## Dependency categories
+
+When assessing a candidate for deepening, classify its dependencies. The category determines how the deepened module is tested across its seam.
+
+### 1. In-process
+
+Pure computation, in-memory state, no I/O. Always deepenable — merge the modules and test through the new interface directly. No adapter needed.
+
+### 2. Local-substitutable
+
+Dependencies that have local test stand-ins (PGLite for Postgres, in-memory filesystem). Deepenable if the stand-in exists. The deepened module is tested with the stand-in running in the test suite. The seam is internal; no port at the module's external interface.
+
+### 3. Remote but owned (Ports & Adapters)
+
+Your own services across a network boundary (microservices, internal APIs). Define a **port** (interface) at the seam. The deep module owns the logic; the transport is injected as an **adapter**. Tests use an in-memory adapter. Production uses an HTTP/gRPC/queue adapter.
+
+Recommendation shape: *"Define a port at the seam, implement an HTTP adapter for production and an in-memory adapter for testing, so the logic sits in one deep module even though it's deployed across a network."*
+
+### 4. True external (Mock)
+
+Third-party services (Stripe, Twilio, etc.) you don't control. The deepened module takes the external dependency as an injected port; tests provide a mock adapter.
+
+## Seam discipline
+
+- **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a port unless at least two adapters are justified (typically production + test). A single-adapter seam is just indirection.
+- **Internal seams vs external seams.** A deep module can have internal seams (private to its implementation, used by its own tests) as well as the external seam at its interface. Don't expose internal seams through the interface just because tests use them.
+
+## Testing strategy: replace, don't layer
+
+- Old unit tests on shallow modules become waste once tests at the deepened module's interface exist — delete them.
+- Write new tests at the deepened module's interface. The **interface is the test surface**.
+- Tests assert on observable outcomes through the interface, not internal state.
+- Tests should survive internal refactors — they describe behaviour, not implementation. If a test has to change when the implementation changes, it's testing past the interface.

package/built-in-skills/codebase-design/DESIGN-IT-TWICE.md

@@ -0,0 +1,44 @@
+# Design It Twice
+
+When the user wants to explore alternative interfaces for a chosen deepening candidate, use this parallel sub-agent pattern. Based on "Design It Twice" (Ousterhout) — your first idea is unlikely to be the best.
+
+Uses the vocabulary in [SKILL.md](SKILL.md) — **module**, **interface**, **seam**, **adapter**, **leverage**.
+
+## Process
+
+### 1. Frame the problem space
+
+Before spawning sub-agents, write a user-facing explanation of the problem space for the chosen candidate:
+
+- The constraints any new interface would need to satisfy
+- The dependencies it would rely on, and which category they fall into (see [DEEPENING.md](DEEPENING.md))
+- A rough illustrative code sketch to ground the constraints — not a proposal, just a way to make the constraints concrete
+
+Show this to the user, then immediately proceed to Step 2. The user reads and thinks while the sub-agents work in parallel.
+
+### 2. Spawn sub-agents
+
+Spawn 3+ sub-agents in parallel using the Agent tool. Each must produce a **radically different** interface for the deepened module.
+
+Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category from [DEEPENING.md](DEEPENING.md), what sits behind the seam). The brief is independent of the user-facing problem-space explanation in Step 1. Give each agent a different design constraint:
+
+- Agent 1: "Minimize the interface — aim for 1–3 entry points max. Maximise leverage per entry point."
+- Agent 2: "Maximise flexibility — support many use cases and extension."
+- Agent 3: "Optimise for the most common caller — make the default case trivial."
+- Agent 4 (if applicable): "Design around ports & adapters for cross-seam dependencies."
+
+Include both [SKILL.md](SKILL.md) vocabulary and CONTEXT.md vocabulary in the brief so each sub-agent names things consistently with the architecture language and the project's domain language.
+
+Each sub-agent outputs:
+
+1. Interface (types, methods, params — plus invariants, ordering, error modes)
+2. Usage example showing how callers use it
+3. What the implementation hides behind the seam
+4. Dependency strategy and adapters (see [DEEPENING.md](DEEPENING.md))
+5. Trade-offs — where leverage is high, where it's thin
+
+### 3. Present and compare
+
+Present designs sequentially so the user can absorb each one, then compare them in prose. Contrast by **depth** (leverage at the interface), **locality** (where change concentrates), and **seam placement**.
+
+After comparing, give your own recommendation: which design you think is strongest and why. If elements from different designs would combine well, propose a hybrid. Be opinionated — the user wants a strong read, not a menu.

package/built-in-skills/codebase-design/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.