@subshell-ai/plugin-claude-code 3.1.1 → 3.1.3

package/dist/index.d.ts

@@ -1,8 +1,104 @@
-//#region ../../plugin-api/dist/types-CW2dMAMW.d.ts
+//#region ../../plugin-api/dist/types-D2qRfuN_.d.ts
+//#region src/previews.d.ts
+/**
+ * How a harness reports loopback ports its own tooling started, for the
+ * preview picker.
+ *
+ * Port discovery attributes sockets by walking the pane's process tree. A
+ * harness that brokers its tool shells through a shared daemon (oh-my-pi
+ * does) leaves that tree, so a server its tools start is reachable but
+ * invisible. A plugin that declares the `previews` capability ships a
+ * reporter the control plane can list those ports from.
+ *
+ * The report carries ports only, never a host: the node dials loopback, so a
+ * report cannot point the proxy at another machine.
+ */
+type HarnessPreviewReporting = "extension" | "hooks";
+/**
+ * What a harness declares about its preview reporting. The rules mirror
+ * {@link HarnessSubagentSupport}: `reporting` is checked against the union at
+ * load, and `setup` is the copy the preset editor shows when a human act is
+ * needed before reports start.
+ */
+interface HarnessPreviews {
+  /** How reports reach the plane: a per-launch extension, or harness lifecycle hooks. */
+  reporting: HarnessPreviewReporting;
+  /** One-time human action required for reporting to work, if any. */
+  setup?: string;
+}
+//#endregion
+//#region src/subagents.d.ts
+/** What a reported agent is doing, as the harness itself says. */
+type HarnessSubagentStatus = "running" | "waiting" | "idle";
+/** A harness agent belongs to an existing terminal, never to a new subshell. */
+interface HarnessSubagent {
+  /** Harness-side identifier; unique among this parent's current children */
+  id: string;
+  /** Parent agent within the harness, when the harness nests */
+  parentId?: string;
+  /** Display name as the harness reports it; generic ones render numbered */
+  name: string;
+  /** What the harness says this agent is doing */
+  status: HarnessSubagentStatus;
+  /**
+   * The harness's own one-line label for what this child was asked to do,
+   * when the harness has one to give. The host bounds it and normalizes it
+   * like a name; it is the harness's summary of the task, never the prompt
+   * text or anything read from the child's transcript.
+   */
+  activity?: string;
+}
+/**
+ * A reported child as the control plane SERVES it: what the harness said, plus
+ * the server's own observation of when the child appeared. Viewers derive
+ * elapsed time from that stamp against their own clock, so a roster that
+ * stopped being polled ages honestly instead of freezing at its last read.
+ */
+interface HarnessSubagentView extends HarnessSubagent {
+  /** Epoch milliseconds of when the server first saw this child; never sent by a harness */
+  startedAt: number;
+}
 /** How the plugin learns about children: harness lifecycle hooks, or a loaded extension. */
 type HarnessSubagentDiscovery = "hooks" | "extension";
 /** Whether the sidebar can move the parent's own view to a child, or the harness keeps that in-app. */
 type HarnessSubagentNavigation = "native" | "unavailable";
