@sema-agent/core 7.27.0 → 7.28.1

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 7.28.1 — 2026-09-22
+
+> **7.28.0 was never published.** Its first `npm publish` was cut off mid-upload by a pipe on the publisher's side; the registry keeps a *staged* half-upload under that number and refuses every later publish of it (`E409 Cannot publish over previously staged version`), and `npm unpublish` does not clear a staged version. This release is the same tree under the next patch number — tag `v7.28.1`; no `v7.28.0` tag or package exists.
+
+### One shell lexer mints word FACTS; the thirteen ANSI-C letters fold; an unterminated quote is a parse failure (#994 S0; behaviour WIDENING ×1 and NARROWING ×1; +0 exports; @cli @test)
+
+- **What changed.** The read faces' lexer moved from `src/tools/fs/bash-lexer.ts` to `src/shell/lex.ts` (a layer-0 module that imports nothing) and grew the structure every later slice reads: each word carries `pieces` (literal / expansion, each with its source span and the quote that holds it), `quotedSpans`, `expansions` (parameter, command, process, arithmetic, tilde, brace, glob), an `assignment` fact (`name`, `op`, `subscript`, `value`, `bare`, `form`, `settlesWholeName`), an `unresolved` reason from a closed set, and `atCommandPosition`. `raw` / `folded` / `wordsOf` / the connectors are unchanged views, pinned byte-identical to the previous lexer over a 91-entry corpus except the deltas below (`test/backlog994-s0-lexer-baseline.test.ts`). No reader migrates in this slice; the position reader, the classifier and the read station read the same two spellings they read before.
+- **WIDENING (ANSI-C).** `$'…'` bodies carrying one of the thirteen single-letter escapes (`\a \b \e \E \f \n \r \t \v \\ \' \" \?`) now fold to the shell's byte instead of refusing the word. The table is admitted by a differential test against the real shells (`test/backlog994-s0-lexer-real-shells.test.ts`: every bash found on the machine, plus `sh`; a machine with no bash or no `sh` FAILS that test rather than skipping). Every other escape — numeric, `\x`, `\u`/`\U`, `\c` — stays `unresolved` (its bytes differ between bash 3.2 and 5.x, or NUL truncates the region), and the refusing sentence is unchanged. Who is hurt: nobody — the thirteen values are fixed on every target shell.
+- **NARROWING (unterminated quotes).** A command with an unclosed `'`, `"` or `$'` is a parse failure in every mode, refused with a sentence, where the strict faces used to re-read it quote-blind (more words, more segments, each vetted). Bash runs nothing on such a command. Consumers: the classify face refuses it (`splitShellCompoundSegments` returns the sentence), the read station's plan is `unreadable` (a card on the bash seats, a refusal headless), and the refused-command whitelist no longer vouches for it. Who is hurt: a deployment whose approvals relied on a quote-blind reading of a malformed command auto-passing as read-only — that reading vouched for text the shell would reject.
+- **Rule import: a persisted-rule body with an unbalanced `$'…'` is refused as `invalid.unbalanced_quotes`, where 7.27.0 refused it as `invalid.not_simple_command`** (`src/core/permission-rule-model.ts`; `RuleRejectCode` gains no member — the code moves within the closed set to the one its `'` / `"` siblings already use, so an import report groups the three spellings together). Consumer flip for a report keyed on the old code (measured on both trees: G5).
+- **An unresolved word refuses ITS reading, not the whole text (merged-tree adversarial round).** The read plan (`planShellReads`) now lexes to facts and keeps every segment beside a word it cannot settle (a compound array value, a subscript, an off-table `$'…'` escape), carrying the refusal sentence as the plan's `unreadable` floor; the fold raises that floor to `unestablishable` and a deny hit anywhere in the text still outranks it (`deny > ask`). Collapsing to an empty plan had let `A=(1 2); cat <deny row>` land on an approvable ask where `cat <deny row>` alone is refused. A PARSE failure is unchanged (no words, bash runs nothing). Pin: `test/backlog994-s0-deny-outranks-unresolved.test.ts`. Glob and brace carving is one walk over the pieces instead of a rebuild per character (a word of 8000 `*` took 1.6 s, now 13 ms; `test/backlog994-s0-lexer-baseline.test.ts` holds the byte-identical reading).
+- **A word the lexer could not settle hands the judge no literal, and a lost working directory keeps the deny floor (round 2).** Every candidate minted from a refused-view unresolved word — a read operand, a `cd` target — is `unresolvable`; an unprovable move loses the base as before, and a relative read after it is ALSO judged for deny rows only against the bases the text was certainly in when it lost track (`ReadCandidate.floorBases`; the declared cwd when nothing had moved — `cd sub && cd $'\\x2e' && cat <row under sub>` is refused through the `sub` floor) (`cd $'\x2e' && cat <deny row>` — bash: `cd .` — had moved the base to a fictitious `/work/\x2e` and walked past the deny; it is refused on both full-shell seats now, and the same text without a deny row stays a mandated ask). Unmatched `{` / `[` no longer rescan the suffix: brace pairs are matched in one forward walk and `]` positions in one backward walk (32 000 unmatched braces: 3.3 s → 37 ms).
+- **Facts minted, verdicts unchanged (until S1).** A subscripted assignment at command position pairs its brackets across blanks and operators as bash does (`A[1 + 1]=v cat f` is ONE word); the position reader still reads the word as an unknown program (a card), and a subscript that bash reads as arithmetic across an operator, a quoted `]`, or a pairing the two bash versions disagree on (after a leading redirection) is `unresolved`. A compound value `NAME=(…)` at command position — or as an operand of `alias`/`declare`/`eval`/`export`/`let`/`local`/`readonly`/`typeset` — is one word marked `unresolved` rather than a `(` group. `$"…"` carries `unresolved: "locale_string"` while the refused-reading view still folds it (refusing it today would turn a deny hit into a card).
+- **Dialect.** The lexer declares `SHELL_LEX_DIALECT = "bash"`; `bashOnlyConstructsOf(lex)` lists the constructs a POSIX `sh` reads differently, for the execution environment's `sh` fallback to degrade on (the reader that consumes it lands in S1).
+- **Retired.** The "any backslash in `$'…'` is unreadable" special case (folded into `unresolved`), and the quote-blind re-run (`scan`'s `quotesLiteral`). `SHELL_CONTROL_PREFIXES` has one home (the lexer; the position reader re-exports it).
+
+### The verification debt: four binary pins have a real-green reading, the embedder pin is in the gate, and five comment ceilings come back down (#970; no behaviour change; +0 exports; @server @test)
+
+- **Four pins that could only ever skip now have a measured green, in the lane that produces the ratchet's own report.** On the gate container (`scripts/remote-gate.sh`, node 24.21.0): ripgrep 13.0.0 — `fs-search-honesty` 156 passed / 0 skipped, including the three real-`rg` legs the baseline had been carrying; sharp 0.35.3 — the two live-sharp legs pass (their `sharp-absent` twin is the far half of a paired conditional and still skips, by design); a real Postgres with pgvector — `pg-live` 4 + `pg-stores` 1, all green, which is the first reading for the two things pg-mem cannot emulate (true `<=>` cosine ranking, real MVCC contention); real language servers over stdio — `lsp-live-servers` 6 passed / 0 failed with typescript-language-server 6.0.0 and pyright 1.1.414 installed into the lane (the five languages with no server installed skip, as the file's own gate intends).
+- **The skip ratchet names its lane and loses five entries.** `test/skip-baseline.json` gained a `note` block (which machine this baseline is judged on, which binaries that lane carries, why an env-gated entry is a deliberate opt-in rather than lost coverage), and the rg ×3 / sharp ×2 entries are gone — they run in that lane, so a machine without those binaries now goes red, which is what a ratchet is for. The LSP and Postgres entries stay: they are opt-in on `LSP_LIVE` / `PG_LIVE` + `PG_URL`, and removing them would make the whole ratchet depend on those services being up. `verify-skip-baseline.mjs --update` / `--merge` used to rewrite the file as `{skipped}` alone, which would have deleted that note one run later; both legs now carry over every non-`skipped` key.
+- **A required-green pin must be PRESENT and PASSED on a full run, not merely "not skipped".** `gate:skips` now passes `--full` to `scripts/verify-skip-baseline.mjs`; on a declared full run every `requiredGreen` entry has to appear in the report as `passed` — a file that was renamed, glob-missed or crashed at collection used to read as green through the skip-only check (main-session receipt counterexample). Scoped runs (no `--full`) keep absence as scope. The baseline `note` now states ONE lane: the gate container is the only lane the full suite runs in on the release path, and the list is re-minted from that lane's report at RC. Six pins spawn the gate on synthetic reports (`test/skip-gate-required-green.test.ts`).
+- **The full-run check runs before the rewrite legs, and the live gate judges its registry on its own (merged-tree adversarial round).** `--full --update` / `--full --merge` refuse when a required pin is absent, skipped or failed (a rewrite must not bank the loss); `run-live-gate.mjs` fails by name when an ENABLED conditional file is missing from the tree and announces a disabled one whether or not the file exists (a renamed file used to vanish without a line). Pins: `test/skip-gate-required-green.test.ts` (+2), `test/live-gate-conditional-registry.test.ts`.
+- **The live gate's verdict is per target (round 2).** `scripts/live-gate-verdict.mjs`: every selected file must be present in the JSON report with at least one passed case and nothing skipped or failed — a selected file vitest never collected used to pass on the aggregate counts. Pin: `test/live-gate-verdict.test.ts`.
+- **The real-embedder pin enters the release gate by name.** `test/memory-embed-live.test.ts` → `test/live-memory-embed.test.ts`: `run-live-gate.mjs` selects the live surface by glob over `test/live-*.test.ts`, so the only real-embedder coverage in the tree had been structurally outside it. An embeddings endpoint is not the standing chat provider, so the file carries an admission condition rather than a flat exclusion — in the default surface when `EMB_LIVE_BASE_URL` is set (live surface 47 → 49 assertions), and when it is not, the gate prints the omission by name instead of silently globbing past it. **Measured while wiring it:** against an endpoint refusing every connection the SECOND pin passed green — its query shared the word `particles` with the note it expected to rank first, so the lexical path answered it alone. The query now shares no term with either body and the leg asserts two rows and a real cosine ordering (refused-endpoint reading: 1 failed / 1 passed before, 2 failed after).
+- **Five comment-ratio ceilings come back off the 7.24.2 raises** (`src` 0.3003/264 → 0.3002/263, `src/examples` 0.1661/38 → 0.1653/37, `src/brain` 0.4227/227 → 0.4210/219, `src/core/memory-engine` 0.3672/954 → 0.3663/932, `src/agents` 0.4385/1056 → 0.4371/1038), by removing narrative rather than contract, and every one is banked in the commit that earned it. `docs/RELEASE-TIERS.md` gains the X-before fixed checklist (the full `gate-all --with-dist --rc` roster, the ratchet/bookkeeping pins, the silent-arm gate and the three failopen files) — gates whose only other chance to be red is after the tag.
+- **Still owed, by their owners.** @server: the Pg/TiDB dialects across the 39-cell memory kit have no real-green reading yet; the lane and the DSN wiring above are the same ones that leg needs. @test: the two memory black-box fences pinned at `core@5.23.0` still exit 2 (SKIP), and the cross-session personal-recall e2e was last exercised on 2026-08-16.
+
 ## 7.27.0 — 2026-09-22
 
 ### Every JSONL read-back is form-judged, and every store that tolerates damage names the loss (#1013; behaviour NARROWING; +0 exports; @server @cli @client-core @test)

