@humwick/runner 0.0.0-stage → 0.130.1

package/src/adapters/claude-token-usage-capture.ts

@@ -0,0 +1,253 @@
+import { readdir } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+// #2482 — per-turn Claude token-usage capture: the runner-side half of the token-usage
+// spine's first capture seam. On every Stop-hook session turn (runner-core's
+// publishSessionTurn) the transcript's APPENDED tail is read and every NEW root-session
+// assistant entry's API-reported usage is extracted (the #2482 sibling parser beside
+// extractLatestContextUsage in adapters/claude-transcript.ts) and one spine record is
+// POSTed per entry, keyed dedupeKey=entry-uuid so the spine's dedupe_key upsert makes
+// replays and retries idempotent by construction.
+//
+// Two invariants the capture owns:
+//   • NO RE-READ — the per-pass position is a byte offset: each turn reads only the bytes
+//     appended since the last pass (partial trailing line buffered until its newline
+//     arrives, split on 0x0A so multi-byte UTF-8 survives byte boundaries). Per-turn cost
+//     is O(new lines), never O(session).
+//   • NO DOUBLE-COUNT — the offset watermark commits only after every POST of the pass
+//     landed; a failed POST leaves it untouched so the same slice replays next pass. A
+//     transcript-path rotation (a committed /clear mints a new session file), an inode
+//     change, or a TRUNCATION (same path, size shrank below the offset) re-reads from
+//     byte 0 and REPOSTS — safe by construction, because every record keys on the
+//     entry uuid and the spine's dedupe_key upsert collapses reposts onto their row
+//     (deliberately NOT ordinal-suppressed: counting entries could silently skip a
+//     genuinely new one inside a shortened file).
+//
+// All passes are serialized through a single queued worker: requests arriving mid-pass
+// coalesce onto the running slot and the worker drains the latest requested path when
+// the pass finishes — even when that pass failed (first error still reaches the caller).
+// Concurrent Stops for the same transcript can never double-read or double-post, and a
+// rotation racing a pass converges on the newest file.
+
+import { errMessage } from "@humwick/sdk";
+import { claudeSessionIdFromTranscriptPath, TranscriptTokenUsageExtractor, type TranscriptTokenUsageEntry } from "./claude-transcript";
+import { incrementalFileNeedsReset, readIncrementalFileRange, splitIncrementalFileLines, statIncrementalFile, type IncrementalFileInfo, type IncrementalFileLineBuffer, type IncrementalFileLinePolicy, type IncrementalFilePosition } from "./incremental-file";
+import type { ProviderTokenUsageRecord } from "../adapter";
+
+/** The spine's turn-less report shape (POST /api/agents/:id/token-usage, #2485). */
+export type TranscriptTokenUsageSpineRecord = ProviderTokenUsageRecord & { provider: "claude" };
+
+// Claude assistant transcript entries carry both the full model output and usage. Eight
+// MiB accommodates multi-megabyte normal responses while still bounding a line that is
+// left unterminated by a pathological writer.
+export const CLAUDE_TRANSCRIPT_LINE_POLICY: IncrementalFileLinePolicy = { maxPartialBytes: 8 * 1024 * 1024 };
+
+export interface ClaudeTranscriptTokenUsageCaptureDeps {
+  subagent?: { id: string; sessionId: string };
+  post: (record: TranscriptTokenUsageSpineRecord) => Promise<unknown>;
+  stat?: (path: string) => Promise<IncrementalFileInfo>;
+  /** Bytes in [start, end) of the transcript file — the incremental tail read. */
+  readRange?: (path: string, start: number, end: number) => Promise<Uint8Array>;
+  debug?: (message: string) => void;
+}
+
+export function spineRecordForEntry(sessionId: string, entry: TranscriptTokenUsageEntry): TranscriptTokenUsageSpineRecord {
+  return {
+    sessionId,
+    provider: "claude",
+    model: entry.model,
+    inputTokens: entry.inputTokens,
+    outputTokens: entry.outputTokens,
+    cacheReadTokens: entry.cacheReadTokens,
+    cacheWriteTokens: entry.cacheWriteTokens,
+    dedupeKey: entry.uuid,
+    createdAt: entry.occurredAt,
+    ...(entry.usageStatus ? { usageStatus: entry.usageStatus } : {}),
+  };
+}
+
+export class ClaudeTranscriptTokenUsageCapture {
+  private readonly children = new Map<string, ClaudeTranscriptTokenUsageCapture>();
+  private childSessionId?: string;
+  private position: IncrementalFilePosition | undefined;
+  private lineBuffer: IncrementalFileLineBuffer = {};
+  private pending: { path: string; promise: Promise<number> } | undefined;
+  private settling?: Promise<void>;
+
+  constructor(private readonly deps: ClaudeTranscriptTokenUsageCaptureDeps) {}
+
+  /**
+   * Report the transcript's not-yet-reported assistant usage entries. Serialized: at
+   * most one pass runs at a time; a request arriving mid-pass coalesces onto the queued
+   * slot (latest path wins) and the worker drains it after the current pass — even when
+   * that pass failed, with the first error still propagated to the caller. Never
+   * rejects for an unreadable transcript (debug note; the next pass re-reads); a failed
+   * POST propagates to the caller's catch with the position held for a next-pass retry.
+   */
+  capture(transcriptPath: string): Promise<number> {
+    return this.settling ? this.settling.then(() => this.capturePassQueued(transcriptPath)) : this.capturePassQueued(transcriptPath);
+  }
+
+  private capturePassQueued(transcriptPath: string): Promise<number> {
+    if (this.pending) {
+      this.pending.path = transcriptPath;
+      return this.pending.promise;
+    }
+    const slot: { path: string; promise: Promise<number> } = { path: transcriptPath, promise: Promise.resolve(0) };
+    slot.promise = (async () => {
+      // Error presence is tracked by flag, not the undefined sentinel: JS permits
+      // `throw undefined`, and `??=` would both swallow that pass's error entirely and
+      // let a later pass's error masquerade as first (round-4).
+      let hasFirstError = false;
+      let firstError: unknown;
+      let postedCount = 0;
+      try {
+        do {
+          const target = slot.path;
+          slot.path = "";
+          try {
+            postedCount += await this.capturePass(target);
+          } catch (error) {
+            // Retain and keep draining: a failed pass must not strand the queued
+            // latest-path request (round-3). The first error still reaches the caller.
+            if (!hasFirstError) {
+              firstError = error;
+              hasFirstError = true;
+            }
+          }
+        } while (slot.path);
+      } finally {
+        this.pending = undefined;
+      }
+      if (hasFirstError) throw firstError;
+      return postedCount;
+    })();
+    this.pending = slot;
+    return slot.promise;
+  }
+
+  /**
+   * A monitorless pane can render idle before Claude flushes its final assistant
+   * JSONL entry. Keep draining the incremental tail through the runner-owned
+   * bounded settle window. Once an entry arrives, wait for a short quiet interval
+   * too: an older delayed entry must not make us abandon the ending turn's own
+   * line when both are being flushed.
+   */
+  captureWithSettle(transcriptPath: string, options: { pollIntervalMs: number; timeoutMs: number; now?: () => number; sleep?: (ms: number) => Promise<unknown> }): Promise<number> {
+    const settle = (this.settling ?? Promise.resolve()).then(() => this.settleTranscript(transcriptPath, options));
+    const barrier = settle.then(() => {}, () => {});
+    this.settling = barrier;
+    void barrier.then(() => { if (this.settling === barrier) this.settling = undefined; });
+    return settle;
+  }
+
+  private async settleTranscript(transcriptPath: string, options: { pollIntervalMs: number; timeoutMs: number; now?: () => number; sleep?: (ms: number) => Promise<unknown> }): Promise<number> {
+    // now/sleep are injectable so tests can drive the settle window on a virtual
+    // clock instead of racing real timers against host load (#2714 flake).
+    const now = options.now ?? Date.now;
+    const sleep = options.sleep ?? Bun.sleep;
+    const deadline = now() + options.timeoutMs;
+    const pollIntervalMs = Math.max(1, options.pollIntervalMs);
+    const quietWindowMs = Math.min(options.timeoutMs, Math.max(pollIntervalMs * 2, 25));
+    // #2491 review round 3 (reverts round 2's watermark bail, which was WRONG — it exited
+    // exactly when the watermark hadn't moved yet, which is precisely the state a still-
+    // flushing final entry looks like before it lands). Seed the quiet-window baseline at
+    // settle START rather than leaving it undefined until something is first found: without
+    // this, when nothing EVER arrives (routine — the turn's own Stop-hook pass already
+    // caught everything) the quiet-window exit never fires and the loop burns the full
+    // settlePollTimeoutMs on every hooked teardown. Seeding it here bounds that case to
+    // quietWindowMs of continued silence instead — still comfortably wider than the ms-scale
+    // flush race this settle exists to catch, just not the full timeout.
+    let lastNewEntryAt: number = now();
+
+    let reported = await this.capturePassQueued(transcriptPath);
+    if (reported) lastNewEntryAt = now();
+    while (now() < deadline) {
+      await sleep(Math.max(1, Math.min(pollIntervalMs, deadline - now())));
+      const count = await this.capturePassQueued(transcriptPath);
+      reported += count;
+      if (count) {
+        lastNewEntryAt = now();
+      } else if (now() - lastNewEntryAt >= quietWindowMs) {
+        return reported;
+      }
+    }
+    return reported;
+  }
+
+  async captureSubagent(transcriptPath: string, settle = false): Promise<number> {
+    if (basename(dirname(transcriptPath)) !== "subagents") throw new Error("Expected a Claude sub-agent transcript");
+    const match = /^agent-(.+)\.jsonl$/.exec(basename(transcriptPath));
+    if (!match) throw new Error("Expected an agent-<id>.jsonl transcript");
+    const sessionId = basename(dirname(dirname(transcriptPath)));
+    if (sessionId !== this.childSessionId) { this.children.clear(); this.childSessionId = sessionId; }
+    let child = this.children.get(transcriptPath);
+    if (!child) {
+      child = new ClaudeTranscriptTokenUsageCapture({ ...this.deps, subagent: { id: match[1]!, sessionId } });
+      this.children.set(transcriptPath, child);
+    }
+    if (settle) return child.captureWithSettle(transcriptPath, { pollIntervalMs: 25, timeoutMs: 1_000 });
+    return child.capture(transcriptPath);
+  }
+
+  private async capturePass(transcriptPath: string): Promise<number> {
+    let count = await this.captureTranscriptPass(transcriptPath);
+    if (this.deps.subagent) return count;
+    const directory = join(dirname(transcriptPath), basename(transcriptPath, ".jsonl"), "subagents");
+    let files;
+    try { files = await readdir(directory, { withFileTypes: true }); }
+    catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return count; throw error; }
+    for (const file of files) {
+      if (file.isFile() && /^agent-.+\.jsonl$/.test(file.name)) count += await this.captureSubagent(join(directory, file.name));
+    }
+    return count;
+  }
+
+  private async captureTranscriptPass(transcriptPath: string): Promise<number> {
+    const stat = this.deps.stat ?? statIncrementalFile;
+    let info: IncrementalFileInfo;
+    try {
+      info = await stat(transcriptPath);
+    } catch (error) {
+      if (this.deps.subagent) throw error;
+      this.deps.debug?.(`token-usage capture: transcript unreadable: ${errMessage(error)}`);
+      return 0;
+    }
+
+    // New path / inode rotation / same-path truncation (size shrank below the offset):
+    // read again from byte 0. Reposts are SAFE, not an error — the spine collapses each
+    // one onto its existing row via dedupeKey=entry-uuid — and a genuinely new entry
+    // carried by a truncated/shortened file still reports. (Count-based ordinal
+    // suppression was tried here and could silently skip such an entry — round-3.)
+    if (incrementalFileNeedsReset(this.position, transcriptPath, info)) {
+      this.position = { path: transcriptPath, ino: info.ino, offset: 0 };
+      this.lineBuffer = {};
+    }
+    const position = this.position;
+    if (!position || info.size <= position.offset) return 0; // nothing appended since the last pass
+
+    const chunk = await (this.deps.readRange ?? readIncrementalFileRange)(transcriptPath, position.offset, info.size);
+    const { lines, buffer } = splitIncrementalFileLines(this.lineBuffer, chunk, CLAUDE_TRANSCRIPT_LINE_POLICY);
+
+    const extractor = new TranscriptTokenUsageExtractor(0, Boolean(this.deps.subagent));
+    const newEntries: TranscriptTokenUsageEntry[] = [];
+    for (const line of lines) {
+      const entry = extractor.appendLine(line.toString("utf8"));
+      if (entry) newEntries.push(entry);
+    }
+
+    const sessionId = this.deps.subagent?.sessionId ?? claudeSessionIdFromTranscriptPath(transcriptPath);
+    if (!sessionId) {
+      this.deps.debug?.("token-usage capture: no session id in transcript path; skipping");
+      return 0;
+    }
+    for (const entry of newEntries) {
+      await this.deps.post({ ...spineRecordForEntry(sessionId, entry), ...(this.deps.subagent ? { subagentId: this.deps.subagent.id } : {}) });
+    }
+    // Commit only after every POST of the pass landed — a throw above leaves the
+    // position and partial buffer untouched, so the whole slice replays next pass
+    // (safe: uuid-keyed, spine-deduped).
+    position.offset = info.size;
+    this.lineBuffer = buffer;
+    return newEntries.length;
+  }
+}

