@subshell-ai/plugin-claude-code 3.1.0 → 3.1.2

package/dist/index.d.ts

@@ -1,19 +1,24 @@
-//#region ../../plugin-api/dist/types-D6R-hjGN.d.ts
-//#region src/types.d.ts
+//#region ../../plugin-api/dist/types-DPriUYLa.d.ts
+/** 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";
 /**
- * The contract a Subshell plugin implements.
- *
- * A plugin is loaded from disk by a compiled binary, which means it CANNOT
- * import anything of ours at runtime. Measured on bun 1.4.2: a bare specifier
- * from a plugin file fails to resolve, because there is no `node_modules`
- * beside it. Everything a plugin needs therefore arrives through
- * {@link PluginHost}, handed to the factory it default-exports.
- *
- * This package is types plus PURE helpers only. A plugin bundles it in at
- * build time, so anything with runtime behaviour would freeze at the version
- * the plugin was built against; a filesystem probe that did that would keep
- * searching last year's install locations forever. Those belong on the host.
+ * What a plugin declares about its harness's child agents. The host uses
+ * `discovery`/`navigation` to decide what the sidebar may offer; `setup`, when
+ * the harness needs a one-time human act (trusting hooks, installing an
+ * extension), is the copy the preset editor shows for that act.
  */
