@namzu/sdk 0.6.0 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,534 @@
 # Changelog
 
+## 1.1.0
+
+### Minor Changes
+
+- ac85934: Add a model-authored `ask_user_question` HITL surface to the coordinator
+  toolset. `HITLDecisionRequest` gains a `user_question` variant carrying
+  `UserQuestionData` (questionId = the asking `tool_use_id`, question text,
+  optional header, 2-4 model-authored options, multiSelect, allowFreeText),
+  and `HITLResumeDecision` gains `answer_question` (selectedOptionIds,
+  optional freeText, optional questionId echo as a misdirection guard).
+  The tool registers only when `buildCoordinatorTools` receives BOTH a
+  `resumeHandler` and a `runId` (SupervisorAgent threads its configured
+  `resumeHandler` through automatically), parks the run through the same
+  ResumeHandler channel as plan approvals, and returns the user's answer
+  verbatim as the tool result — selections quote question and labels,
+  free text is rendered "in their own words", and an empty/misdirected/
+  mismatched answer yields an explicit "the user did not answer" sentinel
+  instead of fabricated consent. The tool is deliberately NOT
+  concurrency-safe so multiple questions in one assistant turn park
+  strictly one at a time against host run-keyed park registries.
+  Headless callers degrade safely: `autoApproveHandler` answers
+  `user_question` with the no-selection sentinel ("No user is available
+  to answer. Proceed using your best judgment."), so runs without an
+  interactive ResumeHandler never deadlock and never invent a choice.
+  Existing ResumeHandler implementations compile unchanged (additive
+  union widening); bare plan-approval and tool-review flows are
+  byte-identical.
+- 9df35d1: Make a Stop abort the IN-FLIGHT model turn, not only between turns.
+
+  `ChatCompletionParams` gains an optional `signal?: AbortSignal`. The query
+  runtime threads the run's abort signal into every provider call (the streaming
+  turn and the forced-final summary) and now drives the provider stream through a
+  MANUAL iterator that RACES each `next()` against the abort — so a cancellation
+  tears the turn down within a tick even if a transport buffers or ignores the
+  signal, with the abort propagating out of the generator so the run settles as
+  `cancelled`. The stream consumer cleans up on every exit (removes the abort
+  listener, calls `iterator.return()`), and the natural-completion break
+  re-checks the signal so a Stop that lands exactly as the turn finishes is
+  recorded as cancelled rather than a normal end-of-turn.
+
+  Every provider now honours the signal at the transport: Anthropic
+  (`messages.create({ signal })`), OpenAI (`create(..., { signal })`), Bedrock
+  (`send(..., { abortSignal })`), OpenRouter + HTTP (compose with the request
+  timeout via `AbortSignal.any`), Ollama (the returned iterator's `.abort()`),
+  and LM Studio (`respond(..., { signal })` → the SDK's websocket cancel) — each
+  plus a cheap per-chunk `signal.throwIfAborted()` for promptness.
+
+  Fully additive and inert when unset: a never-aborted signal is behaviourally
+  identical to omitting it, so existing callers and uncancelled runs are
+  byte-identical.
+
+- 6c09394: Add an optional feedback channel to plan approvals: `HITLResumeDecision`'s
+  `approve_plan` variant now carries `feedback?: string`, the plan-approval
+  resume handler forwards it as `PlanApprovalResponse.feedback`, and the
+  coordinator `approve_plan` tool embeds approve-with-edits feedback in the
+  model-visible tool result so the supervisor applies the user's edits
+  atomically with the approval. Bare approvals are byte-identical to before;
+  existing resume handlers compile and behave unchanged.
+- 8c07556: Tool-loading economics: honor prompt caching in the Anthropic provider and
+  make deferred-tool discovery ranked and bounded.
+
+  `@namzu/anthropic`:
+
+  - `cacheControl` on `ChatCompletionParams` is now honored (it was silently
+    dropped; `cache_read_input_tokens` was always 0). The provider emits up to
+    three `cache_control: {type:'ephemeral'}` breakpoints per request: the
+    tools-array tail, the last `'cache'`-tagged system block, and the last
+    message block (render order tools → system → messages).
+  - System messages are sent as a block array preserving `SystemMessage.cacheHint`
+    segment boundaries instead of being joined into one string. The OAuth
+    Claude Code identity block stays first.
+  - `toolChoice: 'none'` now maps to Anthropic's first-class
+    `tool_choice: {type:'none'}` instead of `{type:'auto'}`, and `tool_choice`
+    is only sent alongside a `tools` param.
+  - `parallelToolCalls: false` now maps to `disable_parallel_tool_use: true`
+    on the `tool_choice` (previously unmapped).
+
+  `@namzu/sdk`:
+
+  - The runtime keeps the tools param byte-stable on forced-final iterations
+    (resource-limit finalization) and forbids tool use via `toolChoice: 'none'`
+    instead of omitting `tools` — omitting busted the whole prompt-cache prefix
+    and risked a 400 with `tool_use`/`tool_result` blocks in history.
+  - `ToolRegistry.toPromptSection()` lists active tools name-only (their
+    descriptions and schemas already ride the runtime tools param every
+    request) and gives deferred tools a first-sentence hint (≤100 chars) so the
+    model can discover what a deferred name does before searching.
+  - `ToolRegistry.searchDeferred()` is now a ranked weighted search (exact
+    name 12, name substring 8, description 5, argument names 3 — the
+    `ToolCatalog.searchTools` weights) with generic CRUD verbs (`list`,
+    `read`, `create`, `update`, `get`, `find`, `delete`, `search`) added to the
+    stop-token set. `search_tools` activates only the top-5 ranked matches and
+    reports up to 5 near-misses as name+hint WITHOUT activating them, so a
+    retrieval miss becomes a cheap re-query instead of a dead end. The
+    `search_tools` input wire shape (`{query}`) is unchanged.
+
+### Patch Changes
+
+- 999e4be: Context-management correctness fixes (Vandal round-3 architecture audit).
+
+  - **Compaction no longer orphans tool pairs.** `runCompactionCheck` now snaps
+    the recent-window boundary through `findSafeTrimIndex` (previously wired only
+    to the unused `ConversationManager` strategy classes), so a compaction cut can
+    never leave a `tool_result` at the head of the recent window whose `tool_use`
+    was summarized away. That orphan otherwise makes the provider reject the very
+    next turn with a 400 — compaction killing the long run it exists to keep alive.
+  - **Resume preserves the compaction summary + working-memory slot.** The
+    checkpoint-restore path used to drop EVERY system message, silently losing the
+    `[COMPACTED CONTEXT]` block (the only record of the older history a pass
+    deleted) on `resumeFromCheckpoint`. It now re-pushes the fresh static/dynamic
+    floor but preserves the compaction summary and the pinned working-memory slot.
+  - **Within-turn usage is merged, not last-write-wins.** `mergeTokenUsage`
+    (per-field high-water mark) replaces `usage = chunk.usage` in `collect()` and
+    the iteration stream reducer, so a late usage frame that omits input/cache
+    tokens no longer zeroes the counts captured earlier in the stream.
+  - **HITL parks are cancellable.** `awaitDecisionOrAbort` races the tool-review
+    and iteration-checkpoint `resumeHandler` parks against the run's abort signal,
+    so a Stop that arrives while parked resolves the park as `abort` instead of
+    hanging until the host answers. Degrades to a plain await when no controller
+    is wired; fails closed to `abort` if the handler rejects.
+
+  All changes are internal correctness fixes; the provider/message wire contract
+  is unchanged and existing consumers stay behaviourally identical outside the
+  buggy edge cases above.
+
+- 42f577e: Recreate shared run workspace manifest directories before atomic writes.
+- 9a0c5ee: Plan-rejection guidance now follows the user's feedback instead of baking in
+  an unconditional revise loop. The old output told the supervisor to "revise
+  your plan ... and call approve_plan again" even when the feedback explicitly
+  asked it to stop, so a rejection meant to halt kept generating new plans.
+  The output now instructs: follow the feedback — revise and re-submit only if
+  changes were requested; acknowledge and end the turn if asked to stop; ask
+  the user how to proceed when no feedback was given.
+- 0d1fb7b: Harden file intake and ACI readiness failure handling.
+
+  The built-in read tool now guides Office and PDF packages through
+  extractor tooling instead of treating binary document containers as
+  UTF-8 text. The ACI Standby Pool backend now deletes a claimed
+  container group when IP or worker readiness polling fails before a
+  Sandbox handle is returned.
+
+- 2c5dd7a: The supervisor's task ledger no longer fabricates success for workers that
+  produced no result. Previously, when a task handle had no `result`, the
+  synthesized entry took its status from `handle.state` (cast to a terminal
+  type) — so a handle reporting `state: 'completed'` but carrying no result was
+  counted toward `completedTasks`. The supervisor then reported "workers done"
+  with empty outputs when the workers never actually produced anything.
+
+  An absent result is now always synthesized as a terminal `'failed'`, so it can
+  never count as a completed task. Handles that carry a real `result` are
+  preserved verbatim, so genuine workers are unaffected. The synthesis and tally
+  are extracted into `synthesizeTaskResults` / `countCompletedTasks` and covered
+  by unit tests.
+
+- 271e6cf: Accept plain-text `approve_plan` step lists and normalize them into canonical
+  step objects before execution. This keeps plan approval cards resilient when a
+  provider emits numbered prose instead of an array-shaped argument.
+- b776acf: Make the package-version read bundle-safe. `version.ts` read `../package.json`
+  via `createRequire(import.meta.url)` at module-init with no guard. esbuild leaves
+  `createRequire` calls as runtime requires and collapses the dist tree into a
+  single file, so in a bundle `../package.json` no longer resolves and the read
+  threw at import time — crashing the whole process on any code path that touches
+  the SDK runtime (`Cannot find module '../package.json'`). Wrap the read in
+  try/catch with a `0.0.0` fallback, mirroring the CLI's existing
+  `readPackageVersion`. Unbundled behaviour is unchanged (real version is read);
+  a bundled build degrades the cosmetic version string instead of crashing.
+
+## 1.0.0
+
+### Major Changes
+
+- df09910: fix(sdk)!: drop plan-task lifecycle from `buildAgentTool`
+
+  `buildAgentTool` used to auto-create a plan task in the supplied
+  `taskStore` and flip it to `'in_progress'` before invoking the
+  subagent. On success it flipped to `'completed'`, but on failure
+  the plan task was left stuck in `'in_progress'` forever — the
+  `TaskStatus` enum has no `'failed'` value to transition to, so
+  there was no honest way to close it from inside the tool.
+
+  Removed `taskStore` and `runId` from `AgentToolOptions` entirely.
+  The `Agent` tool's job is "invoke a subagent and return the
+  result"; plan-task tracking is the parent's responsibility via
+  `TaskCreate` / `TaskUpdate`, where the host owns the status
+  semantics. This avoids the leak class entirely instead of
+  patching it.
+
+  Breaking change for any consumer that was relying on the auto-
+  plan-task behaviour. Migrate by creating the plan task on the
+  host side before calling `Agent`, and updating it on the host
+  side once the tool result is in hand.
+
+- ea21863: feat(sdk)!: rename builtin tools to Claude Code canonical names
+
+  **Breaking change.** Builtin tool names now mirror Claude Code's canonical
+  tool table verbatim (per `code.claude.com/docs/en/tools-reference`):
+
+  - `bash` → `Bash`
+  - `edit` → `Edit`
+  - `glob` → `Glob`
+  - `grep` → `Grep`
+  - `read_file` → `Read`
+  - `write_file` → `Write`
+
+  `LsTool` and `SearchToolsTool` are still exported but **removed from the
+  default `getBuiltinTools()` set**. Claude Code's training distribution
+  does not include `LS` (directory listing is `Bash` + `Glob`) and has no
+  `search_tools` analogue at all. Including them in the defaults gave the
+  model two tools that looked right but degraded alignment. Hosts that
+  genuinely want either can register them explicitly.
+
+  Why this is breaking and worth it: Namzu is a peer to Claude Code's
+  native agentic surface, not a wrapper around the Anthropic Beta Agents
+  API. Mirroring the canonical names verbatim means Claude's pretrained
+  agentic instincts apply for free — no system-prompt argument needed to
+  explain what `Read` or `Bash` does. Idiosyncratic snake_case names threw
+  that alignment away on every call.
+
+  **Migration:** consumers that hard-code tool-name strings in their
+  prompt overlays, friendly-label maps, or per-tool deny rules need to
+  update them to the new PascalCase names. The runtime registry contracts
+  (register / get / has) are unchanged; only the literal string names of
+  the builtin tools moved.
+
+- 8fd9349: feat(sandbox)!: Anthropic-style multi-mount container sandbox layout
+
+  Adds a declarative `ContainerSandboxLayout` shape that maps onto
+  Anthropic's container architecture (Claude container blueprint,
+  Code Interpreter, "skills"). The `Container` prefix is load-bearing
+  — this layout is specific to the container tier; future microVM /
+  process tiers will carry their own layout types when their adapters
+  land. Layout is supplied at provider construction — not per
+  `provider.create()` call — so the type system catches missing-layout
+  mistakes at compile time:
+
+  ```ts
+  import {
+    createSandboxProvider,
+    SANDBOX_DEFAULT_OUTPUTS_PATH, // re-exported from @namzu/sdk
+  } from "@namzu/sandbox";
+
+  const provider = createSandboxProvider({
+    backend: { tier: "container", image: "namzu-worker:latest" },
+    layout: {
+      outputs: {
+        source: {
+          type: "hostDir",
+          hostPath: "/var/lib/vandal/sessions/<task>/outputs",
+        },
+      },
+      uploads: {
+        source: {
+          type: "hostDir",
+          hostPath: "/var/lib/vandal/sessions/<task>/uploads",
+        },
+      },
+      skills: [
+        {
+          id: "pdf-tools",
+          source: { type: "hostDir", hostPath: "/opt/skills/pdf-tools" },
+        },
+      ],
+    },
+  });
+  ```
+
+  Each mount carries a discriminated `ContainerSandboxMountSource`.
+  The single variant today is `{ type: 'hostDir'; hostPath: string }`;
+  future variants (squashfs skill bundles, managed volumes attached
+  to a container backend) land additively as minor bumps without
+  reshaping the consumer call site.
+
+  Layout fields and their defaults:
+
+  - `outputs` — RW. Default `/mnt/user-data/outputs`. **Required**.
+  - `uploads` — RO. Default `/mnt/user-data/uploads`.
+  - `toolResults` — RO. Default `/mnt/user-data/tool_results`.
+  - `skills` — RO list, default `/mnt/skills/<id>` per entry.
+  - `transcripts` — RO. Default `/mnt/transcripts`.
+
+  The defaults are exported as constants from `@namzu/sdk`'s root
+  barrel (`SANDBOX_DEFAULT_OUTPUTS_PATH`,
+  `SANDBOX_DEFAULT_UPLOADS_PATH`, `SANDBOX_DEFAULT_TOOL_RESULTS_PATH`,
+  `SANDBOX_DEFAULT_TRANSCRIPTS_PATH`, `SANDBOX_DEFAULT_SKILLS_PARENT`)
+  and re-exported from `@namzu/sandbox`, so prompt-template generators
+  and the backend agree on a single source of truth. Both import
+  paths (`@namzu/sdk` and `@namzu/sandbox`) are pinned by tests.
+
+  There is intentionally **no `scratchpad` field**: the
+  container-internal RW area (`/home/<imageUser>`) is image-bake
+  responsibility, not a runtime knob.
+
+  **Validation** runs synchronously inside `createSandboxProvider` and
+  collects every violation in one
+  `ContainerSandboxLayoutValidationError.reasons[]`:
+
+  - `outputs` must be present.
+  - Skill IDs match `/^[a-zA-Z0-9_.-]+$/`, and `id.includes('..')` is
+    rejected (path-traversal guard — covers `..`, `foo..bar`,
+    `..foo`, `foo..`). Isolated dots (`pdf-tools.v2`) pass.
+  - Skill IDs are unique.
+  - Resolved `containerPath`s are unique across every mount slot.
+
+  **Error transport.** `ContainerSandboxLayoutValidationError`
+  carries a `cause` field (Error native), `toJSON()` keeps `reasons`
+  (and `cause` when set), and a new helper
+  `serializeSandboxError(err: unknown): SerializedSandboxError`
+  returns a plain object that survives `structuredClone`,
+  `postMessage`, and `JSON.stringify` round-trips uniformly. The
+  helper is **cycle-safe** — a `WeakSet`-threaded recursion detects
+  self-cycles (`a.cause = a`), two-node cycles (`a.cause = b;
+b.cause = a`), and longer loops, replacing the offending node with
+  a `{ name: 'CircularReference', message: '[circular]' }` sentinel
+  rather than overflowing the stack. The helper is also
+  **transport-safe** — non-Error causes (Function, Symbol, BigInt,
+  NaN, ±Infinity, undefined, null, primitives, plain objects) are
+  converted to a typed envelope by `serializeNonErrorCause` BEFORE
+  they enter the wire shape, so values that `JSON.stringify` drops
+  silently or `structuredClone` throws on never appear.
+  `SerializedSandboxError.cause` is strictly typed
+  `SerializedSandboxError | undefined`. Use the helper at any
+  worker / IPC / log-shipper boundary; cloning the Error subclass
+  itself is not supported.
+
+  **Breaking changes** — the legacy single-mount paradigm is removed:
+
+  - `SandboxCreateConfig.hostWorkspaceDir` is removed. Pass the host
+    path on `layout.outputs.source.hostPath` at provider construction.
+  - `ContainerBackendConfig.workspaceMount` is removed. Pass the
+    in-container path on `layout.outputs.containerPath`.
+  - `SandboxProviderConfig` is now a discriminated union: the
+    container variant requires `layout: ContainerSandboxLayout`, the
+    other variants do not carry the field. Constructing a docker
+    provider without a layout fails at compile time.
+  - `SandboxCreateConfig.layout` does NOT exist; layout is
+    factory-baked. The SDK runtime cannot accidentally call a
+    container provider without a layout.
+  - The docker backend no longer allocates host directories
+    (`mkdtemp`) or removes them on `destroy()`. Every bind source is
+    consumer-owned. This also fixes an `EACCES: permission denied,
+mkdir '/Users'` crash that hit sibling-container deployments
+    (Vandal Cowork).
+  - The worker no longer reads `NAMZU_SANDBOX_LAYOUT` (it never
+    branched on the env, only logged it; size grew with the skill
+    list). Only `NAMZU_SANDBOX_WORKSPACE` is forwarded today.
+
+  The reference Dockerfile pre-creates **only the parent directories**
+  `/mnt`, `/mnt/user-data`, `/mnt/skills` — root-owned, mode 0555.
+  Leaf paths (`outputs/`, `uploads/`, `tool_results/`, `transcripts/`,
+  `<skill-id>/`) are intentionally NOT pre-created. When a bind is
+  attached the docker daemon creates the leaf as the bind target;
+  when not attached, the leaf does not exist — the model gets ENOENT
+  instead of an empty writable dir that looks "mounted but uploaded
+  nothing".
+
+  `pnpm sandbox:smoke` (alias for `pnpm --filter @namzu/sandbox
+test:smoke`) runs an opt-in docker integration test exercising the
+  leaf-permission contract against a real docker daemon. Excluded
+  from the default `pnpm test`; gated by a dedicated
+  `.github/workflows/sandbox-smoke.yml` workflow that builds the
+  reference image and runs the smoke test on PR / push when the
+  sandbox surface changes. On CI (`process.env.CI === 'true'`), the
+  smoke test fails fast if docker / the image are absent rather than
+  silently skipping.
+
+  `@namzu/sdk` exports `ContainerSandboxLayout`,
+  `ContainerSandboxLayoutMount`, `ContainerSandboxMountSource`,
+  `ContainerSandboxSkillMount`, `ResolvedContainerSandboxLayout`,
+  and the five `SANDBOX_DEFAULT_*_PATH` constants from its root
+  barrel. `@namzu/sandbox` re-exports those names plus
+  `ContainerSandboxLayoutValidationError`, `serializeSandboxError`,
+  and the `SerializedSandboxError` shape. The packed-tarball shape
+  is verified by `.github/scripts/verify-consumer-install.sh`'s
+  `@namzu/sandbox public-surface fixture`, which installs the
+  package from a tarball into a clean project and asserts every
+  documented constant + runtime export comes back via both
+  `@namzu/sandbox` and `@namzu/sdk` import paths. `@namzu/sandbox`
+  is also added to `ci.yml`'s `publint` and ATTW (Are The Types
+  Wrong) gates.
+
+### Minor Changes
+
+- 542f057: feat(sdk): canonical `Agent` tool for synchronous subagent delegation
+
+  Adds `buildAgentTool({ gateway, workingDirectory, allowedAgentIds, ... })`
+  that builds a single tool named `Agent` with the input shape
+  `{ description, prompt, subagent_type }`. This mirrors Claude Code's
+  training distribution verbatim (per `code.claude.com/docs/en/sub-agents`):
+  the parent's tool call BLOCKS on `gateway.waitForTask(handle.taskId)`,
+  the subagent runs in its own context window, and the subagent's final
+  text comes back as the tool result.
+
+  Why this matters: the existing `buildCoordinatorTools` shipped a
+  non-blocking `create_task` / `continue_task` / `cancel_task` trio that
+  returned immediately and surfaced subagent completion via a
+  `<task-notification>` callback. That pattern is useful for fire-and-
+  forget multi-task fan-out but is **not** what Claude was trained on.
+  Models calling the async coordinator tools waste tokens reasoning
+  about whether the task completed yet; with the canonical `Agent`
+  tool, the model just receives the result and continues. Free
+  alignment, no system-prompt argument needed.
+
+  Both surfaces remain available — the coordinator trio is the right
+  choice for genuine work-queue surfaces, the `Agent` tool is the
+  right choice when the host wants Claude Code parity.
+
+- 265150b: feat(sdk): default sandboxed verification gate preset + expanded brick-pattern denylist
+
+  Ship `defaultSandboxedGateConfig()` and `defaultSandboxedShellGateConfig()` from `@namzu/sdk` so
+  hosts running an agent inside an isolated workspace don't have to hand-roll a `VerificationRule[]`
+  just to keep in-sandbox file mutation from triggering a review prompt on every call. The first
+  preset auto-allows read-only tools and `category: 'filesystem' | 'analysis' | 'custom'`; the
+  second extends auto-allow to `category: 'shell'` for hosts with real OS-level isolation. Both
+  keep the dangerous-patterns hard-deny in place.
+
+  `DANGEROUS_PATTERNS` (consumed by the `deny_dangerous_patterns` rule) gains entries for `sudo`,
+  `su -`, world-writable `chmod 777 /`, `curl|sh` / `wget|sh` exfil-then-exec pipes, outbound
+  `ssh user@host`, and raw dynamic `eval`. The list is still high-signal, not exhaustive — the
+  README in `verification/presets.ts` is explicit that the sandbox itself is the safety boundary
+  and the patterns only catch blatant attempts.
+
+- 52af97e: **Paste images into the conversation (vision input).**
+
+  A user message can now carry image attachments. `@namzu/sdk` adds an optional `attachments` field to user messages (`ImageAttachment { data, mediaType }`, additive — text messages are unchanged), and the Anthropic provider sends them as image content blocks so the model can see them. In the CLI, press `Ctrl+V` to paste an image from the clipboard — it shows as an `⎘ Image #N` chip in the composer and is sent to the model as vision input when you submit.
+
+- a71422a: feat(sdk): ReactiveAgent forwards verificationGate to drainQuery
+
+  Adds an optional `verificationGate?: VerificationGateConfig` field on
+  `ReactiveAgentConfig` and forwards it through `ReactiveAgent.run()` into
+  `drainQuery`, mirroring the existing `SupervisorAgentConfig.verificationGate`
+  plumbing. Without this, child agents running under `ReactiveAgent` could not
+  opt into the same capability-aware deny/allow rules the supervisor already
+  uses — the only path was `drainQuery`'s `autoApproveHandler` default, which
+  approves every tool call silently. Hosts that want defense-in-depth at the
+  child level (deny dangerous shell patterns, restrict by category) can now
+  pass the same preset they pass to the supervisor.
+
+- d6b5bc1: **Remove the legacy `append` file tool.** `AppendFileTool` is gone — it was already excluded from `getBuiltinTools()` (Claude Code's tool distribution has no `Append`), and appending is canonical `edit` with `insertLine: "end"`. The export is removed from the public surface; hosts that relied on it should switch to `edit`. namzu's CLI no longer needs to filter `append` out of its tool set.
+- 63b4885: feat(sdk): forward sandboxProvider through reactive/supervisor agents
+
+  `ReactiveAgentConfig` and `SupervisorAgentConfig` gain an optional
+  `sandboxProvider?: SandboxProvider` field. When set, the agent's
+  `runConfig` builder forwards the provider into `drainQuery`'s
+  `sandboxProvider` slot, so the supervisor — and every child
+  specialist run that inherits the supervisor's run config — gets
+  the same per-task ephemeral container.
+
+  Without this plumbing, a host that wires `sandboxProvider` only on
+  the supervisor sees the field silently dropped before child
+  specialists are spawned, and each child runs without a sandbox.
+  The forwarding closes that gap so multi-agent hosts can pass a
+  single per-task provider instance and have supervisor + every
+  child share one container.
+
+  Pure additive change — `SupervisorAgent` / `ReactiveAgent`
+  constructors that don't pass `sandboxProvider` behave exactly as
+  before.
+
+- d86b161: **namzu can now delegate to sub-agents.**
+
+  The CLI wires the SDK's native delegation: the model gets the canonical `Agent({ description, prompt, subagent_type })` tool and can hand a self-contained task to a fresh `general-purpose` sub-agent that runs in its own context window with its own tools, then returns its result. Delegations show in the transcript as a normal `Agent(...)` tool call with a live spinner and result.
+
+  To support this from a host, `@namzu/sdk` now exports `ThreadManager` and `InMemoryThreadStore` from its public runtime surface (alongside the already-public `AgentManager`, `AgentRegistry`, `ReactiveAgent`, `LocalTaskGateway`, `buildAgentTool`, and the session/summary/capacity/workspace primitives) so a consumer can stand up an `AgentManager` end to end.
+
+### Patch Changes
+
+- 140bcc0: fix(sdk): Agent tool no longer reports failed subagents as successful
+
+  `buildAgentTool` was treating `gateway.waitForTask(handle.taskId)`'s
+  returned `state === 'completed'` as proof of success and ignoring
+  the underlying `BaseAgentResult.status`. That was wrong: some
+  gateways (the SDK's `LocalTaskGateway` for one) forward
+  `task.state` directly from the agent manager without re-deriving it
+  from the run's `status`, so a subagent run with `status: 'failed'`
+  plus a non-empty `lastError` could surface as `state: 'completed'`
+  and fool the parent into receiving `success: true` with garbage
+  output.
+
+  The check now requires BOTH layers to agree before reporting
+  success: gateway state must be `'completed'` AND the run's
+  `BaseAgentResult.status` (when present) must be `'completed'`. On
+  failure the tool surfaces `lastError` and the disagreement state in
+  both `error` and `data` so the parent can debug.
+
+  Adds three pinned cases in
+  `packages/sdk/src/tools/coordinator/__tests__/agent.test.ts`
+  covering: both-agree-success, run-status-failed-but-state-completed
+  (the regression case), and gateway-state-failed.
+
+- 38c4b62: Harden two paths flagged by an adversarial review: `ToolRegistry.searchDeferred` no longer over-activates deferred tools — batched-query tokens match the tool name only (not descriptions) and short/generic tokens like `clawtool` are ignored, so a common word can't activate the whole catalog. The dynamic `Agent` sub-agent now unregisters its per-call `dyn-N` definition in a `finally`, so long sessions don't leak persona registrations on success, failure, or throw.
+- a1c6694: **Fix a race when multiple file-mutating tools run in one turn.**
+
+  The tool executor ran every tool call in a batch with `Promise.all`, ignoring each tool's `concurrencySafe` flag. Several `edit`/`write` calls to the same file in one assistant turn therefore raced on read→modify→write — each read the same starting content and the last writer clobbered the others, even though every call reported success. The executor now honors `concurrencySafe`: read-only tools (ls/grep/glob/…) still run in parallel, but concurrency-unsafe tools (edit/write/append/bash) are serialized within the batch, so same-file edits apply one-after-another.
+
+- 63e44f7: Worker `handleExecute` no longer crashes the per-task container when a
+  single request body is rejected by `resolveWithinWorkspace` (e.g. a host
+  path forwarded as `cwd`) or by the workspace `mkdir`. Each fallible step
+  now returns a typed `400` (or a terminal NDJSON `error` event for
+  post-headers failures) and the worker stays alive for the next call —
+  prior behaviour was an unhandled rejection on the `http.createServer`
+  callback, which on Node ≥ 15 exits the process and gives every
+  subsequent SDK call the bare `fetch failed` from `UND_ERR_SOCKET`.
+
+  The docker backend's host-side `execViaWorker` and `writeFile` fetches
+  now surface `error.cause.code` / `cause.message` instead of the
+  stripped `fetch failed`. The bash builtin no longer forwards
+  `context.workingDirectory` (a host-side path that has no meaning
+  inside the sandbox container) as `cwd`; tools that need a sub-cwd
+  inside the sandbox can be added later via an explicit
+  `SandboxExecOptions` field.
+
+  The SDK's iteration aggregator now derives
+  `ChatCompletionResponse.toolCalls[i].function.arguments` from each
+  bucket's parsed input rather than the raw `argsBuf` buffer. When a
+  provider stream truncates with `stop_reason: "max_tokens"` mid-
+  `input_json_delta`, downstream `JSON.parse` in
+  `runtime/query/executor.ts:executeSingle` no longer rejects with the
+  generic "Invalid JSON in tool arguments" — the tool runs against the
+  empty parsed object and the input zod schema produces a readable
+  "<field> is required" error instead.
+
+- 38c4b62: Fix `search_tools` failing to load deferred tools when the model names several at once. `ToolRegistry.searchDeferred` matched the entire query as a single substring, so a batched query like `"A2aCard PeerRegister PeerList"` matched no tool and activated nothing — the subsequent call then failed with "deferred and cannot be executed". The query is now tokenized: a tool matches if its name or description contains the whole phrase OR any single term, so a batch activates each named tool.
+- 6b74cd0: **Sub-agents do real work, and tool tracking is keyed on the SDK's tool-use id.**
+
+  - Sub-agents now get the same tool set as the parent — builtins, memory, and clawtool's catalog (deferred, incl. web search/fetch and peer dispatch) — so a delegated research/work task can actually use tools instead of answering from memory alone.
+  - The transcript's live tool tracking now matches each call by the SDK's stable `toolUseId` rather than by name/order, so parallel tool calls (even same-named) are attributed correctly.
+  - Stronger anti-fabrication instruction for both the main agent and sub-agents: never claim to have run a tool, written a file, or produced a result without actually doing it; if a capability is unavailable, say so instead of inventing output.
+  - `@namzu/sdk`: the `Agent` tool's `subagent_type` is now optional when only one sub-agent is registered (defaults to it), so the model can't trip a "subagent_type required" validation error on the common single-sub-agent setup.
+
 ## 0.6.0
 
 ### Minor Changes

package/dist/advisory/executor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../src/advisory/executor.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAA;AACpE,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;AAClF,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAA;AACpE,OAAO,EAAE,KAAK,OAAO,EAA0C,MAAM,2BAA2B,CAAA;AAChG,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAC3D,OAAO,EAAE,KAAK,MAAM,EAAiB,MAAM,oBAAoB,CAAA;AAE/D,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,QAAQ,EAAE,OAAO,EAAE,CAAA;IAC5B,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;IACrC,QAAQ,CAAC,WAAW,CAAC,EAAE,aAAa,EAAE,CAAA;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC1B;AAED,MAAM,WAAW,uBAAuB;IACvC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAA;IAC/B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;IAC1B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC3B;AAED,qBAAa,gBAAgB;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;gBAEnB,MAAM,CAAC,EAAE,MAAM;IAIrB,OAAO,CACZ,OAAO,EAAE,iBAAiB,EAC1B,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,mBAAmB,GAC1B,OAAO,CAAC,uBAAuB,CAAC;IAkDnC,OAAO,CAAC,iBAAiB;IAoBzB,OAAO,CAAC,YAAY;IAoCpB,OAAO,CAAC,gBAAgB;IAqBxB;;;;OAIG;IACH,OAAO,CAAC,WAAW;IAMnB;;;;;OAKG;IACH,OAAO,CAAC,WAAW;CAQnB"}
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../src/advisory/executor.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAA;AACpE,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;AAClF,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAA;AACpE,OAAO,EAAE,KAAK,OAAO,EAA0C,MAAM,2BAA2B,CAAA;AAChG,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAC3D,OAAO,EAAE,KAAK,MAAM,EAAiB,MAAM,oBAAoB,CAAA;AAE/D,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,QAAQ,EAAE,OAAO,EAAE,CAAA;IAC5B,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;IACrC,QAAQ,CAAC,WAAW,CAAC,EAAE,aAAa,EAAE,CAAA;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC1B;AAED,MAAM,WAAW,uBAAuB;IACvC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAA;IAC/B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;IAC1B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC3B;AAED,qBAAa,gBAAgB;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;gBAEnB,MAAM,CAAC,EAAE,MAAM;IAIrB,OAAO,CACZ,OAAO,EAAE,iBAAiB,EAC1B,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,mBAAmB,GAC1B,OAAO,CAAC,uBAAuB,CAAC;IAkDnC,OAAO,CAAC,iBAAiB;IAoBzB,OAAO,CAAC,YAAY;IA6CpB,OAAO,CAAC,gBAAgB;IAqBxB;;;;OAIG;IACH,OAAO,CAAC,WAAW;IAMnB;;;;;OAKG;IACH,OAAO,CAAC,WAAW;CAQnB"}

package/dist/advisory/executor.js

@@ -72,8 +72,15 @@ export class AdvisoryExecutor {
             contextParts.push(`## Working State\n${callCtx.workingStateSummary}`);
         }
         if (callCtx.toolCatalog && callCtx.toolCatalog.length > 0) {
-            const toolNames = callCtx.toolCatalog.map((t) => t.function.name);
-            contextParts.push(`## Available Tools\n${toolNames.join(', ')}`);
+            const toolLines = callCtx.toolCatalog.map((tool) => {
+                const description = tool.function.description?.trim();
+                return description ? `- ${tool.function.name}: ${description}` : `- ${tool.function.name}`;
+            });
+            contextParts.push([
+                '## Runtime Tool Summary',
+                'These tools are available to the executor. Their executable schemas remain owned by the runtime tool catalogue; use this as advisory context only.',
+                toolLines.join('\n'),
+            ].join('\n'));
         }
         const messagesToInclude = this.truncateMessages(callCtx.messages, advisor.maxContextTokens);
         if (messagesToInclude.length > 0) {

package/dist/advisory/executor.js.map

@@ -1 +1 @@
-{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../src/advisory/executor.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../src/advisory/executor.ts"],"names":[],"mappings":"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"}

package/dist/advisory/executor.test.d.ts

@@ -21,7 +21,8 @@
  *   - `buildContext`:
  *     - Returns [] when `request.includeContext === false`.
  *     - Includes workingStateSummary when present.
- *     - Includes toolCatalog names when present + non-empty.
+ *     - Includes a runtime tool summary when a toolCatalog is present
+ *       + non-empty; executable schemas remain runtime-owned.
  *     - Includes truncated conversation context (most-recent-first
  *       walk, bounded by `advisor.maxContextTokens * CHARS_PER_TOKEN`).
  *     - Returns [] when no context parts were assembled.

package/dist/advisory/executor.test.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"executor.test.d.ts","sourceRoot":"","sources":["../../src/advisory/executor.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG"}
+{"version":3,"file":"executor.test.d.ts","sourceRoot":"","sources":["../../src/advisory/executor.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG"}

package/dist/advisory/executor.test.js

@@ -21,7 +21,8 @@
  *   - `buildContext`:
  *     - Returns [] when `request.includeContext === false`.
  *     - Includes workingStateSummary when present.
- *     - Includes toolCatalog names when present + non-empty.
+ *     - Includes a runtime tool summary when a toolCatalog is present
+ *       + non-empty; executable schemas remain runtime-owned.
  *     - Includes truncated conversation context (most-recent-first
  *       walk, bounded by `advisor.maxContextTokens * CHARS_PER_TOKEN`).
  *     - Returns [] when no context parts were assembled.
@@ -173,7 +174,7 @@ describe('AdvisoryExecutor — buildContext', () => {
         // Only system + user(question)
         expect(call.messages).toHaveLength(2);
     });
-    it('includes workingStateSummary + toolCatalog names when present', async () => {
+    it('includes workingStateSummary + runtime tool summary when present', async () => {
         const provider = mockProvider();
         const e = new AdvisoryExecutor();
         await e.consult(advisor({ provider }), req, {
@@ -195,8 +196,10 @@ describe('AdvisoryExecutor — buildContext', () => {
         const contextMsg = call.messages[1]?.content ?? '';
         expect(contextMsg).toContain('Working State');
         expect(contextMsg).toContain('state summary here');
-        expect(contextMsg).toContain('Available Tools');
-        expect(contextMsg).toContain('read_file, write_file');
+        expect(contextMsg).toContain('Runtime Tool Summary');
+        expect(contextMsg).toContain('executable schemas remain owned by the runtime tool catalogue');
+        expect(contextMsg).toContain('- read_file: read');
+        expect(contextMsg).toContain('- write_file: write');
     });
     it('includes conversation context (no truncation when no maxContextTokens)', async () => {
         const provider = mockProvider();