Host support: Grok Build — plugin discovery, native hook semantics, and MCP configuration

[ScriptedAlchemy]

Scope / evidence

P2 feature expansion. Research date 2026-09-06; Agent Bundle baseline 5fc8de37c9695b816d55bdcf18a6bcb1dfee69f5. Read xAI's own host documentation and official marketplace repository; no Grok installation/native test was run. Grok Build is the coding harness, not the xAI REST model API.

Primary sources

• Skills, plugins, marketplaces and compatibility
• Native hook events and script contract
• MCP configuration, CLI and precedence
• Official marketplace authoring/source format
• Official marketplace catalog
• Ponytail Grok plugin — consumer example only

Native model and limits

Grok discovers native plugin directories from project/user locations, configured paths and --plugin-dir. Skills come from .grok/skills, global skills, enabled plugins and configured sources. Existing Claude-compatible material may also be discovered. Compatibility discovery is not proof that all callback semantics are identical.

The official marketplace defines conventional skills/, commands/, agents/, hooks/hooks.json, .mcp.json, and .lsp.json; an optional root plugin.json can provide metadata/path overrides. Marketplace remote sources require full commit pinning; a generated component index is not a hand-authored plugin API.

The current hook guide says only PreToolUse is blocking. Passive event stdout is ignored. A deny result or exit 2 blocks; crashes, malformed output and timeouts otherwise fail open. Consequently a canonical promise of context injection on session start or guaranteed deny-on-timeout cannot simply be copied from Claude. Report unsupported control effects rather than inventing them.

Proposed layout and operator setup

composite-root/
  plugin.json
  skills/review/SKILL.md
  commands/review.md
  hooks/grok-hooks.json        # use an override only after parser verification
  hooks/tool-before.grok.mjs
  mcp/example.mjs

Start with explicit local loading to validate the chosen parser/version:

grok --plugin-dir /absolute/composite-root
grok inspect
grok mcp list --json
grok mcp doctor example --json

Use /plugins to inspect and enable installed components and /hooks-trust for project code after user review. Do not automatically add --trust or alter trusted_folders.toml as an installer shortcut.

For independent declared MCP delivery, the host documents:

grok mcp add example -- node /absolute/composite-root/mcp/example.mjs

Equivalent native config shape:

[mcp_servers.example]
command = "node"
args = ["/absolute/composite-root/mcp/example.mjs"]

Project scope uses .grok/config.toml; user scope uses ~/.grok/config.toml. Existing compatible MCP files merge at a different precedence. Keep secret values in the operator environment or native credential flow, not published manifests. Do not both install bundled MCP and add an independent duplicate definition automatically.

Hook lowering example

Host shape, with the command path resolved from a supported native plugin anchor during emission/installation:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "node /installed/example/hooks/tool-before.grok.mjs", "timeout": 10 }]
      }
    ]
  }
}

The adapter must preserve Grok payload fields, matcher behavior, error/timeout semantics and GROK_PLUGIN_ROOT/GROK_PLUGIN_DATA separation. The example's absolute path is illustrative; published output must not contain a build-checkout path. Shell quoting and platform support need real fixtures.

Design requirements

1. Prove whether the existing Claude/portable artifact subset already loads correctly before adding redundant documents.
2. Create a Grok capability profile that distinguishes skill activation, MCP tools, observational hooks and before-tool denial. Do not mark passive context injection supported because a hook process ran.
3. Use canonical operation/schema records for MCP and shared authored content for skills/commands. No independent application registry or Grok agent loop.
4. Pin plugin manifest/override parsing from native evidence or official first-party examples; the high-level compatibility claim alone is insufficient.
5. Test effective discovery when .claude, .cursor, .agents, root plugin and native Grok files coexist. Explicit conflict diagnostics are preferable to silently running hooks twice.
6. Installation receipts own only the native entries created by this integration. Preserve existing project/user MCP config, disabled plugins, trust state and durable data.

Acceptance

• Pin host version and native/compatible discovery rules with reference provenance.
• Static skills package works without a worker/MCP process and preserves native frontmatter semantics; allowed-tools must not be presented as a permission grant.
• A deny prevents a sentinel tool action; malformed/timeout behavior matches the documented host limit and is visible.
• Unsupported passive context mutation produces a build/inspection diagnostic rather than a silent no-op.
• A generated MCP operation succeeds after relocation and actual package installation, with expected namespace/argv/environment.
• Test native and compatible config precedence, multiple plugins, disabled components, and no duplicate activation.
• Full-SHA marketplace source and generated index remain consistent if marketplace distribution is in scope.
• Update/uninstall removes only owned registrations and keeps unrelated files/state.
• Add Composite conformance: test cross-host auto-discovery and precedence, not only file collisions #651 composite and Small-plugin acceptance: skills and plain hooks without an unnecessary MCP/RSC runtime or empty Workbench #652 small-plugin regression coverage; retain custom-host AB4106 isolation until coexistence is proven.

No LSP implementation, automatic marketplace submission, trust bypass, global permission edits, or required domain retry/state system is in scope.

[ScriptedAlchemy]

Resolved by #721 (72a8857ebe).

Grok Build — observed xai-org/grok-build main 72a61251fcffb464bcc687aeb5a998e5a98ec0c9, docs retrieved 2026-09-06. Supported at the skills tier: the emitted skill tree loads; the manifest does not.

Surface	State	Evidence
manifest	unavailable	2026-09-06: unproven. The root manifest is documented only as optional metadata and path overrides, with no published field list, validation rule, or precedence order, so nothing about Grok's handling of the emitted manifest is pinned.
skills	supported	2026-09-06: https://docs.x.ai/build/features/skills-plugins-marketplaces lists "Any enabled plugin's skills/ directory" as a discovery root, and states SKILL.md frontmatter "Extra keys are ignored" — Grok additionally "accepts model, effort, license, and compatibility and does not apply them", all of which this projection may emit.
mcp	unavailable	2026-09-06: the only documented plugin MCP file is .mcp.json (https://docs.x.ai/build/features/mcp-servers: "MCP servers: a .mcp.json file"); no upstream page states that a root, non-dotted mcp.json is read, so the emitted mcp.json is not proven to load.
placeholders	unavailable	2026-09-06: GROK_PLUGIN_ROOT and GROK_PLUGIN_DATA are documented only as hook environment variables ("Plugin hooks additionally receive GROK_PLUGIN_ROOT and GROK_PLUGIN_DATA in their environment"); no ${...} expansion inside plugin MCP configuration is documented.
hooks	unavailable	2026-09-06: Grok reads plugin hooks from hooks/hooks.json and runs them only once the plugin is trusted (https://docs.x.ai/build/features/hooks); Agent Plugins 1.0.0 defines no hooks, so this projection emits no hooks document for it to read.

Paths it reads: skills.
Install (no local-directory form is published): grok plugin install <marketplace plugin name> --trust.

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.