@inixiative/agent-session 0.11.1 → 0.12.1

package/README.md

@@ -2,7 +2,7 @@
 
 > Part of [inixiative](https://www.inixiative.com), technology for cooperation. See [all the projects](https://github.com/inixiative).
 
-Drive Claude Code, Codex and Muse as persistent streaming sessions behind one
+Drive Claude Code and Codex as persistent streaming sessions behind one
 interface. Claude Code runs over its CLI or the Agent SDK, Codex over its
 app-server and Muse over `muse serve`; Gemini and Grok are planned. The package
 also holds warm **primed decision sessions**, **subscription pools** with
@@ -51,7 +51,8 @@ session.kill();
   blocks in the same user message, Codex `image` inputs with a `data:` URL. Anything else is
   refused before a byte is written.
 - **fork / resume / interrupt** and pre-send hooks (rewrite the outgoing
-  message, for example to add context for that turn).
+  message, for example to add context for that turn). Resume is configuration, not a
+  method: build the session with `externalSessionId`.
 - **A resume whose native conversation is not found is typed.** Claude finding no transcript
   ("No conversation found with session ID": cleaned up, deleted, or under another project
   directory or config home) and Codex finding no rollout ("no rollout found for thread id") both
@@ -96,12 +97,13 @@ Codex runs only over `codex app-server --listen stdio://` (`CodexAppServerSessio
 Codex CLI 0.155 has no `mcp-server` subcommand.
 
 Muse Code runs over `muse serve` through Meta's `@muse-code/sdk` (`MuseSession`), pinned to
-the CLI's version (1.4.14): a host serving another version is refused at start. It bills the
+the CLI's version (1.4.20): a host serving another version is refused at start. It bills the
 saved Muse login: metered keys and endpoints never reach it (nor Muse's own tool runs, which
 inherit its environment: a repo command needing `OPENAI_API_KEY` will not see it under Muse),
 and a resumed session must be on provider `meta`. Per-login isolation is `env: { XDG_CONFIG_HOME, XDG_DATA_HOME }` (login and
-sessions). `musePermissions(mode)` maps the host modes to an explicit permission profile, because
-the host default lets Muse's AI reviewer answer approvals instead of the gates. Questions arrive
+sessions). The session's `permissionMode` (default `default`, gated) goes through `musePermissions(mode)`
+to an explicit permission profile, because the host default lets Muse's AI reviewer answer
+approvals instead of the gates. Questions arrive
 through `onUserInput()`; unanswered ones are cancelled with a reason. An approval offering
 no approve-once or reject choice is reported as an `error` event and left open (the turn ends
 at its timeout). Work Muse starts itself
@@ -125,7 +127,10 @@ session.onToolRequest(async (call) => {
 
 - `pre-use` (Claude only) runs before every call in every mode,
   `bypassPermissions` included; only a deny counts. A PreToolUse callback over
-  the control protocol; one the session cannot read is denied.
+  the control protocol; one the session cannot read is denied. An allow may
+  carry `updatedInput`: the call runs with that input (the next gate sees it as
+  `toolInput`), and the runtime's own mode still decides whether it runs.
+  Foundry uses it to add the chorus's brief to a subagent's prompt.
 - `permission` is an ask the runtime's mode raised; the answer is final (no gate:
   denied). Claude: `--permission-prompt-tool stdio`; `decisionReason` says why it
   asked, `agentId` marks a subagent's call. Codex app-server: command and
@@ -218,16 +223,23 @@ const result = await decisions.decide(spec, { input, standby });
   own subagents go to the tool gate untouched.
 - **Fresh per call.** Each member serves one decision. A used one is replaced
   at once; a role with no held spare starts a member with its input inline.
+- **Slices.** `dispatchers` (default 1) splits the roles into fixed slices,
+  each started by its own dispatcher, so refills are written at once. A
+  dispatcher writes one Agent call per member as output tokens: one
+  dispatcher refilled 75 members in ~20 s (2026-11-02). A role keeps its
+  slice while it is wanted; a new role joins the smallest.
 - **Recycle.** A dispatcher's context grows ~700 tokens per member started;
-  past `recycleTokens` (100k) a new generation takes over and the old one
-  ends into the root once empty.
+  past `recycleTokens` (100k) a new generation of its slice takes over and
+  the old one ends into the root once empty.
 - **Orphans.** A nested agent whose parent ended reports its own end to the
   main thread, which wakes the main model (Claude Code 2.1.300). Members of a
   dispatcher that ended unasked are therefore never retired or stopped, and an
   orphan's `answer` call is held for the session's life. Past `maxOrphans`
-  (40) the host stops serving and its caller falls back.
+  (40) `serving()` turns false and `setup` reports `degraded`; `decide()` does
+  not refuse on its own, so the caller checks `serving()` and falls back.
 - **Limits.** Claude Code runs 20 subagents at once by default; the launch
-  raises `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` (`maxSubagents`, 96). The
+  raises `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` to the user's own cap (20 when
+  unset) plus `maxSubagents` (76), so 96 by default. The
   session declares `perTaskStopAffordance`, so the user's Stop spares
   background agents.
 
@@ -243,9 +255,12 @@ const pool = new SubscriptionPool({ instances: [
 const { session, lease } = await pool.open({ runtime: "claude", model: "sonnet", organizationId: "org", preferredInstanceId: "work" });
 ```
 
-Routing is deterministic (quartile-balanced, owner-first or pinned) over
-observed limits, leases and health; stale or unknown limits exclude an instance
-and every exclusion has a reason. `continueOn` moves a thread only between
+Routing is deterministic over observed limits, priority, leases and health, by a
+named strategy (`quartile-balanced` by default, `owner-first`, `priority-balanced`,
+`priority-strict`, `least-used`) or an explicit term list; `pinned` restricts it to
+the preferred instance. By default stale or unknown limits exclude an instance
+(`unknownUtilization: 'rank-last'` ranks it last instead), and every exclusion has a
+reason. `continueOn` moves a thread only between
 instances that share native history, and says why when it cannot.
 
 ## Usage telemetry
@@ -263,6 +278,33 @@ model and tags) in `raw`; they may repeat across content blocks. Do not sum
 request snapshots together with result totals. Interrupted turns retain request
 snapshots in the artifact but do not fabricate a completed-turn total.
 