package/dist/agents/builtin-agents.d.ts

@@ -3,21 +3,12 @@ import type { AgentDefinition } from "../core/types.js";
  * F1 (design/135 批次3 / PARITY-SPOT-AGENT-TYPES-2026-07-10) — the CC 2.1.198 BUILT-IN `Explore` and
  * `Plan` agent types, ported to sema's AgentDefinition roster shape.
  *
- * 198 锚 (亲核 2026-07-10, drift 调研: 198→204→206 逐字零漂移):
- *  - Explore definition `qme` — pretty.js:409186-409198 (`agentType:"Explore"`, whenToUse=nbm,
- *    whenToUseLean=rbm, `disallowedTools:[is,NR,s0,xa,Ic,FR]` = Agent/Artifact/ExitPlanMode/Edit/Write/
- *    NotebookEdit, `model:"inherit"`, `omitClaudeMd:!0`, getSystemPrompt=tbm).
- *  - Explore whenToUse `nbm` / whenToUseLean `rbm` — pretty.js:409173-409174 (verbatim below).
- *  - Explore system prompt `tbm()` — pretty.js:409122-409160 (verbatim below, unix+Glob/Grep arm).
- *  - Plan definition `Xor` — pretty.js:486943-486953 (`agentType:"Plan"`, single whenToUse, same six
- *    disallowedTools, `tools: qme.tools` = undefined, `model:"inherit"`, `omitClaudeMd:!0`).
- *  - Plan system prompt `kBm()` — pretty.js:486874-486930 (verbatim below, unix arm).
- *  - Registry `HCe` — pretty.js:487221-487240: Explore+Plan ship behind `iAt()` (487127-487131:
- *    env kill-switch `CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS` + `tengu_slate_ibis` gate DEFAULT ON)
- *    ⇒ GA default-on in 198 (and byte-stable through 204/206 — CC-DRIFT-198-206-AGENT-TYPES 锚 1-7).
- *    SDK entrypoints ship them too (only `claude-code-guide` is non-SDK); the SDK-form opt-out is
- *    `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` (487221) → sema's deployment-config analog is
- *    `SubagentToolOptions.builtinAgents: false` (config-driven, not env-driven).
+ * Both definitions, their `whenToUse` lines and their system prompts are ported VERBATIM from the
+ * reference implementation's own (unix + Glob/Grep arm), including the six denied tools
+ * (Agent/Artifact/ExitPlanMode/Edit/Write/NotebookEdit) and `model:"inherit"`. Upstream they ship
+ * default-on behind an env kill-switch; sema's analog is the deployment-config
+ * `SubagentToolOptions.builtinAgents: false` rather than an env variable. Per-symbol source
+ * coordinates and the drift re-checks live in the parity register, not here.
  *
  * sema adaptations (deliberate, each recorded):
  *  - De-branding (prompt-sovereignty / SUBAGENT_PROMPT precedent): CC's persona first sentences name the

