@volter/supercode-frontend-vscode 0.1.60 → 0.1.62

package/README.md

@@ -357,7 +357,7 @@ it needs and the fallback it degrades to. Each arm names the producer it reads.
 | Event kind | Producer | Rendered as |
 |---|---|---|
 | `text_delta` | `crates/runtime/src/event.rs` `AgentEvent::TextDelta` | `response.markdown` (streamed) |
-| `user_message` | `sdk/interchange/agent-runtime-host.mjs` accepted-turn projection | the request turn in history; dropped live (VS Code already shows it) |
+| `user_message` | `sdk/interchange/agent-runtime-host.mjs` accepted-turn projection; `runtime-native-projection.mjs` `claudeBlocks` for Claude's own user-role records (`source: harness`) | the request turn in history; dropped live (VS Code already shows it); a harness record shows its `notice` or nothing |
 | `turn_started` / `turn_completed` / `turn_succeeded` | `submit_claimed`; `AgentEvent::TurnCompleted` | lifecycle only — the handler resolves, nothing renders |
 | `turn_interrupted` | `submit_claimed` | an italic notice |
 | `turn_failed` | `submit_claimed` | `ChatResponseWarningPart` → blockquote |
@@ -438,10 +438,17 @@ needs it; a reader does not, and a collapsed block is still a reader's problem.
 one to a person, so `role: 'system'` is dropped outright and the transcript starts where the
 conversation does.
 
-Saved user-role records marked `isMeta`, `isCompactSummary` or
-`promptSource: system` are also context. They create no person-message bubble;
-ordinary quoted text without those flags stays a person message. Claude's
-unmarked, exact `[Request interrupted by user]` record becomes a short turn
+Whose words a user-role record carries is one rule,
+`@volter/supercode-interchange/user-provenance`, vendored here unchanged. Live
+and replayed `user_message` events carry its answer as `source`
+(`person` | `harness`) with a `notice` where one is shown; saved history is
+read through the same rule. Records the harness wrote (`isMeta`,
+`isSynthetic` — the stream's image-coordinate note — `isCompactSummary`,
+`promptSource: system`, sidechain and tool-result records, file attachments)
+create no person-message bubble, live or restored; ordinary quoted text
+without those flags stays a person message. A task notification becomes a
+short background-task notice, and Claude's unmarked, exact interruption
+records (`[Request interrupted by user]`, `… for tool use]`) a short turn
 interruption notice. The native transcript remains authoritative and unchanged.
 [Source evidence and remaining qualification](../../docs/evidence/chat-native-notices-20261013.md).
 

package/dist/extension.js

@@ -1,6 +1,7 @@
 import { resolveSessionBinding } from './bindings.js';
 import { withTextContext } from './context.js';
 import { randomUUID } from 'node:crypto';
+import { WorkbenchTools } from './workbench-tools.js';
 import { ChatHostControls, runtimeIdentity, harnessDisplayName, turnPermission } from './host-controls.js';
 import { SETUP_BEGIN, SETUP_CANCEL, SETUP_STATE, setupAgents, setupPresentation, setupWelcome } from './chat-setup.js';
 import { ChatSetupFlow } from './setup-flow.js';
