feat: observation mode support (unified / directional)

[ajspig]

Priority: Medium

Description:

Summary

Port the observation mode feature from claude-honcho (PR #23, closes #22) to openclaw-honcho.

Currently the plugin runs in a hybrid state — the agent peer has observeOthers=true in hooks/capture.ts (creating cross-observations), but most tools query the owner peer's self-observations. This means cross-observations are generated but never read by tools, wasting deriver cycles and diverging from both the unified and directional patterns. Adding an explicit observationMode config flag fixes this inconsistency.

Current state (code-verified)

Peer config (hooks/capture.ts lines 58-66):

• ownerPeer: observeMe=true, observeOthers=cfg.ownerObserveOthers (default false)
• agentPeer: observeMe=true, observeOthers=true ← creates cross-observations always
• parentPeer (subagent): observeMe=false, observeOthers=true

Tool routing (current):

Tool	Current call	Pattern
honcho_ask (ask.ts)	agentPeer.chat(query, { target: ownerPeer })	cross-query ✓
honcho_context card (context.ts)	ownerPeer.card()	self-query
honcho_context full (context.ts)	ownerPeer.representation()	self-query
honcho_search_conclusions (search.ts)	ownerPeer.representation({ searchQuery })	self-query
honcho_session (session.ts)	session.context({ peerTarget: ownerPeer })	self-query
honcho_search_messages (message-search.ts)	ownerPeer.search()	self-query
context hook — subagent (context.ts)	agentPeer.context({ target: ownerPeer })	cross-query ✓
context hook — main (context.ts)	session.context({ peerTarget: ownerPeer })	self-query
memory runtime (runtime.ts)	ownerPeer.search()	self-query

Problem: ask.ts already uses the cross-query pattern, but context/search/session tools query owner self-observations. The agent peer generates cross-observations via observeOthers=true that are never queried by most tools.

Target state

Unified (default — fix current behavior):

• agentPeer.observeOthers = false (stop generating unused cross-observations)
• All tools query ownerPeer self-observations (current behavior for most tools)
• ask.ts switches to ownerPeer.chat(query) self-query (or keep cross-query — both resolve to same collection when agent has no cross-observations)

Directional (opt-in):

• agentPeer.observeOthers = true (current capture behavior)
• Tools switch to cross-query: agentPeer.context({ target: ownerPeer }), agentPeer.representation({ target: ownerPeer }), etc.
• Each agent maintains its own view of the user

Config

New observationMode: "unified" | "directional" (default "unified").

The existing ownerObserveOthers flag is orthogonal — it controls whether the owner peer observes agent messages (giving the user's representation awareness of agent replies). It should remain independent but the interaction should be documented.

Files to change

File	Change
config.ts	Add observationMode to HonchoConfig, parse + validate
openclaw.plugin.json	Add to configSchema + uiHints
hooks/capture.ts	Set agentPeer.observeOthers based on mode (false for unified, true for directional)
tools/ask.ts	Route based on mode — self-query in unified, cross-query in directional (currently always cross-query)
tools/context.ts	Route card() and representation() through agent peer in directional
tools/search.ts	Route representation({ searchQuery }) through agent peer in directional
tools/session.ts	Route session.context({ peerTarget }) based on mode
tools/message-search.ts	Route search() through agent peer in directional
hooks/context.ts	Main session context routing based on mode (subagent path already uses cross-query)
runtime.ts	Route ownerPeer.search() through agent peer in directional
README.md	Document both modes, migration path, interaction with ownerObserveOthers

OpenClaw-specific considerations

• Multi-session architecture: Observation mode applies only to conversational sessions — subagent sessions already use the cross-query pattern with parent peer as silent observer.
• Multi-peer group chat (PR feat: multi-peer group chat support with review fixes from #31 #51): If feat: multi-peer group chat support with review fixes from #31 #51 lands, directional mode needs to work with per-sender human peers. Routing becomes agentPeer.chat(query, { target: resolvedHumanPeer }).
• crossSessionSearch (v1.3.0): runtime.ts memory manager uses ownerPeer.search() — in directional mode this routes through agent peer.
• Migration path: Users switching modes need the migrate-observations flow from claude-honcho. Consider shipping a honcho migrate-observations CLI command.

Reference

• claude-honcho implementation: fix: correct observer/observed scoping + new MCP (0.2.4) + OSS scaffolding  claude-honcho#23
• Original bug: chat MCP tool doesn't pass target parameter — can't find conclusions claude-honcho#22