Trace external CLI agent flows from launch through event conversion, tool-call persistence, and UI delivery. Use it to diagnose Claude Code or Codex adapter issues, execution identity, session boundaries, and subagent routing across the desktop and CLI pipeline.
Use for external-agent launchers and execution identity, Claude Code/Codex adapters, IPC, event mapping, sessions, persistence and tool-call chains.
Run score Not tested
See how to installThis skill helps investigate and change how an app launches external CLI agents such as Claude Code and Codex. It follows the flow from raw CLI output through adapter event conversion, saved assistant and tool messages, and display in the interface. It also covers turn boundaries, matching tool results to calls, keeping subagent threads separate, state when resuming, and the execution identity passed to a launched process. The guide recommends checking real traces and turning a narrowed reproduction into a focused test.
Use it when an external agent’s response appears twice, tool results do not appear, or multiple tool calls are combined into one. It also helps trace incorrect comment authorship or subagent content that appears in the main conversation, following the path from launch through persistence.
This skill covers the external CLI agent pipeline, rather than the ordinary server-side agent runtime. Compatibility checks with real models are limited to cases where the user explicitly invokes the designated skill.
This overview was written by AI (OpenAI Codex) from the public SKILL.md. Check the original below for the exact behavior.
AI checked the SKILL.md for operations that need care and for setup requirements. The score comes only from actually running the skill (hands-on test).
Not counted in the score. Rated by AI (OpenAI Codex) as of Oct 26, 2026. Treat it as a guide and read the original before installing.
Review the instructions the agent will receive before you install.
Use this skill when the bug or feature lives in the external CLI agent pipeline, not the normal server-side agent runtime.
apps/desktop/src/main/modules/heterogeneousAgent/drivers/packages/heterogeneous-agents/src/adapters/heteroAgentRawLine transport, window.__HETERO_AGENT_TRACE, or executeHeterogeneousAgentmessage.id boundaries, missing tool_result, TodoWrite state drift, or subagent thread routingheteroAgentRawLineHeterogeneousAgentEventexecuteHeterogeneousAgent persists assistant/tool messages and forwards stream eventscreateGatewayEventHandler hydrates the UIagent-tracing or context-engine debuggingapps/desktop/src/main/controllers/HeterogeneousAgentCtr.tsapps/desktop/src/main/modules/heterogeneousAgent/drivers/claudeCode.tsapps/desktop/src/main/modules/heterogeneousAgent/drivers/codex.tspackages/heterogeneous-agents/src/adapters/claudeCode.tspackages/heterogeneous-agents/src/adapters/codex.tssrc/store/chat/slices/agentRun/actions/transports/hetero/heterogeneousAgentExecutor.tssrc/store/chat/slices/agentRun/actions/__tests__/heterogeneousAgentExecutor.test.tscat .heerogeneous-tracing/.last-live-trace rather than hand-rolling a claude -p repro (see references/debug-workflow.md §2).executeHeterogeneousAgent exposes window.__HETERO_AGENT_TRACE.persistToolBatch, persistToolResult, step transitions, and subagent routing.ToolCallPayload.id.message.id are one turn, not multiple turns.tool_result lives in type: 'user' events, not assistant events.message_delta.usage is authoritative; do not trust echoed usage on every assistant block.persistToolBatch must pre-register assistant tools[] before creating tool messages.parentId equal to the owning assistant and tool_call_id equal to the tool id.tool_result must resolve an existing toolMsgIdByCallId.toolMsgIdByCallId map at main step boundaries.A connector or desktop process can itself run inside another Agent's conversation. Its inherited environment identifies the launcher, not the dispatched Agent.
LOBEHUB_AGENT_ID, LOBEHUB_ASSISTANT_MESSAGE_ID, LOBEHUB_TASK_ID, and LOBEHUB_WORKSPACE_ID; replace LOBEHUB_TOPIC_ID and LOBEHUB_OPERATION_ID with the dispatched values. Inject optional context only when supplied by the current dispatch; absent values must not retain ancestor identity.LOBEHUB_JWT or falling back to user credentials must not change the executing Agent. Never infer the author from the topic owner or task assignee.apps/cli/src/commands/task/lifecycle.ts, lh task comment must refuse to post when topic or operation context exists but the Agent ID is missing or blank. Ordinary terminal comments without execution identity remain user-authored. Misattributed Agent progress can otherwise become human <user_feedback> in later task runs.Check all four launch surfaces when changing this contract or adding a launcher:
| Surface | Entry point |
|---|---|
| CLI Agent dispatch | apps/cli/src/device/agentRun.ts — spawnHeteroAgentRun (Agent ID forwarded by apps/cli/src/commands/connect.ts) |
| CLI OpenClaw/Hermes | apps/cli/src/tools/heteroTask.ts — runHeteroTask |
| Desktop Agent dispatch | apps/desktop/src/main/controllers/HeterogeneousAgentImpl.ts — spawnLhHeteroExec |
| Desktop OpenClaw/Hermes | apps/desktop/src/main/controllers/GatewayConnectionCtr.ts — runHeteroTask |
Regression coverage must include a clean environment, conflicting ancestor identity, and missing current Agent/optional context. Check both OpenClaw and Hermes on CLI and Desktop, plus task comments after JWT fallback. Mocked spawn assertions verify environment construction, not end-to-end propagation through an external runtime.
message.id changes.type: 'user' tool_result blocks are being ignored because the code only inspects assistant events.pluginState.todos is being attached at tool-result time.parent_tool_use_id handling and whether subagent chunks are being forwarded to the main gateway handler.newStep or an equivalent turn-change signal.persistToolBatch Phase 1 ran before tool message creation.tool_result for unknown toolCallId and missing result_msg_id backfill.rate_limit_info rides on status: "allowed" too)./testing-heterogeneous-agents in Claude Code or
$testing-heterogeneous-agents in Codex. Do not automatically load or run that
skill during diagnosis. Its failed-cell evidence can be used here for diagnosis
or a code fix.No reviews yet. Tell others what you thought.
No login needed. Share how it worked for you, ask a question, or note where it did not run.
No comments yet. Be the first to write one.
Use this skill to verify a delivery by exercising the real product through a suitable surface such as a CLI, web app, desktop app, or iOS Simulator. It helps create or find a verification plan, capture evidence, and publish an acceptance report.
Use this skill to add an AI model provider to LobeHub across runtime integration, model cards, settings, branding, documentation, and acceptance checks. It also covers provider documentation updates and distinguishes new providers from models added to an existing provider.
Use this skill to add a server-side environment variable that sets a default for a user setting. It walks through validation, server configuration and store merging, plus updating the example environment file and self-hosting documentation.
Provides guidance for registering hooks around an agent’s execution steps, tool calls, human approvals, context compression, and sub-agent calls. Hooks can observe events, supply local mock tool results, or use webhooks to allow or deny tool results under configured policies.
Build event-driven background workflows for agents by defining sources, interpreting them as signals, and running actions through policies. It also guides asynchronous handoffs, deduplication, scoped execution, completion receipts, and observability.
Use this skill to run end-to-end acceptance checks for bot channels in real desktop chat apps. It drives apps such as Discord, Slack, Telegram, WeChat, Lark, and QQ to send a message, wait for a response, and capture the result.