Host support: CodeWhale — Agent Plugins bundles, hash-bound trust, skills, MCP, and TUI hook profile

[ScriptedAlchemy]

Scope / research evidence

P2 feature expansion. Research date 2026-09-06; Agent Bundle baseline 5fc8de37c9695b816d55bdcf18a6bcb1dfee69f5. Read the actual CodeWhale repository and its linked official docs; no CLI or native invocation was run.

This is Hmbown/CodeWhale, whose current canonical site is codewhale.net. Do not build the adapter from an outdated deepseek-tui fork, old branded landing page, or Ponytail's instruction-only fallback. Current upstream has a real plugin-bundle contract; exact released behavior must still be pinned before support is advertised.

Primary specs and harness configuration

• Official docs index and canonical source
• Bundle schema, compatibility, discovery, trust and active components
• Install/update/uninstall and source formats
• Skill discovery, owned versus compatible roots and activation
• Implemented hook contract—not the similarly named RFC/internal event crate
• MCP configuration reference
• General configuration and legacy-path mapping
• Agent Plugins specification

Bundle boundary

Native plugin.json follows Agent Plugins v1 with client-specific metadata under extensions["net.codewhale"]; root mcp.json contains MCP declarations. Legacy plugin.toml remains supported. Multiple manifests have explicit precedence, and compatible Kimi fields have a bounded accepted subset. Unsupported native/LSP surfaces may be inventoried without activation; never label detected-only components runnable.

Prefer testing existing portable Agent Bundle output first. Use explicit native extension metadata only for commands/agents/hooks or policy details the portable format does not express. Keep one canonical operation registry; do not rewrite shared application logic into a second CodeWhale runtime.

Illustrative minimal package:

composite-root/
  plugin.json
  skills/review/SKILL.md
  mcp.json                    # only if declared
  mcp/example.mjs

{
  "$schema":"https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name":"example-plugin",
  "version":"1.0.0",
  "description":"Project review helpers"
}

Pin native namespace keys from the current parser before emitting them; do not guess a hooks or mcpServers top-level property into the closed spec manifest.

Native install and trust lifecycle

/plugin install ./composite-root
/plugin install github:example/repository
/plugin list
/plugin show example-plugin
/plugin trust example-plugin <full-content-hash>.<full-capability-hash>
/plugin enable example-plugin
/plugin disable example-plugin
/plugin uninstall example-plugin

Installation is not activation. The operator reviews content and capability hashes; changes invalidate that authorization. Remote installs are tarball-based and subject to network policy; exactly one bundle root must be discoverable. The native .installed-from marker protects manually placed bundles from overwrite/removal. A changed package update must not be auto-retrusted by Agent Bundle.

Use native registration rather than modifying shared trust files. Distinguish user/workspace plugin selection and their actual precedence. A compatible skills directory may be read-only even when content is visible; import into CodeWhale-owned roots instead of mutating another harness's files. Plugin skill namespaces and ordinary skill aliases must not create duplicate application operations.

MCP constraints relevant to generated output

Plugin MCP is stricter than arbitrary operator MCP configuration. Local paths/argv must satisfy containment rules, reviewed environment mappings name their source variable rather than carry literal secrets, and remote endpoints bind explicit network authority. Plugin-contributed OAuth is not automatically available merely because user-configured MCP supports more authentication modes.

Generate contained artifact-relative executable references and let the host expand supported PLUGIN_ROOT/PLUGIN_DATA semantics. Do not place reserved host anchors into the plugin's env map or repair a validation failure by switching to an unreviewed user-level server. Unsupported transport/authentication settings should fail with an actionable capability diagnostic.

Hook profile

docs/HOOKS.md explicitly limits the documented hook firing points to the interactive TUI; headless exec, dispatcher and ACP are not equivalent. Native hook components have been added to the bundle activation policy, but runtime support must be proved per profile.

Host configuration illustration:

[hooks]
enabled = true

[[hooks.hooks]]
name = "review-before"
event = "tool_call_before"
command = "node /installed/example/hooks/before.codewhale.mjs"
background = false

Project hook files have a different embedding shape from the surrounding user config; use the native serializer, not string pasting. Only documented steering events may change input/verdict. Observers and background hooks cannot provide a blocking decision; mode/env names retain legacy compatibility spellings. Global timeout overrides and TUI-versus-headless behavior require explicit tests.

