@subshell-ai/plugin-codex 0.2.0 → 1.0.1

package/dist/index.d.ts

@@ -1,32 +1,49 @@
-//#region ../../plugin-api/dist/types-B_wiApwK.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.
  *
  * For humans: it groups and labels in the UI and filters the catalog. Code
  * branches on {@link PluginCapability} instead, so adding a type here touches
  * labels while adding a capability touches the launch pipeline.
+ *
+ * ONE exception, and it is structural rather than a branch on a label: a
+ * `network` plugin implements {@link NetworkPlugin} instead of
+ * {@link SubshellPlugin}, so the loader picks WHICH members to require by
+ * type. A harness drives a thing in a pane; a network plugin connects this
+ * host to one network. They share the store, the manifest and the capability
+ * vocabulary, and nothing else.
  */
-type PluginType = "agent-harness" | "terminal";
+type PluginType = "agent-harness" | "terminal" | "network";
 /**
  * What a plugin can DO. The launch pipeline and the UI read this; neither
  * branches on {@link PluginType}.
+ *
+ * The union is shared across types and the applicable SUBSET is not, so
+ * {@link capabilityMismatches} takes the type: a harness claiming `publish`
+ * 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" | "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 */
@@ -163,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>;
 }
@@ -202,10 +230,23 @@ interface SettingsField {
   label: string;
   /** Short description for the editor */
   description?: string;
-  /** One of: string, boolean, number, select */
-  type: "string" | "boolean" | "number" | "select";
+  /**
+   * One of: string, boolean, number, select, secret.
+   *
+   * `secret` is WRITE-ONLY and network-only: the host stores it through
+   * {@link PluginHost.secrets} rather than in the settings object, reads
+   * report only whether one is set, and a plugin never receives the value —
+   * it names the secret and the host hydrates it into a process it spawns
+   * ({@link SupervisedProcessSpec}). The preset editor does not render this
+   * type; a harness declaring one is a bug rather than a second secret store.
+   */
+  type: "string" | "boolean" | "number" | "select" | "secret";
   /** Choices when type === "select" */
   choices?: string[];
+  /** True when the field must be set before the plugin can act */
+  required?: boolean;
+  /** Placeholder / example, shown in the editor. Never a real credential. */
+  placeholder?: string;
   /** Default value when unset */
   default?: string | boolean | number;
 }
@@ -248,6 +289,86 @@ interface PluginHost {
     debug(message: string): void;
     warn(message: string): void;
   };