package/dist/agents/cascade.d.ts

@@ -161,48 +161,44 @@ export declare function runCascade(runner: RunnerSelfSeat, spec: TaskSpec, confi
  *
  * WHY THE SEAT EXISTS: `runCascade` returns a `TaskResult` and DRAINS each rung's event stream
  * internally, so the host never holds a `TaskStream` for any rung. Without this parameter a
- * deployment can observe nothing a rung did — tool beats, forwarded child progress, the resolved
- * workspace — only the per-rung {@link CascadeAttempt} audit rows and the final result. Wiring an
+ * deployment observes nothing a rung did — tool beats, forwarded child progress, the resolved
+ * workspace — only the per-rung {@link CascadeAttempt} audit rows and the final result. An
  * observation sink here (`onActivity`, `onForwardEvent`, `onWorkspaceResolved`) is the only way in.
  *
- * ATTRIBUTION: rungs run SEQUENTIALLY and each is dispatched with the SAME object, so one sink
- * receives the rungs' beats CONCATENATED in ladder order. `ToolActivity` carries no rung identity of
- * its own — the frames of two rungs running the same tool are indistinguishable in content, so the
- * boundary a host keys on is {@link CascadeConfig.onRung}, which fires only after its own rung's
- * beats have been delivered (the sole rung that ends without one is a durable pause, which returns
- * immediately). Two honesty notes: SUBAGENT events forwarded through `onForwardEvent` do carry their
- * own `sourceTaskId`, and a BACKGROUND child outlives the rung that spawned it — its frames can
- * arrive after that rung's `onRung`, i.e. inside the next rung's segment.
+ * ATTRIBUTION: rungs run SEQUENTIALLY with the SAME object, so one sink receives the rungs' beats
+ * CONCATENATED in ladder order. `ToolActivity` carries no rung identity — two rungs running the same
+ * tool are indistinguishable — so the boundary a host keys on is {@link CascadeConfig.onRung}, which
+ * fires only after its own rung's beats have been delivered (the sole rung ending without one is a
+ * durable pause, which returns immediately). Two honesty notes: SUBAGENT events forwarded through
+ * `onForwardEvent` carry their own `sourceTaskId`, and a BACKGROUND child outlives the rung that
+ * spawned it — its frames can arrive inside the next rung's segment.
  *
