docs: add initial ContractorAgent planning

docs/claude/PLAN.md

@@ -0,0 +1,249 @@
+# 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:
+
+```bash
+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:
+
+```bash
+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:
+
+```json5
+{
+  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:
+
+```text
+<agent-workspace>/.openclaw/contractor-agent/session-map.json
+```
+
+Possible structure:
+
+```json
+{
+  "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