+/**
+ * Pane operations the host hands an integration that drives its harness's
+ * own agent picker. The plugin runs in the control plane, so it cannot open a
+ * terminal itself; these are the only two acts it needs, and neither submits
+ * a prompt on its own.
+ */
+interface HarnessSubagentPane {
+  /** The parent pane's current screen with ANSI stripped, exactly as painted. */
+  read(): Promise<string>;
+  /**
+   * Type raw bytes into the pane's own input. Nothing is appended or
+   * translated: send `\r` for Enter, `\u001b[1;3D` for Alt+Left, and so on.
+   */
+  type(text: string): Promise<void>;
+}
+/** What the host hands an integration's {@link HarnessSubagentSupport.select}. */
+interface HarnessSubagentSelectInput {
+  /** The child to show, or null to return the parent itself */
+  agentId: string | null;
+  /** The roster the child came from, server-stamped and bounded */
+  agents: readonly HarnessSubagentView[];
+  /** The parent terminal this selection must happen in */
+  pane: HarnessSubagentPane;
+}
+/** What the integration must report back after the harness actually switched. */
+interface HarnessSubagentSelectResult {
+  /** The view the harness showed when the act finished; null for the parent */
+  selectedId: string | null;
+}
+/**
+ * An integration's own way to move its terminal's view. This is for harnesses
+ * whose picker or inspector exists only inside their TUI (Codex's `/subagents`,
+ * Claude's agent panel, pi's fleet inspector): the integration reads the pane,
+ * sends the harness's own keys, and reports the view it verified. Extensions
+ * without a pane driver keep using the report-loop command.
+ */
+type HarnessSubagentSelect = (input: HarnessSubagentSelectInput) => Promise<HarnessSubagentSelectResult>;
 /**
  * What a plugin declares about its harness's child agents. The host uses
  * `discovery`/`navigation` to decide what the sidebar may offer; `setup`, when
@@ -16,6 +112,13 @@ interface HarnessSubagentSupport {
   navigation: HarnessSubagentNavigation;
   /** One-time user action required for reporting to work, if any */
   setup?: string;
+  /**
+   * The integration's own pane driver, when it has one. Requires
+   * `navigation: "native"`; the host uses it instead of queueing a command.
+   * Works for hook and extension discovery alike: the host only needs the
+   * pane's read/type, and the edit gate is the same.
+   */
+  select?: HarnessSubagentSelect;
 }
 //#endregion
 //#region src/types.d.ts
@@ -43,7 +146,7 @@ type PluginType = "agent-harness" | "terminal" | "network";
  * and a network plugin claiming `resume` are both refused at load, for the
  * same reason a claimed-but-unimplemented capability is.
  */
