# Architecture: Why monkey-patch instead of patching files?

The identity plugin uses **runtime monkey-patching** — no files in the
Hermes repo are modified. This is the key design decision that eliminates
the need for a fork.

## The problem

Kanban workers start with NO gateway user identity. The spawn function
runs `hermes -p <profile> chat -q "work kanban task <id>"`. When Honcho
initializes, `kwargs["user_id"]` is None, so it creates `user-default-*`
peers.

There is no Hermes plugin hook that fires at agent initialization before
Honcho creates the session. The hooks available are:
- `pre_gateway_dispatch` — only fires for gateway sessions (Discord, etc.)
- `on_session_start` — fires AFTER Honcho has already initialized
- `pre_tool_call` / `post_tool_call` — fire during tool execution, too late

## The solution: runtime monkey-patch

Python allows replacing any method on any class at runtime. The identity
plugin does exactly this in its `register()` function:

1. At plugin load time, it imports `HonchoMemoryProvider`
2. Stores a reference to the original `_do_session_init` method
3. Replaces it with a wrapper that checks the identity config first
4. If the wrapper finds a peer name, it injects it via `kwargs["user_id"]`
5. Otherwise, it calls the original method unchanged

```python
# In the plugin's register() function:
provider_cls = plugins.memory.honcho.HonchoMemoryProvider
_original_init = provider_cls._do_session_init

@wraps(_original_init)
def wrapper(self, cfg, session_id, **kwargs):
    if not kwargs.get("user_id"):
        resolved = get_peer_name()  # reads config + env vars
        if resolved:
            kwargs["user_id"] = resolved
    return _original_init(self, cfg, session_id, **kwargs)

provider_cls._do_session_init = wrapper
```

## Advantages over file patching

| Aspect | File patching | Monkey-patching |
|--------|--------------|-----------------|
| Repo modifications | Yes (edits plugin file) | Zero |
| Fork needed | Yes (git diff to maintain) | No |
| Upgrades | Merge conflict on every pull | Unchanged |
| Uninstall | Need to revert file changes | Plugin removed → clean |
| Reliability | Works across restarts | Applied at every load |
| Complexity | Simple file edit | Wrapping pattern |

## When does the patch apply?

- At plugin discovery time (Hermes startup)
- Before any Honcho session is created
- Before any agent is initialized
- Before any kanban worker is spawned

The Hermes plugin loader calls `register()` during gateway/agent startup,
which means the patch is in place before any session can begin.

## Safety guarantees

1. **Non-destructive**: The original method is preserved via closure —
   removing the plugin restores original behavior with zero cleanup.

2. **Idempotent**: `_apply_honcho_patch()` guards against double-patching
   via the `_original_init` sentinel.

3. **Graceful degradation**: If the config file is missing, parsing fails,
   or the kanban DB is unavailable, the wrapper returns None → Honcho
   falls back to its default behavior (creating `user-default-*` peers).

4. **No data loss**: The injected `kwargs["user_id"]` only affects what
   peer name Honcho assigns to the session's messages. It doesn't touch
   any existing data.