How Non-Hive-Aware Providers Receive Initial Prompts and Lifecycle Hooks via Bridge Descriptors in Munder Difflin

Munder Difflin uses bridge descriptors to inject shims or proxies that translate Hive protocol events into provider-native formats, allowing non-hive-aware providers to receive initial prompts through custom flags while exposing full lifecycle hooks to the Hive orchestrator.

In the Munder Difflin framework, provider interoperability depends on whether a CLI can natively parse Hive protocol flags. When a provider lacks this capability—marked as hiveAware: false in the preset configuration—the system relies on bridge descriptors to inject initial prompts and translate lifecycle events. This mechanism ensures that even proprietary or legacy provider CLIs can participate fully in the Hive orchestration ecosystem without modifying their core binaries.

Understanding Hive-Aware vs. Non-Hive-Aware Providers

Munder Difflin categorizes providers based on their ability to accept standard Hive protocol flags such as --append-system-prompt and --settings. A provider with hiveAware: true processes these arguments directly, while non-hive-aware providers require external adaptation. The distinction is declared in the provider preset—specifically in index-j0JdoH0M.js—where the hiveAware boolean determines whether the harness uses native protocol handling or activates bridge descriptor logic.

Bridge Descriptors: The Core Mechanism

Bridge descriptors act as adaptation layers that enable non-hive-aware providers to communicate with the Hive runtime. These descriptors define how initial prompts are delivered and how lifecycle hooks—such as PreToolUse, PostToolUse, and Stop events—are translated between the provider's native callback system and the Hive protocol.

According to the source code in index-j0JdoH0M.js, the bridge object within a provider preset specifies the adaptation strategy through two primary mechanisms: kind: "hooks" for shim-based translation and kind: "proxy" for OpenAI-compatible request routing.

The Bridge Descriptor Structure

A bridge descriptor is defined within the provider preset configuration. For example, the Gemini CLI preset declares:

{
  id: "gemini",
  hiveAware: false,
  bridge: { kind: "hooks", shim: "gemini" },
  initialPromptFlag: "-i",
  canReceiveInbox: true,
  // …other fields
}

This declaration at lines 39869–39871 in index-j0JdoH0M.js instructs the harness to load the Gemini-specific hook shim when spawning the provider process. Similar configurations exist for Opencode, Pi, and other non-hive-aware providers, each specifying their respective shim identifiers or proxy endpoints.

Resolving Bridges with bridgeOf()

The system resolves which bridge to apply through the bridgeOf(provider) helper function, implemented at lines 40211–40215 in index-j0JdoH0M.js. This function returns the bridge descriptor by checking the preset's bridge field first, falling back to a legacy hookBridge construction if necessary:

const bridge = bridgeOf(providerId); // Returns { kind, shim, ... } or undefined

This resolution occurs during the spawn preparation phase, determining whether the harness will inject a hooks shim or route traffic through a protocol proxy.

Delivering Initial Prompts to Non-Hive-Aware Providers

Since non-hive-aware providers cannot parse the Hive protocol's native CLI arguments, Munder Difflin delivers the Hive seed—the serialized protocol state containing the initial prompt and settings—through provider-specific mechanisms defined in the preset configuration.

Flag-Based Prompt Injection

Most non-hive-aware providers accept the initial prompt through a dedicated command-line flag. The initialPromptFlag property in the preset specifies which flag to use:

• Gemini: Uses -i (defined at lines 39873–39874)
• Opencode: Uses --prompt (defined at lines 39958–39960)

The harness concatenates this flag with the serialized Hive seed when constructing the spawn command, effectively bootstrapping the provider with the necessary context without requiring native Hive protocol support.

Positional Argument Injection

Some providers lack specific flags for prompt injection. In these cases, the preset sets positionalInitialPrompt: true (as seen with Grok and Kimi configurations), causing the harness to pass the Hive seed as a positional argument rather than a flagged option. For example, Pi receives the prompt via positional argument (void 0 for initialPromptFlag indicates no flag exists), allowing the shim to capture and process the input stream accordingly.

Lifecycle Hook Translation via Bridge Shims

While initial prompt delivery establishes the starting state, lifecycle hooks provide the ongoing two-way communication necessary for tool orchestration. Bridge descriptors implement this through either hooks-based shims or protocol proxies.

Hooks-Kind Bridges

When bridge.kind equals "hooks", Munder Difflin injects a small shim module that intercepts the provider's native lifecycle callbacks and forwards them to the Hive runtime. The shim field specifies which module to load:

• Gemini: installGeminiHooks translates Gemini's BeforeTool and AfterTool callbacks into Hive's PreToolUse and PostToolUse events
• Opencode: installOpenCodePlugin handles session.idle lifecycle states
• Pi: installPiHooks maps tool_call and agent_end events to corresponding Hive hooks