package/src/adapters/claude-tool-policy.ts

@@ -0,0 +1,165 @@
+import { writeChildEnv } from "@humwick/sdk/env";
+import { harnessSubagentsEnabled } from "@humwick/sdk";
+import type { RunnerSpawnConfig } from "../adapter";
+import type { AgentProfileProviderOptions } from "@humwick/sdk";
+import { isRecord } from "@humwick/sdk/types/guards";
+import { claudeDisallowedWebTools } from "../web-tools";
+
+// ── #2453 — eager "System tools" context trim for the coding/review profiles ─────────────────
+// A BARE tool name on Claude Code's --disallowedTools removes the tool's schema from the
+// model's eager context (the /context "System tools" bucket) WITHOUT touching MCP (mcp__*),
+// skills, or core coding tools — which an allowlist (--tools) would put at risk. The Artifact
+// family + Workflow carry the heaviest eager docstrings and coding/review agents never publish
+// artifacts or run workflows; SendFeedback is misused by autonomous agents (also env-suppressed
+// fleet-wide since T3182 — this is the per-profile context-trim path); ScheduleWakeup is
+// loop-only; ReportFindings duplicates relay report-up.
+export const CLAUDE_CONTEXT_TRIM_DISALLOWED_TOOLS = ["Artifact", "ArtifactComments", "ArtifactData", "ArtifactCheck", "Workflow", "SendFeedback", "ScheduleWakeup", "ReportFindings"];
+
+// The coding/review built-ins the denylist defaults ON for: worker/debugger build+test+land,
+// reviewer review, probe one-shot checks. Coordinators and ops-assistant
+// legitimately use Artifact/Workflow/ScheduleWakeup, so they keep every tool. A profile retunes
+// this per-profile via providerOptions.claude.disallowedTools.
+const CLAUDE_CONTEXT_TRIM_DEFAULT_PROFILES = new Set(["worker", "debugger", "reviewer", "probe"]);
+
+const CLAUDE_DISALLOWED_TOOLS_ARG = /^--(?:disallowedTools|disallowed-tools)(?:=(.*))?$/;
+
+/** Effective #2453 denylist for this launch: a profile-configured array REPLACES the default,
+ * `null` opts the profile out entirely, absent falls back to the default — and only for the
+ * coding/review profiles. Resolves the profile via the established
+ * `agentProfile?.name || profile` pattern. */
+export function claudeProfileDisallowedTools(config: Pick<RunnerSpawnConfig, "profile" | "agentProfile">): string[] {
+  const providerOptions = config.agentProfile?.providerOptions;
+  // A whole-null claude section is an explicit per-provider opt-out, same as
+  // disallowedTools: null — NOT "absent, fall back to the profile default".
+  if (isRecord(providerOptions) && "claude" in providerOptions && providerOptions.claude === null) return [];
+  const claudeOptions = isRecord(providerOptions) && isRecord(providerOptions.claude) ? providerOptions.claude : undefined;
+  if (claudeOptions && "disallowedTools" in claudeOptions) {
+    if (claudeOptions.disallowedTools === null) return [];
+    if (Array.isArray(claudeOptions.disallowedTools)) {
+      return claudeOptions.disallowedTools.filter((tool): tool is string => typeof tool === "string" && tool.length > 0);
+    }
+  }
+  const profileName = config.agentProfile?.name || config.profile || "";
+  if (!CLAUDE_CONTEXT_TRIM_DEFAULT_PROFILES.has(profileName)) return [];
+  // A profile that switches the Artifact or Workflow tool back on (#3171) gets it.
+  const harness = config.agentProfile ? claudeHarnessOptions(config) : CLAUDE_HARNESS_DEFAULTS;
+  return CLAUDE_CONTEXT_TRIM_DISALLOWED_TOOLS.filter((tool) => tool === "Workflow" ? !harness.workflows : !tool.startsWith("Artifact") || !harness.artifacts);
+}
+
+// ── #3171 — harness context trim: Claude Code built-ins Relay agents never use ──────────────────
+export type ClaudeAgentTypes = NonNullable<NonNullable<AgentProfileProviderOptions["claude"]>["agentTypes"]>;
+const CLAUDE_AGENT_TYPES: readonly ClaudeAgentTypes[] = ["all", "general-purpose", "none"];
+export interface ClaudeHarnessOptions {
+  artifacts: boolean;
+  workflows: boolean;
+  bundledSkills: boolean;
+  agentTypes: ClaudeAgentTypes;
+  /** AskUserQuestion + ListAgents: tools for a human at the terminal or native peer sessions. */
+  interactiveTools: boolean;
+}
+
+// Every Relay-launched profile gets this unless its providerOptions.claude says otherwise; the
+// built-in exceptions (coordinator, software-design, probe, ...) live in src/agent-profile-catalog.ts.
+const CLAUDE_HARNESS_DEFAULTS: ClaudeHarnessOptions = { artifacts: false, workflows: false, bundledSkills: false, agentTypes: "general-purpose", interactiveTools: false };
+// Profile-less launches (a human's wrapped `claude`) and a whole-null claude section keep everything.
+const CLAUDE_HARNESS_KEEP_ALL: ClaudeHarnessOptions = { artifacts: true, workflows: true, bundledSkills: true, agentTypes: "all", interactiveTools: true };
+
+// Claude Code 2.1.310's bundled skills, grouped by the tool that needs them. The env switch drops
+// them all, so a profile with Artifact or Workflow on turns the others off one by one instead.
+const ARTIFACT_SKILLS = ["artifact-design", "artifact-diagramming", "artifact-capabilities", "dataviz"];
+const WORKFLOW_SKILLS = ["workflow-authoring"];
+const OTHER_BUNDLED_SKILLS = ["claude-api", "code-review", "security-review", "update-config", "schedule", "run", "loop", "keybindings-help", "simplify", "fewer-permission-prompts", "init"];
+// Survives CLAUDE_CODE_DISABLE_BUNDLED_SKILLS; only skillOverrides removes it.
+const PLUGIN_AUTHORING_SKILL = "plugin-authoring";
+// Explore/Plan go through CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS; these need a deny.
+const NON_GENERAL_AGENT_TYPES = ["claude-code-guide", "statusline-setup", "claude"];
+
+export function claudeHarnessOptions(config: Pick<RunnerSpawnConfig, "agentProfile">): ClaudeHarnessOptions {
+  const providerOptions = config.agentProfile?.providerOptions;
+  if (!config.agentProfile || (isRecord(providerOptions) && "claude" in providerOptions && providerOptions.claude === null)) return CLAUDE_HARNESS_KEEP_ALL;
+  const claude = isRecord(providerOptions) && isRecord(providerOptions.claude) ? providerOptions.claude : {};
+  const flag = (key: "artifacts" | "workflows" | "bundledSkills" | "interactiveTools") => typeof claude[key] === "boolean" ? claude[key] as boolean : CLAUDE_HARNESS_DEFAULTS[key];
+  const agentTypes = CLAUDE_AGENT_TYPES.find((value) => value === claude.agentTypes) ?? CLAUDE_HARNESS_DEFAULTS.agentTypes;
+  return { artifacts: flag("artifacts"), workflows: flag("workflows"), bundledSkills: flag("bundledSkills"), agentTypes, interactiveTools: flag("interactiveTools") };
+}
+
+export interface ClaudeHarnessTrim {
+  env: Record<string, string>;
+  /** Keys for the inline --settings payload. */
+  settings: Record<string, unknown>;
+  /** Bare or `Agent(<type>)` names for --disallowedTools. */
+  deny: string[];
+}
+
+/** The launch levers for one profile's harness options: env switches, skillOverrides and denies. */
+export function claudeHarnessTrim(config: Pick<RunnerSpawnConfig, "agentProfile">): ClaudeHarnessTrim {
+  const options = claudeHarnessOptions(config);
+  const env: Record<string, string> = {};
+  if (!options.artifacts) env.CLAUDE_CODE_DISABLE_ARTIFACT = "1";
+  if (!options.workflows) env.CLAUDE_CODE_DISABLE_WORKFLOWS = "1";
+  if (options.agentTypes !== "all") env.CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS = "1";
+  const skillsOff: string[] = [];
+  if (!options.bundledSkills) {
+    if (options.artifacts || options.workflows) {
+      skillsOff.push(...OTHER_BUNDLED_SKILLS, ...(options.artifacts ? [] : ARTIFACT_SKILLS), ...(options.workflows ? [] : WORKFLOW_SKILLS));
+    } else {
+      env.CLAUDE_CODE_DISABLE_BUNDLED_SKILLS = "1";
+    }
+    skillsOff.push(PLUGIN_AUTHORING_SKILL);
+  }
+  const deny = [
+    ...(options.interactiveTools ? [] : ["AskUserQuestion", "ListAgents"]),
+    ...(options.agentTypes === "none" ? ["Agent"] : options.agentTypes === "general-purpose" ? NON_GENERAL_AGENT_TYPES.map((type) => `Agent(${type})`) : []),
+  ];
+  return { env, settings: skillsOff.length ? { skillOverrides: Object.fromEntries(skillsOff.map((skill) => [skill, "off"])) } : {}, deny };
+}
+
+/** One scan over the launch args: the tool names carried by inherited
+ * `--disallowedTools`/`--disallowed-tools` entries (space-separated multi-value and `=`
+ * comma-list forms), plus the args with those entries removed — so the profile denylist can
+ * UNION with what a caller/provider config already asked for instead of clobbering it. */
+function partitionClaudeDisallowedToolsArgs(args: string[]): { kept: string[]; inherited: string[] } {
+  const kept: string[] = [];
+  const inherited: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    const match = typeof arg === "string" ? CLAUDE_DISALLOWED_TOOLS_ARG.exec(arg) : null;
+    if (!match) {
+      kept.push(arg as string);
+      continue;
+    }
+    if (match[1] !== undefined) {
+      inherited.push(...splitDisallowedToolsList(match[1]));
+      continue;
+    }
+    for (i++; i < args.length; i++) {
+      const value = args[i];
+      if (value === undefined || value.startsWith("--")) break;
+      inherited.push(...splitDisallowedToolsList(value));
+    }
+    i--;
+  }
+  return { kept, inherited };
+}
+
+function splitDisallowedToolsList(value: string): string[] {
+  return value.split(",").map((name) => name.trim()).filter(Boolean);
+}
+
+/** Appends the profile's #2453 denylist to the launch args, merging with any inherited
+ * --disallowedTools entries into ONE canonical trailing occurrence (union, never clobber).
+ * No-op (args returned as-is) when the profile resolves no denylist. The single launch seam
+ * for this trim is ClaudeAdapter.buildSpawnArgs.
+ * Emitted as ONE `--disallowedTools=a,b,...` token: the space-separated variadic form would
+ * consume every following non-flag token — buildSpawnArgs pushes --model only when set and
+ * then the seeded initial-prompt positional, so a trailing variadic on an unpinned-model
+ * launch would eat the prompt as a deny value (silent no-prompt launch). The `=` form
+ * terminates the flag so following positionals survive. */
+export function claudeProfileDisallowedToolsArgs(args: string[], config: Pick<RunnerSpawnConfig, "harnessSubagents" | "profile" | "agentProfile">): string[] {
+  // #3024 — a profile's switched-off web tools are hidden whatever its denylist says.
+  const deny = [...(harnessSubagentsEnabled(config) ? [] : ["Agent", "Task", "TeamCreate", "TeamDelete", "SendMessage"]), ...claudeProfileDisallowedTools(config), ...claudeHarnessTrim(config).deny, ...claudeDisallowedWebTools(config)];
+  if (!deny.length) return args;
+  const { kept, inherited } = partitionClaudeDisallowedToolsArgs(args);
+  const merged = [...new Set([...inherited, ...deny])];
+  return [...kept, `--disallowedTools=${merged.join(",")}`];
+}