+  /**
+   * Runs a command to completion under the host's bounds and reports it.
+   *
+   * The one way a plugin executes anything. A plugin does not spawn: the host
+   * owns the deadline, the environment allowlist (the process's own
+   * environment holds the auth secret and the database path, and is never
+   * handed over), the PATH a service-run server would otherwise lack, and the
+   * output cap. Two refusals throw rather than returning a result, because
+   * both are bugs in the plugin rather than outcomes: `argv[0]` that is not an
+   * ABSOLUTE path (resolve it with {@link findBinary} — a bare name would
+   * resolve against a PATH the plugin cannot see), and `argv[0]` that is
+   * `sudo`. The server has no terminal to answer a password prompt, so a
+   * privileged command is a copy-paste instruction for the operator and never
+   * something this runs.
+   *
+   * Long-running processes are NOT this: a plugin that needs one describes it
+   * ({@link SupervisedProcessSpec}) and the host supervises it.
+   * @since apiVersion 2
+   */
+  run(argv: string[], opts?: RunOptions): Promise<RunResult>;
+  /**
+   * Write-only credential storage, scoped to this plugin.
+   *
+   * There is deliberately NO `get`. A plugin that could read a credential
+   * could put it in an argv (visible in `ps`), a log line or a hint string;
+   * every legitimate consumer is a process the HOST spawns, so the host
+   * hydrates the value itself from the name the plugin gives it. Values are
+   * stored 0600 under the host's data directory, never in the database and
+   * never in a settings row.
+   * @since apiVersion 2
+   */
+  secrets: PluginSecrets;
+  /** The operating system this host runs on. */
+  readonly platform: PluginPlatform;
+  /** The home directory of the user this host runs as. */
+  readonly homeDir: string;
+}
+/** Where a plugin can be driven at all. Mirrors the manifest's `platforms`. */
+type PluginPlatform = "darwin" | "linux";
+/** Options for {@link PluginHost.run}. */
+interface RunOptions {
+  /** Deadline in milliseconds. Default 30_000; the host caps it at 10 minutes. */
+  timeoutMs?: number;
+  /** Called per output line, ANSI already stripped, from both streams interleaved. */
+  onLine?: (line: string) => void;
+  /**
+   * Ends the run early without failing it.
+   *
+   * What an interactive login needs: `tailscale up` with no key blocks until a
+   * human finishes in a browser, having already printed the URL — so the
+   * plugin reads the URL off {@link onLine} and aborts, leaving the daemon
+   * waiting. An aborted run reports `aborted: true` and whatever was captured.
+   */
+  signal?: AbortSignal;
+  /** Extra environment on top of the host's allowlist. Never overrides PATH. */
+  env?: Record<string, string>;
+  /** Text to write to stdin. Absent means stdin is /dev/null, so a prompt cannot hang forever. */
+  stdin?: string;
+}
+/** What {@link PluginHost.run} reports. Never throws for a non-zero exit. */
+interface RunResult {
+  /** Exit code, or null when the process was signalled or never started. */
+  code: number | null;
+  /** Captured stdout, ANSI stripped, capped. */
+  stdout: string;
+  /** Captured stderr, ANSI stripped, capped. */
+  stderr: string;
+  /** True when the deadline ended it. */
+  timedOut: boolean;
+  /** True when {@link RunOptions.signal} ended it. */
+  aborted: boolean;
+}
+/** Write-only, per-plugin credential storage. See {@link PluginHost.secrets}. */
+interface PluginSecrets {
+  /** Stores (or replaces) a credential under this name. */
+  set(name: string, value: string): Promise<void>;
+  /** Whether a credential is stored under this name. The only read there is. */
+  has(name: string): Promise<boolean>;
+  /** Removes it. Absent is not an error. */
+  delete(name: string): Promise<void>;
 }
 /**
  * The plugin itself.
@@ -257,6 +378,8 @@ interface PluginHost {
  * 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. */
@@ -290,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. */
@@ -305,8 +435,17 @@ interface SubshellPlugin {
     description: string;
   }[];
 }
-/** What a plugin module default-exports. */
-type PluginFactory = (host: PluginHost) => SubshellPlugin;
+/**
+ * A factory that returns a harness, for a plugin that knows which it is.
+ *
+ * {@link PluginFactory} is the LOADER's view — it must accept either shape,
+ * because it decides which to expect from the manifest. A plugin itself has no
+ * such ambiguity, and annotating its own factory with the union would widen
+ * what its tests can call: `createPlugin(host).buildCommand(...)` stops
+ * type-checking on a value that might be a network plugin. So a plugin
+ * declares the half it implements and the loader keeps the union.
+ */
+type HarnessPluginFactory = (host: PluginHost) => SubshellPlugin;
 //#endregion
 //#region ../../plugin-api/dist/index.d.ts
 /** How a host finds this plugin's binary, as data, so a scan loads no plugin code. */
