@subshell-ai/plugin-codex 1.0.0 → 1.0.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-CW2dMAMW.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. */
@@ -395,8 +413,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 +642,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
@@ -639,13 +676,18 @@ declare const manifest: SubshellManifest;
  * (a user may put it in their own preset flags — that is their call).
  *
  * subshell MCP is wired automatically WITHOUT touching user state: every
- * launch carries `-c mcp_servers.subshell.command=… -c mcp_servers.subshell.args=…`
+ * launch carries `-c mcp_servers.subshell.command=…`,
+ * `-c mcp_servers.subshell.args=…` and `-c mcp_servers.subshell.env_vars=…`
  * config overrides (dotted path, value parsed as TOML — verified against the
  * real binary), which codex merges over ~/.codex/config.toml for that run
- * only. No config file the harness must read, no CODEX_HOME redirect (that
- * dir holds the user's auth.json). The spawned `subshell mcp` child inherits
- * the subshell's baked SUBSHELL_* pane env for its credential, like every
- * harness.
+ * only. The subagent monitoring hooks ride the same mechanism as
+ * `hooks.SubagentStart/SubagentStop/SessionStart` overrides, so a user's own
+ * `hooks.*` table is REPLACED for the duration of a subshell-launched run —
+ * the documented limitation, same shape as claude-code's; nothing on disk
+ * changes. No config file the harness must read, no CODEX_HOME redirect (that
+ * dir holds the user's auth.json). The spawned `subshell mcp` child needs the
+ * pane's SUBSHELL_* identity, and Codex filters a child's environment, so the
+ * env_vars override re-forwards those names (never values) at each launch.
  * (Flags/values verified against @openai/codex 2026-09 help output.)
  *
  * Identity, detection and install guidance live in this package's

package/dist/index.js

@@ -1,4 +1,4 @@
-//#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",
@@ -134,6 +134,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;
@@ -176,7 +177,8 @@ function parseManifest(pkgJson) {
 		...detect ? { detect } : {},
 		...install ? { install } : {},
 		...hostEnv ? { hostEnv } : {},
-		...parsedNetwork ? { network: parsedNetwork } : {}
+		...parsedNetwork ? { network: parsedNetwork } : {},
+		...block.pickable === false ? { pickable: false } : {}
 	};
 }
 /**
@@ -283,7 +285,7 @@ function validateGenericPreset(preset) {
 const parsed = parseManifest({
 	name: "@subshell-ai/plugin-codex",
 	description: "Codex harness plugin for Subshell",
-	version: "1.0.0",
+	version: "1.0.2",
 	license: "Apache-2.0",
 	type: "module",
 	main: "dist/index.js",
@@ -306,7 +308,7 @@ 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: {
@@ -346,6 +348,14 @@ if ("error" in parsed) throw new Error(`@subshell-ai/plugin-codex has an invalid
 const manifest = parsed;
 //#endregion
 //#region src/index.ts
+const MCP_ENV_VARS = [
+	"SUBSHELL_API_KEY",
+	"SUBSHELL_BASE_URL",
+	"SUBSHELL_ID",
+	"SUBSHELL_NAME",
+	"SUBSHELL_DATA_DIR",
+	"SUBSHELL_SERVER_DATA_DIR"
+];
 /** Known Codex settings, applied as per-invocation CLI flags. */
 const CODEX_SETTINGS_FIELDS = [
 	{
@@ -415,13 +425,18 @@ function tomlStringArray(values) {
 * (a user may put it in their own preset flags — that is their call).
 *
 * subshell MCP is wired automatically WITHOUT touching user state: every
-* launch carries `-c mcp_servers.subshell.command=… -c mcp_servers.subshell.args=…`
+* launch carries `-c mcp_servers.subshell.command=…`,
+* `-c mcp_servers.subshell.args=…` and `-c mcp_servers.subshell.env_vars=…`
 * config overrides (dotted path, value parsed as TOML — verified against the
 * real binary), which codex merges over ~/.codex/config.toml for that run
-* only. No config file the harness must read, no CODEX_HOME redirect (that
-* dir holds the user's auth.json). The spawned `subshell mcp` child inherits
-* the subshell's baked SUBSHELL_* pane env for its credential, like every
-* harness.
+* only. The subagent monitoring hooks ride the same mechanism as
+* `hooks.SubagentStart/SubagentStop/SessionStart` overrides, so a user's own
+* `hooks.*` table is REPLACED for the duration of a subshell-launched run —
+* the documented limitation, same shape as claude-code's; nothing on disk
+* changes. No config file the harness must read, no CODEX_HOME redirect (that
+* dir holds the user's auth.json). The spawned `subshell mcp` child needs the
+* pane's SUBSHELL_* identity, and Codex filters a child's environment, so the
+* env_vars override re-forwards those names (never values) at each launch.
 * (Flags/values verified against @openai/codex 2026-09 help output.)
 *
 * Identity, detection and install guidance live in this package's
@@ -430,11 +445,32 @@ function tomlStringArray(values) {
 *
 * `host` carries what this module cannot import. See `@subshell-ai/plugin-api`.
 */
-const createPlugin = (_host) => ({
-	capabilities: () => ["mcp", "settings"],
+const createPlugin = (host) => ({
+	subagents: {
+		discovery: "hooks",
+		navigation: "unavailable",
+		setup: "Review the Subshell subagent monitoring hooks in /hooks and trust them to show active subagents in the sidebar."
+	},
+	capabilities: () => [
+		"subagents",
+		"mcp",
+		"settings"
+	],
 	buildCommand(input) {
 		const { binary, preset, extraFlags, mcp } = input;
 		const args = [binary];
+		if (input.reporter) {
+			const command = [
+				input.reporter.command,
+				...input.reporter.args,
+				"subagents"
+			].map(host.shellQuote).join(" ");
+			for (const event of [
+				"SubagentStart",
+				"SubagentStop",
+				"SessionStart"
+			]) args.push("-c", `hooks.${event}=[{hooks=[{type="command",command=${JSON.stringify(command)},statusMessage="Subshell subagent monitoring",timeout=2}]}]`);
+		}
 		const s = preset.settings ?? {};
 		if (typeof s.model === "string" && s.model) args.push("-m", s.model);
 		if (typeof s.sandbox === "string" && s.sandbox) args.push("-s", s.sandbox);
@@ -464,13 +500,16 @@ const createPlugin = (_host) => ({
 				`[mcp_servers.${MCP_SERVER_NAME}]`,
 				`command = ${tomlString(launch.command)}`,
 				`args = ${tomlStringArray(launch.args)}`,
+				`env_vars = ${tomlStringArray(MCP_ENV_VARS)}`,
 				""
 			].join("\n"),
 			args: [
 				"-c",
 				`mcp_servers.${MCP_SERVER_NAME}.command=${tomlString(launch.command)}`,
 				"-c",
-				`mcp_servers.${MCP_SERVER_NAME}.args=${tomlStringArray(launch.args)}`
+				`mcp_servers.${MCP_SERVER_NAME}.args=${tomlStringArray(launch.args)}`,
+				"-c",
+				`mcp_servers.${MCP_SERVER_NAME}.env_vars=${tomlStringArray(MCP_ENV_VARS)}`
 			],
 			env: void 0
 		};
@@ -479,7 +518,7 @@ const createPlugin = (_host) => ({
 	mcpSetup(_launch) {
 		return {
 			mode: "auto",
-			summary: "Subshell registers itself with every Codex subshell automatically (per-invocation -c mcp_servers.subshell.* overrides; your ~/.codex config is never modified)."
+			summary: "Subshell registers itself with every Codex subshell automatically (per-invocation -c mcp_servers.subshell.* overrides; your ~/.codex config is never modified). The same overrides carry the subagent monitoring hooks, so a hooks.* you set in ~/.codex is replaced FOR THAT RUN only, and nothing on disk changes."
 		};
 	},
 	validatePreset(preset) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@subshell-ai/plugin-codex",
   "description": "Codex harness plugin for Subshell",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/index.js",
@@ -28,7 +28,7 @@
     "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": {