Do not export secret-bearing environment previews in traces. A plugin receipt is not an OS sandbox, and native tool approval still applies after a server starts.

Acceptance

• Pin released host/parser/activation-policy revision and enumerate active versus inventoried-only components.
• Native validation accepts a portable skills-only package without workers/MCP/state machinery.
• Exactly-one-root archive checks, symlink restrictions and manifest precedence work on a real packed composite.
• Install remains disabled/untrusted until native review; changed bytes/capabilities invalidate trust; disable/revoke stops subsequent dispatch.
• Generated MCP succeeds from a relocated source-free package with reviewed argv/env and correct namespaced identities.
• Unsupported OAuth/network/path settings fail rather than escape through unrelated user config.
• TUI steering/observer hooks preserve actual payload, cancellation, timeout and background semantics; unsupported headless use is reported honestly.
• Global/project/compatible skill precedence is visible and no foreign harness directory is mutated.
• Update/remove preserves native authorization ownership, unowned files and durable data.
• Extend Composite conformance: test cross-host auto-discovery and precedence, not only file collisions #651/Small-plugin acceptance: skills and plain hooks without an unnecessary MCP/RSC runtime or empty Workbench #652 conformance and record successful native execution separately from inventory/validation.

No Fleet orchestrator, provider management, second trust database, model routing, automatic network grant, or broad relaxation of AB4106 is in scope.

[ScriptedAlchemy]

Resolved by #723 (4dc11a4a06).

CodeWhale — observed Hmbown/CodeWhale main 19d34a5fb6c07b34e0b7234beb74a1cf1969efb4, docs retrieved 2026-09-06 (native Agent Plugins v1.0.0 support since v0.9.4). Supported: the emitted package installs as one plugin.

Surface	State	Evidence
manifest	supported	2026-09-06: docs/PLUGIN_BUNDLES.md states "The standard's manifest root is closed: $schema, name, and the optional well-known fields (version, description, author, homepage, repository, license, keywords, extensions). An unknown root key is a parse error" — the closed root this projection emits and validates against the pinned 1.0.0 schema, and "unknown vendor namespaces are ignored, never rejected" for the manifest's extensions object.
skills	supported	2026-09-06: docs/SKILLS.md (commit 92547e460f007abf8807705036ca6a40fba5cbb9, 2026-09-01) and PLUGIN_BUNDLES.md both read skills from the bundle-root skills/ directory that this projection emits.
mcp	degraded	2026-09-06: CodeWhale narrows the standard's env rule — "Local stdio environment entries must use exact ${SOURCE_ENV} references" — so an emitted env value that is anything other than one whole variable reference is not accepted there.
placeholders	unavailable	2026-09-06: CodeWhale rejects PLUGIN_ROOT and PLUGIN_DATA as env entry names (as the 1.0.0 schema does), but its documentation never states whether it provides those variables or expands ${PLUGIN_ROOT} and ${PLUGIN_DATA} in args, env values, or cwd, so the reserved behavior of §9.1 is unproven there.
hooks	unavailable	2026-09-06: docs/HOOKS.md documents CodeWhale's own hook layout; Agent Plugins 1.0.0 defines no hooks, so this projection emits no hooks document for it to read.

Paths it reads: mcp.json, plugin.json, skills.
Install: /plugin install ./<plugin directory>.

Every row above is pinned to that client's own documentation on the date shown, is validated on every build, and renders in INSTALL.md and the generated hosts reference. A surface recorded unavailable or degraded names exactly what the client would need; no unsupported feature is projected silently.

[ScriptedAlchemy]

Current-main reconciliation

#723 delivered the codewhale portable-client record, retained after #727's duplicate-key cleanup. At main b5cf7575e0bcfa6da23e12d2c5628146bdbe5cb1, its MCP limitation still describes only exact-source environment values. The upstream plugin boundary also restricts reviewed network hosts/endpoints, remote headers, secret-bearing URLs and redirects; see the pinned upstream MCP guide.

This deferred correction is now #728, with actual record/rendering tests. Keep the completed compatibility-record work closed; do not infer that a transport the host supports generally means every emitted plugin configuration is accepted, or invent portable metadata to bypass native trust restrictions. The current evidence does not establish a completed native hook adapter or authenticated host journey.