+## Secret scratch pad
+
+A person can hand an agent a secret as `$$word`. `SecretScratchPad(dir)` lifts it out
+of the message before the agent sees it (`lift`), into a private pad per thread
+(`<thread>.pad`, 0600 in a 0700 directory), and leaves a reference in its place:
+`†<message>.<n>` inside its thread, `†<thread>/<message>.<n>` from anywhere else.
+`lift(text, at, { patterns })` also lifts matches of the caller's global regexes, for
+tokens the person forgot to mark, and counts them as `recognised`.
+
+The agent uses a value without reading it. `env` sets `KEY=value` in an env file,
+`write` puts it in a file, and `pipe` runs a command with the value on its stdin,
+from a reference or a key already in an env file; only the exit code comes back, and
+a timeout kills the whole process group. `consume` (or `consume: true` on a use)
+removes a block, `list` shows what is pending without values, `scrub` swaps held
+values in text back to references, and `clear` deletes a pad.
+
+Files `env` and `write` touched are recorded (`heldFiles()`). `privatePathGate`
+(or `privatePathDenial` inside your own gate) denies a tool call naming one of them,
+a `.private` path, a `privatePaths` glob or the pad directory; `isOwnTool` exempts the
+scratch tool's own calls. A `privatePathGate` keeps the `heldFiles` list it was built
+with: rebuild it after `env` or `write`, or call
+`privatePathDenial(request, { scratchDir: pad.dir, heldFiles: pad.heldFiles() })` in your
+own gate on each request. `SECRET_SCRATCH_GUIDANCE` is the text to give the agent.
+The gate reads names, not contents, and a pipe command can still copy a value out:
+it keeps honest agents from reading secrets, it is not a sandbox. Design and
+limits: [tickets/AS-009](tickets/AS-009-secret-scratch-pad.md).
+
 ## Roadmap
 
 | Runtime | Status |
@@ -291,4 +333,4 @@ MIT
 
 ## Runtime
 