package/src/adapters/claude-transcript-tail.ts

@@ -0,0 +1,193 @@
+import { open, stat } from "node:fs/promises";
+import { LatestTurnStepAccumulator, type TurnStep } from "./claude-transcript";
+
+const FINGERPRINT_BYTES = 4096;
+
+export interface ClaudeTranscriptFileIdentity {
+  dev: number;
+  ino: number;
+  birthtimeMs: number;
+}
+
+interface TailFingerprint {
+  offset: number;
+  bytes: Buffer;
+}
+
+interface TranscriptTailFs {
+  stat: typeof stat;
+  open: typeof open;
+}
+
+export interface IncrementalTranscriptPollResult {
+  available: boolean;
+  changed: boolean;
+  reset: boolean;
+  steps: TurnStep[];
+  transcriptLooksComplete: boolean;
+  /** Claude's native prompt id for the latest turn, when known. */
+  promptId?: string;
+  /** Real user entries appended since this tail's previous poll. */
+  userPrompts: string[];
+  /** Entry timestamps corresponding to userPrompts, when Claude supplied them. */
+  userPromptOccurredAts: Array<number | undefined>;
+}
+
+export class IncrementalClaudeTranscriptTail {
+  private offset = 0;
+  private pending = Buffer.alloc(0);
+  private identity: ClaudeTranscriptFileIdentity | undefined;
+  private fingerprint: TailFingerprint | undefined;
+  private newUserPrompts: string[] = [];
+  private newUserPromptOccurredAts: Array<number | undefined> = [];
+  private readonly accumulator = new LatestTurnStepAccumulator();
+
+  constructor(private readonly fs: TranscriptTailFs = { stat, open }) {}
+
+  /** Start watching at the current EOF without parsing an old, potentially huge session. */
+  async seekToEnd(path: string): Promise<boolean> {
+    let fileStat: Awaited<ReturnType<typeof stat>>;
+    try { fileStat = await this.fs.stat(path); } catch { return false; }
+    const length = Math.min(FINGERPRINT_BYTES, fileStat.size);
+    const buffer = Buffer.alloc(length);
+    let handle: Awaited<ReturnType<typeof open>>;
+    try { handle = await this.fs.open(path, "r"); } catch { return false; }
+    try {
+      const read = await handle.read(buffer, 0, length, fileStat.size - length);
+      if (read.bytesRead !== length) return false;
+    } finally { await handle.close(); }
+    this.offset = fileStat.size;
+    this.pending = Buffer.alloc(0);
+    this.identity = { dev: fileStat.dev, ino: fileStat.ino, birthtimeMs: fileStat.birthtimeMs };
+    this.fingerprint = { offset: fileStat.size - length, bytes: buffer };
+    this.accumulator.reset();
+    this.newUserPrompts = [];
+    this.newUserPromptOccurredAts = [];
+    return true;
+  }
+
+  async poll(path: string): Promise<IncrementalTranscriptPollResult> {
+    this.newUserPrompts = [];
+    this.newUserPromptOccurredAts = [];
+    let fileStat: Awaited<ReturnType<typeof stat>>;
+    try {
+      fileStat = await this.fs.stat(path);
+    } catch {
+      return this.result({ available: false, changed: false, reset: false });
+    }
+
+    const nextIdentity = { dev: fileStat.dev, ino: fileStat.ino, birthtimeMs: fileStat.birthtimeMs };
+    const replaced = this.identity !== undefined && !sameIdentity(this.identity, nextIdentity);
+    const truncated = this.offset > fileStat.size;
+    let reset = replaced || truncated;
+    if (!reset && this.identity && this.fingerprint && fileStat.size >= this.offset) {
+      reset = !(await this.fingerprintMatches(path));
+    }
+    if (reset) this.reset(nextIdentity);
+    else if (!this.identity) this.identity = nextIdentity;
+
+    if (this.offset === fileStat.size) {
+      return this.result({ available: true, changed: false, reset });
+    }
+
+    const length = fileStat.size - this.offset;
+    const buffer = Buffer.alloc(length);
+    let bytesRead = 0;
+    // A transcript can be rotated after stat() but before open(). That is ordinary lifecycle
+    // churn, not a runner-fatal error: report this poll as unavailable and retry next interval.
+    let handle: Awaited<ReturnType<typeof open>>;
+    try {
+      handle = await this.fs.open(path, "r");
+    } catch {
+      return this.result({ available: false, changed: false, reset });
+    }
+    try {
+      const read = await handle.read(buffer, 0, length, this.offset);
+      bytesRead = read.bytesRead;
+    } finally {
+      await handle.close();
+    }
+
+    this.offset += bytesRead;
+    const delta = buffer.subarray(0, bytesRead);
+    this.updateFingerprint(delta);
+    const changed = bytesRead > 0 && this.consume(delta);
+    // A reset replays the new file from byte zero. Its history predates this
+    // submission probe, even when an old user entry happens to match this prompt.
+    if (reset) {
+      this.newUserPrompts = [];
+      this.newUserPromptOccurredAts = [];
+    }
+    return this.result({ available: true, changed, reset });
+  }
+
+  private reset(identity: ClaudeTranscriptFileIdentity): void {
+    this.offset = 0;
+    this.pending = Buffer.alloc(0);
+    this.fingerprint = undefined;
+    this.identity = identity;
+    this.accumulator.reset();
+    this.newUserPrompts = [];
+    this.newUserPromptOccurredAts = [];
+  }
+
+  private async fingerprintMatches(path: string): Promise<boolean> {
+    if (!this.fingerprint) return true;
+    const buffer = Buffer.alloc(this.fingerprint.bytes.length);
+    let handle: Awaited<ReturnType<typeof open>>;
+    try {
+      handle = await this.fs.open(path, "r");
+    } catch {
+      return false;
+    }
+    try {
+      const read = await handle.read(buffer, 0, buffer.length, this.fingerprint.offset);
+      return read.bytesRead === buffer.length && buffer.equals(this.fingerprint.bytes);
+    } finally {
+      await handle.close();
+    }
+  }
+
+  private updateFingerprint(delta: Buffer): void {
+    if (!delta.length) return;
+    const previous = this.fingerprint?.bytes ?? Buffer.alloc(0);
+    const combined = previous.length ? Buffer.concat([previous, delta]) : delta;
+    const bytes = Buffer.from(combined.subarray(Math.max(0, combined.length - FINGERPRINT_BYTES)));
+    this.fingerprint = { offset: this.offset - bytes.length, bytes };
+  }
+
+  private consume(delta: Buffer): boolean {
+    if (!delta.length) return false;
+    const combined = this.pending.length ? Buffer.concat([this.pending, delta]) : delta;
+    const lastNewline = combined.lastIndexOf(0x0a);
+    if (lastNewline === -1) {
+      this.pending = Buffer.from(combined);
+      return false;
+    }
+
+    const complete = combined.subarray(0, lastNewline + 1);
+    this.pending = Buffer.from(combined.subarray(lastNewline + 1));
+    this.accumulator.appendJsonl(complete.toString("utf8"));
+    const prompts = this.accumulator.drainUserPrompts();
+    this.newUserPrompts = prompts.map((prompt) => prompt.text);
+    this.newUserPromptOccurredAts = prompts.map((prompt) => prompt.occurredAt);
+    return true;
+  }
+
+  private result(input: { available: boolean; changed: boolean; reset: boolean }): IncrementalTranscriptPollResult {
+    return {
+      ...input,
+      steps: this.accumulator.steps,
+      transcriptLooksComplete: this.accumulator.transcriptLooksComplete,
+      ...(this.accumulator.promptId ? { promptId: this.accumulator.promptId } : {}),
+      userPrompts: this.newUserPrompts,
+      userPromptOccurredAts: this.newUserPromptOccurredAts,
+    };
+  }
+}
+
+function sameIdentity(a: ClaudeTranscriptFileIdentity, b: ClaudeTranscriptFileIdentity): boolean {
+  return a.dev === b.dev && a.ino === b.ino && a.birthtimeMs === b.birthtimeMs;
+}
+
+export const sameClaudeTranscriptFileIdentityForTests = sameIdentity;