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

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.