These shims reside in the src/shims/ directory (e.g., shims/gemini.js) and register with the provider's hook API at runtime:

module.exports.install = () => {
  const { on } = require('gemini-hooks');
  on('BeforeTool', payload => forwardToHive('PreToolUse', payload));
  on('AfterTool',  payload => forwardToHive('PostToolUse', payload));
  on('Stop',       payload => forwardToHive('Stop', payload));
};

Proxy-Kind Bridges

For providers that expose an OpenAI-compatible HTTP interface rather than a CLI hook system, bridge descriptors use kind: "proxy". This configuration routes the provider through a generic OpenAI proxy that injects the Hive protocol as a standard request payload. Providers such as Qwen and Crush utilize this method, allowing the harness to wrap the provider's API without requiring native CLI flag support.

Implementation Example: Spawning a Provider with Bridge Support

The following implementation demonstrates how Munder Difflin orchestrates the spawn process for a non-hive-aware provider, combining bridge resolution, prompt injection, and shim installation:

import { providerPreset, bridgeOf } from './index-j0JdoH0M.js';
import { spawn } from 'child_process';

function spawnProvider(providerId, hiveSeed) {
  const preset = providerPreset(providerId);
  const bridge = bridgeOf(providerId);        // Resolve bridge descriptor
  const flag   = preset.initialPromptFlag;   // e.g., '-i' or '--prompt'

  // Construct CLI command
  let cmd = [preset.defaultCommand];
  if (flag) {
    cmd.push(flag, hiveSeed);                // Flag-based injection
  } else if (preset.positionalInitialPrompt) {
    cmd.push(hiveSeed);                      // Positional injection
  }

  // Install appropriate bridge mechanism
  if (bridge?.kind === 'hooks') {
    const shim = require(`./shims/${bridge.shim}.js`);
    shim.install();                          // Register hook translators
  } else if (bridge?.kind === 'proxy') {
    startOpenAIProxy(bridge);                // Initialize protocol proxy
  }

  // Execute provider process
  const child = spawn(cmd[0], cmd.slice(1), { stdio: 'inherit' });
  return child;
}

This pattern ensures that providers like Gemini, Opencode, and Pi receive the full Hive protocol context through their native input mechanisms while their lifecycle events remain visible to the orchestrator via the bridge descriptor's translation layer.

Summary

• Non-hive-aware providers are marked with hiveAware: false in index-j0JdoH0M.js and require bridge descriptors for Hive protocol integration.
• Bridge descriptors define adaptation strategies via kind: "hooks" (shim injection) or kind: "proxy" (protocol routing).
• The bridgeOf() function resolves the appropriate bridge configuration from provider presets, handling both modern bridge fields and legacy hookBridge definitions.
• Initial prompts are delivered through provider-specific flags (e.g., Gemini's -i, Opencode's --prompt) or as positional arguments when positionalInitialPrompt is enabled.
• Hooks-kind bridges load shim modules (such as installGeminiHooks, installOpenCodePlugin, or installPiHooks) that translate provider-native callbacks into Hive lifecycle events including PreToolUse, PostToolUse, and Stop.
• Proxy-kind bridges route requests through an OpenAI-compatible adapter, enabling API-based providers to participate without CLI modifications.

Frequently Asked Questions

What defines a "non-hive-aware" provider in Munder Difflin?

A provider is classified as non-hive-aware when its CLI cannot directly parse Hive protocol flags such as --append-system-prompt or --settings. This status is explicitly declared in the provider preset's hiveAware: false property within index-j0JdoH0M.js, triggering the harness to activate bridge descriptor logic for protocol adaptation.

How does the bridgeOf function determine which bridge to use?

The bridgeOf function, located at lines 40211–40215 in index-j0JdoH0M.js, checks the provider preset for a bridge property first. If present, it returns that descriptor object. If absent, it constructs a fallback bridge from legacy hookBridge properties, ensuring backward compatibility while preferring the modern descriptor format.

Can non-hive-aware providers receive real-time tool execution callbacks?

Yes. Through kind: "hooks" bridge descriptors, Munder Difflin injects shim modules that intercept the provider's native lifecycle callbacks—such as Gemini's BeforeTool or Pi's tool_call events—and forward them to the Hive runtime as standardized PreToolUse and PostToolUse events. This provides full lifecycle visibility without requiring native Hive protocol support in the provider binary.

What is the difference between hooks-kind and proxy-kind bridges?

Hooks-kind bridges (kind: "hooks") load JavaScript shim modules that hook into the provider's native callback system to translate events, suitable for CLI-based providers like Gemini and Opencode. Proxy-kind bridges (kind: "proxy") route the provider through an OpenAI-compatible HTTP proxy that injects Hive protocol data into standard API requests, used for providers such as Qwen and Crush that expose REST endpoints rather than CLI hooks.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}