@@ -360,6 +361,16 @@ export async function activate(context) {
     const controls = await ChatHostControls.fromEnvironment();
     const controlsChanged = new vscode.EventEmitter();
     context.subscriptions.push(controlsChanged);
+    // The workbench's tools for the host's runtimes, on the endpoint the host names (ADR 0255).
+    if (controls) {
+        const workbenchTools = new WorkbenchTools();
+        context.subscriptions.push(workbenchTools);
+        const serveTools = (state) => {
+            workbenchTools.serve(state.workbenchTools).catch(error => log.warn(`Workbench tools unavailable: ${String(error)}`));
+        };
+        context.subscriptions.push({ dispose: controls.onState(serveTools) });
+        serveTools(controls.state);
+    }
     // A person's explicit picker choice: per conversation once it is bound, and for the new chat before then.
     let permission;
     const permissions = new Map(context.workspaceState.get('supercode.sessionPermissions', []));

package/dist/host-controls.d.ts

@@ -79,15 +79,26 @@ export interface HostState {
     /** Project policy for the next start/resume; an existing runtime uses its recorded session policy. */
     newChatRuntimePolicy?: 'default' | 'yolo' | null;
     runtimePolicyError?: string | null;
+    /** The workbench tools this host's runtimes reach (ADR 0255): the tag they carry, and the socket and token the host
+     *  named, where their relay (`supercode mcp workbench`) calls them. Absent, they reach none. */
+    workbenchTools?: WorkbenchToolsEndpoint;
+}
+export interface WorkbenchToolsEndpoint {
+    tag: string;
+    socket: string;
+    token: string;
 }
 export interface HostSelectionResult extends HostState {
     connection: Record<string, string>;
 }
 export declare class ChatHostControls {
+    #private;
     readonly baseUrl: string;
     private readonly credential;
     state: HostState;
     private updating;
+    /** Call `listener` with each state the host replies with; returns the unsubscribe. */
+    onState(listener: (state: HostState) => void): () => void;
     private constructor();
     static fromEnvironment(env?: NodeJS.ProcessEnv): Promise<ChatHostControls | undefined>;
     refresh(): Promise<void>;

package/dist/host-controls.js

@@ -4,6 +4,12 @@ export class ChatHostControls {
     credential;
     state;
     updating = Promise.resolve();
+    #stateListeners = new Set();
+    /** Call `listener` with each state the host replies with; returns the unsubscribe. */
+    onState(listener) {
+        this.#stateListeners.add(listener);
+        return () => this.#stateListeners.delete(listener);
+    }
     constructor(baseUrl, credential, state) {
         this.baseUrl = baseUrl;
         this.credential = credential;
@@ -37,6 +43,8 @@ export class ChatHostControls {
         const pending = this.updating.then(async () => {
             const result = await this.request(path, selection);
             this.state = result;
+            for (const listener of this.#stateListeners)
+                listener(result);
             return result;
         });
         this.updating = pending.then(() => undefined, () => undefined);

package/dist/view.d.ts

@@ -172,14 +172,6 @@ export interface ProjectedTurn {
     /** Rendered parts for an assistant turn. */
     parts?: ChatPart[];
 }
-/**
- * A "user" message no person typed: Claude Code's `<task-notification>` (a background task reporting back) or the
- * editor's automatic tripwire nudge or Claude's unmarked interruption record. None is shown as the person's words.
- * A task notification and interruption are short notices; a nudge is not shown. Undefined for a person's message.
- */
-export declare function automaticPrompt(body: string): {
-    notice?: string;
-} | undefined;
 export declare function projectReplayTurns(events: readonly FrontendEvent[], granted: ReadonlySet<string>, context: ProjectionContext, history?: readonly ProjectedTurn[]): ProjectedTurn[];
 /**
  * The attach snapshot's canonical history as chat turns. Bounded: when older

package/dist/view.js

@@ -1,3 +1,4 @@
+import { userProvenance } from '../vendor/supercode-interchange/user-provenance.mjs';
 /**
  * The bounded projection this presentation package renders. Mirrors
  * `@volter/supercode-frontend-browser`'s rule: the view is size-bounded
@@ -439,18 +440,18 @@ export function projectPendingRequests(requests, context) {
 export function projectEvent(event, context) {
     const payload = payloadOf(event);
     switch (event.kind) {
-        // crates/harness/src/server.rs `submit_claimed` — the runtime's echo of the
-        // initial prompt, before `turn_started`. VS Code renders that request turn.
-        // A rejoined turn has no submitting handler; later runtime input is visible
+        // runtime-hosted.mjs `#submitClaimed` — the runtime's echo of the initial
+        // prompt, before `turn_started`. VS Code renders that request turn. A
+        // rejoined turn has no submitting handler; later runtime input is visible
         // within its live response and remains a user turn in canonical history.
+        // The harness's own user-role records (runtime-native-projection.mjs
+        // `claudeBlocks`) arrive stamped `source: 'harness'`: a notice or nothing.
         case 'user_message': {
+            const notice = notPersonNotice(payload);
+            if (notice !== undefined)
+                return notice ? [stable({ part: 'markdown', value: `\n\n${notice}\n\n` })] : [];
             if (context.liveUserMessages) {
                 const body = text(payload.text);
-                const automatic = automaticPrompt(body);
-                if (automatic)
-                    return automatic.notice
-                        ? [stable({ part: 'markdown', value: `\n\n${automatic.notice}\n\n` })]
-                        : [];
                 const prefix = '\n\n**Additional input**\n\n';
                 const suffix = '\n\n';
                 const value = clamp(stripControls(body), VSCODE_CHAT_LIMITS.partCharacters - prefix.length - suffix.length);
@@ -730,47 +731,64 @@ function messageText(message) {
         .join('\n');
 }
 /**
- * A "user" message no person typed: Claude Code's `<task-notification>` (a background task reporting back) or the
- * editor's automatic tripwire nudge or Claude's unmarked interruption record. None is shown as the person's words.
- * A task notification and interruption are short notices; a nudge is not shown. Undefined for a person's message.
+ * What a `user_message` shows when no person typed it: undefined for the person's words, '' to show nothing, else a
+ * short notice. The harness's own records carry `source: 'harness'` (and a `notice` where one is shown) from the one
+ * provenance rule the runtime applies (`@volter/supercode-interchange/user-provenance`). The editor's automatic
+ * tripwire nudge travels through the person's input door, so the editor's frame is what names it.
  */
-export function automaticPrompt(body) {
-    const trimmed = body.trimStart();
-    if (trimmed.startsWith('<task-notification>')) {
-        const tag = (name) => clamp(stripControls(new RegExp(`<${name}>([\\s\\S]*?)</${name}>`).exec(trimmed)?.[1]?.trim() ?? ''), 200);
-        const summary = tag('summary');
-        const status = tag('status');
-        return { notice: `_Background task${status ? ` ${status}` : ''}${summary ? `: ${summary}` : ''}_` };
-    }
-    if (trimmed.startsWith('[Volter editor tripwire'))
-        return {};
-    // Claude persists this reserved notice as an unmarked user-role record.
-    if (trimmed.trimEnd() === '[Request interrupted by user]')
-        return { notice: '_Turn interrupted._' };
+function notPersonNotice(payload) {
+    if (payload.source === 'harness')
+        return noticeMarkdown(text(payload.notice));
+    if (editorNudge(text(payload.text)))
+        return '';
     return undefined;
 }
+/** The rule's plain notice as this view's italic line; '' for none. */
+function noticeMarkdown(notice) {
+    const value = clamp(stripControls(notice ?? ''), VSCODE_CHAT_LIMITS.partCharacters - 2);
+    return value ? `_${value}_` : '';
+}
+function editorNudge(body) {
+    return body.trimStart().startsWith('[Volter editor tripwire');
+}
 export function projectReplayTurns(events, granted, context, history = []) {
     // Join canonical history with its sequenced tail. Retained request/decision
     // events can be re-sequenced past history_cursor with no originating turn.
     // Before the replay supplies a prompt, give its parts their own runtime
     // history turn rather than attributing old approvals to the latest answer.
     const turns = history.map(turn => ({ ...turn, parts: turn.parts?.slice() }));
+    // An approval the replay shows allowed is not drawn again: live, its card is hidden (Auto approve) or answered,
+    // and its allowed resolution says nothing more, so the tool row is the record (`request_resolved` above).
+    const allowed = new Set();
+    for (const event of events) {
+        if (event.kind !== 'request_resolved')
+            continue;
+        const payload = payloadOf(event);
+        const response = payload.response;
+        if (typeof payload.request_id === 'number' && response?.kind === 'approval' && response.decision !== 'deny')
+            allowed.add(payload.request_id);
+    }
     let replayTurn = false;
     let streamedText;
     for (const event of events) {
+        if (event.kind === 'request') {
+            const request = (payloadOf(event).request ?? payloadOf(event));
+            if (typeof request?.id === 'number' && allowed.has(request.id))
+                continue;
+        }
         if (event.kind === 'user_message') {
             streamedText = undefined;
             const payload = payloadOf(event);
-            const automatic = automaticPrompt(text(payload.text));
-            if (automatic) {
-                if (!automatic.notice)
+            const shown = notPersonNotice(payload);
+            if (shown !== undefined) {
+                if (!shown)
                     continue;
                 if (!replayTurn) {
                     turns.push({ role: 'user', prompt: HISTORY_MARKER_PROMPT });
                     replayTurn = true;
                 }
                 const last = turns[turns.length - 1];
-                const notice = { part: 'markdown', value: `\n\n${automatic.notice}\n\n` };
+                const notice = { part: 'markdown', value: `\n\n${shown}\n\n` };
                 if (last.role === 'assistant' && last.parts)
                     last.parts.push(notice);
                 else
@@ -870,17 +888,16 @@ export function projectHistory(history, granted, pendingToolNames = new Set()) {
                     pushAssistant([{ part: 'markdown', value: clamp(stripControls(text), VSCODE_CHAT_LIMITS.partCharacters) }]);
                 continue;
             }
-            const automatic = automaticPrompt(body);
-            if (automatic) {
-                if (automatic.notice)
-                    pushAssistant([{ part: 'markdown', value: `\n\n${automatic.notice}\n\n` }]);
+            // The codec preserves the harness's provenance; the one rule reads it.
+            // Image-coordinate notes, compact summaries, task notifications and the
+            // interruption record are not the person's words.
+            const provenance = userProvenance(message.metadata, body);
+            if (provenance.source === 'harness' || editorNudge(body)) {
+                const notice = noticeMarkdown(provenance.notice);
+                if (notice)
+                    pushAssistant([{ part: 'markdown', value: `\n\n${notice}\n\n` }]);
                 continue;
             }
-            // The codec preserves the harness's provenance. Image-coordinate notes,
-            // compact summaries and injected context are not the person's words.
-            if (message.metadata?.isMeta === 'true' || message.metadata?.isCompactSummary === 'true' ||
-                message.metadata?.promptSource === 'system')
-                continue;
             toolRows.clear();
             turns.push({ role: 'user', prompt: clamp(stripControls(body), VSCODE_CHAT_LIMITS.partCharacters) });
             continue;

package/dist/workbench-tools.d.ts

@@ -0,0 +1,13 @@
+import * as vscode from 'vscode';
+import type { WorkbenchToolsEndpoint } from './host-controls.js';
+export declare class WorkbenchTools implements vscode.Disposable {
+    #private;
+    /** Serve on the endpoint the host names, or nothing when it names none. A changed endpoint replaces the server.
+     *  Calls apply in order, so two quick state replies cannot race a close against a listen. */
+    serve(endpoint: WorkbenchToolsEndpoint | undefined): Promise<void>;
+    private apply;
+    private answer;
+    private handle;
+    private close;
+    dispose(): void;
+}

package/dist/workbench-tools.js

@@ -0,0 +1,81 @@
+/**
+ * The workbench's tools, for the harness agents in its Chat (ADR 0255).
+ *
+ * The host names the tools and where they run (`HostState.workbenchTools`: a tag, a socket and a token), and lists
+ * them to its runtimes itself, through `supercode mcp workbench`. That relay calls them here: this serves, in the
+ * extension host where `vscode.lm` exists, one call of a tool `vscode.lm.tools` lists with the tag, through
+ * Code-OSS's own tool service. With no endpoint it serves nothing.
+ *
+ * The wire is one JSON line each way per connection: `{token, name, input}` → `{text, isError}`.
+ */
+import { rmSync } from 'node:fs';
+import { createServer } from 'node:net';
+import * as vscode from 'vscode';
+export class WorkbenchTools {
+    #served;
+    #applying = Promise.resolve();
+    /** Serve on the endpoint the host names, or nothing when it names none. A changed endpoint replaces the server.
+     *  Calls apply in order, so two quick state replies cannot race a close against a listen. */
+    serve(endpoint) {
+        const applying = this.#applying.then(() => this.apply(endpoint));
+        this.#applying = applying.catch(() => undefined);
+        return applying;
+    }
+    async apply(endpoint) {
+        const current = this.#served?.endpoint;
+        if (current?.tag === endpoint?.tag && current?.socket === endpoint?.socket && current?.token === endpoint?.token)
+            return;
+        this.close();
+        if (!endpoint)
+            return;
+        // A socket left by an earlier extension host of this window is this window's own.
+        if (process.platform !== 'win32')
+            rmSync(endpoint.socket, { force: true });
+        const server = createServer(socket => this.answer(socket, endpoint));
+        await new Promise((resolve, reject) => { server.once('error', reject); server.listen(endpoint.socket, resolve); });
+        this.#served = { endpoint, server };
+    }
+    answer(socket, endpoint) {
+        let buffer = '';
+        socket.setEncoding('utf8');
+        socket.on('data', chunk => {
+            buffer += chunk;
+            const end = buffer.indexOf('\n');
+            if (end < 0)
+                return;
+            const line = buffer.slice(0, end);
+            buffer = '';
+            void this.handle(line, endpoint).then(reply => socket.end(`${JSON.stringify(reply)}\n`));
+        });
+        socket.on('error', () => socket.destroy());
+    }
+    async handle(line, { tag, token }) {
+        let request;
+        try {
+            request = JSON.parse(line);
+        }
+        catch {
+            return { text: 'The call was not JSON.', isError: true };
+        }
+        if (request.token !== token)
+            return { text: 'The call was refused.', isError: true };
+        const name = request.name;
+        if (typeof name !== 'string' || !vscode.lm.tools.some(tool => tool.name === name && tool.tags.includes(tag))) {
+            return { text: `The workbench has no tool ${String(name)}.`, isError: true };
+        }
+        try {
+            const input = request.input && typeof request.input === 'object' ? request.input : {};
+            const result = await vscode.lm.invokeTool(name, { input, toolInvocationToken: undefined });
+            return { text: result.content.map(part => part instanceof vscode.LanguageModelTextPart ? part.value : '').join(''), isError: false };
+        }
+        catch (error) {
+            return { text: error instanceof Error ? error.message : String(error), isError: true };
+        }
+    }
+    close() {
+        const served = this.#served;
+        this.#served = undefined;
+        served?.server.close();
+    }
+    dispose() { this.close(); }
+}

package/package.json

@@ -1,14 +1,7 @@
 {
   "name": "@volter/supercode-frontend-vscode",
-  "devEngines": {
-    "packageManager": {
-      "name": "pnpm",
-      "version": ">=12.15.0",
-      "onFail": "error"
-    }
-  },
   "displayName": "Volter Harness",
-  "version": "0.1.60",
+  "version": "0.1.62",
   "type": "module",
   "description": "VS Code chat-view frontend for an existing Volter Harness SDK runtime",
   "repository": {
@@ -29,11 +22,17 @@
     "LICENSE-APACHE",
     "dist",
     "vendor/supercode-frontend",
+    "vendor/supercode-interchange",
     "scripts/pack-extension.mjs",
     "README.md",
     "NOTICE.md",
     "media"
   ],
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist', {recursive:true, force:true})\" && node scripts/sync-sdk.mjs && node scripts/fetch-icon.mjs && node scripts/sync-marks.mjs && tsc -p tsconfig.build.json",
+    "extension": "npm run build && node scripts/pack-extension.mjs",
+    "prepack": "npm run build"
+  },
   "engines": {
     "node": ">=20",
     "vscode": "^1.138.0"
@@ -214,9 +213,5 @@
     "version": "0.2.12",
     "mode": "generated-artifact"
   },
-  "license": "MIT OR Apache-2.0",
-  "scripts": {
-    "build": "node -e \"require('node:fs').rmSync('dist', {recursive:true, force:true})\" && node scripts/sync-sdk.mjs && node scripts/fetch-icon.mjs && node scripts/sync-marks.mjs && tsc -p tsconfig.build.json",
-    "extension": "pnpm run build && node scripts/pack-extension.mjs"
-  }
-}
+  "license": "MIT OR Apache-2.0"
+}

package/vendor/supercode-frontend/package.json

@@ -1,6 +1,5 @@
 {
   "name": "@volter/supercode-frontend",
-  "devEngines": { "packageManager": { "name": "pnpm", "version": ">=12.15.0", "onFail": "error" } },
   "version": "0.2.12",
   "type": "module",
   "description": "Generated language-neutral attachment client for Volter Harness SDK runtimes",

package/vendor/supercode-interchange/user-provenance.d.mts

@@ -0,0 +1,19 @@
+// Generated from sdk/interchange/user-provenance.mjs by scripts/user-provenance-copies.mjs (the pre-commit hook
+// runs it): edit that rule, not this file.
+export type UserSource = "person" | "harness";
+export interface UserProvenance {
+	source: UserSource;
+	/** The short line shown in place of a harness record, where one is shown. */
+	notice?: string;
+}
+export const CLAUDE_INTERRUPTION_TEXTS: readonly string[];
+export function isClaudeInterruption(text: unknown): boolean;
+export function userProvenance(
+	metadata: Readonly<Record<string, string>> | null | undefined,
+	text?: string,
+): UserProvenance;
+export function isHarnessAuthoredUser(
+	metadata: Readonly<Record<string, string>> | null | undefined,
+	text?: string,
+): boolean;
+export function claudeRecordProvenance(record: unknown): Record<string, string>;

package/vendor/supercode-interchange/user-provenance.mjs

@@ -0,0 +1,230 @@
+// Generated from sdk/interchange/user-provenance.mjs by scripts/user-provenance-copies.mjs (the pre-commit hook
+// runs it): edit that rule, not this file.
+// Whose words a user-role record carries: the person's, or the harness's own.
+// One rule for every reader (the live projection, replay, history, client
+// transcripts, Teams' turn and mail readers, voice, trace). It imports nothing,
+// so a host that cannot resolve this package (the VS Code extension, the browser
+// observer, the hosted viewer, supercode-ui) carries its exact bytes; the
+// pre-commit hook writes those copies (scripts/user-provenance-copies.mjs).
+//
+// The rule reads, in order:
+//   1. a person's marker: the record says a person wrote it. A person who quotes
+//      a frame (`<task-notification> showed up in my chat`) or types a reserved
+//      notice is still the person.
+//   2. a harness marker: the record says the harness wrote it.
+//   3. only for a record with no marker either way, its text: a reserved notice
+//      or a frame the harness opens its unmarked records with.
+// A record with nothing of the three is the person's.
+//
+// Measured (local Claude Code corpus; Claude Code 2.1.312 stream-json):
+//   - person records carry `origin.kind = "human"` or `promptSource` typed /
+//     queued / sdk; no task notification carries either. Claude Code's relay of a
+//     person's line into a busy fork ("The user sent a new message while you were
+//     working: …") carries both `isMeta` and `origin.kind = "human"` (15): the
+//     person's words, so the person's marker decides. `isMeta` records otherwise
+//     carry `promptSource = "system"` only (35,680);
+//   - task notifications: `origin.kind = "task-notification"` and
+//     `promptSource = "system"` on every user record opening `<task-notification>`
+//     (1,964); `commandMode = "task-notification"` on every such `queued_command`
+//     attachment (1,586, against 926 `commandMode = "prompt"`, each a person's);
+//   - local-command caveats and image-coordinate notes: `isMeta` in the
+//     transcript (397 caveats);
+//   - the image-coordinate note on the live stream-json door: `isSynthetic: true`
+//     and no `isMeta` (the transcript stores the same uuid with `isMeta: true`).
+//     The stream carries no person's marker at all: it does not echo the person's
+//     prompt (the host publishes that itself), so its records reach step 2 or 3;
+//   - compact summaries: `isCompactSummary` (with `isVisibleInTranscriptOnly`);
+//   - subagent traffic: `isSidechain` in the transcript, `parent_tool_use_id` on
+//     the stream; tool results: `toolUseResult` / `tool_use_result` or a
+//     `tool_result` block.
+// Unmarked records, whose text is the only evidence (a 400-transcript sample of
+// unmarked main-thread user text: `<command-name>` 18, `<local-command-stdout>`
+// 16, `<bash-input>` 13, `<bash-stdout>` 13, the interruption notice 13, plain 2):
+//   - the interruption record, whose whole text is one of Claude's reserved
+//     notices (832 and 195 corpus occurrences of the two below);
+//   - slash-command and shell-mode plumbing (`<command-name>`, `<command-message>`,
+//     `<local-command-stdout>`, `<bash-input>`, `<bash-stdout>`, …): a local
+//     command the terminal ran and its output, not a message to the agent;
+//   - a task notification on a live adapter path, which can arrive without the
+//     persisted stamps (not yet measured on the stream-json door);
+//   - context other harnesses and hosts open a user turn with (AGENTS.md / CLAUDE.md
+//     instructions, `<environment_context>`, `<system-reminder>`, …) and
+//     supercode's own frames (`<supercode-notice>`, a cross-session notice, an
+//     edited-file attachment flattened to text).
+// Frames are openers, never substrings: the tag is the part the harness controls,
+// and a person quoting one mid-sentence is still talking.
+
+/** `promptSource` values a person's input carries (Claude Code's, and the hosts'
+ * that deliver a person's turn: Teams rooms, terminals, apps). */
+export const PERSON_PROMPT_SOURCES = Object.freeze([
+	"typed",
+	"queued",
+	"sdk",
+	"user",
+	"human",
+	"terminal",
+	"api",
+	"room",
+	"app",
+]);
+
+/** Metadata a host stamps on a turn it delivered for an authenticated person. */
+const PERSON_ATTRIBUTION_KEYS = Object.freeze([
+	"source_via",
+	"source_principal_id",
+	"source_name",
+]);
+
+/** Attachment subtypes that are an envelope the runtime built around a file
+ * body. `attachmentType` is Claude Code's subtype, kept by the session loader. */
+const CONTEXT_ATTACHMENT_TYPES = new Set(["file", "edited_text_file", "nested_memory"]);
+
+/** Claude's reserved interruption notices, persisted as unmarked user records. */
+export const CLAUDE_INTERRUPTION_TEXTS = Object.freeze([
+	"[Request interrupted by user]",
+	"[Request interrupted by user for tool use]",
+]);
+
+/** The openers of user-role records the harness or host writes with no marker. */
+const HARNESS_FRAMES = Object.freeze([
+	/^<(?:command-name|command-message|local-command-[a-z]+|bash-input|bash-stdout|bash-stderr)>/,
+	/^<(?:system-reminder|environment_context|user_instructions|user_info|hook_prompt|supercode-notice)\b/,
+	/^(?:# )?(?:AGENTS|CLAUDE)\.md instructions for .+\n\n<INSTRUCTIONS>/,
+	/^<recommended_plugins>[\s\S]*<\/recommended_plugins>\s*(?:# )?(?:AGENTS|CLAUDE)\.md instructions for .+\n\n<INSTRUCTIONS>/,
+	/^\[Cross-session [a-z ]*notice\]/i,
+	/^\[edited file:/,
+]);
+const TASK_NOTIFICATION_OPENER = "<task-notification>";
+
+const TURN_INTERRUPTED_NOTICE = "Turn interrupted.";
+const NOTICE_FIELD_CHARACTERS = 200;
+
+// The loader keeps flags as "true"; a host that kept the native boolean is read the same.
+const flag = (metadata, key) =>
+	metadata?.[key] === "true" || metadata?.[key] === true;
+const object = (value) =>
+	value !== null && typeof value === "object" && !Array.isArray(value);
+
+/** Whether a host delivered this turn for an authenticated person. */
+export function isPersonAttributed(metadata) {
+	return PERSON_ATTRIBUTION_KEYS.some((key) => metadata?.[key] != null);
+}
+
+/** Whether the record carries a person's marker (rule step 1). */
+export function isPersonMarked(metadata) {
+	if (!metadata) return false;
+	return (
+		isPersonAttributed(metadata) ||
+		Object.keys(metadata).some((key) => key.startsWith("codex_typed_user")) ||
+		PERSON_PROMPT_SOURCES.includes(metadata.promptSource) ||
+		metadata.origin === "human" ||
+		metadata.commandMode === "prompt"
+	);
+}
+
+const taskNotificationMarked = (metadata) =>
+	metadata?.origin === "task-notification" ||
+	metadata?.commandMode === "task-notification";
+
+/** Whether the record carries a harness marker (rule step 2). */
+export function isHarnessMarked(metadata) {
+	if (!metadata) return false;
+	return (
+		taskNotificationMarked(metadata) ||
+		metadata.promptSource === "system" ||
+		flag(metadata, "isMeta") ||
+		flag(metadata, "isSynthetic") ||
+		flag(metadata, "isCompactSummary") ||
+		flag(metadata, "isSidechain") ||
+		flag(metadata, "toolResult") ||
+		CONTEXT_ATTACHMENT_TYPES.has(metadata.attachmentType)
+	);
+}
+
+/** Whether `text` is, in full, one of Claude's reserved interruption notices. */
+export function isClaudeInterruption(text) {
+	return typeof text === "string" && CLAUDE_INTERRUPTION_TEXTS.includes(text.trim());
+}
+
+/** Whether `text` opens with a frame the harness or host writes its unmarked
+ * user-role records with (rule step 3; a task notification included). */
+export function isHarnessFrame(text) {
+	if (typeof text !== "string") return false;
+	const body = text.trimStart();
+	return (
+		body.startsWith(TASK_NOTIFICATION_OPENER) ||
+		HARNESS_FRAMES.some((frame) => frame.test(body))
+	);
+}
+
+function taskNotice(text) {
+	const tag = (name) => {
+		const value =
+			new RegExp(`<${name}>([\\s\\S]*?)</${name}>`).exec(text)?.[1]?.trim() ?? "";
+		return [...value].length <= NOTICE_FIELD_CHARACTERS
+			? value
+			: `${[...value].slice(0, NOTICE_FIELD_CHARACTERS - 1).join("")}…`;
+	};
+	const summary = tag("summary"),
+		status = tag("status");
+	return `Background task${status ? ` ${status}` : ""}${summary ? `: ${summary}` : ""}`;
+}
+
+/**
+ * The provenance of one user-role record: `metadata` is the string map the
+ * session loader keeps (or `claudeRecordProvenance` reads from a native record);
+ * `text` is the record's text. `source` is `"person"` for the person's own words
+ * and `"harness"` for a record the harness wrote; `notice` is the short plain-text
+ * line a reader shows in place of a harness record, where one is shown at all
+ * (each renderer styles it; none shows the record's own text).
+ * @param {Record<string, string> | null | undefined} metadata
+ * @param {string} [text]
+ * @returns {{ source: "person" | "harness", notice?: string }}
+ */
+export function userProvenance(metadata, text = "") {
+	const body = typeof text === "string" ? text : "";
+	if (isPersonMarked(metadata)) return { source: "person" };
+	if (taskNotificationMarked(metadata))
+		return { source: "harness", notice: taskNotice(body) };
+	if (isHarnessMarked(metadata)) return { source: "harness" };
+	if (body.trimStart().startsWith(TASK_NOTIFICATION_OPENER))
+		return { source: "harness", notice: taskNotice(body) };
+	if (isClaudeInterruption(body))
+		return { source: "harness", notice: TURN_INTERRUPTED_NOTICE };
+	if (isHarnessFrame(body)) return { source: "harness" };
+	return { source: "person" };
+}
+
+/** Whether a user-role record is the harness's own, not the person's words. */
+export function isHarnessAuthoredUser(metadata, text = "") {
+	return userProvenance(metadata, text).source === "harness";
+}
+
+/**
+ * The rule's metadata read from one whole native Claude Code `user` record, as
+ * the stream-json door emits it or the transcript stores it. Reads the record,
+ * never one content block of it: the stamps sit beside `message`.
+ * @param {unknown} record
+ * @returns {Record<string, string>}
+ */
+export function claudeRecordProvenance(record) {
+	const metadata = {};
+	if (!object(record)) return metadata;
+	if (typeof record.promptSource === "string")
+		metadata.promptSource = record.promptSource;
+	for (const key of ["isMeta", "isSynthetic", "isCompactSummary", "isSidechain"])
+		if (record[key] === true) metadata[key] = "true";
+	if (typeof record.parent_tool_use_id === "string")
+		metadata.isSidechain = "true";
+	if (object(record.origin) && typeof record.origin.kind === "string")
+		metadata.origin = record.origin.kind;
+	const content = object(record.message) ? record.message.content : undefined;
+	if (
+		Object.hasOwn(record, "toolUseResult") ||
+		Object.hasOwn(record, "tool_use_result") ||
+		(Array.isArray(content) &&
+			content.some((block) => object(block) && block.type === "tool_result"))
+	)
+		metadata.toolResult = "true";
+	return metadata;
+}