feat(claude): emit experimental themes and monitors (#187)

.changeset/claude-experimental-themes-monitors.md

@@ -0,0 +1,5 @@
+---
+"agent-bundle": minor
+---
+
+Add validated Claude Code experimental theme and monitor declarations, including default-location emission, monitor trigger checks, and host-availability warnings.

packages/agent-bundle/src/adapters/capabilities/claude-2.1.250.json

@@ -77,6 +77,12 @@
       "semverRanges": true,
       "tagConvention": "{name}--v{version}"
     },
+    "experimentalThemes": {
+      "defaultDirectory": "themes",
+      "experimental": true,
+      "manifestField": "experimental.themes",
+      "readOnly": true
+    },
     "devtools": {
       "details": true,
       "listJson": true,
@@ -136,6 +142,18 @@
         "version"
       ]
     },
+    "monitors": {
+      "commandTokens": ["${CLAUDE_PLUGIN_ROOT}", "${CLAUDE_PLUGIN_DATA}", "${CLAUDE_PROJECT_DIR}", "${ENV_VAR}"],
+      "config": "monitors/monitors.json",
+      "defaultWhen": "always",
+      "experimental": true,
+      "interactiveCliOnly": true,
+      "manifestField": "experimental.monitors",
+      "monitorToolRequired": true,
+      "projectScopeSkillsDirectoryPlugins": false,
+      "userConfigSubstitution": false,
+      "unsandboxed": true
+    },
     "manifest": ".claude-plugin/plugin.json",
     "marketplace": ".claude-plugin/marketplace.json",
     "paths": {
@@ -245,6 +263,13 @@
       "2026-09-01: https://code.claude.com/docs/en/plugins-reference documents that an existing `enabledPlugins` user setting and an active dependency requirement both take precedence over plugin.json `defaultEnabled`, while a marketplace entry's `defaultEnabled` takes precedence over the plugin manifest value.",
       "2026-09-01: https://code.claude.com/docs/en/plugins-reference documents that wrong types make most manifest fields fail plugin loading, but non-object `experimental` and `metadata` values are ignored with a `claude plugin validate` warning; `--strict` promotes warnings to failure. Before v2.1.222, `metadata` was treated as unrecognized.",
       "2026-09-01: https://code.claude.com/docs/en/plugins-reference documents custom component path fields as string or array values: commands, agents, workflows, outputStyles, experimental.themes, and experimental.monitors replace their default scans, while skills adds to the default scan. Keeping a replaced default requires listing it explicitly, for example `\"commands\": [\"./commands/\", \"./extras/\"]`.",
+      "2026-09-01: https://code.claude.com/docs/en/plugins-reference documents experimental plugin themes as JSON files in the default themes/ directory, each with a required base preset and sparse overrides map; the documented example also names the theme. Selected plugin themes persist as custom:<plugin>:<theme> and are read-only until Ctrl+E copies one into ~/.claude/themes/ for local editing.",
+      "2026-09-01: https://code.claude.com/docs/en/plugins-reference documents experimental plugin monitors at monitors/monitors.json as an array whose entries require unique name, persistent shell command, and description; optional when defaults to always and also accepts on-skill-invoke:<skill>.",
+      "2026-09-01: https://code.claude.com/docs/en/plugins-reference documents monitor command substitution for ${CLAUDE_PLUGIN_ROOT}, ${CLAUDE_PLUGIN_DATA}, ${CLAUDE_PROJECT_DIR}, and environment variables, but explicitly rejects ${user_config.*} because monitor commands run through a shell; monitor processes also receive no CLAUDE_PLUGIN_OPTION_ environment variables.",
+      "2026-09-01: https://code.claude.com/docs/en/plugins-reference documents that monitors run only in interactive CLI sessions, unsandboxed at hook trust level, are skipped when the Monitor tool is unavailable, do not load for project-scope skills-directory plugins, survive mid-session plugin disable until session end, and require a session restart after plugin update.",
+      "2026-09-01: https://code.claude.com/docs/en/plugins-reference marks themes and monitors experimental and warns their manifest schema may change between releases. Top-level themes and monitors still work with a validation warning, while a future release will require experimental.themes and experimental.monitors; Agent Bundle emits neither manifest field because the generated documents use the default locations.",
+      "2026-09-01: Local host proof against Claude Code 2.1.257 shows `claude plugin validate --strict` accepts emitted default-location themes and monitors, but also accepts a malformed theme missing base with a non-string override and a malformed monitor missing command without naming either file. The compiler's claude.themes.* and claude.monitors.* diagnostics and pinned schemas are therefore the content-validation guard.",
+      "2026-09-01: The same Claude Code 2.1.257 strict probe rejects a deprecated top-level `monitors` manifest key, confirming that the documented migration warning is promoted to failure by `--strict`; default-location emission avoids that unstable manifest key entirely.",
       "2026-09-01: https://code.claude.com/docs/en/plugins-reference requires component paths to be relative to the plugin root and start with `./`, except skills also accepts `.` starting in v2.1.221; before that version `.` failed manifest validation. A marketplace-root source that declares specific skills subdirectories replaces the default skills scan.",
       "2026-09-01: https://code.claude.com/docs/en/plugins-reference documents that a default folder shadowed by a replacing manifest path still allows the plugin to load but warns in `claude plugin list` and the `/plugin` detail view. Its file-locations table defines commands/ as flat Markdown Skill files and recommends skills/ for new plugins; Agent Bundle already emits flat `.md` commands in the canonical commands/ directory and deliberately leaves custom-path discovery to the host.",
       "2026-09-01: Local host proof against the observed Claude Code 2.1.257 binary (newer than the pinned 2.1.250 table): `claude plugin validate --strict` accepts an emitted plugin manifest containing displayName, object metadata, and defaultEnabled, and separately accepts `\"commands\": \"./custom/deploy.md\"` when that flat Markdown file exists and no default commands/ directory exists (host-adapters.native.test.ts). These positive probes establish acceptance; they do not claim that the CLI checks custom-path existence or contents.",