zidane 5.4.2 → 5.5.0

package/docs/ARCHITECTURE.md

@@ -142,7 +142,9 @@ flowchart TB
     VC -->|yes| VCH["validation:coerce hook\n(observational)"]
     VC -->|no| T7
     VCH --> T7["tool:before hook\n(ctx.coercions when present, runToolCounts)"]
-    T7 --> T8["toolDef.execute(coercedInput, ctx)"]
+    T7 --> T8["toolDef.execute(coercedInput, ctx)\nracing against perCallAbort.signal"]
+    T8 -->|cancelled by\nagent.cancelTool| TC["tool:cancelled hook\n(reason, runToolCounts)"]
+    TC --> TCR["Return TOOL_USE_CANCELLED_MESSAGE\n(isError: true; skips tool:transform/after)"]
     T8 -->|error| T9["tool:error hook\n(can substitute result)"]
     T8 -->|ok| T10["tool:transform hook\n(can mutate result;\nctx.outputBytes pre-mutation)"]
     T9 --> T10
@@ -158,6 +160,8 @@ flowchart TB
 
 **`tool:gate` mutations.** Set `block` to refuse (`Blocked: reason`), `result` to substitute and skip execute, or neither to run normally. `block` wins over `result` so a policy gate always beats a consumer cache. The substitute path skips `tool:before` + validate + execute but fires `tool:transform` + `tool:after` — budgets and telemetry stay consistent with executed calls.
 
+**Per-call cancellation.** Each dispatch registers an `AbortController` in `LoopContext.pendingToolCancels` keyed by `callId`; the tool body's `ctx.signal` is `AbortSignal.any([ctx.signal, perCallAbort.signal])`. `agent.cancelTool(callId, reason?)` flips the per-call signal, the body promise races against the cancellation, the loop emits `tool:cancelled`, and the wire result becomes `TOOL_USE_CANCELLED_MESSAGE` with `isError: true`. Other in-flight tools in the same batch keep running — distinct from `agent.abort()` (whole-run abort → `INTERRUPT_MESSAGE_FOR_TOOL_USE` at the batch layer) and `TOOL_USE_SKIPPED_MESSAGE` (steered out before dispatch). The map entry is removed in a `finally` so it only ever holds currently-dispatching calls; the body promise gets a no-op `.catch` so misbehaving tools that ignore the signal can't surface as unhandled rejections after the loop has moved on.
+
 **`runToolCounts`** is a frozen pre-call snapshot, scoped to `runId`. Includes dedup + gate-`result` substitutes; excludes blocked calls. Resumed sessions reset the counter. Concurrent fleets see the same pre-batch snapshot — built-in budget/dedup middleware uses its own gate-time reservation counter so `behavior.toolBudgets` stays atomic across the fleet.
 
 **Output shape.** `string | ToolResultContent[]`. Text tools return strings; multimodal tools (MCP browsers, screenshots) return `[{ type: 'text' }, { type: 'image', mediaType, data }]`. Providers with `capabilities.imageInToolResult: true` (Anthropic, OpenAI Codex) route arrays natively; OpenAI-compat emits a companion `user` message with `image_url` parts. Non-vision providers swap image blocks for a text marker before the hook fires.
@@ -359,15 +363,22 @@ per run():
     skills_use({ name })                   → state.activate(skill, 'model')
                                              → skills:activate (via: 'model')
                                              → <skill_content> wrapper
+    skills_use({ name, mode: 'deactivate' }) → state.deactivate(skill)
+                                             → skills:deactivate (reason: 'model')
+                                             → "Skill X deactivated" confirmation
     skills_read / skills_run_script        → gated on state.isActive + path sandbox
   run end: deactivateAllSkills()           → skills:deactivate (reason: 'run-end')
 
 agent.activateSkill(name)                  → skills:activate (via: 'explicit')
 agent.deactivateSkill(name)                → skills:deactivate (reason: 'explicit')
 agent.reset()                              → skills:deactivate (reason: 'reset')
+
+session-resume rehydration:
+  last-mode-wins per skill across history's skills_use blocks
+  → trailing mode:'deactivate' STAYS deactivated; activate/deactivate/activate ends active
 ```
 
-**allowed-tools.** When any active skill declares `allowed-tools`, a `tool:gate` handler blocks calls outside the union (the three skills tools are always implicitly allowed).
+**allowed-tools.** When any active skill declares `allowed-tools`, a `tool:gate` handler blocks calls outside the union (the three skills tools are always implicitly allowed). Block-list (`- entry`) and flow-list (`[a, b]`) authoring shapes both normalize to `string[]` via the frontmatter parser's array-aware path; `AgentToolNotAllowedError.message` carries a recovery hint pointing the model at `skills_use({ mode: 'deactivate', name })` to release the offending skill without waiting for a run boundary.
 
 **Body-only delivery.** `skills_use` returns the body (frontmatter stripped) wrapped in `<skill_content>` for host-SDK context protection. Body includes shell-interpolated instructions (`` !`cmd` ``, fresh per activation), the skill directory, the resource listing (not eagerly loaded), and compatibility + allowed-tools when present.
 
@@ -420,7 +431,7 @@ run end: uninstallLazyDisclosureGate; unlocked GC-eligible on next run()
 skills:resolve                               ← once per agent, after discovery (warmup / run / activateSkill — first wins)
 skills:catalog    [mutable: catalog]         ← once per agent, after system-prompt catalog built (same trigger)
 skills:activate                              ← per activation; { skill, via: 'model' | 'explicit' | 'resume' }
-skills:deactivate                            ← per deactivation; { skill, reason: 'run-end' | 'explicit' | 'reset' }
+skills:deactivate                            ← per deactivation; { skill, reason: 'run-end' | 'explicit' | 'reset' | 'model' }
 ```
 
 Every run ends with an implicit deactivate-all pass (`reason: 'run-end'`); activation state never leaks across runs unless re-asserted via `agent.activateSkill()`.