-Development and new continuation captures use Bun 1.4.2, pinned in `.bun-version` and `package.json`. Historical S0 recordings retain their original Bun 1.3.14 evidence; they are not new 1.4.2 captures.
+Development and new continuation captures use Bun 1.4.4, pinned in `.bun-version` and `package.json`. Historical S0 recordings retain their original Bun 1.3.14 evidence; they are not new 1.4.4 captures.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inixiative/agent-session",
-  "version": "0.11.1",
+  "version": "0.12.1",
   "description": "Drive coding-agent CLIs as persistent, streaming, event-captured sessions over interchangeable transports, with primed decision sessions, subscription pools, routing, limit polling and continuity.",
   "type": "module",
   "main": "src/index.ts",
@@ -18,6 +18,7 @@
     "check": "bun run typecheck && bun run lint && bun run test",
     "prepublishOnly": "bun run check",
     "measure:primed": "bun scripts/measure-primed.ts",
+    "record:muse": "bun scripts/record-muse.ts",
     "lint": "biome check .",
     "prepare": "if git rev-parse --git-dir >/dev/null 2>&1; then lefthook install; fi"
   },
@@ -36,12 +37,12 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@inixiative/json-rules": "^3.16.0",
-    "@muse-code/sdk": "1.4.14"
+    "@inixiative/json-rules": "^3.22.0",
+    "@muse-code/sdk": "1.4.20"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.2",
-    "@inixiative/config": "^0.5.186",
+    "@inixiative/config": "^0.5.212",
     "@types/bun": "1.4.4",
     "lefthook": "2.1.9",
     "typescript": "6.0.3"

package/src/claude-code-session.ts

@@ -1746,7 +1746,15 @@ export class ClaudeCodeSession implements HarnessSession {
               permissionDecisionReason: decision.message,
             },
           }
-        : {};
+        : decision?.updatedInput
+          ? // No permission decision: the call runs with the new input under the session's own mode.
+            {
+              hookSpecificOutput: {
+                hookEventName: 'PreToolUse',
+                updatedInput: structuredClone(decision.updatedInput),
+              },
+            }
+          : {};
     return decision?.behavior === 'allow'
       ? { behavior: 'allow', updatedInput: structuredClone(request.toolInput) }
       : { behavior: 'deny', message: decision?.message ?? 'Denied' };

package/src/claude-in-session.ts

@@ -19,9 +19,13 @@
 //              standby context matches answers that call with its input; the member answers
 //              through `answer`. A decision with no spare starts a member with its input inline.
 //              Each member serves one decision (fresh every call); a used one is started again.
+//   slices     the roles are split into `dispatchers` fixed slices, each started by its own
+//              dispatcher generation under the root, so their refills are written at once: a
+//              dispatcher writes one Agent call per member as output tokens, so one dispatcher for a
+//              large roster is slow to refill (75 members took ~20 s; 2026-11-02).
 //   recycle    a dispatcher's context grows with every member it starts. Past a bound the root
-//              starts a new generation; the old one's held spares are retired as their
-//              replacements hold, and it ends into the root once empty.
+//              starts a new generation of that slice; the old one's held spares are retired as
+//              their replacements hold, and it ends into the root once empty.
 //
 // Agent definitions are generic (no prompt of their own): every member's composed text rides in
 // its pinned prompt, so an edit reaches the next spare without relaunching the session.
@@ -98,6 +102,11 @@ export interface ClaudeInSessionConfig {
   setupDeadlineMs?: number;
   /** A dispatcher whose context passes this many tokens is replaced. Default 100k. */
   recycleTokens?: number;
+  /**
+   * Dispatchers running at once, each starting a fixed slice of the roles (a role keeps its slice
+   * while it is wanted; a new one joins the smallest). Default 1.
+   */
+  dispatchers?: number;
   /**
    * Subagents this host may run on top of the user's own concurrent-subagent cap
    * (`CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS`, 20 by default in Claude Code 2.1.300): the root, a
@@ -146,6 +155,8 @@ interface Starter {
   ended?: boolean;
   /** A dispatcher whose line went out to the root. */
   issued?: boolean;
+  /** A dispatcher's slice of the roles. */
+  slice?: number;
 }
 
 interface Member {
@@ -214,6 +225,7 @@ export class ClaudeInSessionDecisions implements PrimedSessions, ClaudeSessionEx
         | 'recycleTokens'
         | 'maxOrphans'
         | 'maxSetups'
+        | 'dispatchers'
       >
     >;
   private _host?: ClaudeSessionHost;
@@ -221,7 +233,12 @@ export class ClaudeInSessionDecisions implements PrimedSessions, ClaudeSessionEx
   private _seq = 0;
   private _generation = 0;
   private _root?: Starter;
-  private _gen?: Starter;
+  /** The current dispatcher generation of each slice. */
+  private _current: Array<Starter | undefined> = [];
+  /** Each wanted role's slice. */
+  private readonly _sliceOf = new Map<string, number>();
+  /** Direct members of roles outside every slice go out round-robin. */
+  private _nextDirect = 0;
   private readonly _gens = new Map<string, Starter>();
   private readonly _spares = new Map<string, Spare>();
   private readonly _members = new Set<Member>();
@@ -254,8 +271,14 @@ export class ClaudeInSessionDecisions implements PrimedSessions, ClaudeSessionEx
       recycleTokens: config.recycleTokens ?? 100_000,
       maxOrphans: config.maxOrphans ?? 40,
       maxSetups: config.maxSetups ?? 2,
+      dispatchers: config.dispatchers ?? 1,
     };
