Summary

Two substantial deliverables. After this lands: 7/7 plugin extractions complete (closes Lock R3-2); 9/9 periodic-task listeners on the gateway path (Phase 2 of 6).

Companion kora-docs PR with HOW_TO doc: https://github.com/rafe-walker/kora-docs/pull/new/docs/kora-KR-PLUGIN-IDENTITY-OPTION-C-AND-DAEMON-PHASE2-MEGABUCKET

Deliverable A — KR-PLUGIN-IDENTITY (Option C)

Full identity-as-plugin architecture. Multi-tenant deployments + `pip install kora-runtime` distribution become possible.

IdentitySpec contract

```python
@DataClass(frozen=True)
class IdentitySpec:
soul_md_content: str # persona prompt (historically ~/.kora/SOUL.md)
system_prompt_content: str # reasoning-engine prompt (kora_system_prompt.md)
identity_metadata: dict # free-form: agent_name, version, plugin_name, etc.
```

Hook firing

```python

kora_cli/reasoning/anthropic_engine.py — AnthropicReasoningEngine.init

results = invoke_hook("pre_agent_identity_set", engine=self)
for r in results:
if isinstance(r, dict) and isinstance(r.get("identity"), IdentitySpec):
# first-non-None wins; engine uses identity.system_prompt_content
break

else fall back to existing file-read at kora_system_prompt.md

```

Plugin author surface

```python
def my_identity_provider(*, engine, **kw) -> IdentitySpec | None:
return IdentitySpec(soul_md_content="...", system_prompt_content="...")

In plugin's register(ctx):

ctx.register_identity_provider(my_identity_provider)
```

The convenience method wraps the `{"identity": ...}` envelope automatically; plugin authors return raw `IdentitySpec`. First-non-None-wins semantic. Fail-safe on exceptions.

Kora's identity sub-plugin

`kora_cli/reasoning/kora_hermes_plugin/identity/` — follows the #185 template (constants + loader + plugin + register). Claims Kora's canonical identity from `kora_system_prompt.md` + `SOUL.md`. Operator escape hatch: `KORA_DISABLE_IDENTITY_PROVIDER=true` falls back to file-read.

Backward compat

• Bare-Hermes-no-Kora-plugin: file-read fallback at `kora_system_prompt.md` still works (existing pre-Option-C behavior unchanged).
• `KORA_DISABLE_IDENTITY_PROVIDER=true`: env opt-out → file-read fallback.
• `agent/prompt_builder.py:load_soul_md` stays callable (preferred-deprecated; future refactor consumes `IdentitySpec.soul_md_content`).

Upstream-PR drafting deferred

Per Joshua's amended `feedback-local-first-upstream-after`: "we deal with sharing the CODE once its actually fucking tested." The new hook + IdentitySpec + ctx method live in the Kora fork only. No upstream-PR draft created in this bucket. Battle-testing happens first.

Deliverable B — KR-DAEMON-LISTENERS-VIA-GATEWAY Phase 2

8 remaining periodic-task listeners migrated to dual-registry shape (Path B thin-shim; same pattern as snapshot listener in #196).

Per-listener migration table

Per-Listener-class shape changes

• Process-wide `_listener_singleton` so both registries point at the same instance's bound methods (prevents double-log-on-startup if both consumers fire)
• `startup()` now accepts optional `coordinator` kwarg so Hermes consumer (positional Callable[[Any], Any]) and Kora consumer (no-arg) both work
• `BackgroundDaemonEntry` registered with `PeriodicTaskSpec` carrying the same callback + interval
• Defensive duplicate-registration guard for importlib.reload + xdist workers

Note on bucket-spec divergence (already flagged in commit body)

• Bucket said "purelymail_client (IMAP poller)". The actual IMAP poller is `email_inbound_imap_listener.py`; `purelymail_client_listener.py` is the outbound SMTP singleton-holder. Migrated `email_inbound_imap` per the actual periodic-task taxonomy.
• 3 newer promotion listeners exist that weren't in my prior audit (`promote_probe_fix_envelopes`, `promote_router_tuning`, `promote_tool_trimming`). Same shape as feat(KR-2 ST3): scratchpad reads + deferred-write surface #7-8; recommend a tiny Phase 2.5 follow-up bucket.

Test plan

• 78 new tests across identity (26) + Phase 2 listeners (38) + IdentitySpec (5) + count updates (renamed eight→nine, mock additions)
• 563/563 focused regression set green: all listener tests + all kora_hermes_plugin tests + cost_ladder + cost_telemetry + cost_telemetry_listener
• Smoke import: all 9 periodic-task listeners present in BackgroundDaemonRegistry; Kora canonical identity loads with 10204-char system prompt + 1750-char SOUL.md
• Pre-merge: ST3 in production already (post-feat(kora): KR-REASONING-ROUTE-THROUGH-GATEWAY-ST3 — flip KORA_REASONING_USE_GATEWAY default to gateway (DRAFT) #195); daemon Phase 1 merged (feat(kora): KR-DAEMON-LISTENERS-VIA-GATEWAY Phase 1 — snapshot listener migration (DRAFT — merges after ST3 #195) #196); this PR's behavior changes are additive only
• Post-merge: 48h monitoring window for any listener-lifecycle surprise on the gateway path

HOW_TO_BUILD_YOUR_OWN_AGENT.md preview

(In companion kora-docs PR. TOC reproduced here for convenience.)

1. Why this exists
2. The surface (IdentitySpec / hook / register_identity_provider)
3. Walkthrough — building a "Marvin" agent (project layout / manifest / register function / verification)
4. Multi-tenant scenarios (single identity / per-engine routing / composite identity)
5. What Kora's plugin does vs what's generic
6. Distribution path — `pip install your-agent-runtime`
7. Known limitations + future work (engine-init-only hook; SOUL.md not yet engine-consumed; FIFO ordering)

🤖 Generated with Claude Code