@inixiative/agent-session 0.8.0 → 0.10.0

package/README.md

@@ -84,7 +84,7 @@ const session = createSession(kind, { cwd, model: "gpt-6-luna", env: { CODEX_HOM
 | Status | ✅ live | ✅ live | ✅ live | ✅ live | stub | stub |
 | Resume / fork | native / native | native / – | native / native | native / native | – | – |
 | Interrupt | acknowledged | acknowledged | acknowledged | acknowledged | – | – |
-| Push | – | steer | steer | – | – | – |
+| Push | steer | steer | steer | – | – | – |
 | Approvals | callback | callback | callback | callback | – | – |
 | Limits stream / poll | ✅ / ✅ | ✅ / ✅ | ✅ / ✅ | ✅ / – | – | – |
 | Primed reset | fork | fork | – | – | – | – |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inixiative/agent-session",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "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",
@@ -41,7 +41,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.2",
-    "@inixiative/config": "^0.5.173",
+    "@inixiative/config": "^0.5.183",
     "@types/bun": "1.4.4",
     "lefthook": "2.1.9",
     "typescript": "6.0.3"

package/src/claude-agent-sdk-session.ts

@@ -23,6 +23,7 @@ import {
   type ClaudeCodeSessionConfig,
   type PipedSubprocess,
 } from './claude-code-session';
+import type { PushOutcome } from './harness-session';
 import { TRANSPORTS } from './transport';
 
 /** The subset of the SDK's Query this transport uses. */
@@ -429,6 +430,16 @@ export class ClaudeAgentSdkSession extends ClaudeCodeSession {
     this._sdk = config;
   }
 
+  /**
+   * Not wired here: the bridge forwards a steer's `priority` to the SDK's input, but whether the SDK
+   * stream surfaces the `command_lifecycle` frames a steer is tracked by has not been verified.
+   */
+  override async push(payload: { kind: string; text: string }): Promise<PushOutcome> {
+    const reason = 'the Agent SDK transport does not steer (not verified)';
+    this._emitPushIgnored(payload.kind, reason);
+    return { outcome: 'ignored', reason };
+  }
+
   /** get_usage is not reachable through the SDK Query API. */
   override async readLimits(): Promise<never> {
     throw Error(

package/src/claude-code-session.ts

@@ -51,6 +51,7 @@ import type {
   BeforeSendHook,
   HarnessSession,
   NativeInterruptOutcome,
+  PushOutcome,
   SessionArtifact,
   SessionEvent,
   SessionEventHandler,
@@ -218,8 +219,40 @@ interface QueuedTurn {
   timeout: number;
   resolve: (result: SessionResult) => void;
   reject: (error: Error) => void;
+  /**
+   * Messages push() wrote into this turn, by uuid, with their `command_lifecycle` state. One not yet
+   * `started` when a result arrives is answered after it, in a follow-on result of the same turn.
+   */
+  steers?: Map<string, SteerState>;
+  /** The turn reached a result while a steer was still waiting: it settles on the next result. */
+  held?: { nativeOutcome: 'completed'; tokens?: SessionTokens };
 }
 
+/** `written` until the CLI's `command_lifecycle` names it; `unconfirmed` after push() gave up waiting. */
+type SteerState = 'written' | 'queued' | 'started' | 'completed' | 'cancelled' | 'unconfirmed';
+const STEER_ACK_MS = 10_000;
+
+const TOKEN_KEYS = [
+  'input',
+  'output',
+  'cacheRead',
+  'cacheWrite',
+  'cacheWrite5m',
+  'cacheWrite1h',
+  'thinking',
+] as const;
+/** One turn's usage over several results (a steer answered after a result). Provider usage is the last result's. */
+const addTokens = (
+  a: SessionTokens | undefined,
+  b: SessionTokens | undefined,
+): SessionTokens | undefined => {
+  if (!a || !b) return b ?? a;
+  const sum: SessionTokens = { ...b };
+  for (const key of TOKEN_KEYS)
+    if (a[key] !== undefined || b[key] !== undefined) sum[key] = (a[key] ?? 0) + (b[key] ?? 0);
+  return sum;
+};
+
 // ---------------------------------------------------------------------------
 // Session
 // ---------------------------------------------------------------------------
@@ -342,6 +375,10 @@ export class ClaudeCodeSession implements HarnessSession {
   private _agentsDir?: string;
   /** Inbound control requests awaiting a gate decision, by request id. */
   private _inbound = new Map<string, AbortController>();
+  /** push() calls waiting for the CLI to name their message, by uuid. */
+  private _steerAcks = new Map<string, (state: SteerState) => void>();
+  /** Steers written and not yet ended natively: a late `completed` after their turn settled is theirs. */
+  private _steerUuids = new Set<string>();
   private readonly _hookCallbackId = `agent-session-pre-tool-${crypto.randomUUID()}`;
   private _limits?: LimitSnapshot;
   private _controlSeq = 0;
@@ -501,23 +538,128 @@ export class ClaudeCodeSession implements HarnessSession {
   }
 
   /**
-   * Mid-turn push. Claude Code's stream-json stdin accepts user messages
-   * only; there is no dedicated out-of-band signal channel. So the current
-   * behavior is to emit a "push_ignored" error event — callers observe it
-   * but the model does not see the payload until the next turn.
-   *
-   * A future improvement: push via the MCP bridge (FLOW.md Loop 4) so the
-   * signal reaches the in-flight turn as a tool result the model must read.
+   * Mid-turn steer: a stream-json user message with `priority: "next"` and its own `uuid`, written
+   * while the owned turn runs. The CLI answers `command_lifecycle` queued → started → completed for
+   * that uuid. It takes the message in at the turn's next model request (after a tool result), or,
+   * when the turn's reply was already final, runs it right after that result as a follow-on result:
+   * either way it is this turn's, and send() settles on the last result (validated against claude
+   * 2.1.316, fixtures/s0/claude-steer-*.jsonl).
    */
-  async push(payload: { kind: string; text: string }): Promise<void> {
+  async push(payload: { kind: string; text: string }): Promise<PushOutcome> {
+    const ignored = (reason: string): PushOutcome => {
+      this._emitPushIgnored(payload.kind, reason);
+      return { outcome: 'ignored', reason };
+    };
+    const turn = this._inflight;
+    const a = turn?.evidence;
+    if (!turn || !a || a.dispatch !== 'attempted' || a.nativeOutcome !== 'unknown')
+      return ignored('no owned in-flight turn');
+    if (!this._proc || !this._alive) return ignored('session not running');
+    const uuid = crypto.randomUUID();
+    turn.steers ??= new Map();
+    const steers = turn.steers;
+    steers.set(uuid, 'written');
+    this._steerUuids.add(uuid);
+    const acknowledged = new Promise<SteerState>((resolve) => this._steerAcks.set(uuid, resolve));
+    try {
+      this._proc.stdin.write(
+        `${JSON.stringify({
+          type: 'user',
+          message: { role: 'user', content: [{ type: 'text', text: payload.text }] },
+          uuid,
+          parent_tool_use_id: null,
+          priority: 'next',
+        })}\n`,
+      );
+      this._proc.stdin.flush();
+    } catch (error) {
+      steers.delete(uuid);
+      this._steerAcks.delete(uuid);
+      return ignored(`write failed: ${(error as Error).message.slice(0, 200)}`);
+    }
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const state = await Promise.race([
+      acknowledged,
+      new Promise<'unconfirmed'>((resolve) => {
+        timer = setTimeout(() => resolve('unconfirmed'), STEER_ACK_MS);
+      }),
+    ]).finally(() => clearTimeout(timer));
+    this._steerAcks.delete(uuid);
+    const identity = { ...a.identity, admissionId: a.admissionId };
+    if (state === 'cancelled')
+      return ignored('the runtime cancelled it before the turn took it in');
+    if (state === 'unconfirmed') {
+      // Never named by the CLI: it no longer holds the turn open.
+      if (steers.get(uuid) === 'written') steers.set(uuid, 'unconfirmed');
+      this._releaseHeld(turn);
+      this._emit({
+        ...identity,
+        kind: 'native_status',
+        timestamp: Date.now(),
+        raw: { type: 'push-unknown', kind: payload.kind },
+      });
+      return { outcome: 'unknown' };
+    }
+    this._emit({
+      ...identity,
+      kind: 'native_status',
+      timestamp: Date.now(),
+      raw: { type: 'push-steered', kind: payload.kind, uuid },
+    });
+    return { outcome: 'steered' };
+  }
+
+  protected _emitPushIgnored(kind: string, reason: string): void {
     this._emit({
       kind: 'error',
       timestamp: Date.now(),
-      text: `push_ignored: kind=${payload.kind} — stream-json stdin has no OOB channel`,
-      raw: payload,
+      text: `push_ignored: kind=${kind} — ${reason}`,
+      raw: { kind },
     });
   }
 
+  /** A steer of `turn` the CLI has not started yet (or not named yet). */
+  private _steerWaiting(turn: QueuedTurn): boolean {
+    for (const state of turn.steers?.values() ?? [])
+      if (state === 'written' || state === 'queued') return true;
+    return false;
+  }
+
+  /**
+   * A held turn settles with the result it already had once no steer can still produce a result:
+   * none waiting, and none started (a started steer of a held turn is its follow-on run).
+   */
+  private _releaseHeld(turn: QueuedTurn): void {
+    if (!turn.held || this._inflight !== turn || this._steerWaiting(turn)) return;
+    for (const state of turn.steers?.values() ?? []) if (state === 'started') return;
+    const a = turn.evidence;
+    a.tokens = turn.held.tokens;
+    a.nativeOutcome = turn.held.nativeOutcome;
+    turn.held = undefined;
+    this._resolveTurn();
+  }
+
+  /** Withdraw `turn`'s steers the CLI has not started, so none outlives it as an unowned turn. */
+  private async _withdrawSteers(turn: QueuedTurn, timeoutMs: number): Promise<void> {
+    const waiting = [...(turn.steers ?? [])].filter(
+      ([, state]) => state === 'queued' || state === 'written',
+    );
+    await Promise.all(
+      waiting.map(([uuid]) =>
+        this._controlRequest(
+          { subtype: 'cancel_async_message', message_uuid: uuid },
+          timeoutMs,
+        ).then(
+          (response) => {
+            if ((response.response as { cancelled?: unknown } | undefined)?.cancelled === true)
+              turn.steers?.set(uuid, 'cancelled');
+          },
+          () => {},
+        ),
+      ),
+    );
+  }
+
   // ---------------------------------------------------------------------------
   // start() — spawn the persistent process
   // ---------------------------------------------------------------------------
@@ -822,6 +964,10 @@ export class ClaudeCodeSession implements HarnessSession {
     if (turn?.evidence.dispatch !== 'attempted' || turn.evidence.nativeOutcome !== 'unknown')
       return 'no-turn';
     const deadline = Date.now() + (opts?.timeoutMs ?? 5_000);
+    // A stop is for the whole turn: a steer still waiting dies with it, never runs after it.
+    await this._withdrawSteers(turn, Math.max(1, Math.min(2_000, deadline - Date.now())));
+    this._releaseHeld(turn);
+    if (turn.evidence.nativeOutcome !== 'unknown') return 'acknowledged';
     try {
       await this._controlRequest({ subtype: 'interrupt' }, Math.max(1, deadline - Date.now()));
     } catch {
@@ -1278,6 +1424,30 @@ export class ClaudeCodeSession implements HarnessSession {
       return;
     }
 
+    // A steer's lifecycle: the CLI naming a message push() wrote into the owned turn.
+    if (raw.type === 'command_lifecycle' && typeof raw.command_uuid === 'string') {
+      const turn = this._inflight;
+      const state = raw.state;
+      const ours = this._steerUuids.has(raw.command_uuid);
+      if (ours && (state === 'completed' || state === 'cancelled'))
+        this._steerUuids.delete(raw.command_uuid);
+      if (
+        turn?.steers?.has(raw.command_uuid) &&
+        (state === 'queued' ||
+          state === 'started' ||
+          state === 'completed' ||
+          state === 'cancelled')
+      ) {
+        turn.steers.set(raw.command_uuid, state);
+        this._steerAcks.get(raw.command_uuid)?.(state);
+        if (state === 'cancelled') this._releaseHeld(turn);
+        return;
+      }
+      // A steer's own end after its turn settled (its follow-on result settled the turn first).
+      if (!ours) this._unattributed(raw, 'no-admission');
+      return;
+    }
+
     // Account limits are account-level evidence, never part of an admission's output.
     if (raw.type === 'rate_limit_event') {
       const snapshot = claudeRateLimitSnapshot(raw.rate_limit_info);
@@ -1353,6 +1523,7 @@ export class ClaudeCodeSession implements HarnessSession {
       correlation: 'ordered-stream',
     };
     const terminal = raw.type === 'result';
+    let holding = false;
     if (terminal) {
       if (terminalKey) this._seenTerminals.add(terminalKey);
       const subtype = typeof raw.subtype === 'string' ? raw.subtype : undefined;
@@ -1369,6 +1540,12 @@ export class ClaudeCodeSession implements HarnessSession {
         (status !== undefined && status >= 400) ||
         reason === 'api_error';
       a.nativeOutcome = failed ? 'failed' : subtype === 'success' ? 'completed' : 'unknown';
+      // A steer the CLI has not started yet runs after this result, still in this turn: the turn
+      // stays open (and this result reads as an intermediate one) until the steer's own result.
+      if (a.nativeOutcome === 'completed' && this._steerWaiting(turn)) {
+        holding = true;
+        a.nativeOutcome = 'unknown';
+      }
       a.terminal = {
         type: 'result',
         eventId: terminalKey,
@@ -1405,6 +1582,16 @@ export class ClaudeCodeSession implements HarnessSession {
       this._emit(e);
     }
     if (terminal) {
+      // Each result reports its own run's usage: the turn's is their sum.
+      const tokens = addTokens(turn.held?.tokens, a.tokens);
+      if (holding) {
+        turn.held = { nativeOutcome: 'completed', ...(tokens ? { tokens } : {}) };
+        a.tokens = tokens;
+        return;
+      }
+      turn.held = undefined;
+      a.tokens = tokens;
+      if (a.nativeOutcome === 'failed') void this._withdrawSteers(turn, 2_000);
       if (a.nativeOutcome !== 'unknown') this._resolveTurn();
       else
         this._rejectInflight(

package/src/codex-session.ts

@@ -20,6 +20,7 @@ import type {
   BeforeSendHook,
   HarnessSession,
   NativeInterruptOutcome,
+  PushOutcome,
   SessionArtifact,
   SessionEvent,
   SessionEventHandler,
@@ -886,15 +887,17 @@ export class CodexAppServerSession implements HarnessSession {
   }
 
   /** Mid-turn steer (turn/steer) into the owned in-flight turn; otherwise records push_ignored. */
-  async push(payload: { kind: string; text: string }): Promise<void> {
+  async push(payload: { kind: string; text: string }): Promise<PushOutcome> {
     const a = this._inflight?.evidence;
-    const ignored = (reason: string) =>
+    const ignored = (reason: string): PushOutcome => {
       this._emit({
         kind: 'error',
         timestamp: Date.now(),
         text: `push_ignored: kind=${payload.kind} — ${reason}`,
         raw: { kind: payload.kind },
       });
+      return { outcome: 'ignored', reason };
+    };
     if (
       a?.dispatch !== 'attempted' ||
       a.nativeOutcome !== 'unknown' ||
@@ -925,17 +928,19 @@ export class CodexAppServerSession implements HarnessSession {
         timestamp: Date.now(),
         raw: { type: 'push-steered', kind: payload.kind },
       });
+      return { outcome: 'steered' };
     } catch (error) {
       // A refusal is the runtime's answer; no answer leaves delivery unknown, never "ignored".
-      if (timedOut || !this._alive)
-        this._emit({
-          ...a.identity,
-          admissionId: a.admissionId,
-          kind: 'native_status',
-          timestamp: Date.now(),
-          raw: { type: 'push-unknown', kind: payload.kind },
-        });
-      else ignored(`turn/steer refused: ${(error as Error).message.slice(0, 200)}`);
+      if (!timedOut && this._alive)
+        return ignored(`turn/steer refused: ${(error as Error).message.slice(0, 200)}`);
+      this._emit({
+        ...a.identity,
+        admissionId: a.admissionId,
+        kind: 'native_status',
+        timestamp: Date.now(),
+        raw: { type: 'push-unknown', kind: payload.kind },
+      });
+      return { outcome: 'unknown' };
     } finally {
       clearTimeout(timer);
     }

package/src/harness-session.ts

@@ -411,6 +411,11 @@ export type ToolGate = (request: ToolRequest) => ToolDecision | Promise<ToolDeci
 /** `acknowledged`: the runtime confirmed the stop and the turn reached a native terminal. */
 export type NativeInterruptOutcome = 'acknowledged' | 'no-turn' | 'unacknowledged';
 
+/** What became of a push(): `steered` (the runtime took it into the owned turn), `unknown` (sent, never confirmed), `ignored` (not delivered; `reason` says why). */
+export type PushOutcome =
+  | { readonly outcome: 'steered' | 'unknown' }
+  | { readonly outcome: 'ignored'; readonly reason: string };
+
 export interface HarnessSession {
   /** How this session reaches its model, with the capabilities that transport declares. */
   readonly transport?: TransportDescriptor;
@@ -484,15 +489,15 @@ export interface HarnessSession {
   onToolRequest?(gate: ToolGate): () => void;
 
   /**
-   * Mid-turn push: out-of-band signal injected into an in-flight turn.
-   * Used by guards and Herald to deliver urgent feedback. Best-effort —
-   * the underlying runtime may or may not honor the push.
+   * Mid-turn push (steer): add input to the owned in-flight turn, where the transport declares
+   * `push: "steer"`. It never opens a turn of its own: the pushed text is answered inside the turn
+   * it was pushed into, whose send() settles once that turn (and everything pushed into it) ends.
    *
-   * Implementations that cannot support mid-turn push should emit a
-   * "push_ignored" error event rather than throw, so callers can observe
-   * that the push was attempted but not delivered.
+   * Never throws. `ignored` (with an emitted "push_ignored" error event) means nothing was
+   * delivered: no owned in-flight turn, the runtime refused, or the transport cannot steer.
+   * `unknown` means it was written but the runtime never confirmed it.
    */
-  push(payload: { kind: string; text: string }): Promise<void>;
+  push(payload: { kind: string; text: string }): Promise<PushOutcome>;
 
   /** Full session record for Oracle evaluation. */
   artifact(): SessionArtifact;

package/src/index.ts

@@ -141,6 +141,24 @@ export {
   type SubscriptionCandidate,
   type UnknownUtilizationPolicy,
 } from './routing';
+// The secret scratch pad (AS-009): `$$word` secrets used by reference, never read.
+export {
+  formatScratchRef,
+  isPrivatePath,
+  type PrivatePathOptions,
+  parseScratchRef,
+  privatePathDenial,
+  privatePathGate,
+  type ScratchDagger,
+  type ScratchPadSummary,
+  type ScratchRef,
+  type ScratchSource,
+  type ScratchUse,
+  SECRET_MARKER,
+  SECRET_SCRATCH_GUIDANCE,
+  SecretScratchError,
+  SecretScratchPad,
+} from './secret-scratch';
 // Transports: how a session reaches its model, with declared capabilities.
 export {
   TRANSPORTS,

package/src/muse-session.ts

@@ -18,6 +18,7 @@ import {
   type HarnessSession,
   NativeBindingMissingError,
   type NativeInterruptOutcome,
+  type PushOutcome,
   type SessionArtifact,
   type SessionAttempt,
   type SessionEvent,
@@ -1859,16 +1860,18 @@ export class MuseSession implements HarnessSession {
   }
 
   /** Mid-turn steer (turn/steer) into the owned in-flight turn; otherwise records push_ignored. */
-  async push(payload: { kind: string; text: string }): Promise<void> {
+  async push(payload: { kind: string; text: string }): Promise<PushOutcome> {
     const a = this._inflight?.evidence;
     const sessionId = this._externalSessionId;
-    const ignored = (reason: string) =>
+    const ignored = (reason: string): PushOutcome => {
       this._emit({
         kind: 'error',
         timestamp: Date.now(),
         text: `push_ignored: kind=${payload.kind} — ${reason}`,
         raw: { kind: payload.kind },
       });
+      return { outcome: 'ignored', reason };
+    };
     if (
       a?.dispatch !== 'attempted' ||
       a.nativeOutcome !== 'unknown' ||
@@ -1894,16 +1897,18 @@ export class MuseSession implements HarnessSession {
         timestamp: Date.now(),
         raw: { type: 'push-steered', kind: payload.kind },
       });
+      return { outcome: 'steered' };
     } catch (error) {
       // A refusal is the runtime's answer; no answer leaves delivery unknown, never "ignored".
-      if (error instanceof MspError) ignored(`turn/steer refused: ${error.message.slice(0, 200)}`);
-      else
-        this._emit({
-          ...identity,
-          kind: 'native_status',
-          timestamp: Date.now(),
-          raw: { type: 'push-unknown', kind: payload.kind },
-        });
+      if (error instanceof MspError)
+        return ignored(`turn/steer refused: ${error.message.slice(0, 200)}`);
+      this._emit({
+        ...identity,
+        kind: 'native_status',
+        timestamp: Date.now(),
+        raw: { type: 'push-unknown', kind: payload.kind },
+      });
+      return { outcome: 'unknown' };
     }
   }
 }

package/src/secret-scratch.ts

@@ -0,0 +1,595 @@
+import { spawn } from 'node:child_process';
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { basename, isAbsolute, join, resolve, sep } from 'node:path';
+import type { ToolGate, ToolRequest } from './harness-session';
+
+/**
+ * The secret scratch pad (AS-009): secrets a person hands an agent as `$$word` are lifted out of the
+ * message into a private file per thread, and the agent uses them by reference without reading them.
+ *
+ * One pad per thread accumulates: a dagger per message that carried secrets, a numbered block per
+ * secret, a blank line, the next message. A reference is thread, message and position; inside its
+ * own thread it is written `†<message>.<n>`, anywhere else `†<thread>/<message>.<n>`.
+ */
+
+/** The marker: a word starting with it is a secret, up to the next whitespace. */
+export const SECRET_MARKER = '$$';
+
+/** What the agent is told, wherever the tool is offered: use the values, never read them. */
+export const SECRET_SCRATCH_GUIDANCE =
+  "A reference like †<message>.<n> in a message is a secret the person handed you, held in the thread's scratch pad. You never see the value and must not try to read it: use it. The normal path is env (set KEY in an env file) and then pipe from that env file (a command gets the value on its stdin; its output is thrown away and only the exit code comes back). write puts a value in a file. Pass consume: true on the last use to remove it from the pad. list shows what is pending, here or, given a thread, in another thread whose references you have. A file the pad has written to is then off limits to read, search or print, like files named .private, *.private or *.private.*: use it through pipe. A secret is one word after $$; a multi-line secret cannot be lifted.";
+
+const REF = /^†?(?:([A-Za-z0-9_.:-]+)\/)?([A-Za-z0-9_.:-]+)\.(\d+)$/;
+const ID = /^[A-Za-z0-9_:-][A-Za-z0-9_.:-]*$/;
+const ENV_KEY = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const MARKED = /(^|\s)\$\$(\S+)/g;
+const PAD_SUFFIX = '.pad';
+/** A held value shorter than this is not scrubbed from text: it would match ordinary words. */
+const SCRUB_MIN = 6;
+
+export interface ScratchRef {
+  readonly thread: string;
+  readonly message: string;
+  readonly position: number;
+}
+
+/** A dagger as the agent may see it: where it came from and what is pending, never a value. */
+export interface ScratchDagger {
+  readonly message: string;
+  readonly at: string;
+  /** The start of the message, with its secrets already replaced by references. */
+  readonly excerpt: string;
+  readonly positions: readonly number[];
+}
+
+export interface ScratchPadSummary {
+  readonly thread: string;
+  readonly daggers: readonly ScratchDagger[];
+}
+
+/** Where `pipe` reads its value: a held block, or a key already set in an env file. */
+export type ScratchSource =
+  | { readonly ref: string }
+  | { readonly envFile: string; readonly key: string };
+
+export interface ScratchUse {
+  /** Remove the block from the pad once this use succeeds. */
+  readonly consume?: boolean;
+}
+
+/** A failure that names references and paths only, never a value. */
+export class SecretScratchError extends Error {
+  override readonly name = 'SecretScratchError';
+}
+
+interface Dagger {
+  message: string;
+  at: string;
+  excerpt: string;
+  blocks: Map<number, string>;
+}
+
+/** `†<message>.<n>` inside `thread`, `†<thread>/<message>.<n>` from anywhere. */
+export function formatScratchRef(ref: ScratchRef, from?: string): string {
+  return from === ref.thread
+    ? `†${ref.message}.${ref.position}`
+    : `†${ref.thread}/${ref.message}.${ref.position}`;
+}
+
+/** A reference as written by the agent; a short one belongs to `thread`. */
+export function parseScratchRef(text: string, thread: string): ScratchRef {
+  const match = REF.exec(text.trim());
+  if (!match) throw new SecretScratchError(`Not a scratch pad reference: ${clip(text)}`);
+  const position = Number(match[3]);
+  const ref = { thread: match[1] ?? thread, message: match[2]!, position };
+  if (!ID.test(ref.thread) || !ID.test(ref.message) || position < 1)
+    throw new SecretScratchError(`Not a scratch pad reference: ${clip(text)}`);
+  return ref;
+}
+
+/** A path no agent reads: a `.private` segment, a name ending in `.private` or holding `.private.`, or an extra glob. */
+export function isPrivatePath(path: string, extra: readonly string[] = []): boolean {
+  const segments = path.split(/[\\/]+/).filter(Boolean);
+  if (
+    segments.some(
+      (segment) =>
+        segment === '.private' || segment.endsWith('.private') || segment.includes('.private.'),
+    )
+  )
+    return true;
+  return extra.some((pattern) => {
+    const glob = new Bun.Glob(pattern);
+    return glob.match(path) || glob.match(basename(path));
+  });
+}
+
+const PATH_KEYS = [
+  'file_path',
+  'path',
+  'paths',
+  'notebook_path',
+  'pattern',
+  'glob',
+  'include',
+  'cwd',
+] as const;
+
+/** Every path and command word a tool call names. */
+function namedTargets(request: Pick<ToolRequest, 'toolInput' | 'blockedPath'>): string[] {
+  const input = request.toolInput;
+  const changes = Array.isArray(input.changes) ? input.changes : [];
+  const command = Array.isArray(input.command)
+    ? input.command.filter((part): part is string => typeof part === 'string').join(' ')
+    : input.command;
+  return [
+    request.blockedPath,
+    ...PATH_KEYS.flatMap((key) => (Array.isArray(input[key]) ? input[key] : [input[key]])),
+    ...changes.flatMap((change) => {
+      const c = change as { path?: unknown; movePath?: unknown } | null;
+      return [c?.path, c?.movePath];
+    }),
+    ...(typeof command === 'string' ? command.replace(/\\/g, '').split(/[\s'"`;|&<>()=]+/) : []),
+  ].filter((value): value is string => typeof value === 'string' && value.length > 0);
+}
+
+export interface PrivatePathOptions {
+  /** The scratch pad directory, private whatever its name. */
+  readonly scratchDir?: string;
+  /** Extra globs that are private too (`*.pem`). */
+  readonly privatePaths?: readonly string[];
+  /** Files the tool has written secrets into (`SecretScratchPad.heldFiles()`): used through pipe, never read. */
+  readonly heldFiles?: readonly string[];
+  /** Whether a call is the scratch tool's own (it names paths it writes, never reads). Default: none is. */
+  readonly isOwnTool?: (
+    request: Pick<ToolRequest, 'toolName' | 'toolServer' | 'toolMethod'>,
+  ) => boolean;
+}
+
+/** A command word or path that names a held file: the same absolute path, or a relative path ending one. */
+function namesHeldFile(target: string, held: readonly string[]): boolean {
+  if (isAbsolute(target)) return held.includes(resolve(target));
+  const tail = target.replace(/^(\.\/)+/, '');
+  if (!tail || tail === '.' || tail.startsWith('..')) return false;
+  return held.some((file) => file.endsWith(`${sep}${tail}`));
+}
+
+/** Why a tool call is refused for naming a private path or the scratch pad; undefined when it names none. */
+export function privatePathDenial(
+  request: Pick<
+    ToolRequest,
+    'toolInput' | 'blockedPath' | 'toolMethod' | 'toolName' | 'toolServer'
+  >,
+  options: PrivatePathOptions = {},
+): string | undefined {
+  if (options.isOwnTool?.(request)) return undefined;
+  const scratchDir = options.scratchDir ? resolve(options.scratchDir) : undefined;
+  const hit = namedTargets(request).find(
+    (target) =>
+      isPrivatePath(target, options.privatePaths) ||
+      namesHeldFile(target, options.heldFiles ?? []) ||
+      (scratchDir !== undefined &&
+        isAbsolute(target) &&
+        (resolve(target) === scratchDir || resolve(target).startsWith(scratchDir + sep))),
+  );
+  if (!hit) return undefined;
+  return `${clip(hit)} is private: it is never read, searched or printed. Use the scratch pad's tools instead: pipe from an env file, or env, pipe or write a held reference. They never show a value.`;
+}
+
+/** A tool gate that denies every call naming a private path or the scratch pad. */
+export function privatePathGate(options: PrivatePathOptions = {}): ToolGate {
+  return (request) => {
+    const message = privatePathDenial(request, options);
+    return message ? { behavior: 'deny', message } : { behavior: 'allow' };
+  };
+}
+
+/**
+ * The pads of one directory: one file per thread, 0600 in a 0700 directory. Every pad change is a
+ * synchronous read, edit and rewrite (a temporary file and a rename), so in one process no two
+ * changes interleave and a turn path that cannot wait can lift.
+ */
+export class SecretScratchPad {
+  private readonly _dir: string;
+
+  constructor(dir: string) {
+    this._dir = resolve(dir);
+  }
+
+  get dir(): string {
+    return this._dir;
+  }
+
+  /** Lift every `$$word` out of `text` into `thread`'s pad, under the dagger for `message`. */
+  lift(
+    text: string,
+    at: { thread: string; message: string; now?: Date },
+  ): { text: string; refs: string[] } {
+    const values = [...text.matchAll(MARKED)].map((match) => match[2] ?? '');
+    if (!values.length) return { text, refs: [] };
+    checkId(at.thread, 'thread');
+    checkId(at.message, 'message');
+    const daggers = this._read(at.thread);
+    let dagger = daggers.find((d) => d.message === at.message);
+    const first = dagger ? Math.max(0, ...dagger.blocks.keys()) + 1 : 1;
+    const refs: string[] = [];
+    const lifted = text.replace(MARKED, (_whole, lead: string) => {
+      const ref = formatScratchRef(
+        { thread: at.thread, message: at.message, position: first + refs.length },
+        at.thread,
+      );
+      refs.push(ref);
+      return `${lead}${ref}`;
+    });
+    if (!dagger) {
+      dagger = {
+        message: at.message,
+        at: (at.now ?? new Date()).toISOString(),
+        excerpt: lifted.replace(/\s+/g, ' ').trim().slice(0, 80),
+        blocks: new Map(),
+      };
+      daggers.push(dagger);
+    }
+    for (const [i, value] of values.entries()) dagger.blocks.set(first + i, value);
+    this._write(at.thread, daggers);
+    return { text: lifted, refs };
+  }
+
+  /** Every pad here (or one thread's) with what it holds pending, never the values. */
+  list(thread?: string): ScratchPadSummary[] {
+    const threads = thread ? [checkId(thread, 'thread')] : this.threads();
+    return threads
+      .map((id) => ({ thread: id, daggers: this._read(id).map(summary) }))
+      .filter((pad) => pad.daggers.length > 0);
+  }
+
+  /** The threads that have a pad here. */
+  threads(): string[] {
+    let names: string[];
+    try {
+      names = readdirSync(this._dir);
+    } catch {
+      return [];
+    }
+    return names
+      .filter((name) => name.endsWith(PAD_SUFFIX))
+      .map((name) => name.slice(0, -PAD_SUFFIX.length))
+      .filter((id) => ID.test(id))
+      .sort();
+  }
+
+  /** Files the tool has written secrets into, absolute: the gate keeps them from being read. */
+  heldFiles(): string[] {
+    const text = readText(this._heldPath());
+    if (!text) return [];
+    try {
+      const files = JSON.parse(text) as unknown;
+      return Array.isArray(files) ? files.filter((f): f is string => typeof f === 'string') : [];
+    } catch {
+      throw new SecretScratchError('The held-files list is unreadable.');
+    }
+  }
+
+  /** Write the value into a file: `replace` writes it exactly, `append` adds it on its own line. New files are 0600. */
+  write(
+    ref: string,
+    from: string,
+    path: string,
+    options: ScratchUse & { mode?: 'replace' | 'append'; cwd?: string } = {},
+  ): void {
+    const target = parseScratchRef(ref, from);
+    const value = this._held(target);
+    const file = this._target(options.cwd, path);
+    const before = options.mode === 'append' ? readText(file) : '';
+    const lead = before && !before.endsWith('\n') ? '\n' : '';
+    writeTarget(file, options.mode === 'append' ? `${before}${lead}${value}\n` : value);
+    this._hold(file);
+    if (options.consume) this._drop(target);
+  }
+
+  /** Set `KEY=value` in an env file: the line for KEY is replaced, or added at the end. */
+  env(
+    ref: string,
+    from: string,
+    path: string,
+    key: string,
+    options: ScratchUse & { cwd?: string } = {},
+  ): void {
+    if (!ENV_KEY.test(key)) throw new SecretScratchError(`Not an env key: ${clip(key)}`);
+    const target = parseScratchRef(ref, from);
+    const value = this._held(target);
+    const file = this._target(options.cwd, path);
+    const text = readText(file);
+    const newline = text.includes('\r\n') ? '\r\n' : '\n';
+    const lines = text.split(/\r?\n/);
+    if (lines[lines.length - 1] === '') lines.pop();
+    const line = `${key}=${envValue(value)}`;
+    // Loaders take the last line for a key, so that is the one replaced.
+    const at = lines.findLastIndex((l) => envLineKey(l) === key);
+    if (at >= 0) lines[at] = line;
+    else lines.push(line);
+    writeTarget(file, `${lines.join(newline)}${newline}`);
+    this._hold(file);
+    if (options.consume) this._drop(target);
+  }
+
+  /**
+   * Run `command` in a shell with the value on its stdin. Its output is thrown away; only the exit
+   * code comes back. The value comes from a held block or a key already in an env file. A failed
+   * command keeps its block, so it can be tried again.
+   */
+  async pipe(
+    source: ScratchSource,
+    from: string,
+    command: string,
+    options: ScratchUse & { cwd?: string; timeoutMs?: number } = {},
+  ): Promise<{ exitCode: number }> {
+    if ('ref' in source) {
+      const target = parseScratchRef(source.ref, from);
+      const result = await runWithStdin(command, this._held(target), options);
+      if (options.consume && result.exitCode === 0) this._drop(target);
+      return result;
+    }
+    if (!ENV_KEY.test(source.key))
+      throw new SecretScratchError(`Not an env key: ${clip(source.key)}`);
+    const file = this._target(options.cwd, source.envFile);
+    if (!existsSync(file)) throw new SecretScratchError(`No env file at ${clip(source.envFile)}`);
+    const line = readText(file)
+      .split(/\r?\n/)
+      .findLast((l) => envLineKey(l) === source.key);
+    if (line === undefined)
+      throw new SecretScratchError(`${source.key} is not set in ${clip(source.envFile)}`);
+    return runWithStdin(command, envLineValue(line), options);
+  }
+
+  /** Remove a block; a dagger with no blocks left goes too, and an empty pad is deleted. */
+  consume(ref: string, from: string): void {
+    const target = parseScratchRef(ref, from);
+    this._held(target);
+    this._drop(target);
+  }
+
+  /** Delete a thread's pad. */
+  clear(thread: string): void {
+    rmSync(this._path(checkId(thread, 'thread')), { force: true });
+  }
+
+  /** Replace every held value of `thread` found in `text` with its reference. */
+  scrub(thread: string, text: string): string {
+    const pairs = this._read(checkId(thread, 'thread'))
+      .flatMap((d) =>
+        [...d.blocks].map(([position, value]) => ({
+          value,
+          ref: formatScratchRef({ thread, message: d.message, position }, thread),
+        })),
+      )
+      .filter((pair) => pair.value.length >= SCRUB_MIN)
+      .sort((a, b) => b.value.length - a.value.length);
+    if (!pairs.length) return text;
+    const refs = new Map(pairs.map((pair) => [pair.value, pair.ref]));
+    const pattern = new RegExp(pairs.map((pair) => RegExp.escape(pair.value)).join('|'), 'g');
+    return text.replace(pattern, (value) => refs.get(value) ?? value);
+  }
+
+  private _held(ref: ScratchRef): string {
+    const value = this._read(ref.thread)
+      .find((d) => d.message === ref.message)
+      ?.blocks.get(ref.position);
+    if (value === undefined)
+      throw new SecretScratchError(
+        `Nothing is held at ${formatScratchRef(ref)}: it was consumed, or the reference is wrong. Call list to see what is pending.`,
+      );
+    return value;
+  }
+
+  /** Re-read and drop the block, so a lift made while a pipe ran is kept. */
+  private _drop(ref: ScratchRef): void {
+    const daggers = this._read(ref.thread);
+    daggers.find((d) => d.message === ref.message)?.blocks.delete(ref.position);
+    this._write(ref.thread, daggers);
+  }
+
+  /** A file the agent names, never inside the pad directory. */
+  private _target(cwd: string | undefined, path: string): string {
+    const file = resolve(cwd ?? '.', path);
+    if (file === this._dir || file.startsWith(this._dir + sep))
+      throw new SecretScratchError('The scratch pad directory is not a target.');
+    return file;
+  }
+
+  private _heldPath(): string {
+    return join(this._dir, 'held-files.json');
+  }
+
+  private _hold(file: string): void {
+    const files = this.heldFiles();
+    if (files.includes(file)) return;
+    mkdirSync(this._dir, { recursive: true, mode: 0o700 });
+    writePrivate(this._heldPath(), JSON.stringify([...files, file].sort(), null, 2));
+  }
+
+  private _path(thread: string): string {
+    return join(this._dir, `${thread}${PAD_SUFFIX}`);
+  }
+
+  private _read(thread: string): Dagger[] {
+    try {
+      return parsePad(readText(this._path(thread)));
+    } catch (error) {
+      if (error instanceof SecretScratchError) throw error;
+      throw new SecretScratchError(`The pad for ${thread} is unreadable.`);
+    }
+  }
+
+  private _write(thread: string, daggers: Dagger[]): void {
+    const live = daggers.filter((d) => d.blocks.size > 0);
+    if (!live.length) {
+      rmSync(this._path(thread), { force: true });
+      return;
+    }
+    mkdirSync(this._dir, { recursive: true, mode: 0o700 });
+    chmodSync(this._dir, 0o700);
+    writePrivate(this._path(thread), formatPad(thread, live));
+  }
+}
+
+function checkId(id: string, what: string): string {
+  if (!ID.test(id)) throw new SecretScratchError(`Not a ${what} id: ${clip(id)}`);
+  return id;
+}
+
+function clip(text: string): string {
+  return text.length > 120 ? `${text.slice(0, 117)}...` : text;
+}
+
+function summary(d: Dagger): ScratchDagger {
+  return {
+    message: d.message,
+    at: d.at,
+    excerpt: d.excerpt,
+    positions: [...d.blocks.keys()].sort((a, b) => a - b),
+  };
+}
+
+/** The pad as written: a line naming the thread, then per dagger its line, its blocks and a blank line. */
+function formatPad(thread: string, daggers: Dagger[]): string {
+  const body = daggers.map((d) =>
+    [
+      `†${d.message} (${d.at}, ${JSON.stringify(d.excerpt)})`,
+      ...[...d.blocks]
+        .sort(([a], [b]) => a - b)
+        .map(([position, value]) => `[${position}] ${JSON.stringify(value)}`),
+    ].join('\n'),
+  );
+  return `# secret scratch pad: thread ${thread}\n\n${body.join('\n\n')}\n`;
+}
+
+function parsePad(text: string): Dagger[] {
+  const daggers: Dagger[] = [];
+  let current: Dagger | undefined;
+  for (const line of text.split('\n')) {
+    const dagger = /^†(\S+) \((\S+), (".*")\)$/.exec(line);
+    if (dagger) {
+      current = {
+        message: dagger[1]!,
+        at: dagger[2]!,
+        excerpt: JSON.parse(dagger[3]!) as string,
+        blocks: new Map(),
+      };
+      daggers.push(current);
+      continue;
+    }
+    const block = /^\[(\d+)\] (".*")$/.exec(line);
+    if (block && current) {
+      current.blocks.set(Number(block[1]), JSON.parse(block[2]!) as string);
+      continue;
+    }
+    // Anything else but the heading and blank lines is damage: stop rather than rewrite without it.
+    if (line !== '' && !line.startsWith('# '))
+      throw new SecretScratchError('The pad is unreadable.');
+  }
+  return daggers;
+}
+
+function writePrivate(path: string, text: string): void {
+  const temp = `${path}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    writeFileSync(temp, text, { mode: 0o600, flag: 'wx' });
+    renameSync(temp, path);
+    chmodSync(path, 0o600);
+  } catch (error) {
+    rmSync(temp, { force: true });
+    throw new SecretScratchError(`Could not write ${clip(path)}: ${errorCode(error)}`);
+  }
+}
+
+/** A file the agent named: written in place (a symlinked env file stays a link); a new one is 0600. */
+function writeTarget(path: string, text: string): void {
+  try {
+    writeFileSync(path, text, { mode: 0o600 });
+  } catch (error) {
+    throw new SecretScratchError(`Could not write ${clip(path)}: ${errorCode(error)}`);
+  }
+}
+
+/** A file's text; a missing file is empty, any other failure stops the operation. */
+function readText(path: string): string {
+  try {
+    return readFileSync(path, 'utf8');
+  } catch (error) {
+    if (errorCode(error) === 'ENOENT') return '';
+    throw new SecretScratchError(`Could not read ${clip(path)}: ${errorCode(error)}`);
+  }
+}
+
+function errorCode(error: unknown): string {
+  return (error as NodeJS.ErrnoException | undefined)?.code ?? 'error';
+}
+
+/** A dotenv value: bare when plain, otherwise double-quoted with escapes. */
+function envValue(value: string): string {
+  if (/^[A-Za-z0-9_./:@+,=-]*$/.test(value)) return value;
+  // Single quotes are literal in dotenv loaders and shells: no `$` expansion.
+  if (!/['\n\r]/.test(value)) return `'${value}'`;
+  return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n').replace(/\r/g, '\\r')}"`;
+}
+
+function envLineKey(line: string): string | undefined {
+  return /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(line)?.[1];
+}
+
+function envLineValue(line: string): string {
+  const raw = line.slice(line.indexOf('=') + 1).trim();
+  const double = /^"((?:[^"\\]|\\.)*)"\s*(?:#.*)?$/.exec(raw);
+  if (double)
+    return (double[1] ?? '').replace(/\\(.)/g, (_m, c: string) =>
+      c === 'n' ? '\n' : c === 'r' ? '\r' : c,
+    );
+  const single = /^'([^']*)'\s*(?:#.*)?$/.exec(raw);
+  if (single) return single[1] ?? '';
+  if (raw.startsWith('"') || raw.startsWith("'"))
+    throw new SecretScratchError(
+      'The env value spans lines or is unterminated; it cannot be piped.',
+    );
+  return raw.replace(/\s+#.*$/, '');
+}
+
+function runWithStdin(
+  command: string,
+  value: string,
+  options: { cwd?: string; timeoutMs?: number },
+): Promise<{ exitCode: number }> {
+  return new Promise((done, fail) => {
+    const child = spawn('/bin/sh', ['-c', command], {
+      cwd: options.cwd,
+      stdio: ['pipe', 'ignore', 'ignore'],
+      detached: true,
+    });
+    // The whole group dies on a timeout, so nothing the command started keeps the value.
+    const timer = setTimeout(() => {
+      try {
+        if (child.pid) process.kill(-child.pid, 'SIGKILL');
+      } catch {
+        child.kill('SIGKILL');
+      }
+    }, options.timeoutMs ?? 120_000);
+    child.on('error', () => {
+      clearTimeout(timer);
+      fail(new SecretScratchError('The command could not start.'));
+    });
+    child.on('close', (code, signal) => {
+      clearTimeout(timer);
+      done({ exitCode: code ?? (signal ? 128 : 1) });
+    });
+    child.stdin.on('error', () => undefined);
+    child.stdin.end(value);
+  });
+}

package/src/transport.ts

@@ -73,7 +73,7 @@ export const TRANSPORTS: Readonly<Record<TransportKind, TransportDescriptor>> =
       fork: 'native',
       rollback: 'none',
       interrupt: 'acknowledged',
-      push: 'none',
+      push: 'steer',
       approvals: 'callback',
       usage: true,
       limits: { stream: true, poll: true },
@@ -87,6 +87,7 @@ export const TRANSPORTS: Readonly<Record<TransportKind, TransportDescriptor>> =
       'textOnly launches with no tools, MCP servers, slash commands or user settings.',
       'Primed decisions (ClaudePrimedSessions) fork a persisted primed session per cycle with a pre-spawned spare.',
       "interruptNative() and readLimits() use the CLI's stdio control protocol (`interrupt`, `get_usage`).",
+      'push() steers: a stream-json user message with `priority: "next"` and a `uuid`, tracked by its `command_lifecycle` frames; one the turn had not taken in when its result came runs as a follow-on result of the same turn, and a stop withdraws it (`cancel_async_message`). Live-verified on claude 2.1.316.',
       'toolGate: true launches with `--permission-prompt-tool stdio` and registers a PreToolUse callback over the control protocol: onToolRequest() gates see every call (`pre-use`, any mode, bypass included; only a deny counts) and the asks the permission mode raises (`permission`, final).',
       'Rollback (`--resume-session-at`) exists natively but is not wired here.',
       'Images ride in the same stream-json user message as base64 `image` content blocks, before the text.',
@@ -147,7 +148,7 @@ export const TRANSPORTS: Readonly<Record<TransportKind, TransportDescriptor>> =
       "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). Images, steer, interrupt, questions and Muse-initiated turns follow the SDK wire types without a live run.',
+      '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.',
     ],
   },
   'claude-agent-sdk': {
@@ -172,6 +173,7 @@ export const TRANSPORTS: Readonly<Record<TransportKind, TransportDescriptor>> =
     notes: [
       'Drives `@anthropic-ai/claude-agent-sdk` query() supplied by the caller; this package keeps zero dependencies.',
       "Reuses ClaudeCodeSession's event classification and admission evidence over the SDK message stream.",
+      'push() is not wired: whether the SDK stream surfaces `command_lifecycle` (which a steer is tracked by) is unverified.',
     ],
   },
   acp: {