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

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-//#region ../../plugin-api/dist/types-B_wiApwK.d.ts
+//#region ../../plugin-api/dist/types-D6R-hjGN.d.ts
 //#region src/types.d.ts
 /**
  * The contract a Subshell plugin implements.
@@ -20,13 +20,25 @@
  * 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" | "publish" | "supervise" | "guard" | "settings";
 /** A harness preset as defined by the user (decoded JSON blobs). */
 interface PresetDefinition {
   /** Human-friendly preset name */
@@ -202,10 +214,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 +273,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.
@@ -305,8 +410,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 +429,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 +615,8 @@ 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;
 }
 //#endregion
 //#region src/manifest.d.ts
@@ -382,6 +640,6 @@ declare const manifest: SubshellManifest;
  * version probe, shell quoting, a namespaced logger). See
  * `@subshell-ai/plugin-api`.
  */
-declare const createPlugin: PluginFactory;
+declare const createPlugin: HarnessPluginFactory;
 //#endregion
 export { createPlugin as default, manifest };

package/dist/index.js

@@ -1,7 +1,13 @@
 import { join, resolve } from "node:path";
-//#region ../../plugin-api/dist/manifest-Czd9ea1g.js
+//#region ../../plugin-api/dist/manifest-DKMceUPh.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`
@@ -29,6 +35,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.
 *
@@ -44,7 +124,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" };
@@ -71,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
@@ -81,17 +163,84 @@ 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 } : {}
+	};
+}
+/**
+* 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
@@ -135,7 +284,7 @@ function validateGenericPreset(preset) {
 const parsed = parseManifest({
 	name: "@subshell-ai/plugin-claude-code",
 	description: "Claude Code harness plugin for Subshell",
-	version: "2.0.0",
+	version: "3.1.0",
 	license: "Apache-2.0",
 	type: "module",
 	main: "dist/index.js",
@@ -284,6 +433,10 @@ const SUGGESTED_ENV = [
 		key: "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC",
 		description: "Disable telemetry/update traffic (1)"
 	},
+	{
+		key: "CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN",
+		description: "Classic renderer: appends to scrollback so the pane shows a scrollbar (1)"
+	},
 	{
 		key: "CLAUDE_CODE_SSE_URL",
 		description: "Anthropic SSE URL override (e.g. http://localhost:8080/anthropic)"
@@ -395,13 +548,29 @@ const reporterHook = (host, reporter, ...verb) => [
 * - `Stop` / `Notification` — fire-and-forget attention reporting. The server
 *   gates delivery on the subshell's bell and derives the "waiting for you"
 *   state; a missed event costs one notification, never a broken turn.
+*   `Notification` carries a matcher because the unfiltered hook rang
+*   "Needs your approval" for EVERY notification type — `idle_prompt`,
+*   `auth_success`, `elicitation_complete` after the human had already
+*   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.
 * - `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
 *   transcript id in-pane and nothing else tells the server, so the next
 *   restart would resurrect a stale conversation (observed 2026-09-03). This
 *   fires on every such transition (source: startup|resume|clear|compact|fork)
-*   and is the one hook that reads stdin — the reporter forwards `session_id`
+*   and reads stdin like `Stop` now does — the reporter forwards `session_id`
 *   from that payload and nothing else.
 */
 const attentionHooks = (host, reporter) => ({
@@ -409,9 +578,20 @@ const attentionHooks = (host, reporter) => ({
 		type: "command",
 		command: reporterHook(host, reporter, "attention", "turn_complete")
 	}] }],
-	Notification: [{ hooks: [{
+	Notification: [{
+		matcher: "permission_prompt|agent_needs_input|elicitation_dialog|elicitation_url_dialog",
+		hooks: [{
+			type: "command",
+			command: reporterHook(host, reporter, "attention", "needs_attention")
+		}]
+	}],
+	UserPromptSubmit: [{ hooks: [{
+		type: "command",
+		command: reporterHook(host, reporter, "attention", "resumed")
+	}] }],
+	PreToolUse: [{ hooks: [{
 		type: "command",
-		command: reporterHook(host, reporter, "attention", "needs_attention")
+		command: reporterHook(host, reporter, "attention", "resumed")
 	}] }],
 	SessionStart: [{ hooks: [{
 		type: "command",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@subshell-ai/plugin-claude-code",
   "description": "Claude Code harness plugin for Subshell",
-  "version": "2.0.0",
+  "version": "3.1.0",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/index.js",