+interface HarnessSubagentSupport {
+  /** How subagent lifecycle events reach Subshell */
+  discovery: HarnessSubagentDiscovery;
+  /** Whether subshell may navigate the parent's own view to a child */
+  navigation: HarnessSubagentNavigation;
+  /** One-time user action required for reporting to work, if any */
+  setup?: string;
+}
+//#endregion
+//#region src/types.d.ts
 /**
  * What kind of thing a plugin provides.
  *
@@ -38,7 +43,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" | "publish" | "supervise" | "guard" | "settings";
+type PluginCapability = "mcp" | "resume" | "attention" | "subagents" | "publish" | "supervise" | "guard" | "settings";
 /** A harness preset as defined by the user (decoded JSON blobs). */
 interface PresetDefinition {
   /** Human-friendly preset name */
@@ -175,14 +180,25 @@ interface McpLaunchSpec {
 }
 /** Per-subshell MCP registration rendered in the plugin's own config dialect. */
 interface McpRegistration {
+  /**
+   * Companion integration modules written next to the config file, under
+   * `<configPath>.d/`. Keys are basenames only, and the host refuses a name
+   * outside `[A-Za-z0-9_-]+\.(mjs|py|json)`, more than eight files, or more
+   * than 64 KiB of content — by throwing at launch, so the registration must
+   * stay inside those rules. Each file ships self-contained: on a pane's
+   * machine nothing of ours is importable (see the package doc).
+   */
+  files?: Record<string, string>;
   /** File content the harness reads, written to the subshell's config path */
   fileContent: string;
   /** argv the harness needs to load the file (e.g. claude's ["--mcp-config", path]) */
   args?: string[];
   /**
    * Extra pane env the harness needs to discover the file (e.g. OPENCODE_CONFIG).
-   * Consumed by the HOST, which bakes it into the pane env ahead of preset env;
-   * plugins never read it back.
+   * Consumed by the HOST, which layers it AFTER preset env in the pane's
+   * environment: the wiring wins on purpose, so the harness always finds the
+   * config this launch wrote even when a preset sets the same name. Plugins
+   * never read it back.
    */
   env?: Record<string, string>;
 }
@@ -362,6 +378,8 @@ interface PluginSecrets {
  * plugin is a binary and an argv rather than eight stubs.
  */
 interface SubshellPlugin {
+  /** Native child-agent reporting and optional in-place navigation. */
+  subagents?: HarnessSubagentSupport;
   /** Builds the argv (no shell) used to launch a subshell. */
   buildCommand(input: BuildCommandInput): string[];
   /** Validates a preset definition before saving. */
@@ -379,6 +397,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. */
@@ -395,8 +426,15 @@ interface SubshellPlugin {
    * then surfaces one-time manual setup via {@link mcpSetup} instead.
    */
   mcpRegistration?(launch: McpLaunchSpec, configPath: string): McpRegistration;
-  /** How users obtain the subshell MCP tools here. Declare the `mcp` capability with it. */
-  mcpSetup?(launch: McpLaunchSpec): McpSetupInfo;
+  /**
+   * How users obtain the subshell MCP tools here. Declare the `mcp`
+   * capability with it. `reporter` is the host-resolved command prefix that
+   * re-enters the subshell binary on a pane's machine (same shape as
+   * {@link BuildCommandInput.reporter}), present only when the host could
+   * resolve one: use it to render hook-configuration steps, and omit those
+   * steps when it is absent rather than guessing a binary name.
+   */
+  mcpSetup?(launch: McpLaunchSpec, reporter?: ReporterSpec): McpSetupInfo;
   /** Settings rendered in the PRESET editor and stored on the preset. */
   presetSettings?(): SettingsField[];
   /** Known extra env var suggestions for the preset editor. */
@@ -617,6 +655,18 @@ interface SubshellManifest {
   hostEnv?: string[];
   /** Network facts. Present exactly when `type` is `network`. */
   network?: NetworkManifest;
+  /**
+   * False means the launch pickers must not offer this plugin, even though
+   * it drives a pane. Absent means true.
+   *
+   * The declaration belongs to the plugin because only it knows whether a
+   * bare launch means something: a harness whose useful launch needs inputs
+   * no picker carries (SSH needs a destination, which the connect form
+   * supplies through its own door) would otherwise be a row that starts a
+   * dying pane. This hides the entry, not the route: the plugin stays
+   * launchable by id for whatever flow does supply the inputs.
+   */
+  pickable?: boolean;
 }
 //#endregion
 //#region src/manifest.d.ts

package/dist/index.js

@@ -1,5 +1,5 @@
 import { join, resolve } from "node:path";
-//#region ../../plugin-api/dist/manifest-DKMceUPh.js
+//#region ../../plugin-api/dist/manifest-XGvw0ugx.js
 /** Every {@link PluginType}, for anything that has to iterate or validate them. */
 const PLUGIN_TYPES = [
 	"agent-harness",
@@ -135,6 +135,7 @@ function parseManifest(pkgJson) {
 		const icon = block.icon;
 		if (!ICON_EXTENSIONS.some((ext) => icon.endsWith(ext))) return { error: `\`subshell.icon\` must end in one of: ${ICON_EXTENSIONS.join(", ")}` };
 	}
+	if (block.pickable !== void 0 && typeof block.pickable !== "boolean") return { error: "`subshell.pickable` must be a boolean when present" };
 	if (typeof block.entry !== "string" || block.entry.trim() === "") return { error: "`subshell.entry` must be a non-empty relative path" };
 	if (block.entry.startsWith("/") || block.entry.split("/").includes("..")) return { error: "`subshell.entry` must stay inside the package (no leading `/` and no `..` segment)" };
 	let detect;
@@ -177,7 +178,8 @@ function parseManifest(pkgJson) {
 		...detect ? { detect } : {},
 		...install ? { install } : {},
 		...hostEnv ? { hostEnv } : {},
-		...parsedNetwork ? { network: parsedNetwork } : {}
+		...parsedNetwork ? { network: parsedNetwork } : {},
+		...block.pickable === false ? { pickable: false } : {}
 	};
 }
 /**
@@ -284,7 +286,7 @@ function validateGenericPreset(preset) {
 const parsed = parseManifest({
 	name: "@subshell-ai/plugin-claude-code",
 	description: "Claude Code harness plugin for Subshell",
-	version: "3.1.0",
+	version: "3.1.2",
 	license: "Apache-2.0",
 	type: "module",
 	main: "dist/index.js",
@@ -307,14 +309,14 @@ const parsed = parseManifest({
 		"lint": "biome check --write --unsafe src && biome format src --write && biome lint src --fix",
 		"lint:check": "biome check --no-errors-on-unmatched src",
 		"lint:staged": "biome check --no-errors-on-unmatched --write --unsafe --staged src",
-		"test": "bun test",
+		"test": "bash \"$(git rev-parse --show-toplevel)/scripts/par-test.sh\" 4 bun test",
 		"verify-types": "tsc --project tsconfig.json --noEmit"
 	},
 	devDependencies: {
 		"@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"
 	},
@@ -554,16 +556,27 @@ 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`).
-* - `UserPromptSubmit` / `PreToolUse` — 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 for you" for its whole
-*   next turn (2026-09-24). The pane knows better: work has resumed when the
-*   human's prompt is submitted, AND when a tool starts after an approval
-*   answered in the dialog (approving is not a prompt, so
-*   UserPromptSubmit alone misses that path). PreToolUse fires on every tool
-*   call; the endpoint's clear is conditional, so the common stamp-less case
-*   is a silent no-op. Neither hook's stdin is read — their payloads are the
-*   prompt text and the tool input, and the report is only ever the fact.
+*   `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
+*   for you" for its whole next turn (2026-09-24). The pane knows better:
+*   work has resumed when the human's prompt is submitted, AND when a tool
+*   starts after an approval answered in the dialog (approving is not a
+*   prompt, so UserPromptSubmit alone misses that path). PreToolUse fires on
+*   every tool call; the endpoint's clear is conditional, so the common
+*   stamp-less case is a silent no-op. Neither of these two reads its stdin:
+*   their payloads are the prompt text and the tool input, and the report is
+*   only ever the fact.
+* - `PreToolUse` with `Agent|Task` — subagent spawn labels. Claude's
+*   SubagentStart payload has no description field, but the spawn's tool
+*   input does, so this second entry runs the same `report subagents` verb,
+*   which forwards names and descriptions, never prompts or commands.
 * - `SessionStart` — conversation identity. The restart-resume pin
 *   (`--session-id` at launch) only survives while the pane keeps that ONE
 *   conversation, but /clear, /resume <other> and /fork start a DIFFERENT
@@ -573,10 +586,21 @@ const reporterHook = (host, reporter, ...verb) => [
 *   and reads stdin like `Stop` now does — the reporter forwards `session_id`
 *   from that payload and nothing else.
 */
-const attentionHooks = (host, reporter) => ({
+const paneHooks = (host, reporter) => ({
+	SubagentStart: [{ hooks: [{
+		type: "command",
+		command: reporterHook(host, reporter, "subagents")
+	}] }],
+	SubagentStop: [{ hooks: [{
+		type: "command",
+		command: reporterHook(host, reporter, "subagents")
+	}] }],
 	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",
@@ -592,10 +616,26 @@ const attentionHooks = (host, reporter) => ({
 	PreToolUse: [{ hooks: [{
 		type: "command",
 		command: reporterHook(host, reporter, "attention", "resumed")
-	}] }],
+	}] }, {
+		matcher: "Agent|Task",
+		hooks: [{
+			type: "command",
+			command: reporterHook(host, reporter, "subagents")
+		}]
+	}],
+	PostToolUse: [{
+		matcher: "Agent|Task",
+		hooks: [{
+			type: "command",
+			command: reporterHook(host, reporter, "subagents")
+		}]
+	}],
 	SessionStart: [{ hooks: [{
 		type: "command",
 		command: reporterHook(host, reporter, "session")
+	}, {
+		type: "command",
+		command: reporterHook(host, reporter, "subagents")
 	}] }]
 });
 /** Claude's transcript folder name for a project dir: every non-alphanumeric → `-`. */
@@ -603,6 +643,16 @@ 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;
+/**
 * Built-in harness: Claude Code.
 *
 * Launch shape:
@@ -620,12 +670,19 @@ function projectSlug(cwd) {
 * `@subshell-ai/plugin-api`.
 */
 const createPlugin = (host) => ({
+	subagents: {
+		discovery: "hooks",
+		navigation: "unavailable"
+	},
 	capabilities: () => [
+		"subagents",
 		"mcp",
 		"resume",
 		"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>`)
@@ -657,8 +714,8 @@ const createPlugin = (host) => ({
 		if (mcp?.args) args.push(...mcp.args);
 		if (harnessSession) args.push(harnessSession.mode === "resume" ? "--resume" : "--session-id", harnessSession.id);
 		const settings = { ...preset.settings ?? {} };
-		if (reporter) settings.hooks = attentionHooks(host, reporter);
-		else host.log.warn("no reporter resolved for this launch: attention and conversation-identity hooks are omitted");
+		if (reporter) settings.hooks = paneHooks(host, reporter);
+		else host.log.warn("no reporter resolved for this launch: attention, conversation-identity, and subagent-roster hooks are omitted");
 		if (Object.keys(settings).length > 0) args.push("--settings", JSON.stringify(settings));
 		if (subshellName) args.push("--name", subshellName);
 		for (const flag of preset.flags) args.push(flag);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@subshell-ai/plugin-claude-code",
   "description": "Claude Code harness plugin for Subshell",
-  "version": "3.1.0",
+  "version": "3.1.2",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/index.js",
@@ -28,14 +28,14 @@
     "lint": "biome check --write --unsafe src && biome format src --write && biome lint src --fix",
     "lint:check": "biome check --no-errors-on-unmatched src",
     "lint:staged": "biome check --no-errors-on-unmatched --write --unsafe --staged src",
-    "test": "bun test",
+    "test": "bash \"$(git rev-parse --show-toplevel)/scripts/par-test.sh\" 4 bun test",
     "verify-types": "tsc --project tsconfig.json --noEmit"
   },
   "devDependencies": {
     "@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"
   },