@subshell-ai/plugin-claude-code 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,348 @@
+//#region ../../plugin-api/dist/types-90lJTTx6.d.ts
+//#region src/types.d.ts
+/**
+ * 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 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.
+ */
+type PluginType = "agent-harness" | "terminal";
+/**
+ * What a plugin can DO. The launch pipeline and the UI read this; neither
+ * branches on {@link PluginType}.
+ */
+type PluginCapability = "mcp" | "resume" | "attention" | "settings";
+/** A harness profile as defined by the user (decoded JSON blobs). */
+interface ProfileDefinition {
+  /** Human-friendly profile name */
+  name: string;
+  /** Optional longer description */
+  description?: string | null;
+  /** Extra environment variables to set on the subshell */
+  env: Record<string, string>;
+  /** Extra CLI flags to pass to the harness binary */
+  flags: string[];
+  /** Settings blob passed to the harness (e.g. claude --settings JSON) */
+  settings: Record<string, unknown> | null;
+  /** If true, only this profile's config sources apply (isolation) */
+  configIsolation: boolean;
+  /** If true, new subshells from this profile auto-restart on exit */
+  restartOnExit?: boolean;
+}
+/** Snapshot of a single field-level validation error on a profile. */
+interface ProfileValidationIssue {
+  /** Field name (e.g. "name", "env", "settings") */
+  field: string;
+  /** Human-readable problem description */
+  message: string;
+}
+interface ProfileValidationResult {
+  valid: boolean;
+  issues: ProfileValidationIssue[];
+}
+/** Everything a plugin needs to build a launch command. */
+interface BuildCommandInput {
+  /** Resolved absolute path to the harness binary */
+  binary: string;
+  /** Working directory the harness runs in */
+  cwd: string;
+  /** The validated profile being used */
+  profile: ProfileDefinition;
+  /** Subshell display name ("" = let the harness pick a default) */
+  subshellName: string;
+  /** Any additional CLI flags from route/request context */
+  extraFlags?: string[];
+  /**
+   * The subshell's MCP registration (channels + subshell orchestration), as
+   * produced by this plugin's own `mcpRegistration` and already written to
+   * disk. Plugins consume ONLY `mcp.args`: splice them where the dialect needs
+   * them (claude right after the binary). `mcp.env` is baked into the pane by
+   * the host before the command runs; plugins must not consume it themselves.
+   * Undefined = no registration for this launch.
+   */
+  mcp?: McpRegistration;
+  /**
+   * Conversation identity for restart-resume; set only when this plugin
+   * declares the `resume` capability. `mode: "start"` means the conversation
+   * is NEW and must be created under exactly this id (pin it, because the host
+   * stores it and later resumes by it); `mode: "resume"` names an EXISTING
+   * conversation to continue (the host only asks after {@link HarnessResume.canResume}
+   * confirmed it survives).
+   */
+  harnessSession?: {
+    id: string;
+    mode: "start" | "resume";
+  };
+}
+/**
+ * Restart-resume, implemented only by plugins that can continue a previous
+ * conversation.
+ *
+ * The ids here are HARNESS conversation ids (a claude transcript uuid, say),
+ * never subshell ids: the host pins {@link allocateHarnessSessionId} at launch,
+ * stores it on the subshell row, and consults {@link canResume} before every
+ * restart to choose between continuing and starting fresh.
+ */
+interface HarnessResume {
+  /** Allocates the HARNESS conversation id to pin at launch (a uuid for claude). */
+  allocateHarnessSessionId(): string;
+  /**
+   * Whether the harness conversation `harnessSessionId` (last run in `cwd`)
+   * still exists and can be resumed. False means the host launches a fresh
+   * conversation rather than handing the harness an id it would reject.
+   */
+  canResume(harnessSessionId: string, cwd: string): boolean;
+}
+/** How to spawn the `subshell mcp` stdio server. */
+interface McpLaunchSpec {
+  /** Executable to run (the self command, the interpreter, or the agent binary) */
+  command: string;
+  /** Arguments for the executable (e.g. the mcp entry script path) */
+  args: string[];
+}
+/** Per-subshell MCP registration rendered in the plugin's own config dialect. */
+interface McpRegistration {
+  /** 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 profile env;
+   * plugins never read it back.
+   */
+  env?: Record<string, string>;
+}
+/** One copy-paste line shown in the profile editor for manual-setup harnesses. */
+interface McpSetupStep {
+  /** What the user should do, and where the text goes */
+  label: string;
+  /** Copyable command or snippet */
+  command: string;
+}
+/**
+ * How a harness obtains the `subshell mcp` tools.
+ *
+ * Discriminated on purpose: auto harnesses explain themselves in one line and
+ * manual harnesses carry steps, and a plugin cannot mix the two.
+ */
+type McpSetupInfo = {
+  mode: "auto";
+  summary: string;
+} | {
+  mode: "manual";
+  steps: McpSetupStep[];
+};
+/** A single option in a plugin's settings editor. */
+interface SettingsField {
+  /** Key into the settings object (e.g. "permissionMode") */
+  key: string;
+  /** Property label */
+  label: string;
+  /** Short description for the editor */
+  description?: string;
+  /** One of: string, boolean, number, select */
+  type: "string" | "boolean" | "number" | "select";
+  /** Choices when type === "select" */
+  choices?: string[];
+  /** Default value when unset */
+  default?: string | boolean | number;
+}
+/**
+ * Why there is no binary.
+ *
+ * `no-binary` is not a failure: a plugin (a `terminal` one, say) can declare
+ * no binary at all, and rendering that as "not on PATH" tells someone their
+ * PATH is wrong about something that never wanted one.
+ */
+type DetectionReason = "not-on-path" | "override-invalid" | "no-binary";
+/** A detection answer: the path, or the reason there is not one. */
+type DetectionResult = {
+  path: string;
+  reason?: undefined;
+} | {
+  path: null;
+  reason: DetectionReason;
+};
+/**
+ * Everything the host lends a plugin, because a plugin can import none of it.
+ *
+ * This is also the version boundary: a host at a higher `apiVersion` keeps
+ * older plugins working by keeping the fields they were compiled against, so
+ * members are ADDED here and never removed or retyped.
+ */
+interface PluginHost {
+  /** The API version this host implements. Always >= the plugin's own. */
+  readonly apiVersion: number;
+  /** Resolve a binary through the host's full lookup ladder. */
+  findBinary(name: string, envOverride: string, knownPaths: string[]): Promise<string | null>;
+  /** The same lookup, reporting why it failed. */
+  detectBinary(name: string, envOverride: string, knownPaths: string[]): Promise<DetectionResult>;
+  /** Run a short command with a deadline; trimmed stdout, or null. */
+  probeVersion(binary: string, args?: string[]): Promise<string | null>;
+  /** POSIX-quote one argument for a shell command line. */
+  shellQuote(value: string): string;
+  /** Structured logging, namespaced to the plugin. */
+  log: {
+    debug(message: string): void;
+    warn(message: string): void;
+  };
+}
+/**
+ * The plugin itself.
+ *
+ * Only the first three members are required. Everything else is a capability
+ * the plugin opts into and declares from {@link capabilities}, so a `terminal`
+ * plugin is a binary and an argv rather than eight stubs.
+ */
+interface SubshellPlugin {
+  /** Builds the argv (no shell) used to launch a subshell. */
+  buildCommand(input: BuildCommandInput): string[];
+  /** Validates a profile definition before saving. */
+  validateProfile(profile: ProfileDefinition): ProfileValidationResult;
+  /** Which optional members below are meaningful on this plugin. */
+  capabilities(): PluginCapability[];
+  /** Maps a harness exit code to a human label (null = unknown). */
+  exitStatus?(code: number): string | null;
+  /**
+   * Interprets the raw stdout of the version probe.
+   *
+   * Probing is the host's job (it owns the deadline); making sense of the
+   * output is the plugin's, because only the plugin knows its harness prints
+   * a banner rather than a bare semver. Omit it and the trimmed output is
+   * used as-is, which is right for every harness that prints just a version.
+   */
+  parseVersion?(raw: string): string | null;
+  /** Overrides manifest-driven detection. Almost no plugin needs this. */
+  detect?(): Promise<DetectionResult>;
+  /** Restart-resume support. Declare the `resume` capability with it. */
+  resume?: HarnessResume;
+  /**
+   * True when `buildCommand` wires this harness's native "needs attention"
+   * reporting into the launch. The host's quiet-output idle watcher skips
+   * these. Declare the `attention` capability with it.
+   */
+  supportsAttentionHooks?: boolean;
+  /**
+   * Renders the per-subshell MCP registration in this harness's config format.
+   * Omit when the harness cannot consume a per-subshell config file; the host
+   * 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;
+  /** Settings rendered in the PROFILE editor and stored on the profile. */
+  profileSettings?(): SettingsField[];
+  /** Known extra env var suggestions for the profile editor. */
+  suggestedEnv?(): {
+    key: string;
+    description: string;
+  }[];
+  /** Known CLI flag suggestions for the profile editor. */
+  suggestedFlags?(): {
+    flag: string;
+    description: string;
+  }[];
+}
+/** What a plugin module default-exports. */
+type PluginFactory = (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. */
+interface DetectSpec {
+  /** Executable name to look for, e.g. "claude" */
+  binaryName: string;
+  /** Env var that overrides the lookup outright, e.g. "CLAUDE_PATH" */
+  envOverride: string;
+  /** Well-known locations relative to HOME, tried after PATH */
+  knownPaths: string[];
+}
+/** Where to send someone whose binary is missing. */
+interface InstallSpec {
+  /** Copy-pasteable install command for the official installer */
+  command: string;
+  /** URL of the installation documentation */
+  docsUrl: string;
+}
+/** The parsed `subshell` block. */
+interface SubshellManifest {
+  /** plugin-api version this plugin was built against */
+  apiVersion: number;
+  /** Stable id, also its directory name */
+  id: string;
+  /** What kind of thing this provides */
+  type: PluginType;
+  /** Display name */
+  name: string;
+  /** One-line description shown in the UI */
+  description: string;
+  /** Optional emoji/glyph */
+  icon?: string;
+  /** Module to import, relative to the package directory */
+  entry: string;
+  /** Manifest-driven detection; absent for a plugin that needs no binary */
+  detect?: DetectSpec;
+  /** Install guidance shown when the binary is missing */
+  install?: InstallSpec;
+}
+//#endregion
+//#region src/manifest.d.ts
+declare const manifest: SubshellManifest;
+//#endregion
+//#region src/index.d.ts
+/** The `--settings` hooks object injected into every Claude Code launch. */
+declare const ATTENTION_HOOKS: {
+  readonly Stop: readonly [{
+    readonly hooks: readonly [{
+      readonly type: "command";
+      readonly command: string;
+    }];
+  }];
+  readonly Notification: readonly [{
+    readonly hooks: readonly [{
+      readonly type: "command";
+      readonly command: string;
+    }];
+  }];
+  readonly SessionStart: readonly [{
+    readonly hooks: readonly [{
+      readonly type: "command";
+      readonly command: string;
+    }];
+  }];
+};
+/**
+ * Built-in harness: Claude Code.
+ *
+ * Launch shape:
+ *   claude --settings <json> --name <subshell> [profile flags] [extra flags]
+ * Settings are passed as a JSON string via `--settings` (per-invocation, so
+ * profile config never needs to write into the user's real ~/.claude).
+ *
+ * Identity, detection and install guidance live in this package's
+ * package.json `subshell` block, NOT here: the host reads them without
+ * importing or executing a line of this file, which is what lets it list a
+ * plugin cheaply and detect `claude` before this plugin is even installed.
+ *
+ * `host` carries what this module cannot import (binary lookup, the bounded
+ * version probe, shell quoting, a namespaced logger). See
+ * `@subshell-ai/plugin-api`.
+ */
+declare const createPlugin: PluginFactory;
+//#endregion
+export { ATTENTION_HOOKS, createPlugin as default, manifest };

package/dist/index.js

@@ -0,0 +1,490 @@
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+//#region ../../plugin-api/dist/manifest-im30YVIq.js
+/** Every {@link PluginType}, for anything that has to iterate or validate them. */
+const PLUGIN_TYPES = ["agent-harness", "terminal"];
+/**
+* The MCP server name every harness registers the built-in `subshell mcp`
+* server under: the config object key, and the `hermes mcp add|remove`
+* argument alike. The server reports the same name in its MCP handshake, which
+* is what harnesses surface in wire tool ids (`mcp__<name>__<tool>`).
+*/
+const MCP_SERVER_NAME = "subshell";
+/**
+* Ids become directory names under `<dataDir>/plugins/`, so they are path
+* segments and nothing else: no separators, no traversal, no surprises from a
+* case-insensitive filesystem.
+*/
+const ID_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Reads and validates the `subshell` block of a plugin's package.json.
+*
+* Answers `{ error }` rather than throwing, because every caller is reporting
+* a broken plugin to a person rather than handling an exception: the node
+* marks the plugin broken and renders this message beside it. The strings are
+* therefore specific on purpose.
+* @param pkgJson - the parsed package.json of a plugin directory
+*/
+function parseManifest(pkgJson) {
+	if (!isRecord(pkgJson)) return { error: "package.json is not an object" };
+	const block = pkgJson.subshell;
+	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 1` };
+	if (block.apiVersion > 1) return { error: `this plugin needs plugin-api ${block.apiVersion}, but this host implements 1; upgrade the agent` };
+	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" };
+	if (typeof block.description !== "string") return { error: "`subshell.description` must be a string" };
+	if (block.icon !== void 0 && typeof block.icon !== "string") return { error: "`subshell.icon` must be a string" };
+	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;
+	if (block.detect !== void 0) {
+		const d = block.detect;
+		if (!isRecord(d) || typeof d.binaryName !== "string" || typeof d.envOverride !== "string" || !Array.isArray(d.knownPaths) || !d.knownPaths.every((k) => typeof k === "string")) return { error: "`subshell.detect` needs binaryName, envOverride and a knownPaths array of strings" };
+		detect = {
+			binaryName: d.binaryName,
+			envOverride: d.envOverride,
+			knownPaths: d.knownPaths
+		};
+	}
+	let install;
+	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" };
+		install = {
+			command: i.command,
+			docsUrl: i.docsUrl
+		};
+	}
+	return {
+		apiVersion: block.apiVersion,
+		id: block.id,
+		type: block.type,
+		name: block.name,
+		description: block.description,
+		...typeof block.icon === "string" ? { icon: block.icon } : {},
+		entry: block.entry,
+		...detect ? { detect } : {},
+		...install ? { install } : {}
+	};
+}
+//#endregion
+//#region ../../plugin-api/dist/index.js
+/**
+* The profile checks every built-in harness performs unchanged: a non-empty
+* name, string env values, and flags that look like flags. Harnesses with
+* extra rules run their own checks on top of these.
+* @param profile - The decoded profile definition to check
+* @returns Issues per field; `valid` is true when no issues were found
+*/
+function validateGenericProfile(profile) {
+	const issues = [];
+	if (!profile.name || profile.name.trim().length === 0) issues.push({
+		field: "name",
+		message: "Profile name is required."
+	});
+	for (const [key, value] of Object.entries(profile.env)) if (typeof value !== "string") issues.push({
+		field: "env",
+		message: `Env var "${key}" must be a string.`
+	});
+	for (const flag of profile.flags) if (!flag.startsWith("-")) issues.push({
+		field: "flags",
+		message: `Flag "${flag}" must start with "-".`
+	});
+	return {
+		valid: issues.length === 0,
+		issues
+	};
+}
+//#endregion
+//#region src/manifest.ts
+/**
+* This package's own `subshell` block, read from its package.json so the
+* manifest has ONE source of truth.
+*
+* A host that installs this plugin at runtime reads package.json off disk; a
+* host that ships it built in imports this. Both must describe the same
+* plugin, and the only way to guarantee that is for them to be the same bytes.
+*/
+const parsed = parseManifest({
+	name: "@subshell-ai/plugin-claude-code",
+	description: "Claude Code harness plugin for Subshell",
+	version: "0.0.1",
+	license: "Apache-2.0",
+	type: "module",
+	main: "dist/index.js",
+	exports: { ".": {
+		"types": "./dist/index.d.ts",
+		"import": "./dist/index.js"
+	} },
+	types: "dist/index.d.ts",
+	scripts: {
+		"build": "tsdown",
+		"build:dev": "hash-runner",
+		"clean": "rm -rf .turbo node_modules dist .hashes.json",
+		"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",
+		"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",
+		"tsdown": "0.22.14",
+		"typescript": "7.0.2"
+	},
+	files: ["dist"],
+	publishConfig: { "access": "public" },
+	subshell: {
+		"apiVersion": 1,
+		"id": "claude-code",
+		"type": "agent-harness",
+		"name": "Claude Code",
+		"description": "Anthropic's agentic coding assistant (interactive CLI)",
+		"icon": "🤖",
+		"entry": "dist/index.js",
+		"detect": {
+			"binaryName": "claude",
+			"envOverride": "CLAUDE_PATH",
+			"knownPaths": [
+				".local/bin/claude",
+				".local/share/claude/versions/claude",
+				".claude/local/claude",
+				".npm-global/bin/claude"
+			]
+		},
+		"install": {
+			"command": "curl -fsSL https://claude.ai/install.sh | bash",
+			"docsUrl": "https://code.claude.com/docs/en/setup"
+		}
+	}
+});
+if ("error" in parsed) throw new Error(`@subshell-ai/plugin-claude-code has an invalid manifest: ${parsed.error}`);
+const manifest = parsed;
+//#endregion
+//#region src/index.ts
+/** Known claude-code settings editor fields (top-level `--settings` keys). */
+const CLAUDE_SETTINGS_FIELDS = [
+	{
+		key: "permissionMode",
+		label: "Permission mode",
+		description: "How permissions are handled for tool use",
+		type: "select",
+		choices: [
+			"default",
+			"acceptEdits",
+			"bypassPermissions",
+			"plan",
+			"dontAsk"
+		]
+	},
+	{
+		key: "model",
+		label: "Model",
+		description: "Model alias or full name (e.g. 'sonnet', 'opus', 'fable')",
+		type: "string"
+	},
+	{
+		key: "maxTokens",
+		label: "Max output tokens",
+		type: "number"
+	},
+	{
+		key: "outputStyle",
+		label: "Output style",
+		type: "select",
+		choices: [
+			"default",
+			"compact",
+			"expanded"
+		]
+	},
+	{
+		key: "alwaysAllowReadOnly",
+		label: "Always allow read-only tools",
+		type: "boolean"
+	},
+	{
+		key: "includeCoAuthoredBy",
+		label: "Add Co-Authored-By footer",
+		type: "boolean"
+	}
+];
+const SUGGESTED_ENV = [
+	{
+		key: "ANTHROPIC_API_KEY",
+		description: "API key (overrides logged-in account)"
+	},
+	{
+		key: "ANTHROPIC_AUTH_TOKEN",
+		description: "OAuth/bearer token instead of an API key"
+	},
+	{
+		key: "ANTHROPIC_MODEL",
+		description: "Model alias (deprecated in favor of settings)"
+	},
+	{
+		key: "ANTHROPIC_BASE_URL",
+		description: "API base URL (e.g. a gateway/proxy)"
+	},
+	{
+		key: "ANTHROPIC_DEFAULT_SONNET_MODEL",
+		description: "Model behind the 'sonnet' alias"
+	},
+	{
+		key: "ANTHROPIC_DEFAULT_OPUS_MODEL",
+		description: "Model behind the 'opus' alias"
+	},
+	{
+		key: "ANTHROPIC_DEFAULT_HAIKU_MODEL",
+		description: "Model behind the 'haiku' alias"
+	},
+	{
+		key: "CLAUDE_CODE_MAX_OUTPUT_TOKENS",
+		description: "Max output tokens"
+	},
+	{
+		key: "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC",
+		description: "Disable telemetry/update traffic (1)"
+	},
+	{
+		key: "CLAUDE_CODE_SSE_URL",
+		description: "Anthropic SSE URL override (e.g. http://localhost:8080/anthropic)"
+	},
+	{
+		key: "CLAUDE_CODE_USE_BEDROCK",
+		description: "Use Amazon Bedrock (1)"
+	},
+	{
+		key: "CLAUDE_CODE_USE_VERTEX",
+		description: "Use Google Vertex AI (1)"
+	},
+	{
+		key: "BASH_DEFAULT_TIMEOUT_MS",
+		description: "Default timeout for Bash tool commands"
+	},
+	{
+		key: "MAX_THINKING_TOKENS",
+		description: "Cap on extended-thinking tokens"
+	}
+];
+const SUGGESTED_FLAGS = [
+	{
+		flag: "--dangerously-skip-permissions",
+		description: "Skip all permission prompts"
+	},
+	{
+		flag: "--permission-mode plan",
+		description: "Start in plan mode"
+	},
+	{
+		flag: "--model sonnet",
+		description: "Use a specific model alias"
+	},
+	{
+		flag: "--effort high",
+		description: "Effort level for the subshell"
+	},
+	{
+		flag: "--fallback-model opus",
+		description: "Fall back when the primary model is overloaded"
+	},
+	{
+		flag: "--agent reviewer",
+		description: "Use a custom agent definition"
+	},
+	{
+		flag: "--append-system-prompt <text>",
+		description: "Append to the system prompt"
+	},
+	{
+		flag: "--allowedTools Bash,Read,Edit",
+		description: "Allow only these tools"
+	},
+	{
+		flag: "--disallowedTools WebSearch",
+		description: "Deny these tools"
+	},
+	{
+		flag: "--mcp-config <path>",
+		description: "Load MCP servers from a JSON file"
+	},
+	{
+		flag: "--max-turns <n>",
+		description: "Cap agentic turns (print mode)"
+	},
+	{
+		flag: "--continue",
+		description: "Continue the most recent conversation"
+	},
+	{
+		flag: "--resume <id>",
+		description: "Resume a specific past conversation"
+	},
+	{
+		flag: "--fork-session",
+		description: "Fork instead of resuming in place"
+	},
+	{
+		flag: "--worktree",
+		description: "Run in a fresh git worktree"
+	}
+];
+/**
+* Fire-and-forget attention reporting. Each hook runs `bun -e` (bun is on the
+* pane PATH — the image ships it, and no curl exists there) and POSTs the
+* subshell's own bearer to the attention endpoint; the server gates delivery
+* on the subshell's bell and derives the "waiting for you" state. The env
+* vars are baked into the pane by the backend (`subshellMcpEnv`), and every
+* failure path is swallowed: a missing hook event costs one notification,
+* never a broken subshell turn. SUBSHELL_BASE_URL must be reachable from inside
+* the pane's network — in the container that means the published port, which
+* compose already passes via APP_BASE_URL.
+*/
+const attentionPing = (kind) => `bun -e 'fetch(process.env.SUBSHELL_BASE_URL+"/api/subshells/"+process.env.SUBSHELL_ID+"/attention",{method:"POST",headers:{authorization:"Bearer "+process.env.SUBSHELL_API_KEY,"content-type":"application/json"},body:JSON.stringify({kind:${JSON.stringify(kind)}}),signal:AbortSignal.timeout(5000)}).catch(()=>{}).finally(()=>process.exit(0))'`;
+/**
+* Conversation-identity reporting. 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). The SessionStart hook fires on
+* every such transition (source: startup|resume|clear|compact|fork).
+*
+* Unlike the attention pings, THIS command reads stdin — the deliberate,
+* documented exception to the no-stdin rule (whose rationale is that
+* Stop/Notification payloads carry conversation text): the SessionStart
+* payload is pure metadata ({session_id, transcript_path, cwd, source,…})
+* and ONLY `session_id` is forwarded; the response is fire-and-forget like
+* the pings — every failure path is swallowed.
+*
+* Both awaits are bounded: a self-kill timer caps the WHOLE hook (4 s — an
+* unclosed stdin must never stall the pane start, and a SessionStart hook
+* blocks the harness until it exits) and a 2 s fetch timeout caps the POST
+* (a lost report is harmless — the next transition re-reports).
+*/
+const sessionReportPing = () => "bun -e 'setTimeout(()=>process.exit(0),4000);try{const j=JSON.parse(await Bun.stdin.text());if(j.session_id)await fetch(process.env.SUBSHELL_BASE_URL+\"/api/subshells/\"+process.env.SUBSHELL_ID+\"/harness-session\",{method:\"POST\",headers:{authorization:\"Bearer \"+process.env.SUBSHELL_API_KEY,\"content-type\":\"application/json\"},body:JSON.stringify({sessionId:j.session_id}),signal:AbortSignal.timeout(2000)})}catch{}process.exit(0)'";
+/** The `--settings` hooks object injected into every Claude Code launch. */
+const ATTENTION_HOOKS = {
+	Stop: [{ hooks: [{
+		type: "command",
+		command: attentionPing("turn_complete")
+	}] }],
+	Notification: [{ hooks: [{
+		type: "command",
+		command: attentionPing("needs_attention")
+	}] }],
+	SessionStart: [{ hooks: [{
+		type: "command",
+		command: sessionReportPing()
+	}] }]
+};
+/** Claude's state dir: the documented override, else `~/.claude`. */
+function claudeConfigDir() {
+	const override = process.env.CLAUDE_CONFIG_DIR?.trim();
+	return override ? resolve(override) : join(homedir(), ".claude");
+}
+/** Claude's transcript folder name for a project dir: every non-alphanumeric → `-`. */
+function projectSlug(cwd) {
+	return cwd.replace(/[^a-zA-Z0-9]/g, "-");
+}
+/**
+* Built-in harness: Claude Code.
+*
+* Launch shape:
+*   claude --settings <json> --name <subshell> [profile flags] [extra flags]
+* Settings are passed as a JSON string via `--settings` (per-invocation, so
+* profile config never needs to write into the user's real ~/.claude).
+*
+* Identity, detection and install guidance live in this package's
+* package.json `subshell` block, NOT here: the host reads them without
+* importing or executing a line of this file, which is what lets it list a
+* plugin cheaply and detect `claude` before this plugin is even installed.
+*
+* `host` carries what this module cannot import (binary lookup, the bounded
+* version probe, shell quoting, a namespaced logger). See
+* `@subshell-ai/plugin-api`.
+*/
+const createPlugin = (_host) => ({
+	capabilities: () => [
+		"mcp",
+		"resume",
+		"attention",
+		"settings"
+	],
+	supportsAttentionHooks: true,
+	/**
+	* Restart-resume: conversations are PINNED at start (`--session-id <uuid>`)
+	* so subshell always knows the exact id to resume by, and resume mode adds
+	* `--resume <id>` (Claude appends to the same transcript, so one id
+	* survives repeated restarts). Pinning is what avoids both `--continue`'s
+	* "most recent in this directory" ambiguity, since several subshells can
+	* share a cwd, and parsing the exit banner back out of the pane log.
+	*/
+	resume: {
+		allocateHarnessSessionId: () => crypto.randomUUID(),
+		canResume: (harnessSessionId, cwd) => existsSync(join(claudeConfigDir(), "projects", projectSlug(cwd), `${harnessSessionId}.jsonl`))
+	},
+	buildCommand(input) {
+		const { binary, profile, subshellName, extraFlags, mcp, harnessSession } = input;
+		const args = [binary];
+		if (mcp?.args) args.push(...mcp.args);
+		if (harnessSession) args.push(harnessSession.mode === "resume" ? "--resume" : "--session-id", harnessSession.id);
+		const settings = {
+			...profile.settings ?? {},
+			hooks: ATTENTION_HOOKS
+		};
+		args.push("--settings", JSON.stringify(settings));
+		if (subshellName) args.push("--name", subshellName);
+		for (const flag of profile.flags) args.push(flag);
+		if (extraFlags) args.push(...extraFlags);
+		return args;
+	},
+	/** Claude Code's `--mcp-config` document: `{ mcpServers: { subshell: {...} } }`. */
+	mcpRegistration(launch, configPath) {
+		return {
+			fileContent: `${JSON.stringify({ mcpServers: { [MCP_SERVER_NAME]: {
+				command: launch.command,
+				args: launch.args
+			} } }, null, 2)}\n`,
+			args: ["--mcp-config", configPath]
+		};
+	},
+	/** Auto: `buildCommand` wires `--mcp-config` into every subshell. */
+	mcpSetup(_launch) {
+		return {
+			mode: "auto",
+			summary: "Subshell registers itself with every Claude Code subshell automatically (via --mcp-config)."
+		};
+	},
+	validateProfile(profile) {
+		return validateGenericProfile(profile);
+	},
+	profileSettings() {
+		return CLAUDE_SETTINGS_FIELDS;
+	},
+	suggestedEnv() {
+		return SUGGESTED_ENV;
+	},
+	suggestedFlags() {
+		return SUGGESTED_FLAGS;
+	},
+	exitStatus(code) {
+		return {
+			1: "error doing work",
+			5: "permissions denied",
+			10: "closed-loop complete",
+			11: "gate closed"
+		}[code] ?? null;
+	}
+});
+//#endregion
+export { ATTENTION_HOOKS, createPlugin as default, manifest };

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@subshell-ai/plugin-claude-code",
+  "description": "Claude Code harness plugin for Subshell",
+  "version": "0.0.1",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsdown",
+    "build:dev": "hash-runner",
+    "clean": "rm -rf .turbo node_modules dist .hashes.json",
+    "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",
+    "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",
+    "tsdown": "0.22.14",
+    "typescript": "7.0.2"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "subshell": {
+    "apiVersion": 1,
+    "id": "claude-code",
+    "type": "agent-harness",
+    "name": "Claude Code",
+    "description": "Anthropic's agentic coding assistant (interactive CLI)",
+    "icon": "\ud83e\udd16",
+    "entry": "dist/index.js",
+    "detect": {
+      "binaryName": "claude",
+      "envOverride": "CLAUDE_PATH",
+      "knownPaths": [
+        ".local/bin/claude",
+        ".local/share/claude/versions/claude",
+        ".claude/local/claude",
+        ".npm-global/bin/claude"
+      ]
+    },
+    "install": {
+      "command": "curl -fsSL https://claude.ai/install.sh | bash",
+      "docsUrl": "https://code.claude.com/docs/en/setup"
+    }
+  }
+}