- * FAILURE-ISOLATED since #248, by the same primitive as {@link CascadeConfig.onRung}: engine-invoked
- * through a run-scoped safe notifier — a throwing `onActivity` is contained (first failure per site
- * disclosed via `console.warn`, later ones counted) and no longer faults the rung. Before #248 the
- * fault AMPLIFIED: the faulted rung was rejected by the gate, the cascade escalated, and a
- * non-idempotent tool the rung had ALREADY executed ran AGAIN on the next rung — the MEASURED
- * HAZARD pin that recorded that now pins containment.
+ * FAILURE-ISOLATED, by the same primitive as {@link CascadeConfig.onRung}: engine-invoked through a
+ * run-scoped safe notifier — a throwing `onActivity` is contained (first failure per site disclosed
+ * via `console.warn`, later ones counted) and never faults the rung. Uncontained, the fault
+ * AMPLIFIES: the faulted rung is rejected by the gate, the cascade escalates, and a non-idempotent
+ * tool the rung had ALREADY executed runs AGAIN on the next rung — the MEASURED HAZARD pin holds
+ * containment.
  *
  * FORWARDED WHOLE, NOT FILTERED: every field rides every rung, including the ref-valued ones
  * (`peerSelfRef`, `ownOrgAdmissionRef`) whose own contract is one ref per RUN — wiring those here
- * makes the ladder's rungs share one carrier. The seat is meant for observation sinks; anything else
- * is a choice the caller is making explicitly, not a default this layer applies.
+ * makes the ladder's rungs share one carrier. The seat is meant for observation sinks; anything
+ * else is a choice the caller is making explicitly, not a default this layer applies.
  *
  * `isolation: "worktree"` in particular rides through here, where the verification gate REFUSES it —
- * an asymmetry with a reason. That field mints a NEW workspace per RUN. The gate's runs are one
+ * an asymmetry with a reason. That field mints a NEW workspace per RUN: the gate's runs are one
  * artifact judged and repaired by several legs, so separate workspaces would have the verifier
- * grading files the implementation never wrote to; a ladder's rungs are INDEPENDENT COLD RE-RUNS of
- * the same task (this function's own contract), so one workspace per rung is the coherent reading —
- * each attempt gets its own tree. What a host must then know, stated without promises this function
- * cannot keep: the returned result is ONE rung's, its work lives in THAT rung's workspace, and no
- * field of the result names it — `onWorkspaceResolved` is the only place the path appears, once per
- * rung in ladder order. Whether the path is still readable afterwards is the FACTORY's contract, not
- * this function's: each rung's factory-minted env is torn down at the end of that rung's run, and
- * what teardown does to the workspace is the factory's business.
+ * grading files the implementation never wrote to, while a ladder's rungs are INDEPENDENT COLD
+ * RE-RUNS, so one workspace per rung is the coherent reading. What a host must then know: the
+ * returned result is ONE rung's, its work lives in THAT rung's workspace, and no field of the result
+ * names it — `onWorkspaceResolved` is the only place the path appears, once per rung in ladder
+ * order. Whether it is still readable afterwards is the FACTORY's contract: each rung's
+ * factory-minted env is torn down at the end of that rung's run.
  *
- * Absent ⇒ every rung is dispatched exactly as before (the call site passes `undefined`, which is
- * what an omitted optional argument already was) — with ONE design/380 O1② placement delta either
- * way: when neither `placementRoot` nor `rootSessionId` is present, rungs after the first are
- * dispatched with a fresh shallow copy carrying `placementRoot` = the first rung's resolved
- * sessionId (the ladder's placement fixed point); every other field still rides by the same
- * reference, and an internals object that already carries a fixed point is forwarded verbatim.
+ * Absent ⇒ every rung is dispatched with `undefined`, with ONE design/380 O1② placement delta either
+ * way: when neither `placementRoot` nor `rootSessionId` is present, rungs after the first get a
+ * fresh shallow copy carrying `placementRoot` = the first rung's resolved sessionId (the ladder's
+ * placement fixed point); every other field still rides by the same reference, and an internals
+ * object that already carries a fixed point is forwarded verbatim.
  */
 internals?: RunInternals): Promise<CascadeRunResult>;

package/dist/agents/observer.d.ts

