docs: fix Mode C handler example — cwd-based agent resolution

[ajianaz]

Summary

Fix the Mode C handler example in Hermes integration docs.

Problem

The example handler used /proc/self/cmdline to resolve agent name. This is unreliable because:

1. Shell hooks run as child subprocesses — their cmdline is the handler script, not the gateway
2. Module-level AGENT = _resolve_agent_name() resolves once at import time, not per invocation
3. Hardcoded UTEKE_BIN path doesn't work for users who install uteke differently

This caused agent name resolution failures when hooks were invoked from asyncio contexts (e.g., session expiry watcher).

Changes

Before	After
/proc/self/cmdline → parse -p flag	cwd from Hermes wire protocol payload
AGENT = _resolve_agent_name() (module-level)	Per-invocation: _resolve_agent_name(raw.get("cwd", ""))
UTEKE_BIN path check + hardcoded fallback	"uteke" (assumes on PATH)
Cron session skip in handler	Removed (registration-level concern)

The cwd-based approach is battle-tested across all 6 production agents and documented in the Hermes hook injection reference.

Files

• docs/integrations/hermes.md — Mode C handler example script

[github-actions]

🔍 Cora AI Code Review

❌ Blocked — critical issues found.

🔴 Error (1)

• docs/integrations/hermes.md:409 — The new _resolve_agent_name iterates [p, *p.parents] starting from the cwd itself (deepest) and returns the first directory whose name isn't "profiles". If the cwd is a subdirectory beneath the agent directory (e.g., /opt/data/profiles/myagent/sessions/123), the function returns 123 (the session ID) instead of myagent (the agent name). The != "profiles" check implies the expected structure is .../profiles/<agent_name>/..., but the iteration order returns the deepest component, not the one immediately following "profiles". This would cause memories to be stored/recalled under the wrong namespace.

---

Review powered by cora-cli · BYOK · MIT