ContractorAgent/docs/claude/PLAN.md

ContractorAgent Plan

Project Goal

Build an OpenClaw integration that turns contractor coding agents such as Claude Code into OpenClaw-managed agents.

Phase 1 focuses on Claude Code only. Gemini support is deferred.

Product Direction

The goal is not merely to launch Claude Code from OpenClaw, but to make Claude Code behave like an OpenClaw-managed agent while preserving Claude Code's own model capability and execution workflow.

Desired properties:

• OpenClaw manages agent identity, routing, workspace, and session ownership
• Claude Code manages the live conversational and task context for its own session
• OpenClaw tools and skills are adapted into forms Claude Code can consume
• OpenClaw channels and sessions remain the outer control plane

Core Design

Session Proxy Runtime

Use a session proxy runtime rather than replaying full OpenClaw-managed context into Claude Code on every turn.

Core idea:

• map each OpenClaw session to a Claude Code session
• on each new user message, find the mapped Claude session
• resume or continue that Claude session
• forward only the newest actionable message plus minimal metadata
• avoid rebuilding full prompt history on every turn

This reduces:

• duplicated context management
• token waste
• divergence between OpenClaw-visible history and Claude's actual working memory

Control Plane Split

OpenClaw remains source of truth for:

• agent registration
• routing and bindings
• workspace ownership
• permissions and approvals
• channel transport
• tool hosting

Claude Code remains source of truth for:

• live conversation state within a contractor session
• reasoning and coding flow
• internal execution trajectory

Feasibility Notes from Docs

OpenClaw ACP Agents

OpenClaw already supports Claude Code as an ACP harness runtime.

Relevant doc statements:

"ACP sessions let OpenClaw run external coding harnesses (for example ... Claude Code ...) through an ACP backend plugin."

"For Claude Code through ACP, the stack is:

1. OpenClaw ACP session control plane
2. bundled acpx runtime plugin
3. Claude ACP adapter
4. Claude-side runtime/session machinery"

This indicates Claude Code session hosting is already available as a foundation.

Source:

• https://docs.openclaw.ai/tools/acp-agents

OpenClaw ACP Session Semantics

Relevant doc statements:

"Follow-up messages in that conversation route to the same ACP session."

"/new and /reset reset the same bound ACP session in place."

"Use resumeSessionId to continue a previous ACP session instead of starting fresh."

These features support a persistent contractor-session bridge.

Source:

• https://docs.openclaw.ai/tools/acp-agents

OpenClaw Plugin Extensibility

Relevant doc statements:

"Plugins extend OpenClaw with new capabilities: channels, model providers, ... agent tools, or any combination."

"Agent tools | api.registerTool(...)"

"For provider plugins, tool plugins, hook plugins, and anything that is not a messaging channel."

These suggest a native OpenClaw plugin can host the contractor-agent bridge logic.

Sources:

• https://docs.openclaw.ai/plugins/building-plugins
• https://docs.openclaw.ai/plugins/sdk-entrypoints

OpenClaw CLI Extension Surface

Plugins can register CLI commands, but current docs do not show support for patching an existing core command such as openclaw agents add with extra flags.

Relevant doc statements:

"Common registration methods: ... registerCommand / registerCli | CLI commands"

"For plugin-owned root CLI commands, prefer api.registerCli(..., { descriptors: [...] }) ..."

Therefore the safer design is to add a plugin-owned command root rather than extending openclaw agents add directly.

Sources:

• https://docs.openclaw.ai/tools/plugin
• https://docs.openclaw.ai/plugins/sdk-entrypoints

Claude Code Plugin Surface

Claude Code has a plugin model with skills, agents, hooks, MCP servers, and LSP servers.

Relevant doc statements:

"A plugin is a self-contained directory of components that extends Claude Code with custom functionality. Plugin components include skills, agents, hooks, MCP servers, and LSP servers."

"Plugins add skills to Claude Code ... Claude can invoke them automatically based on task context"

This supports the idea that OpenClaw skills and tooling may be adapted into Claude Code-friendly forms instead of being injected as raw prompt only.

Source:

• https://code.claude.com/docs/en/plugins-reference

Initial CLI Plan

Introduce a plugin-owned command:

openclaw contractor-agents add --agent-id <agent-id> --workspace <workspace> --contractor <claude|gemini>

For phase 1, only claude is supported.

Intended behavior

For --contractor claude, the command should:

1. call:

openclaw agents add <agent-id> --workspace <workspace> --model <bridge-model-id> --non-interactive

2. mark the created agent as a contractor-backed agent
3. persist contractor runtime metadata for that agent
4. prepare storage for OpenClaw-session to Claude-session mappings

Proposed Agent Config Shape

Exact schema TBD, but directionally:

{
  agents: {
    list: [
      {
        id: "my-agent",
        workspace: "/path/to/workspace",
        model: "contractor-claude-bridge",
        runtime: {
          type: "contractor",
          contractor: {
            kind: "claude",
            backend: "acp",
            mode: "persistent"
          }
        }
      }
    ]
  }
}

Session Mapping Store

Keep dynamic mappings out of main config.

Suggested runtime state file location:

<agent-workspace>/.openclaw/contractor-agent/session-map.json

Possible structure:

{
  "sessions": [
    {
      "openclawSessionKey": "agent:my-agent:main",
      "claudeSessionId": "<resumeSessionId-or-runtime-id>",
      "createdAt": "2026-04-10T00:00:00Z",
      "lastActivityAt": "2026-04-10T00:00:00Z",
      "state": "active"
    }
  ]
}

Phase 1 Scope

In scope

• Claude contractor agent creation flow
• plugin-owned CLI for contractor agent management
• bridge model placeholder for Claude-backed agents
• persistent mapping of OpenClaw sessions to Claude sessions
• initial Claude-only runtime design
• planning documents and repository structure

Out of scope for now

• Gemini implementation
• full OpenClaw skill auto-conversion
• complete tool surface bridging
• advanced recovery and replay semantics
• UI polish and operational tooling

Open Questions

1. What is the best implementation seam for the bridge model inside OpenClaw, provider plugin, tool plugin, or service-backed pseudo model?
2. How should contractor metadata be persisted, agent runtime stanza, plugin config, or both?
3. What is the canonical identifier for Claude session continuation, ACP session id, adapter resume id, or plugin-owned alias?
4. Which minimal OpenClaw tools should be exposed first to Claude?
5. How should reset/new map to Claude-side session recreation?

Immediate Next Steps

1. Design the openclaw contractor-agents add CLI surface in detail
2. Define config schema for contractor-backed agents
3. Define session-map file schema and lifecycle
4. Determine how the bridge model id is registered by the plugin
5. Draft implementation skeleton for Claude-only support