@@ -1,16 +1,16 @@
 /**
  * Observer agents — CC 2.1.206 parity (逐字锚: docs/CC206-OBSERVER-ANCHORS-2026-07-11.md).
  *
- * A definition may declare `observer: "<agent name>"`: whenever that agent runs, the named agent
- * type is auto-spawned in the background, PAIRED with it. The observer receives read-only activity
- * digests of the observed run (assistant text / tool calls / tool results / turn boundaries) and
- * may push a report back through the {@link createObserverReportTool | ObserverReport} tool — the
- * expected steady state is silence. One-way by construction: the observed agent never replies, and
- * SendMessage is refused in BOTH directions (sender-is-observer and target-is-observer).
+ * A definition may declare `observer: "<agent name>"`: whenever that agent runs, the named agent type
+ * is auto-spawned in the background, PAIRED with it. The observer receives read-only activity digests
+ * of the observed run (assistant text / tool calls / tool results / turn boundaries) and may push a
+ * report back through the {@link createObserverReportTool | ObserverReport} tool — the expected steady
+ * state is silence. One-way by construction: the observed agent never replies, and SendMessage is
+ * refused in BOTH directions.
  *
- * This module is the anchor-faithful half (digest model / renderers / envelope / postamble /
- * framing prompt / declaration resolver / pairing state machine / ObserverReport tool). The spawn
- * wiring (event tap on the delegation lanes + auto-spawn + delivery) lives in `subagent.ts`.
+ * This module is the anchor-faithful half (digest model / renderers / envelope / postamble / framing
+ * prompt / declaration resolver / pairing state machine / ObserverReport tool); the spawn wiring
+ * (event tap on the delegation lanes + auto-spawn + delivery) lives in `subagent.ts`.
  *
  * CC anchor coordinates cited per symbol below refer to `claude-cli-2.1.206.pretty.js`.
  */
