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

> Learn how non-hive-aware providers get initial prompts and lifecycle hooks using Munder Diffin's bridge descriptors. This guide explains the shim injection process.

- Repository: [Chaitanya Giri/munder-difflin](https://github.com/chaitanyagiri/munder-difflin)
- Tags: deep-dive
- Published: 2026-08-29

---

**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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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:

```js
{
  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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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:

```js
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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/shims/gemini.js)) and register with the provider's hook API at runtime:

```js
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:

```js
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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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.