-    if (this._config.sparesPerRole < 1 || this._config.recycleTokens < 10_000)
+    if (
+      this._config.sparesPerRole < 1 ||
+      this._config.recycleTokens < 10_000 ||
+      !Number.isSafeInteger(this._config.dispatchers) ||
+      this._config.dispatchers < 1
+    )
       throw Error('Invalid in-session decision bounds');
     // On top of the user's own cap (Claude Code's default 20), so the main agent keeps its slots.
     const own = Number(process.env.CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS) || 20;
@@ -368,7 +391,8 @@ export class ClaudeInSessionDecisions implements PrimedSessions, ClaudeSessionEx
     }
     this._spares.clear();
     this._gens.clear();
-    this._root = this._gen = undefined;
+    this._root = undefined;
+    this._current = [];
   }
 
   mcp(_server: string, requestId: string, message: Record<string, unknown>): void {
@@ -591,7 +615,7 @@ export class ClaudeInSessionDecisions implements PrimedSessions, ClaudeSessionEx
         const waiting = this._awaitingSlot.shift();
         if (waiting) {
           this._reissue(waiting);
-          if (this._gen) this._feed(this._gen);
+          if (waiting.gen) this._feed(waiting.gen);
         }
       }
       return true;
@@ -621,10 +645,11 @@ export class ClaudeInSessionDecisions implements PrimedSessions, ClaudeSessionEx
         owner.context = add.input + add.cacheRead + add.cacheWrite;
         if (
           owner.kind === 'dispatch' &&
-          owner === this._gen &&
+          owner.slice !== undefined &&
+          owner === this._current[owner.slice] &&
           owner.context > this._config.recycleTokens
         )
-          this._recycle();
+          this._recycle(owner.slice);
       } else {
         const target = owner.member?.deliveredAt ? owner.usage : owner.standby;
         for (const key of Object.keys(add) as Array<keyof Usage>) target[key] += add[key];
@@ -740,6 +765,7 @@ export class ClaudeInSessionDecisions implements PrimedSessions, ClaudeSessionEx
         ];
       }),
     );
+    this._assignSlices();
     for (const spare of this._spares.values())
       if (
         !spare.direct &&
@@ -864,7 +890,8 @@ export class ClaudeInSessionDecisions implements PrimedSessions, ClaudeSessionEx
       lines: [],
       context: 0,
     };