@@ -86,18 +86,16 @@ export declare function renderObserverDigestBatch(pairing: {
  * CC `OIu` (220 `vrd` @374408) — the observer's opening system framing (delivered as the first
  * prompt message).
  *
- * RB-306 ① (undeclared divergence, now declared — text unchanged): CC's report-target slot is an
- * IDENTITY — `reportTargetTaskId ?? "main"` (@374409), i.e. the observed run's task id, or the
- * literal "main" for the main conversation. sema passes the observed agent's NAME
- * (`childAgentName`, see subagent.ts's arm) because a delegated child's task id is minted inside
- * the delegation and carries no meaning for the observer's own reasoning, while the agent name is
- * exactly what the digests are tagged with (`<{name}-activity>`). Deliberate: the slot's job is to
- * tell the observer WHERE its report lands, and in sema the name is the addressable form. Note the
- * ``?? "main"`` fallback is byte-identical to CC on the no-label leg.
+ * DIVERGENCE (declared, text unchanged): CC's report-target slot is an IDENTITY —
+ * `reportTargetTaskId ?? "main"` (@374409). sema passes the observed agent's NAME (`childAgentName`,
+ * see subagent.ts's arm): a delegated child's task id is minted inside the delegation and means
+ * nothing to the observer, while the name is exactly what the digests are tagged with
+ * (`<{name}-activity>`) and the addressable form here. The ``?? "main"`` fallback is byte-identical
+ * on the no-label leg.
  *
- * Not implemented (declared gap, not a divergence in this function): CC's SECOND framing shape —
- * the coordinator/worker chain (`viaWorkerName`, @374419-374426), where an observer watches a
- * WORKER but reports to the COORDINATOR. sema has one pairing shape (observer ⇄ observed).
+ * Declared gap: CC's SECOND framing shape — the coordinator/worker chain (`viaWorkerName`,
+ * @374419-374426), where an observer watches a WORKER but reports to the COORDINATOR. sema has one
+ * pairing shape (observer ⇄ observed).
  */
 export declare function observerFramingPrompt(args: {
     observedEnvelopeName: string;

package/dist/agents/subagent.d.ts

@@ -5,27 +5,25 @@ import { type ExecutionEnv } from "../internal/harness.js";
 import type { TaskNotificationPayload } from "../core/task-notification.js";
 import { RETAIN_DEFAULT_TTL_MS, RETAIN_DEFAULT_MAX } from "../config/defaults.js";
 /**
- * #505 residual — the two GRANULARITY facts a delegation's terminal `usage` was missing beside
- * tokens/turns/cost, closing a real reporting asymmetry rather than adding decoration: the workflow
- * lane's completion notification has published `tool_uses` (summed `stats.toolCalls`) and `duration_ms`
- * (wall clock) since it was written, and the Agent tool's own SYNC report publishes both in its
- * `<usage>` footer — only the delegation TERMINAL faces (the background/fork/revive notification and its
- * observer twin) reported neither, so the same child answered "how much work, how long" on one lane and
- * refused on the other.
+ * The two GRANULARITY facts a delegation's terminal `usage` carries beside tokens/turns/cost. The
+ * workflow lane's completion notification publishes `tool_uses` (summed `stats.toolCalls`) and
+ * `duration_ms` (wall clock), and the Agent tool's own SYNC report publishes both in its `<usage>`
+ * footer, so a delegation TERMINAL face (the background/fork/revive notification and its observer
+ * twin) that reported neither would have the same child answering "how much work, how long" on one
+ * lane and refusing on the other.
  *
  * PROVENANCE is the workflow lane's — `stats.toolCalls`, the RUN's own count — because that is the
  * quantity the other side of the comparison publishes, and because it is available on every terminal
  * lane, including the revive lane, which has no parent-side forwarding observer at all.
  *
- * WHAT THIS DOES NOT CLOSE, stated because the honest scope is narrower than "one name, one meaning":
- * the Agent tool's SYNC `<usage>` footer keeps its own `tool_uses`, counted by the parent-side
+ * WHAT THIS DOES NOT CLOSE, since the honest scope is narrower than "one name, one meaning": the Agent
+ * tool's SYNC `<usage>` footer keeps its own `tool_uses`, counted by the parent-side
  * `toolStatsCounter`, and the two numbers differ in BOTH directions for the same child — that counter
- * EXCLUDES the delegation tool's own calls and INCLUDES descendants' (CC's nested fold), while
- * `stats.toolCalls` counts the direct child's calls and counts its delegations among them. A child that
- * itself delegates therefore reports two different `tool_uses` depending on whether it was run
- * synchronously or in the background. That footer is a byte-pinned CC-anchored face; reconciling the
- * two is a separate ruling, and until it is made this comment is the place the divergence is written
- * down rather than a claim that it is gone.
+ * EXCLUDES the delegation tool's own calls and INCLUDES descendants' (the reference implementation's
+ * nested fold), while `stats.toolCalls` counts the direct child's calls and counts its delegations
+ * among them. A child that itself delegates therefore reports two different `tool_uses` depending on
+ * whether it ran synchronously or in the background. That footer is a byte-pinned anchored face;
+ * reconciling the two is a separate ruling, and this is where the divergence is written down.
  *
  * Knownness follows `delegatedCostField`'s rule exactly: `toolCalls` is optional on the stats face
  * ("undefined means the gateway reported no usage", and a checkpointed resume folds it per-leg), so the
@@ -39,11 +37,11 @@ import { RETAIN_DEFAULT_TTL_MS, RETAIN_DEFAULT_MAX } from "../config/defaults.js
  * word is minted on either side.
  *
  * Exported at MODULE level (not from the package index — the same posture as `completedAgentCard` and
- * `classifySubagentError`, and for the same reason): the ABSENT arm is the point of the knownness rule
- * and it is not reachable through a real child. This engine's runner initializes `stats.toolCalls` to a
- * number on every path, so only a `TaskResult` from elsewhere — a foreign runner, an older checkpoint —
- * can carry the optional-and-missing shape the stats face declares. A pin that only ever sees a live
- * child cannot tell "absent" apart from "zero", which is precisely the confusion being prevented.
+ * `classifySubagentError`): the ABSENT arm is the point of the knownness rule and is not reachable
+ * through a real child. This runner initializes `stats.toolCalls` to a number on every path, so only a
+ * `TaskResult` from elsewhere — a foreign runner, an older checkpoint — carries the
+ * optional-and-missing shape the stats face declares, and a pin that only sees a live child cannot
+ * tell "absent" apart from "zero".
  */
 export declare function delegatedGranularityFields(stats: {
     toolCalls?: number;
@@ -241,17 +239,14 @@ export declare function classifySubagentError(terminal: TerminalCause): {
     retryable: boolean;
 } | undefined;
 /**
- * structured-card audit 2026-08-05, item D — the Agent family's **completed** `tool_end.structured`
- * card, assembled from an EXPLICIT field whitelist over the child `TaskResult`.
+ * The Agent family's **completed** `tool_end.structured` card, assembled from an EXPLICIT field
+ * whitelist over the child `TaskResult`.
  *
- * ### What was broken
  * `TaskEvent.tool_end.structured`'s 双面契约 (core/types.ts) states that a host MUST render a
- * delegation's landing report from `structured` and MUST NOT scrape the model-facing text. The
- * `async_launched` receipt honored it (`type:"agent"`, on the allowlist); the **completed** delivery
- * did not: its `details` was `{...child}` — a bare `TaskResult` spread with no `type` key at all — so
- * the card projector's allowlist dropped it every time. The one card the contract names by name was the
- * one card that could never arrive, and the only way to get the child's report was the thing the
- * contract forbids.
+ * delegation's landing report from `structured` and MUST NOT scrape the model-facing text — so this
+ * card has to carry `type:"agent"` and survive the card projector's allowlist. A bare `{...child}`
+ * spread does not: with no `type` key the projector drops it, and the one card the contract names is
+ * the one card that can never arrive.
  *
  * ### Reconciling with "never leak the whole child TaskResult"
  * tool-output-projection.ts's own header calls the subagent `details` its example of what must NOT
@@ -263,37 +258,34 @@ export declare function classifySubagentError(terminal: TerminalCause): {
  * - **`checkpointToken`** — the resume CAPABILITY ("never log it or put it in a URL", per its own
  *   JSDoc). A durable pause is short-circuited into `durablePauseDelegationReport` well before this
  *   point, but that is NOT what keeps the token off the wire: a child whose orchestrator mapped an
- *   unexpected `suspended` down to `failed` (`errorCode:"unexpected.suspended"`) reaches this function
- *   carrying one. Under a spread, registering the completed card would have published it.
+ *   unexpected `suspended` down to `failed` (`errorCode:"unexpected.suspended"`) arrives here carrying
+ *   one, and a spread would publish it with the completed card.
  * - **`checkpointGate`** — the token's other half (who must approve what); useless without the token
  *   and part of the same capability story.
  *
  * Everything admitted below is already on the MODEL face of the same tool result (status, result text,
- * failure attribution, run totals, the transcript id) or was already an additive key on the previous
- * `details` object (`resolvedModel` / `toolStats` / `worktreePath`, CC207-B/206-B). So this widens the
- * WIRE by exactly the fields a host needs to render the report, and widens what anyone can read by
- * nothing at all. New `TaskResult` fields do NOT join automatically — that is the point of the
- * whitelist: admitting one is a deliberate edit here, reviewed against this boundary.
+ * failure attribution, run totals, the transcript id) or an additive key on `details`
+ * (`resolvedModel` / `toolStats` / `worktreePath`). So the WIRE carries exactly the fields a host
+ * needs to render the report, and nothing new becomes readable. New `TaskResult` fields do NOT join
+ * automatically — that is the point: admitting one is a deliberate edit here.
  *
  * ### What this whitelist actually governs (wider than "the wire")
  * `details` is the tool result's structured face, so this set is ALSO what the in-process consumers
  * see: the parent's `afterToolCall` hook, the persisted tool-result message in the parent transcript,
  * and anything reading `toolResult.details` — not only `tool_end.structured`. Omitting a field here
- * therefore withholds it from every one of them, which is why the omission of a machine-actionable
- * field (2026-08-04: `retryAfterMs`, the wait hint paired with `errorCode:"usage.window_exhausted"`,
- * and `degraded`, the reduced-quality fact) is a real loss rather than a cosmetic one. The capability
- * fields (`checkpointToken` / `checkpointGate`) stay excluded on exactly the same reading — the
- * whitelist's reach is the reason their exclusion is worth anything.
+ * withholds it from all of them, which is why dropping a machine-actionable field (`retryAfterMs`,
+ * the wait hint paired with `errorCode:"usage.window_exhausted"`; `degraded`, the reduced-quality
+ * fact) is a real loss. The capability fields stay excluded on the same reading — the whitelist's
+ * reach is the reason their exclusion is worth anything.
  *
  * The card keeps `type:"agent"` (rather than minting a second word): CC models the Agent tool's output
  * as one union discriminated by `status`, and both sema cards already carry `status` —
  * `"async_launched"` for the receipt, the child's terminal status here. A consumer branches on it.
  *
  * Exported at MODULE level (not from the package index, same as `classifySubagentError`) so the leak
- * boundary can be pinned directly against a child result carrying a token — the `unexpected.suspended`
- * shape is reachable in production (a child running its own team/verify orchestration) but expensive to
- * stage end-to-end, and a pin that only ever sees an ordinary completed child cannot tell this
- * whitelist apart from a spread.
+ * boundary can be pinned against a child result carrying a token: the `unexpected.suspended` shape is
+ * reachable in production but expensive to stage, and a pin that only sees an ordinary completed
+ * child cannot tell this whitelist apart from a spread.
  */
 export declare function completedAgentCard(child: {
     taskId: string;
@@ -578,21 +570,19 @@ export interface SubagentToolOptions {
      * exists at all after the fact.** A SYNC or BACKGROUND child mints its session through
      * `runner.sessions`, never through the parent leg's store, so a deployment that mounts the Agent
      * tool on a DIFFERENT runner than the one serving root tasks has split the transcript lane away
-     * from the session lane. (The FORK lane is the deliberate exception and shows the split is a known
-     * shape: a fork branches the CALLER's session through `ctx.hostSessionFork` — the host Runner's
-     * own store — precisely because `runner` may be a split child-execution runner whose store never
-     * held the source. A fork child therefore follows the HOST store's fate, an ordinary child this
-     * runner's, and the same deployment can land one on disk and lose the other.) Three shapes for the
-     * ordinary lanes, all reachable and all silent:
+     * from the session lane. (The FORK lane is the deliberate exception: a fork branches the CALLER's
+     * session through `ctx.hostSessionFork` — the host Runner's own store — precisely because `runner`
+     * may be a split child-execution runner whose store never held the source. A fork child follows the
+     * HOST store's fate, an ordinary child this runner's, and one deployment can land one on disk and
+     * lose the other.) Three shapes for the ordinary lanes, all reachable and all silent:
      *  - durable store on THIS runner whose `release` PRESERVES history (`evict:"forget"`, the
      *    `FileStorageBackend` default), no {@link SubagentToolOptions.background}.`agentStore` — the
      *    child transcript lands UNPLACED and survives the settle leg's eager release (a cache drop),
      *    so post-hoc forensics work even though nothing can ADDRESS it through an `a*` handle. The
-     *    qualifier is load-bearing, not decorative: durability and release semantics are INDEPENDENT
-     *    declarations, and a store that declares itself durable while deleting on release
-     *    (`new FileStorageBackend({ evict: "delete" })`, or any custom store with the same policy)
-     *    destroys the transcript at settle — the settle leg calls `release`, and there is no placement
-     *    to make the deletion refuse. "Durable" is a statement about restarts, never about release;
+     *    qualifier is load-bearing: durability and release semantics are INDEPENDENT declarations, and
+     *    a store declaring itself durable while deleting on release destroys the transcript at settle —
+     *    the settle leg calls `release`, and no placement makes the deletion refuse. "Durable" is a
+     *    statement about restarts, never about release;
      *  - durable store + `agentStore` — the placed partition (see the mint gate in the background
      *    lane): addressable across a restart, list-excluded, joint-reaped with its row. This arm is
      *    also the one immune to the evict policy above (the settle leg keeps a confirmed row's
@@ -602,21 +592,19 @@ export interface SubagentToolOptions {
      *    reaches disk whatever the root leg's store is. Nothing in the engine compensates: the
      *    completion notification's recent steps and the in-memory registry are the only readers, and
      *    both die with the process.
-     * The asymmetry this produces is worth naming, because it reads as a bug from the outside: the
-     * `run_workflow` tool is mounted by the ENGINE on the run's own runner (prepare-task's
-     * `runnerSelf`), so a workflow node's child session always follows the ROOT store, while this tool
-     * is mounted by the DEPLOYMENT and follows whatever runner it was handed. One data root can
-     * therefore hold every workflow node's transcript and none of the Agent tool's.
-     * There is deliberately NO manifest field that answers "does a child transcript reach disk here":
+     * The asymmetry this produces reads as a bug from the outside: the `run_workflow` tool is mounted by
+     * the ENGINE on the run's own runner (prepare-task's `runnerSelf`), so a workflow node's child
+     * session always follows the ROOT store, while this tool is mounted by the DEPLOYMENT and follows
+     * whatever runner it was handed. One data root can hold every workflow node's transcript and none
+     * of the Agent tool's.
+     * There is deliberately NO manifest field answering "does a child transcript reach disk here":
      * `WiringManifest.fleet.subagentTranscripts` is the ADDRESSABILITY tier and folds to `"none"` on
-     * the absent-row-store arm before it ever looks at a session store, so it cannot separate the
-     * first shape above from the third (the landing pins carry that as an explicit arm). The facts
-     * that DO answer it are this runner's store's own declarations — `sessions.durability` and its
-     * release/evict policy — read together, which is why they are named here rather than folded into
-     * a word. Upstream anchor (CC 2.1.250): a sub-agent transcript is written unconditionally to
-     * its own file beside the parent session (`projects/<projectKey>/<sessionId>/subagents/agent-<id>
-     * .jsonl` + a `.meta.json` sidecar), so "the child conversation is readable afterwards" is a
-     * property CC never makes conditional on a store tier.
+     * the absent-row-store arm before it looks at a session store, so it cannot separate the first
+     * shape above from the third. What DOES answer it is this runner's store's own pair of
+     * declarations — `sessions.durability` and its release/evict policy — read together. Upstream
+     * (CC 2.1.250) writes a sub-agent transcript unconditionally to its own file beside the parent
+     * session, so "the child conversation is readable afterwards" is never conditional on a store
+     * tier there.
      */
     runner: RunnerSelfSeat;
     /**

package/dist/agents/tool-filter.d.ts

@@ -13,14 +13,12 @@ import type { ToolSpec } from "../core/types.js";
  * newly-added sensitive tool to every agent. Names not present in the pool are ignored (no error) — an
  * allow/deny list is a filter over what's available, not an assertion that those tools exist.
  *
- * anchor ruling (dual-leg verified, adversarially reviewed): this spawn-time item-level filter IS
- * the upstream shape for allow entries — CC's resolveAgentTools partitions unknown names into an
- * `invalidTools` bucket nobody consumes at runtime (88 readable source), and a live 2.1.207 probe shows
- * the agent stays listed/delegable with the unknown item silently dropped, zero warnings. The
- * "rejected at startup" posture this replaced had no verbatim anchor and did not survive verification.
- * The asymmetric prepare-time fail-loud for `TaskSpec.agents` DENY entries is a deliberate sema
- * extension (no upstream deny-list exists): an allow-typo silently narrows (safe direction), a
- * deny-typo silently widens (unacceptable) — each face follows its own failure direction.
+ * Anchored (dual-leg verified): this spawn-time item-level filter IS the upstream shape for allow
+ * entries — CC's resolveAgentTools partitions unknown names into an `invalidTools` bucket nobody
+ * consumes at runtime, and a live 2.1.207 probe shows the agent stays listed/delegable with the
+ * unknown item silently dropped, zero warnings. The asymmetric prepare-time fail-loud for
+ * `TaskSpec.agents` DENY entries is a deliberate sema extension (no upstream deny-list exists): an
+ * allow-typo silently narrows (safe direction), a deny-typo silently widens (unacceptable).
  *
  * Note: `"*"` in `allowTools` is the "allow all" sentinel, so a tool literally NAMED `"*"` cannot be
  * the sole allowed tool via this path (tool names are conventionally identifiers, so this is moot).
@@ -28,10 +26,10 @@ import type { ToolSpec } from "../core/types.js";
 /**
  * Membership check for ONE tool name under the same allow/deny semantics as {@link resolveToolSubset}
  * (canonicalized both sides; `"*"` allow sentinel; deny wins). Used by the delegation tool to decide
- * whether a chosen agent DEFINITION may re-delegate: a per-agent allow/deny that excludes the delegation
- * tool's own name suppresses the nested delegation tool (CC 2.1.198 parity — Explore/Plan
- * `disallowedTools` include Agent, pretty.js:409189/486948; CC filters the Agent tool like any other).
- * The TOOL-level allow/deny deliberately keeps its old semantics (delegation governed by `maxDepth`).
+ * whether a chosen agent DEFINITION may re-delegate: a per-agent allow/deny that excludes the
+ * delegation tool's own name suppresses the nested delegation tool (upstream parity — the built-in
+ * Explore/Plan denials include Agent, and the delegation tool is filtered like any other). The
+ * TOOL-level allow/deny keeps its own semantics (delegation governed by `maxDepth`).
  */
 export declare function toolNameAllowed(name: string, allowTools?: ReadonlyArray<string>, denyTools?: ReadonlyArray<string>): boolean;
 export declare function resolveToolSubset(pool: ReadonlyArray<ToolSpec>, allowTools?: ReadonlyArray<string>, denyTools?: ReadonlyArray<string>): ToolSpec[];