@@ -315,16 +454,158 @@ interface DetectSpec {
   binaryName: string;
   /** Env var that overrides the lookup outright, e.g. "CLAUDE_PATH" */
   envOverride: string;
-  /** Well-known locations relative to HOME, tried after PATH */
+  /**
+   * Well-known locations, tried after PATH and before the version managers.
+   *
+   * HOME-relative (`.local/bin/mytool`), or ABSOLUTE when the entry starts
+   * with `/` — which is how a vendor's GUI install is named, since
+   * `/Applications/Tailscale.app/Contents/MacOS/Tailscale` is nobody's HOME.
+   * Each is a candidate to search, so an entry that does not resolve costs
+   * nothing and the ladder carries on.
+   */
   knownPaths: string[];
 }
 /** Where to send someone whose binary is missing. */
 interface InstallSpec {
-  /** Copy-pasteable install command for the official installer */
+  /**
+   * Copy-pasteable install command for the official installer.
+   *
+   * A command the HOST may run on request, which is why it may not be
+   * privileged: `sudo`, `doas` and `pkexec` are refused by the parser at any
+   * command boundary (the line is run through a shell — see
+   * {@link needsPrivileges}), so an installer that needs root is described
+   * under {@link NetworkManifest.privileged} instead and is only ever shown to
+   * copy. Without that refusal the two would be one field with two meanings,
+   * and the surface offering a button would have to guess.
+   */
   command: string;
-  /** URL of the installation documentation */
+  /**
+   * URL of the installation documentation.
+   *
+   * Rendered as a link on an admin page, so it must be `http:` or `https:`
+   * and the parser refuses anything else — see {@link isDocsUrl}.
+   */
   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" */
+  label: string;
+  /** The command to copy. Usually `sudo …`. */
+  command: string;
+  /** Where the vendor documents it; `http:`/`https:` only, as {@link isDocsUrl} requires. */
+  docsUrl?: string;
+  /**
+   * Which ALTERNATIVE this step belongs to, and the heading it renders under.
+   *
+   * Steps sharing a group are one sequence to run in order; different groups
+   * are different ways to arrive at the same place, and a surface renders an
+   * `or` between them rather than continuing the numbering. Steps with no
+   * group are one plain sequence, which is what every step was before this
+   * existed.
+   *
+   * It exists because a platform can genuinely offer two routes: on macOS
+   * Tailscale ships both a GUI app and a command-line daemon, and a page that
+   * numbered those 1..3 told a person to install both. Non-empty when present
+   * — it is a heading, so `""` is refused rather than coerced.
+   */
+  group?: string;
+}
+/**
+ * The `subshell.network` block. Required when `type` is `network`.
+ *
+ * Everything here is DATA a host reads without loading plugin code: which
+ * machines this plugin can run on at all, whether it can produce a login URL,
+ * what publishing it exposes, and which steps only a human with root can
+ * perform. A page can therefore say "not available on this platform" or print
+ * the two sudo commands before any plugin code has been imported — and before
+ * the vendor's CLI is anywhere on the machine.
+ */
+interface NetworkManifest {
+  /**
+   * Operating systems this plugin can be driven on.
+   *
+   * Not a hint: a host refuses every act on a platform absent from this list,
+   * and the UI renders the row as unavailable rather than offering a button
+   * that would 409. Vendors differ here for real reasons — a CLI that talks to
+   * a logged-in desktop session cannot be driven from a launchd service.
+   */
+  platforms: PluginPlatform[];
+  /**
+   * True when `join({})` with no credential can yield a URL a human finishes.
+   *
+   * Data rather than a capability because it describes what a RETURN VALUE may
+   * be, and a capability is checked against members. The UI reads it to decide
+   * whether to offer "sign in" beside "paste a key".
+   */
+  interactiveLogin?: boolean;
+  /**
+   * True when publishing leaves NOTHING the daemon can later be asked about.
+   *
+   * NetBird is the case that forced the field: a join is the whole publish,
+   * so `status()` can only ever see the join, and a plugin that declared
+   * itself `published` would claim a thing its own vendor CLI never told it.
+   * The HOST's publish record is the one witness of the transition, and this
+   * flag is what lets the host (and only the host) upgrade `joined` to
+   * `published` from it. A plugin without the flag is never upgraded: for
+   * Tailscale a serve reset outside this app is a real state, and `joined`
+   * is the honest reading of it.
+   */
+  publishImplicit?: boolean;
+  /**
+   * What publishing on this network exposes the server to.
+   *
+   * `private` is a network only invited machines are on. `public-with-gate`
+   * reaches the open internet with an identity check in front — a different
+   * security posture, stated here so every surface can say so before the act
+   * rather than after it.
+   */
+  exposure: "private" | "public-with-gate";
+  /**
+   * Steps the host can never perform, per platform, in the order to run them.
+   *
+   * Every mesh VPN installs a daemon as root and the server has no terminal to
+   * answer a password prompt, so these are printed to copy and never executed.
+   * Keeping them out of {@link InstallSpec} is what lets a surface offer a
+   * button for one and a copy row for the other without inspecting the string.
+   */
+  privileged?: Partial<Record<PluginPlatform, PrivilegedStep[]>>;
+  /**
+   * What this network calls the two things a person acts on.
+   *
+   * Vendors name the same act differently and a generic word is wrong rather
+   * than merely bland: Tailscale takes an "auth key", NetBird a "setup key",
+   * Cloudflare a "tunnel token", and a field labelled "Auth key" on the
+   * NetBird row asks for something NetBird does not have. Likewise publishing
+   * is "Tailscale Serve" on one network and starting a tunnel on another.
+   *
+   * MANIFEST data rather than something the plugin returns, for the same
+   * reason `platforms` is: a surface renders these before any plugin code has
+   * been loaded, and before the vendor's CLI is anywhere on the machine. Both
+   * are optional and both have a sensible generic default, so a plugin that
+   * says nothing is merely plain rather than broken.
+   */
+  labels?: NetworkLabels;
+}
+/** The vendor's own words for the two acts a person takes. See {@link NetworkManifest.labels}. */
+interface NetworkLabels {
+  /** What to call the pasted credential: "Auth key", "Setup key", "Tunnel token". */
+  credential?: string;
+  /** What to call publishing: "Publish with Tailscale Serve", "Start tunnel". */
+  publish?: string;
+  /**
+   * Where the credential named by `credential` comes from — the vendor page
+   * that mints one.
+   *
+   * The credential box asks for an "Auth key" on a card that otherwise says
+   * nothing about what an auth key is or where to get it, and every vendor
+   * words that differently enough that the SPA cannot write the sentence
+   * itself. So the plugin names its page, and the card renders it as a Docs
+   * link on the label row. http(s) only, refused at parse like every other
+   * URL this contract carries — it lands in an `href` on an admin page.
+   */
+  credentialDocsUrl?: string;
+}
 /** The parsed `subshell` block. */
 interface SubshellManifest {
   /** plugin-api version this plugin was built against */
@@ -359,6 +640,20 @@ interface SubshellManifest {
    * fallback, i.e. a resume that quietly never offers itself (§11).
    */
   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
@@ -384,7 +679,11 @@ declare const manifest: SubshellManifest;
  * launch carries `-c mcp_servers.subshell.command=… -c mcp_servers.subshell.args=…`
  * 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
+ * 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 inherits
  * the subshell's baked SUBSHELL_* pane env for its credential, like every
  * harness.
@@ -396,6 +695,6 @@ declare const manifest: SubshellManifest;
  *
  * `host` carries what this module cannot import. See `@subshell-ai/plugin-api`.
  */
-declare const createPlugin: PluginFactory;
+declare const createPlugin: HarnessPluginFactory;
 //#endregion
 export { createPlugin as default, manifest };

package/dist/index.js

@@ -1,6 +1,12 @@
-//#region ../../plugin-api/dist/manifest-Czd9ea1g.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", "terminal"];
+const PLUGIN_TYPES = [
+	"agent-harness",
+	"terminal",
+	"network"
+];
+/** Every {@link PluginPlatform}, for validation. */
+const PLUGIN_PLATFORMS = ["darwin", "linux"];
 /**
 * The MCP server name every harness registers the built-in `subshell mcp`
 * server under: the config object key, and the `hermes mcp add|remove`
@@ -28,6 +34,80 @@ const ID_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
 function isRecord(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+/** The privilege wrappers no install command may ever run, by first-word basename. */
+const PRIVILEGED_COMMANDS = [
+	"sudo",
+	"doas",
+	"pkexec"
+];
+/** Shell boundaries that introduce a NEW command word: `;` `|` `&` (so `&&` and `||` too) and newline. */
+const COMMAND_BOUNDARY_RE = /[;&|\n]+/;
+/** A leading `NAME=…` env assignment, which `sh` strips before choosing the command. */
+const ENV_ASSIGNMENT_RE = /^[A-Za-z_][A-Za-z0-9_]*=\S*\s*/;
+/**
+* Whether a shell line runs one of {@link PRIVILEGED_COMMANDS} AS A COMMAND
+* anywhere in it — not merely at the start.
+*
+* `install.command` is the one manifest field a host RUNS, and it runs through
+* `sh -c` (`api/network/install-network.route.ts`), which means any boundary
+* in the line can start the privileged command the start of the line hides:
+* `"apt-get update && sudo apt-get install -y x"` is sudo-without-prompt on a
+* NOPASSWD host. A line-start regex was the first gate and it was not one.
+*
+* The split is CONSERVATIVE, not a shell parser: segments are taken at every
+* boundary character quote-blind (so a `;` inside a quoted string still
+* counts, which can only over-refuse), leading env assignments are stripped
+* (`FOO=bar sudo x` runs sudo), and each segment's first word is compared by
+* BASENAME (`/usr/bin/sudo` is sudo, `pkexec-demo` is not). A word merely
+* CONTAINING the token is fine — the comparison is equality on the basename.
+* The accepted limit is a wrapper hidden inside quotes (`sh -c 'sudo …'`),
+* which is the same limit `PluginHost.run`'s first-word check has, and it is
+* accepted for the same reason: a plugin whose code LOADS can already run
+* anything in this process (`docs/security.md` §11.9) — this rule refuses
+* careless manifests deterministically, it is not a sandbox.
+*/
+function needsPrivileges(command) {
+	for (const segment of command.split(COMMAND_BOUNDARY_RE)) {
+		let rest = segment.trim();
+		while (ENV_ASSIGNMENT_RE.test(rest)) rest = rest.replace(ENV_ASSIGNMENT_RE, "");
+		if (rest === "") continue;
+		const ws = rest.search(/\s/);
+		const firstWord = ws === -1 ? rest : rest.slice(0, ws);
+		const base = firstWord.slice(firstWord.lastIndexOf("/") + 1);
+		if (PRIVILEGED_COMMANDS.includes(base)) return true;
+	}
+	return false;
+}
+/**
+* Whether a string may be rendered as a link in an operator's browser.
+*
+* Every `docsUrl` in this contract ends up as the `href` of an anchor on an
+* admin page, and an `href` is not inert: a `javascript:` URL in one is script
+* running on the control plane's own origin, in the session of the one person
+* who can install plugins. So a URL this contract carries is restricted to the
+* two schemes that navigate, and both the parser below and the host check it.
+*
+* It is checked in two places on purpose. A manifest is static data, so a bad
+* value there is a plugin defect and is refused at load. A URL a plugin
+* REPORTS at runtime is often something it read off a vendor CLI — Tailscale's
+* `AuthURL` comes from whichever control server the operator pointed the
+* daemon at — so the host drops that one instead, because refusing to load a
+* working plugin over a value its control server chose would be the wrong
+* failure.
+*
+* Not a reachability claim: nothing fetches these, and a docs page that 404s
+* is a broken link rather than a hazard.
+* @param value - the candidate URL, as written in a manifest or returned by a plugin
+*/
+function isDocsUrl(value) {
+	let parsed;
+	try {
+		parsed = new URL(value);
+	} catch {
+		return false;
+	}
+	return parsed.protocol === "http:" || parsed.protocol === "https:";
+}
 /**
 * Reads and validates the `subshell` block of a plugin's package.json.
 *
@@ -43,7 +123,7 @@ function parseManifest(pkgJson) {
 	if (!isRecord(block)) return { error: "package.json has no `subshell` block, so it is not a Subshell plugin" };
 	if (typeof block.apiVersion !== "number" || !Number.isInteger(block.apiVersion)) return { error: "`subshell.apiVersion` must be an integer" };
 	if (block.apiVersion < 1) return { error: `this plugin declares plugin-api ${block.apiVersion}, which is not a version; the lowest is 1 and this host implements 2` };
-	if (block.apiVersion > 2) return { error: `this plugin needs plugin-api ${block.apiVersion}, but this host implements 2; upgrade the agent` };
+	if (block.apiVersion > 2) return { error: `this plugin needs plugin-api ${block.apiVersion}, but this host implements 2; upgrade Subshell` };
 	if (typeof block.id !== "string" || !ID_RE.test(block.id)) return { error: "`subshell.id` must be lowercase letters, digits and hyphens, starting alphanumeric (it becomes a directory name)" };
 	if (typeof block.type !== "string" || !PLUGIN_TYPES.includes(block.type)) return { error: `\`subshell.type\` must be one of: ${PLUGIN_TYPES.join(", ")}` };
 	if (typeof block.name !== "string" || block.name.trim() === "") return { error: "`subshell.name` must be a non-empty string" };
@@ -54,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;
@@ -70,6 +151,8 @@ function parseManifest(pkgJson) {
 	if (block.install !== void 0) {
 		const i = block.install;
 		if (!isRecord(i) || typeof i.command !== "string" || typeof i.docsUrl !== "string") return { error: "`subshell.install` needs a command and a docsUrl" };
+		if (needsPrivileges(i.command)) return { error: "`subshell.install.command` must not need sudo, doas or pkexec — the host runs it through a shell and has no terminal for a password prompt; put privileged steps in `subshell.network.privileged`" };
+		if (!isDocsUrl(i.docsUrl)) return { error: "`subshell.install.docsUrl` must be an http(s) URL — it is rendered as a link on an admin page" };
 		install = {
 			command: i.command,
 			docsUrl: i.docsUrl
@@ -80,17 +163,85 @@ function parseManifest(pkgJson) {
 		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" };
 		hostEnv = [...block.hostEnv];
 	}
+	const type = block.type;
+	const parsedNetwork = parseNetworkBlock(block.network, type);
+	if (parsedNetwork !== void 0 && "error" in parsedNetwork) return parsedNetwork;
 	return {
 		apiVersion: block.apiVersion,
 		id: block.id,
-		type: block.type,
+		type,
 		name: block.name,
 		description: block.description,
 		...typeof block.icon === "string" ? { icon: block.icon } : {},
 		entry: block.entry,
 		...detect ? { detect } : {},
 		...install ? { install } : {},
-		...hostEnv ? { hostEnv } : {}
+		...hostEnv ? { hostEnv } : {},
+		...parsedNetwork ? { network: parsedNetwork } : {},
+		...block.pickable === false ? { pickable: false } : {}
+	};
+}
+/**
+* Parses `subshell.network`, which is required for and exclusive to `network`.
+*
+* Both directions are refused rather than tolerated. A network plugin without
+* the block would be unrenderable — nothing could say which platforms it runs
+* on or what publishing it exposes, and the safe default for "what does this
+* expose" is not a default anyone should pick silently. A harness WITH one
+* declares facts nothing reads, which is how a manifest starts lying.
+* @returns the parsed block, an error, or undefined when there is none to have
+*/
+function parseNetworkBlock(raw, type) {
+	if (type !== "network") {
+		if (raw !== void 0) return { error: `\`subshell.network\` is only for \`type: "network"\` plugins, and this one is \`${type}\`` };
+		return;
+	}
+	if (!isRecord(raw)) return { error: "`subshell.network` is required for `type: \"network\"` plugins" };
+	if (!Array.isArray(raw.platforms) || raw.platforms.length === 0 || !raw.platforms.every((p) => typeof p === "string" && PLUGIN_PLATFORMS.includes(p))) return { error: `\`subshell.network.platforms\` must be a non-empty array of: ${PLUGIN_PLATFORMS.join(", ")}` };
+	if (raw.exposure !== "private" && raw.exposure !== "public-with-gate") return { error: "`subshell.network.exposure` must be \"private\" or \"public-with-gate\"" };
+	if (raw.interactiveLogin !== void 0 && typeof raw.interactiveLogin !== "boolean") return { error: "`subshell.network.interactiveLogin` must be a boolean" };
+	if (raw.publishImplicit !== void 0 && typeof raw.publishImplicit !== "boolean") return { error: "`subshell.network.publishImplicit` must be a boolean" };
+	let privileged;
+	if (raw.privileged !== void 0) {
+		if (!isRecord(raw.privileged)) return { error: "`subshell.network.privileged` must be an object keyed by platform" };
+		privileged = {};
+		for (const [platform, steps] of Object.entries(raw.privileged)) {
+			if (!PLUGIN_PLATFORMS.includes(platform)) return { error: `\`subshell.network.privileged\` has an unknown platform "${platform}"` };
+			if (!Array.isArray(steps) || !steps.every((s) => isRecord(s) && typeof s.label === "string" && s.label.trim() !== "" && typeof s.command === "string" && s.command.trim() !== "" && (s.docsUrl === void 0 || typeof s.docsUrl === "string") && (s.group === void 0 || typeof s.group === "string"))) return { error: `\`subshell.network.privileged.${platform}\` must be an array of { label, command, docsUrl?, group? }` };
+			const badGroup = steps.find((s) => s.group !== void 0 && s.group.trim() === "");
+			if (badGroup) return { error: `\`subshell.network.privileged.${platform}\` has an empty \`group\`, which is a heading with no words: "${badGroup.label}"` };
+			const badDocs = steps.find((s) => s.docsUrl !== void 0 && !isDocsUrl(s.docsUrl));
+			if (badDocs) return { error: `\`subshell.network.privileged.${platform}\` has a docsUrl that is not an http(s) URL: "${badDocs.label}"` };
+			privileged[platform] = steps.map((s) => ({
+				label: s.label,
+				command: s.command,
+				...s.docsUrl ? { docsUrl: s.docsUrl } : {},
+				...s.group ? { group: s.group } : {}
+			}));
+		}
+	}
+	let labels;
+	if (raw.labels !== void 0) {
+		if (!isRecord(raw.labels)) return { error: "`subshell.network.labels` must be an object" };
+		for (const key of ["credential", "publish"]) {
+			const value = raw.labels[key];
+			if (value !== void 0 && (typeof value !== "string" || value.trim() === "")) return { error: `\`subshell.network.labels.${key}\` must be a non-empty string` };
+		}
+		const credDocs = raw.labels.credentialDocsUrl;
+		if (credDocs !== void 0 && (typeof credDocs !== "string" || !isDocsUrl(credDocs))) return { error: "`subshell.network.labels.credentialDocsUrl` must be an http(s) URL — it is rendered as a link on an admin page" };
+		labels = {
+			...typeof raw.labels.credential === "string" ? { credential: raw.labels.credential } : {},
+			...typeof raw.labels.publish === "string" ? { publish: raw.labels.publish } : {},
+			...typeof raw.labels.credentialDocsUrl === "string" ? { credentialDocsUrl: raw.labels.credentialDocsUrl } : {}
+		};
+	}
+	return {
+		platforms: [...raw.platforms],
+		exposure: raw.exposure,
+		...raw.interactiveLogin === true ? { interactiveLogin: true } : {},
+		...raw.publishImplicit === true ? { publishImplicit: true } : {},
+		...privileged ? { privileged } : {},
+		...labels && Object.keys(labels).length > 0 ? { labels } : {}
 	};
 }
 //#endregion
@@ -134,7 +285,7 @@ function validateGenericPreset(preset) {
 const parsed = parseManifest({
 	name: "@subshell-ai/plugin-codex",
 	description: "Codex harness plugin for Subshell",
-	version: "0.2.0",
+	version: "1.0.1",
 	license: "Apache-2.0",
 	type: "module",
 	main: "dist/index.js",
@@ -157,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: {
@@ -269,7 +420,11 @@ function tomlStringArray(values) {
 * launch carries `-c mcp_servers.subshell.command=… -c mcp_servers.subshell.args=…`
 * 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
+* 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 inherits
 * the subshell's baked SUBSHELL_* pane env for its credential, like every
 * harness.
@@ -281,11 +436,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);
@@ -330,7 +506,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": "0.2.0",
+  "version": "1.0.1",
   "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": {