@@ -453,6 +464,7 @@ turn:after                                       ← always fires (incl. errors)
   tool:transform      [mutable: result, isError] ← + outputBytes pre-mutation
   tool:after                                     ← + outputBytes post-mutation
   tool:error          [mutable: result?]         ← on execute throw; ctx.result substitutes
+  tool:cancelled                                 ← agent.cancelTool(callId); skips transform/after; wire = TOOL_USE_CANCELLED_MESSAGE
 tool-results:after                               ← after the tool-results user turn is pushed (persistence seam)
 usage                                            ← running totals
 output                                           ← when behavior.schema set
@@ -481,6 +493,27 @@ session:end                          ← run finished (completed | aborted | err
                                        includes turnRange [start, end] for cleanup
 ```
 
+### Background task lifecycle
+
+Fires when the model invokes `shell({ run_in_background: true })`. The shell tool dispatches via `ExecutionContext.execBackground`, which spawns a process group, opens a `WriteStream` to `<userDir>/<sessionId>/tasks/<task-id>.<context-timestamp>.log` (the timestamp segment is `YYYYMMDD-HHMMSS-mmm` UTC, shared by every task in the same `ExecutionContext` so two contexts on the same session never collide), and returns immediately with a `TaskHandle`. The agent listens to `background:exit` and queues a `<task-notification>` block for injection into the next user turn (see "Notification queue" below).
+
+**Host opt-in / opt-out.** Background mode is auto-disabled at the schema level (the `run_in_background` field is dropped from the `shell` tool's input schema and the related description paragraphs are stripped) when either `behavior.tasksDir` is unset or `behavior.disableBackgroundTasks: true` is set. `createAgent` performs the rewrite once per run as it indexes tools by spec name — only for the identity-equal framework `shell` constant, so host-customized shell-named tools are left untouched. The runtime check in `runBackground` stays as defense-in-depth (forged inputs that smuggle the flag in past the schema fall through to a clean error, not a silent fallthrough to foreground). Hosts that want explicit control should call `createShellTool({ allowBackground })` and register the tailored variant directly.
+
+```
+background:start     ← spawn succeeded; payload carries taskId + pid + outputPath
+                       (observational; tools don't wait on listeners)
+background:exit      ← at-most-once per task; the context's settle latch
+                       guarantees no duplicate fires (close-or-error race-safe)
+```
+
+**Notification queue.** The agent owns a `Map<taskId, TaskExitInfo>` populated by the `background:exit` listener. At the start of every `agent.run()`, the queue drains and each entry becomes a leading `text` block on the seeded user turn (`<task-notification>…</task-notification>` XML — see `renderTaskNotificationXml` in `src/agent.ts`). The same agent listens to `tool:after` for `shell_kill` (deletes by `task_id` from input) and `read_file` / `read` (deletes by matching the `path` argument against any pending entry's `outputPath`) so the model never receives a redundant signal when it already learned about the exit through other means. The drain happens once per entry — `Map.set` overwrites by id, so a defensive double-enqueue can't multiply notifications.
+
+**Replay synthesis.** `eventsFromTurns` detects the `<task-notification>` XML in persisted user-turn text blocks (anchored regex — no false positives mid-prompt) and emits a structured `'task-notification'` `StreamEvent` instead of the generic `user-prompt` event. The XML text block is dropped from the rendered stream so the banner doesn't double-paint alongside the raw XML. Field decoding is tolerant — every tag falls back to a safe default if the persisted block predates a later schema addition.
+
+**Destroy ordering.** `agent.destroy()` runs cleanup INSIDE-the-session first (notification queue, per-call cancels) then NEEDED-by-the-session (MCP connection, execution handle, skills cache). The execution context's own `destroy(handle)` walks its background-task registry, SIGTERMs each survivor's process group, and only resolves once every output stream has flushed + closed. The reverse order would tear down the handle underneath still-flushing tasks and corrupt log files. The queue is re-cleared AFTER `executionContext.destroy()` because the `background:exit` hook listener stays bound for the agent's lifetime and may re-populate the map mid-teardown.
+
+**Orphan reaper.** `ProcessContext` lazy-registers a `process.on('exit')` handler on the first `execBackground` call that synchronously SIGTERMs every still-running task's process group. Without it, the `detached: true` spawn flag (required for the kill-tree semantics) would leak children when the host process exits without calling `destroy()` (Ctrl+C, uncaught exception, OOM kill). The handler deregisters in `destroy()` so reconstructed contexts don't accumulate listeners.
+
 ### Once (lazy on first `warmup()` / `run()` / `activateSkill()` — or eager when `eager: true`)
 
 ```
@@ -509,6 +542,7 @@ The child's lifecycle also bubbles to the parent hook surface with `childId` + `
 ```
 child:stream:text / child:stream:thinking / child:stream:end / child:stream:error
 child:tool:gate / child:mcp:tool:gate          ← share the child's ctx — parent mutations propagate
+child:tool:cancelled                           ← bubbled per-call cancel from a subagent's tool
 child:tool:transform                           ← share the child's ctx — parent mutations propagate
 child:tool:before / child:tool:after / child:tool:error
 child:turn:after

package/docs/CHAT.md

@@ -419,7 +419,7 @@ type ChipColorMap = { default: ChipColor } & Partial<Record<string, ChipColor>>
 
 Per-tool approval gate with a per-project safelist. The agent emits a `tool:gate` hook; the chat layer's wired handler:
 
-1. If `IMPLICITLY_SAFE_TOOLS` covers the call → allow.
+1. If `IMPLICITLY_SAFE_TOOLS` covers the call → allow. The list is `['read_file', 'list_files', 'glob', 'grep', 'ask_user', 'present_plan', 'todowrite', 'todoread', 'skills_use']` — pure reads, interaction prompts (the picker IS the gate), todo metadata, and skill activation (mutates a per-agent Map; no shell/disk/network — gating it would also break the model's recovery path when it deactivates a skill after an `AgentToolNotAllowedError`). `skills_read` (touches disk) and `skills_run_script` (executes scripts) are intentionally NOT on the list.
 2. If the project safelist (`~/.zidane/projects.json`) matches → allow.
 3. Else push an `ApprovalRequest` onto `SafeModeProvider`'s queue and await.
 
@@ -958,6 +958,7 @@ Render path expectations on the `'tool'` `StreamEvent`:
 - Tags every child-run event with `{ childId: 'child-N', depth }` where `child-N` is chronologically assigned by `startedAt`. Same labels the live spawn tool emits.
 - Strips the redundant `Tokens: …` line from spawn tool-result bodies — only when guarded by the `[sub-agent <id>] …` header, so a body line that legitimately starts with `Tokens:` is preserved.
 - Emits a `'compact-summary'` event for every `compact-summary` content block, with `compact` metadata (`replacedCount`, `model`, `compactedAt`, `inputTokens`, `outputTokens`, `cacheReadTokens`, `cacheCreationTokens`).
+- Detects leading `<task-notification>` text blocks (the wire format `renderTaskNotificationXml` emits) on user turns and synthesizes a `'task-notification'` event with structured `task` metadata (`taskId`, `status`, `exitCode`, `outputPath`, `command`, `durationMs`). The raw text block is suppressed from the `'user-prompt'` stream so the banner doesn't double-paint. Detection is anchored — a stray notification-shaped phrase mid-prompt won't trigger.
 
 `lastContextSizeFromTurns(turns, runs)` returns the most recent **depth-0** assistant turn's input token total (cache-aware: `input + cacheRead + cacheCreation`) — the next prompt feeds the parent, so a session that ended mid-spawn doesn't surface the child's window in the footer.
 
@@ -1016,7 +1017,7 @@ The discriminated union the renderer consumes. `kind` values:
 'thinking' | 'tool' | 'tool-result' | 'error'
 | 'user-prompt' | 'info' | 'separator'
 | 'markdown' | 'spawn-start' | 'spawn-end'
-| 'compact-summary'
+| 'compact-summary' | 'task-notification'
 ```
 
 Notable fields:
@@ -1030,6 +1031,7 @@ Notable fields:
 - `refs?: { start, end, providerId }[]` — chip-highlight spans on `'user-prompt'` events.
 - `turnId?: string` — the `SessionTurn.id` the event was emitted by; drives select-turn highlighting.
 - `compact?: { replacedCount, model, compactedAt, inputTokens, outputTokens, cacheReadTokens, cacheCreationTokens }` — metadata for `'compact-summary'` boundary cards.
+- `task?: { taskId, status: 'exited' | 'killed', exitCode, outputPath, command, durationMs }` — metadata for `'task-notification'` banners. Synthesized in `eventsFromTurns` from persisted `<task-notification>` XML in user-turn text blocks; the raw XML block is dropped from the user-prompt stream so the banner doesn't double-paint alongside it.
 
 `'user-prompt'` carries the **raw** user prompt without a `❯` prefix; renderers add their own chevron. `refs` offsets are aligned to the raw text.