-    this._newGeneration();
+    this._current = [];
+    for (let slice = 0; slice < this._config.dispatchers; slice++) this._newGeneration(slice);
     clearTimeout(this._setupTimer);
     this._setupTimer = setTimeout(() => {
       if (this._setup.status === 'starting') this._publishSetup('degraded');
@@ -891,25 +918,37 @@ export class ClaudeInSessionDecisions implements PrimedSessions, ClaudeSessionEx
       [...this._spares.values()].filter((s) => s.held && !s.done && !s.retired).map((s) => s.name),
     );
     const all = [...this._desired.keys()].every((name) => held.has(name));
-    if (this._rostered && all && this._gen?.next) {
+    // Every slice's dispatcher has taken its lines (it waits in `next` again).
+    const dispatching = this._current.length > 0 && this._current.every((gen) => !!gen?.next);
+    if (this._rostered && all && dispatching) {
       clearTimeout(this._setupTimer);
       this._publishSetup('ready');
     } else this._publishSetup('starting');
   }
 
-  private _newGeneration(): Starter {
+  private _newGeneration(slice: number): Starter {
     const token = `g${++this._generation}`;
-    const gen: Starter = { token, kind: 'dispatch', prompt: STARTER(token), lines: [], context: 0 };
+    const gen: Starter = {
+      token,
+      kind: 'dispatch',
+      prompt: STARTER(token),
+      lines: [],
+      context: 0,
+      slice,
+    };
     this._gens.set(token, gen);
-    this._gen = gen;
+    this._current[slice] = gen;
     this._root!.lines.push(`${IN_SESSION_AGENTS.dispatch} ${token}`);
     this._feed(this._root!);
     return gen;
   }
 
-  /** A dispatcher past its bound: a new generation takes new spares; the old one's are retired as replacements hold. */
-  private _recycle(): void {
-    const old = this._gen;
+  /**
+   * A slice's dispatcher past its bound: a new generation of that slice takes new spares; the old
+   * one's are retired as replacements hold.
+   */
+  private _recycle(slice: number): void {
+    const old = this._current[slice];
     if (!old || old.stopping || !this._root?.taskId) return;
     old.stopping = true;
     this._emit({
@@ -919,11 +958,33 @@ export class ClaudeInSessionDecisions implements PrimedSessions, ClaudeSessionEx
     });
     for (const spare of this._spares.values())
       if (spare.gen === old && !spare.member && !spare.done) spare.superseded = true;
-    this._newGeneration();
+    this._newGeneration(slice);
     this._replenish();
     this._endIfEmpty(old);
   }
 
+  /** Keep every wanted role in a slice: a role keeps its slice; a new one joins the smallest. */
+  private _assignSlices(): void {
+    for (const name of [...this._sliceOf.keys()])
+      if (!this._desired.has(name)) this._sliceOf.delete(name);
+    const sizes = Array.from({ length: this._config.dispatchers }, () => 0);
+    for (const slice of this._sliceOf.values()) sizes[slice]!++;
+    for (const name of this._desired.keys()) {
+      if (this._sliceOf.has(name)) continue;
+      const slice = sizes.indexOf(Math.min(...sizes));
+      this._sliceOf.set(name, slice);
+      sizes[slice]!++;
+    }
+  }
+
+  /** The dispatcher that starts this role's members now: its slice's, or round-robin for a role in none. */
+  private _genFor(name: string): Starter | undefined {
+    const slice = this._sliceOf.get(name);
+    if (slice !== undefined) return this._current[slice];
+    const live = this._current.filter((gen): gen is Starter => !!gen && !gen.stopping);
+    return live.length ? live[this._nextDirect++ % live.length] : undefined;
+  }
+
   /** Answer a starter's held `next` with what it should start (or stop). */
   private _feed(starter: Starter): void {
     if (!starter.next) return;
@@ -1007,16 +1068,19 @@ export class ClaudeInSessionDecisions implements PrimedSessions, ClaudeSessionEx
     return best;
   }
 
-  /** Keep `sparesPerRole` free spares of every desired role, in the current generation. */
+  /** Keep `sparesPerRole` free spares of every desired role, in its slice's current generation. */
   private _replenish(): void {
-    const gen = this._gen;
-    if (this._closed || !gen || gen.stopping) return;
+    if (this._closed) return;
     const free = new Map<string, number>();
     for (const spare of this._spares.values())
       if (!spare.direct && !spare.member && !spare.done && !spare.superseded && !spare.retired)
         if (this._desired.get(spare.name)?.standbyHash === spare.standbyHash)
           free.set(spare.name, (free.get(spare.name) ?? 0) + 1);
-    for (const [name, desired] of this._desired)
+    const fed = new Set<Starter>();
+    for (const [name, desired] of this._desired) {
+      const gen = this._genFor(name);
+      if (!gen || gen.stopping) continue;
+      fed.add(gen);
       for (let n = free.get(name) ?? 0; n < this._config.sparesPerRole; n++) {
         const token = `w${++this._seq}`;
         this._spares.set(token, {
@@ -1032,7 +1096,8 @@ export class ClaudeInSessionDecisions implements PrimedSessions, ClaudeSessionEx
         });
         gen.lines.push(`${IN_SESSION_AGENTS.member} ${token}`);
       }
-    this._feed(gen);
+    }
+    for (const gen of fed) this._feed(gen);
   }
 
   /** A spare's replacement holds: retire one superseded spare of the same role. */
@@ -1144,8 +1209,8 @@ export class ClaudeInSessionDecisions implements PrimedSessions, ClaudeSessionEx
   /** A decision with no spare: a member started with its whole input. */
   private async _direct(member: Member, composed: string): Promise<void> {
     if (!(await this._admit(member))) return;
-    const gen = this._gen;
-    if (!gen) {
+    const gen = this._genFor(member.name);
+    if (!gen || gen.stopping) {
       member.reject(
         new DecisionError(
           'No dispatcher running',
@@ -1230,7 +1295,7 @@ export class ClaudeInSessionDecisions implements PrimedSessions, ClaudeSessionEx
         if (this._closed) return;
         const orphaned = [...this._spares.values()].filter((sp) => !sp.done);
         this._gens.clear();
-        this._gen = undefined;
+        this._current = [];
         this._root = undefined;
         this._publishSetup('degraded');
         this._startSetup();
@@ -1241,7 +1306,13 @@ export class ClaudeInSessionDecisions implements PrimedSessions, ClaudeSessionEx
       // Its members outlive it (nested background agents are not stopped with their parent).
       this._gens.delete(owner.token);
       const planned = owner.stopping && this._empty(owner);
-      if (owner === this._gen && !this._closed) this._newGeneration();
+      if (
+        owner.slice !== undefined &&
+        owner === this._current[owner.slice] &&
+        !this._closed &&
+        this._root
+      )
+        this._newGeneration(owner.slice);
       if (!planned && !this._closed)
         for (const spare of this._spares.values())
           if (spare.gen === owner && !spare.done) this._orphan(spare);
@@ -1293,8 +1364,8 @@ export class ClaudeInSessionDecisions implements PrimedSessions, ClaudeSessionEx
   }
 
   private _reissue(spare: Spare): void {
-    const gen = this._gen;
-    if (this._closed || !gen || spare.done) return;
+    const gen = this._genFor(spare.name);
+    if (this._closed || !gen || gen.stopping || spare.done) return;
     spare.gen = gen;
     spare.issued = false;
     const line = `${IN_SESSION_AGENTS.member} ${spare.token}`;

package/src/harness-session.ts

@@ -399,7 +399,15 @@ export interface ToolRequest {
   readonly signal?: AbortSignal;
 }
 export type ToolDecision =
-  | { readonly behavior: 'allow' }
+  | {
+      readonly behavior: 'allow';
+      /**
+       * `pre-use` only (Claude): the input the call runs with instead of the one the model wrote
+       * (e.g. a subagent's prompt with context appended). The runtime's own mode still decides
+       * whether the call runs. Later gates see it as their `toolInput`.
+       */
+      readonly updatedInput?: Readonly<Record<string, unknown>>;
+    }
   | { readonly behavior: 'deny'; readonly message: string };
 /** Gates compose in registration order: the first deny wins; a thrown or rejected gate denies. */
 export type ToolGate = (request: ToolRequest) => ToolDecision | Promise<ToolDecision>;

package/src/muse-session.ts

@@ -40,17 +40,18 @@ import { TurnState } from './turn-state';
 // ---------------------------------------------------------------------------
 // MuseSession — one `muse serve` host per session, driven through Meta's
 // `@muse-code/sdk` MuseClient (Muse Session Protocol). The facade opens the
-// session, submits turns, answers approvals and folds the view; the calls it
-// lacks (turn/interrupt, turn/steer, session/fork, session/setApprovalMode,
-// usage/read, userInput/cancel) go through the same connection's `command`.
+// session, submits turns, answers approvals and folds the view. turn/interrupt,
+// turn/steer, session/fork, session/setApprovalMode, usage/read and
+// userInput/cancel go through the same connection's `command`, written before
+// the facade had them (1.4.14) and kept on the raw wire, whose types 1.4.20 keeps.
 // Every view notification is classified into the shared SessionEvent taxonomy.
 // The Muse session id is the externalSessionId used for cold resume.
 //
-// Wire contract: Muse Code 1.4.14 / @muse-code/sdk 1.4.14 (lockstep).
+// Wire contract: Muse Code 1.4.20 / @muse-code/sdk 1.4.20 (lockstep).
 // ---------------------------------------------------------------------------
 
 /** The SDK version this session is built against; the served CLI must report the same. */
-export const MUSE_SDK_VERSION = '1.4.14';
+export const MUSE_SDK_VERSION = '1.4.20';
 
 export type MuseApprovalMode = 'allowAll' | 'promptUnmatched';
 export type MusePermissionProfile = ':ask-me' | ':read-only' | ':unrestricted';
@@ -226,13 +227,15 @@ const CLIENT_INFO = { name: 'agent_session', title: 'agent-session', version: '1
 
 /**
  * Inherited variables that would bill, route or loosen Muse away from its saved subscription login
- * and the gates, by the names the 1.4.14 binary reads: metered keys and endpoints (META_, LLM_,
+ * and the gates, by the names the 1.4.20 binary reads: metered keys and endpoints (META_, LLM_,
  * MODEL_, LLAMA_, OPENROUTER_, ANTHROPIC_, OPENAI_), Meta's auth and key-mint endpoints, and MUSE_
- * switches for the model, experiments, contributor mode, the approval judge and a fail-open
- * profile. Muse's own tool runs inherit this environment, so they do not see these either.
+ * switches for the model, experiments, contributor mode, the approval judge, a fail-open profile,
+ * request routing and custom headers, the computer-use dev policy and identity skip, the launcher's
+ * channel and install switches, the credential backend, and the eval and test hooks (prompt injection,
+ * policy and grant overrides). The CA and TLS roots stay: a machine behind a proxy needs them. Muse's own tool runs inherit this environment, so they do not see these either.
  */
 const COMPETING_ENV =
-  /^(META_|LLM_|MODEL_|LLAMA_|OPENROUTER_|ANTHROPIC_|OPENAI_|TBH_(AUTH|MINT)_BASE_URL$|MUSE_EXPERIMENTAL_|MUSE_(MODEL|CONTRIBUTOR_MODE|DISABLE_APPROVAL_JUDGE|PERMISSION_PROFILE_FAIL_OPEN)$)/;
+  /^(META_|LLM_|MODEL_|LLAMA_|OPENROUTER_|ANTHROPIC_|OPENAI_|TBH_(AUTH|MINT)_BASE_URL$|MUSE_EXPERIMENTAL_|TBH_(CREDENTIAL_BACKEND$|EVAL_|TEST_)|MUSE_CUA_DEV_|MUSE_(MODEL|CHANNEL|LAUNCHER_INSTALL|CONTRIBUTOR_MODE|DISABLE_APPROVAL_JUDGE|PERMISSION_PROFILE_FAIL_OPEN|WWW_ROUTING|CUSTOM_HEADERS)$)/;
 
 export class MuseSession implements HarnessSession {
   get transport() {
@@ -1914,10 +1917,10 @@ export class MuseSession implements HarnessSession {
 }
 
 // ---------------------------------------------------------------------------
-// Default host: `muse serve` through the SDK's owned-process handshake
+// Default host: `muse serve` through the SDK's owned-process handshake; exported for scripts/record-muse.ts
 // ---------------------------------------------------------------------------
 
-async function spawnMuseHost(launch: MuseLaunch): Promise<MuseHost> {
+export async function spawnMuseHost(launch: MuseLaunch): Promise<MuseHost> {
   const handshake = spawnMspConnection({
     command: launch.museBin,
     args: launch.args,

package/src/tool-gate.ts

@@ -25,17 +25,22 @@ export class ToolGates {
     return [...this._gates];
   }
 
-  /** Never rejects. Undefined means no decision: only a `pre-use` request without a deny. */
+  /**
+   * Never rejects. Undefined means no decision: only a `pre-use` request without a deny or a new
+   * input. A gate's `updatedInput` (pre-use) is the next gate's `toolInput` and the decision's.
+   */
   async decide(request: ToolRequest): Promise<ToolDecision | undefined> {
     const gates = [...this._gates];
     if (!gates.length)
       return request.stage === 'permission'
         ? { behavior: 'deny', message: 'No approval handler' }
         : undefined;
+    let current = request;
+    let updatedInput: Readonly<Record<string, unknown>> | undefined;
     for (const gate of gates) {
       let decision: ToolDecision;
       try {
-        decision = await gate(request);
+        decision = await gate(current);
       } catch (error) {
         return {
           behavior: 'deny',
@@ -46,8 +51,19 @@ export class ToolGates {
         return { behavior: 'deny', message: String(decision.message ?? 'Denied') };
       if (decision?.behavior !== 'allow')
         return { behavior: 'deny', message: 'Tool gate failed: malformed decision' };
+      if (decision.updatedInput !== undefined && request.stage === 'pre-use') {
+        if (
+          !decision.updatedInput ||
+          typeof decision.updatedInput !== 'object' ||
+          Array.isArray(decision.updatedInput)
+        )
+          return { behavior: 'deny', message: 'Tool gate failed: malformed updatedInput' };
+        updatedInput = Object.freeze(structuredClone(decision.updatedInput));
+        current = { ...current, toolInput: updatedInput };
+      }
     }
-    return request.stage === 'permission' ? { behavior: 'allow' } : undefined;
+    if (request.stage === 'permission') return { behavior: 'allow' };
+    return updatedInput ? { behavior: 'allow', updatedInput } : undefined;
   }
 }
 

package/src/transport.ts

@@ -143,12 +143,12 @@ export const TRANSPORTS: Readonly<Record<TransportKind, TransportDescriptor>> =
     },
     notes: [
       "`muse serve --trust-workspace` (plus `--disable-sandbox` under bypassPermissions) driven through Meta's `@muse-code/sdk` MuseClient, pinned to the installed CLI's version.",
-      'Billing is the saved Muse Code login: metered keys and endpoints (META_, LLM_, MODEL_, LLAMA_, OPENROUTER_, ANTHROPIC_, OPENAI_), Meta auth endpoints (TBH_) and the MUSE_ model, experiment, contributor, approval-judge and fail-open switches are removed from the child environment; a resumed or forked session must report provider `meta`.',
+      'Billing is the saved Muse Code login: metered keys and endpoints (META_, LLM_, MODEL_, LLAMA_, OPENROUTER_, ANTHROPIC_, OPENAI_), Meta auth endpoints (TBH_) and the MUSE_ model, experiment, contributor, approval-judge, fail-open, routing, custom-header, computer-use dev, channel and install switches, and the TBH_ credential backend and eval/test hooks are removed from the child environment; a resumed or forked session must report provider `meta`.',
       'Approvals use an explicit permission profile (`:ask-me` supervised, `:read-only` plan, `:unrestricted` bypass), never the host default `:auto-review`, whose AI reviewer would decide instead of the gates; the committed profile, approval mode and (gated) a human reviewer are read back before any turn.',
       "Work Muse starts itself (cron firings, monitor and background-terminal wakes, goals, reminder agents, workflows, another client's messages) is folded like a turn's and emitted with `unattributedReason: 'task'`, plus a `task` lifecycle typed `muse-cron`, `muse-monitor`, `muse-goal`, `muse-reminder`, `muse-workflow` or `muse-turn`; it is seen only while this host has the session loaded.",
       "interruptNative() sends turn/interrupt; push() sends turn/steer; fork() runs session/fork on the new session's own host; readLimits() sends usage/read.",
       'userInput/request questions go to onUserInput(); without an answer they are cancelled with a reason, so a turn never waits on them.',
-      'Live-verified (muse 1.4.14): start, profile read-back, multi-stage shell and network approvals, text and tool events, token usage, usage/changed and usage/read (recorded in fixtures/muse); fork, resume with setApprovalMode and sessionNotFound were checked live without a model turn (not recorded). A steer (`turn/steer` into a running shell turn, answered in that turn) was checked live 2026-11-02 (not recorded). Images, interrupt, questions and Muse-initiated turns follow the SDK wire types without a live run.',
+      'Live-verified (muse 1.4.20, 2026-11-15): start, profile read-back, multi-stage shell and network approvals, text and tool events, token usage, usage/changed and usage/read (recorded in fixtures/muse); fork, resume with setApprovalMode and sessionNotFound were checked live on 1.4.14 without a model turn (not recorded). A steer (`turn/steer` into a running shell turn, answered in that turn) and an interrupt (`turn/interrupt`, terminal `cancelled`) were checked live on 1.4.20, 2026-11-15 (not recorded). Images, questions and Muse-initiated turns follow the SDK wire types without a live run.',
     ],
   },
   'claude-agent-sdk': {