II.
Page overview
Reference · livepage:docs-adapters-babysitter-integrations-plugin-mode
Plugin Mode — Babysitter SDK Running Inside Host Agents overview
Inspect the raw attributes, linked wiki pages, and inbound or outbound graph edges for page:docs-adapters-babysitter-integrations-plugin-mode.
Attributes
nodeKind
Page
sourcePath
docs/adapters-babysitter-integrations/plugin-mode.md
sourceKind
repo-docs
title
Plugin Mode — Babysitter SDK Running Inside Host Agents
displayName
Plugin Mode — Babysitter SDK Running Inside Host Agents
slug
docs/adapters-babysitter-integrations/plugin-mode
articlePath
wiki/docs/adapters-babysitter-integrations/plugin-mode.md
article
# Plugin Mode — Babysitter SDK Running Inside Host Agents
## Summary
When babysitter runs as a plugin inside another agent (claude-code, codex, gemini-cli, copilot), the SDK operates in "plugin mode" — effects are delegated to the host agent, capabilities are discovered via environment variables, and the hook lifecycle is driven by hooks-adapter.
This document covers gaps in the plugin integration surface and what's needed to enable cross-agent dispatch from within plugin mode.
## Current Architecture
```
Host Agent (claude-code, codex, etc.)
↓ turn.stop hook fires
hooks-adapter adapter (per-agent normalizer)
↓ injects AGENT_CAPABILITIES_JSON + AGENT_SESSION_ID
Babysitter SDK (unified adapter)
↓ runs process iteration
↓ ctx.task() creates effects → throws EffectRequestedError
↓ stop-hook handler: {"decision": "block", "pendingEffects": [...]}
hooks-adapter renders response back to host
↓
Host agent resolves effects (file edits, bash, etc.)
↓ calls babysitter MCP server task_post
SDK journals resolution → next iteration
```
## Gaps
### 1. No adapters dispatch from plugin mode
**Current:** When babysitter runs as a plugin inside claude-code, it can only delegate effects to claude-code itself. It cannot ask codex or gemini-cli to do something.
**Needed:** Process definitions running in plugin mode should be able to create `external: true` agent tasks that dispatch through adapters, just like the standalone genty path.
**Implementation:**
- The stop-hook handler must distinguish between "host-resolvable" effects and "external agent" effects
- Host-resolvable effects: file edits, bash, breakpoints → delegated to host agent
- External agent effects: `kind: "agent", agent.external: true` → resolved by babysitter itself via adapters
- The SDK's `stopHookHandler.ts` needs a branch: if effect is external-agent, resolve it internally before returning control to host
**Files affected:**
- `packages/babysitter-sdk/src/harness/hooks/stopHookHandler.ts:152-186` — detect external effects
- `packages/babysitter-sdk/src/harness/hooks/stopHookContinuation.ts` — include external dispatch results
- `packages/genty/platform/src/harness/internal/createRun/orchestration/externalAgentEffect.ts` — shared resolution logic
### 2. No host tool discovery
**Current:** The SDK knows the host agent's *capabilities* (file-edit, bash, browser) via `AGENT_CAPABILITIES_JSON`, and may receive an optional structured `hostTools` inventory when the adapter can report reliable host-native tool descriptors.
**Needed:** The SDK should be able to query the host agent's tool inventory so process definitions can make informed decisions about what to delegate vs. what to dispatch externally.
**Implementation:**
- Extend `AGENT_CAPABILITIES_JSON` to include optional `hostTools` inventory
- hooks-adapter adapters populate this from reliable host agent tool descriptors when available
- SDK's promptContext includes available host tools and renders them separately from external agent dispatch guidance
**Files affected:**
- `packages/adapters/hooks/core/src/types/adapter.ts` — extend AdapterCapabilities
- `packages/adapters/hooks/adapter-claude/src/adapter.ts` — populate tool list
- `packages/babysitter-sdk/src/harness/unified/capabilities.ts` — parse tool inventory
- `packages/babysitter-sdk/src/harness/unified/promptContext.ts` — include in process context
### 3. No effect cancellation from host
**Current:** Host agent can resolve effects via `task_post` but cannot cancel pending effects.
**Needed:** `task_cancel` MCP tool so the host agent can abandon effects it can't or doesn't want to resolve.
**Files affected:**
- `packages/babysitter-sdk/src/mcp/tools/tasks.ts` — add `task_cancel` tool
- `packages/babysitter-sdk/src/runtime/intrinsics/task.ts` — handle cancellation in journal
### 4. No cross-plugin coordination
**Current:** Each plugin instance is isolated. Babysitter plugin in claude-code can't coordinate with babysitter plugin in codex running in a different session.
**Needed (future):** Shared task queue across plugin instances via tasks-adapter. When babysitter in claude-code creates a breakpoint, a babysitter instance in codex could pick it up.
**Files affected:**
- `packages/tasks-adapter/src/backend.ts` — backend needs multi-session support
- `packages/babysitter-sdk/src/harness/hooks/stopHookHandler.ts` — check for cross-session tasks
### 5. Subprocess support in plugin mode
**Status:** Plugin-mode CLI iteration now opts into explicit `"plugin-local"` subprocess support when the run is executing inside a host-agent plugin session. Agent-platform continues to use `"agent-platform"`, and ordinary local iteration keeps subprocess support disabled.
**Lifecycle:** Plugin-local subprocesses are emitted as subprocess effects. They stay tied to the parent run journal and existing `ctx.onCleanup()` terminal cleanup path, so cleanup callbacks are not flushed while the parent is waiting on the subprocess effect and are flushed on terminal run paths.
**Files affected:**
- `packages/babysitter-sdk/src/runtime/intrinsics/subprocess.ts` — allow explicit supported modes while preserving disabled as a hard block
- `packages/babysitter-sdk/src/runtime/types.ts` — include the plugin-local subprocess support mode
- `packages/babysitter-sdk/src/cli/commands/runIterate.ts` — detect plugin-mode iteration and opt into plugin-local support
### 6. Process creation context lacks host agent identity
**Current:** Process creation prompts mention harness capabilities but don't clearly state "you are running inside claude-code" or "codex is your host."
**Needed:** The process definition prompt should explicitly say what agent it's running inside, what that agent can do, and what it can't do. This helps the LLM choose between host delegation and external dispatch.
**Files affected:**
- `packages/genty/platform/src/harness/internal/createRun/planProcess/phase.ts` — inject host identity
- `packages/genty/platform/src/harness/internal/createRun/prompts.ts` — host-aware prompt section
## Integration with External Agent Tasks
When an external agent task is dispatched from plugin mode:
```
Process running in claude-code plugin:
ctx.task(externalCodexTask) // kind: "agent", external: true, adapter: "codex"
↓
SDK creates effect with externalDispatch: true
↓
Stop-hook handler detects external effect
↓
Instead of delegating to host, resolves internally:
- Checks adapters availability
- Calls adapterBridge.invokeViaAgentMux("codex", { prompt, model })
- Journals result + cost
↓
Returns to host with external effect already resolved
↓
Host sees only remaining host-resolvable effects
```
This means external dispatch is **transparent to the host agent** — the host never needs to know about adapters.
## Test Strategy
| Test | Description |
|------|-------------|
| Plugin stop-hook with external effects | Mock host hook → SDK creates external effect → verify it's resolved internally, not delegated to host |
| Plugin stop-hook with mixed effects | Some host-resolvable + some external → verify external resolved, host effects returned |
| Host tool discovery | Mock AGENT_CAPABILITIES_JSON with tools → verify promptContext includes them |
| task_cancel MCP tool | Cancel a pending effect → verify journal has cancellation event |
| Subprocess in plugin mode | Create subprocess effect in plugin mode → verify it works (currently blocked) |
documents
[]
Outgoing edges
None.
Incoming edges
contains_page1
- page:docs-adapters-babysitter-integrations·PageAgent-Adapter ↔ Babysitter Integration