slopus--happy/docs/competition/claude/message-protocol.md

Claude Code Protocol and Control Surface

Bottom line

Claude Code is not one protocol. It is several layers:

• ACP for clean client/agent session control
• hook JSON for event interception and policy
• local ~/.claude/ files for rich team and subagent state
• product behavior documented partly in changelog and settings examples

That makes it powerful, but harder to copy cleanly.

ACP session protocol

ACP is the cleanest part of the Claude stack.

• ACP is JSON-RPC
• sessions stream updates through session/update
• updates include user chunks, agent chunks, thoughts, tool calls, tool call updates, plans, current mode updates, config option updates, and session info
• prompt execution, cancel, load, resume, fork, close, and list are all explicit protocol operations

Primary source files:

• ../happy-adjacent/research/agent-client-protocol/src/agent.rs
• ../happy-adjacent/research/agent-client-protocol/src/client.rs
• ../happy-adjacent/research/agent-client-protocol/src/tool_call.rs

Claude ACP adapter behavior

The Claude ACP adapter maps Claude Code behavior into ACP.

• permission modes such as default, acceptEdits, plan, dontAsk, and bypassPermissions are surfaced through ACP-facing controls
• mode and model configuration are emitted as config options and current-mode updates
• additional workspace scope is passed through _meta.additionalRoots
• session create, load, resume, replay, and fork are implemented in the adapter layer

This is important for Happy because it shows where clean protocol stops and provider-specific behavior begins.

Primary source files:

• ../happy-adjacent/research/claude-code-acp/src/acp-agent.ts
• ../happy-adjacent/research/claude-code-acp/src/settings.ts

Hook/event protocol

Claude has a separate typed event surface for hooks.

• hook input includes session_id, transcript_path, cwd, permission_mode, and hook_event_name
• hook events include PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, and Notification
• changelog notes add additional events such as PermissionRequest, SubagentStart, TeammateIdle, and TaskCompleted
• hook outputs can allow, deny, ask, suppress output, or inject system messages

This is one of the best pieces of Claude's design: event interception is explicit.

Primary source files:

• ../happy-adjacent/research/claude-code/plugins/plugin-dev/skills/hook-development/SKILL.md
• ../happy-adjacent/research/claude-code/CHANGELOG.md

Subagents and task tracking

Claude is strongest here at the product level, but the state lives in several places.

• custom agents are markdown-defined with frontmatter such as name, description, model, color, and optional tool restrictions
• the Task tool launches or communicates with agents
• local team state lives under ~/.claude/teams/
• local task queue state lives under ~/.claude/tasks/
• subagent conversation chains live under ~/.claude/projects/.../subagents/

The main lesson for Happy is not to copy the hidden-file layout. The lesson is to keep agent identity, team membership, and task lifecycle explicit.

Primary source files:

• ../happy-adjacent/research/claude-code/plugins/plugin-dev/skills/agent-development/SKILL.md
• docs/research/agent-teams-claude-code.md
• ~/.claude/teams/
• ~/.claude/tasks/

Permissions and mode switching

Claude treats this as real state, not a prompt-only convention.

• settings files define ask/deny policy and whether bypass mode is allowed
• PreToolUse hooks can make permission decisions
• dedicated PermissionRequest hooks can also approve or deny
• plan mode is a real runtime mode, not just different wording
• custom agents can carry their own permission mode

This is a strong pattern for Happy: mode and permission state should be first-class and inspectable.

Primary source files:

• ../happy-adjacent/research/claude-code/examples/settings/settings-strict.json
• ../happy-adjacent/research/claude-code/plugins/plugin-dev/skills/hook-development/SKILL.md
• ../happy-adjacent/research/claude-code/CHANGELOG.md

Sandbox and workspace controls

Claude's safety story is layered.

• shell sandboxing is focused mainly on Bash
• settings include network allowlists, command exclusions, and nested sandbox behavior
• additional read/write controls and protected directories exist
• workspace trust is a separate gate from sandboxing

This is less unified than Codex's sandbox policy, but still better than pretending all tool safety is the same thing.

Primary source files:

• ../happy-adjacent/research/claude-code/examples/settings/README.md
• ../happy-adjacent/research/claude-code/examples/settings/settings-bash-sandbox.json
• ../happy-adjacent/research/claude-code/CHANGELOG.md

Resume, fork, and lifecycle

Claude clearly treats session lifecycle as a product priority.

• session start/end and compaction have hook events
• resume and continue have many changelog fixes around transcript restoration and tool-result replay
• fork was renamed to branch and needed isolation fixes
• sessions support naming and named resume
• local per-session state is often keyed by session_id

This is a reminder for Happy that resume correctness is not a small detail; it is a protocol feature.

Remote and sync implications

Claude is the weakest clean reference here.

• ACP is promising for remote control and agent interoperability
• there is a remote-control bridge to claude.ai/code
• MCP networking is well-documented
• but the richest team and subagent state still lives in local files under ~/.claude/

So Claude is useful as a workflow reference, but not the best single source for Happy's own sync protocol.

What Happy should steal

• first-class mode and permission state
• typed event interception around tools and lifecycle
• strong subagent identity and task lifecycle concepts
• explicit resume/fork semantics
• do not copy the dependency on hidden local files as the main state model