-type PluginCapability = "mcp" | "resume" | "attention" | "subagents" | "publish" | "supervise" | "guard" | "settings";
+type PluginCapability = "mcp" | "resume" | "attention" | "subagents" | "previews" | "publish" | "supervise" | "guard" | "settings";
 /** A harness preset as defined by the user (decoded JSON blobs). */
 interface PresetDefinition {
   /** Human-friendly preset name */
@@ -380,6 +483,13 @@ interface PluginSecrets {
 interface SubshellPlugin {
   /** Native child-agent reporting and optional in-place navigation. */
   subagents?: HarnessSubagentSupport;
+  /**
+   * Native preview-port reporting: the harness tells the plane which loopback
+   * ports its tooling serves, so the picker lists servers discovery cannot
+   * attribute to the pane's process tree. Declare the `previews` capability
+   * with it.
+   */
+  previews?: HarnessPreviews;
   /** Builds the argv (no shell) used to launch a subshell. */
   buildCommand(input: BuildCommandInput): string[];
   /** Validates a preset definition before saving. */
@@ -397,6 +507,19 @@ interface SubshellPlugin {
    * used as-is, which is right for every harness that prints just a version.
    */
   parseVersion?(raw: string): string | null;
+  /**
+   * Turns the harness's own terminal title into the subshell name the rail
+   * shows.
+   *
+   * The host removes escape sequences and control bytes and trims the result
+   * before calling this, so `raw` is safe text. Interpret what the title adds
+   * around the session name — a brand, a run-state separator, a cycling
+   * status glyph — and return the name behind it. Return "" when the title
+   * names nothing, and the caller keeps the name the pane already had. Omit
+   * the member when the harness titles its pane with the name the host
+   * supplied, which needs no interpretation.
+   */
+  parsePaneTitle?(raw: string): string;
   /** Overrides manifest-driven detection. Almost no plugin needs this. */
   detect?(): Promise<DetectionResult>;
   /** Restart-resume support. Declare the `resume` capability with it. */
@@ -487,6 +610,24 @@ interface InstallSpec {
    */
   docsUrl: string;
 }
+/**
+ * How this plugin's harness CLI updates itself in place.
+ *
+ * The installer doubles as the updater for every built-in today (`curl … | sh`
+ * and `npm i -g` lines are idempotent), so this is OPTIONAL and falls back to
+ * {@link InstallSpec}. Declare it where the vendor ships a dedicated verb or a
+ * different channel — `claude update`, say — so pressing Update runs the
+ * vendor's own update path rather than reinstalling.
+ *
+ * Like `install.command`, this is a SHELL LINE the host runs through `sh -c`,
+ * on the node that holds the harness, and it may not need privileges.
+ */
+interface UpdateSpec {
+  /** Shell line that updates the CLI in place. */
+  command: string;
+  /** Where the vendor documents it; http(s) only, when present. */
+  docsUrl?: string;
+}
 /** One step an operator must run themselves, because the host may not. */
 interface PrivilegedStep {
   /** What it does, in a few words: "Install the daemon" */
@@ -630,6 +771,11 @@ interface SubshellManifest {
   detect?: DetectSpec;
   /** Install guidance shown when the binary is missing */
   install?: InstallSpec;
+  /**
+   * How the CLI updates itself, when the installer is not the updater.
+   * Absent means `install.command` is the update path too.
+   */
+  update?: UpdateSpec;
   /**
    * Environment variables this plugin computes against (spec 2026-09-10 §5).
    *

package/dist/index.js

@@ -1,5 +1,5 @@
 import { join, resolve } from "node:path";
-//#region ../../plugin-api/dist/manifest-XGvw0ugx.js
+//#region ../../plugin-api/dist/manifest-CrULrf80.js
 /** Every {@link PluginType}, for anything that has to iterate or validate them. */
 const PLUGIN_TYPES = [
 	"agent-harness",
@@ -159,6 +159,19 @@ function parseManifest(pkgJson) {
 			docsUrl: i.docsUrl
 		};
 	}
+	let update;
+	if (block.update !== void 0) {
+		const u = block.update;
+		if (!isRecord(u) || typeof u.command !== "string" || u.command.trim() === "") return { error: "`subshell.update` needs a non-empty command" };
+		if (needsPrivileges(u.command)) return { error: "`subshell.update.command` must not need sudo, doas or pkexec — the host runs it through a shell and has no terminal for a password prompt" };
+		if (u.docsUrl !== void 0) {
+			if (typeof u.docsUrl !== "string" || !isDocsUrl(u.docsUrl)) return { error: "`subshell.update.docsUrl` must be an http(s) URL — it is rendered as a link on an admin page" };
+			update = {
+				command: u.command,
+				docsUrl: u.docsUrl
+			};
+		} else update = { command: u.command };
+	}
 	let hostEnv;
 	if (block.hostEnv !== void 0) {
 		if (!Array.isArray(block.hostEnv) || !block.hostEnv.every((k) => typeof k === "string" && k.trim() !== "")) return { error: "`subshell.hostEnv` must be an array of environment variable names" };
@@ -177,6 +190,7 @@ function parseManifest(pkgJson) {
 		entry: block.entry,
 		...detect ? { detect } : {},
 		...install ? { install } : {},
+		...update ? { update } : {},
 		...hostEnv ? { hostEnv } : {},
 		...parsedNetwork ? { network: parsedNetwork } : {},
 		...block.pickable === false ? { pickable: false } : {}
@@ -286,7 +300,7 @@ function validateGenericPreset(preset) {
 const parsed = parseManifest({
 	name: "@subshell-ai/plugin-claude-code",
 	description: "Claude Code harness plugin for Subshell",
-	version: "3.1.1",
+	version: "3.1.3",
 	license: "Apache-2.0",
 	type: "module",
 	main: "dist/index.js",
@@ -316,7 +330,7 @@ const parsed = parseManifest({
 		"@internal/tsconfig": "workspace:*",
 		"@subshell-ai/plugin-api": "workspace:*",
 		"@types/bun": "1.3.14",
-		"hash-runner": "4.0.0",
+		"hash-runner": "5.0.0",
 		"tsdown": "0.22.14",
 		"typescript": "7.0.2"
 	},
@@ -556,6 +570,12 @@ const reporterHook = (host, reporter, ...verb) => [
 *   answered (spec 2026-09-23). `Stop` reports `turn_complete` blind here:
 *   the reporter reads the hook payload and stays silent for a session
 *   parked on background work (`packages/mcp-core/src/report.ts`).
+*   `Stop` carries a second command, `report subagents`: the turn-end payload
+*   enumerates the harness's live background agents, and the server replaces
+*   its roster with that set. Edge events cannot reconcile it alone — a
+*   background child killed with `TaskStop` fires no lifecycle hook at all,
+*   so its row would pin the rail "running" forever (measured on Claude Code
+*   2.1.296; the rail then only self-heals at the next turn boundary).
 * - `UserPromptSubmit` / `PreToolUse` (the matcher-less entry) — the waiting
 *   CLEAR (`resumed`). The plane's idle-watcher can only clear what it can
 *   stat, so an agent-node pane — log on the node's disk — stayed "waiting
@@ -592,6 +612,9 @@ const paneHooks = (host, reporter) => ({
 	Stop: [{ hooks: [{
 		type: "command",
 		command: reporterHook(host, reporter, "attention", "turn_complete")
+	}, {
+		type: "command",
+		command: reporterHook(host, reporter, "subagents")
 	}] }],
 	Notification: [{
 		matcher: "permission_prompt|agent_needs_input|elicitation_dialog|elicitation_url_dialog",
@@ -634,6 +657,78 @@ function projectSlug(cwd) {
 	return cwd.replace(/[^a-zA-Z0-9]/g, "-");
 }
 /**
+* Claude Code puts a cycling status glyph at the front of its pane title
+* (`✳ Ship the rename feature`, then `✻ …` on the next sweep). The glyph is
+* Claude's run state, not part of the session name, and leaving it in made the
+* mirrored name churn between sweeps. Strip the leading decoration — glyphs,
+* punctuation, and the space after them — so only the task text remains. A
+* title that is nothing but the glyph parses to nothing, and the caller keeps
+* the name it already had.
+*/
+const STATUS_GLYPH = /^[^\p{L}\p{N}]+/u;
+const DOWN = "\x1B[B";
+const UP = "\x1B[A";
+const ENTER = "\r";
+const ESC = "\x1B";
+const CLAUDE_SELECT_MARK = "[>❯]";
+const CLAUDE_STATUS_GLYPH = "[●◉◯○◦•]";
+const CLAUDE_AGENT_ROW = new RegExp(`^\\s*(${CLAUDE_SELECT_MARK})?\\s*(${CLAUDE_STATUS_GLYPH})?\\s*([^\\s·]+)(?:\\s+·\\s+|\\s{2,})`);
+const CLAUDE_MAIN_ROW = new RegExp(`^\\s*(${CLAUDE_SELECT_MARK})?\\s*(${CLAUDE_STATUS_GLYPH})?\\s*main(?:\\s{2,}.*)?\\s*$`);
+function claudePanelRows(screen) {
+	const lines = screen.split("\n");
+	const prompt = lines.findLastIndex((line) => /^\s*❯\s+(?![●◉◯○◦•])/.test(line));
+	return (prompt < 0 ? lines : lines.slice(prompt + 1)).map((line) => {
+		const main = line.match(CLAUDE_MAIN_ROW);
+		if (main) return {
+			name: "main",
+			selected: main[1] === ">" || main[1] === "❯"
+		};
+		const agent = line.match(CLAUDE_AGENT_ROW);
+		return agent ? {
+			name: (agent[3] ?? "").trim(),
+			selected: agent[1] === ">" || agent[1] === "❯"
+		} : void 0;
+	}).filter((row) => row !== void 0 && (row.name === "main" || /^[\p{L}\p{N}_.-]+$/u.test(row.name)));
+}
+async function selectClaudeSubagent(input) {
+	const { agentId, agents, pane } = input;
+	let screen = await pane.read();
+	let rows = claudePanelRows(screen);
+	if (agentId === null) {
+		if (rows.some((row) => row.selected && row.name === "main")) return { selectedId: null };
+		if (!rows.length) {
+			if (!(/main\s*>\s*\S/.test(screen) || agents.some((agent) => screen.includes(agent.name)))) throw new Error("Claude isn't showing an agent view to return from.");
+			await pane.type(ESC);
+			screen = await pane.read();
+			rows = claudePanelRows(screen);
+		}
+		if (!rows.length) throw new Error("Claude isn't showing its agent panel.");
+		if (!rows.some((row) => row.selected)) return { selectedId: null };
+		for (let step = 0; step < rows.length + 2; step++) {
+			if (claudePanelRows(await pane.read()).findIndex((row) => row.selected) === 0) break;
+			await pane.type(UP);
+		}
+		if (!claudePanelRows(await pane.read()).some((row) => row.selected && row.name === "main")) throw new Error("Claude didn't select the main agent in its agent panel.");
+		await pane.type(ENTER);
+		return { selectedId: null };
+	}
+	const target = agents.find((agent) => agent.id === agentId);
+	if (!target) throw new Error("Claude didn't report that subagent.");
+	if (!rows.length) throw new Error("Claude isn't showing its agent panel.");
+	const targetName = target.name.trim();
+	const ordinal = agents.filter((agent) => agent.name.trim() === targetName).findIndex((agent) => agent.id === agentId);
+	const targetRow = rows.flatMap((row, index) => row.name === targetName ? [index] : [])[ordinal] ?? -1;
+	if (targetRow < 0) throw new Error("Claude didn't list that subagent in its agent panel.");
+	for (let step = 0; step < rows.length + 2; step++) {
+		const current = claudePanelRows(await pane.read()).findIndex((row) => row.selected);
+		if (current === targetRow) break;
+		await pane.type(current < 0 || current < targetRow ? DOWN : UP);
+	}
+	if (!claudePanelRows(await pane.read())[targetRow]?.selected) throw new Error("Claude didn't select that subagent in its agent panel.");
+	await pane.type(ENTER);
+	return { selectedId: agentId };
+}
+/**
 * Built-in harness: Claude Code.
 *
 * Launch shape:
@@ -653,7 +748,8 @@ function projectSlug(cwd) {
 const createPlugin = (host) => ({
 	subagents: {
 		discovery: "hooks",
-		navigation: "unavailable"
+		navigation: "native",
+		select: selectClaudeSubagent
 	},
 	capabilities: () => [
 		"subagents",
@@ -662,6 +758,8 @@ const createPlugin = (host) => ({
 		"attention",
 		"settings"
 	],
+	/** Claude Code prefixes its pane title with a cycling status glyph. */
+	parsePaneTitle: (raw) => raw.replace(STATUS_GLYPH, "").trim(),
 	supportsAttentionHooks: true,
 	/**
 	* Restart-resume: conversations are PINNED at start (`--session-id <uuid>`)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@subshell-ai/plugin-claude-code",
   "description": "Claude Code harness plugin for Subshell",
-  "version": "3.1.1",
+  "version": "3.1.3",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/index.js",
@@ -35,7 +35,7 @@
     "@internal/tsconfig": "workspace:*",
     "@subshell-ai/plugin-api": "workspace:*",
     "@types/bun": "1.3.14",
-    "hash-runner": "4.0.0",
+    "hash-runner": "5.0.0",
     "tsdown": "0.22.14",
     "typescript": "7.0.2"
   },