Context

I currently have a small cluster of open PRs into Hermes, mostly around Honcho. A lot of these came directly from user-facing friction rather than internal roadmap work, and Honcho is not a subsystem Teknium has a lot of context for yet, so I wanted one condensed map.

This issue is meant to answer four questions quickly:

1. What does each PR actually solve?
2. Which user complaint or observed friction produced it?
3. Which PRs overlap or stack on each other?
4. What is the least painful merge path?

High-level grouping

Honcho UX / correctness

• fix(honcho): hide session banner when not explicitly configured #1960 — banner should not appear unless Hermes Honcho was explicitly configured
• fix(honcho): sync aiPeer with SOUL.md identity at runtime #1969 — if SOUL.md renames the agent, Honcho aiPeer should not keep leaking hermes

Honcho runtime / performance

• fix(honcho): lazy session init in tools mode #1957 — recallMode=tools should not eagerly create/fetch a Honcho session on startup

Honcho config / multi-instance / startup-context bundle

• feat(honcho): support instance-local config via HERMES_HOME #1962 — instance-local Honcho config via $HERMES_HOME, plus the stacked tools-startup-context work

Non-Honcho but adjacent CLI extensibility

• refactor(cli): add protected TUI extension hooks for wrapper CLIs #1749 — protected TUI extension hooks for wrapper CLIs

PR-by-PR map

#1960 — fix(honcho): hide session banner when not explicitly configured

PR: #1960

Problem:
Users were seeing Honcho session: ... on CLI startup even when they had never intentionally configured Hermes Honcho, just because they had a shared ~/.honcho/config.json or HONCHO_API_KEY from another tool.

User-facing symptom:
"Hermes is acting like Honcho is on when I never set it up here."

What it changes:

• gates the startup banner so it only shows after explicit Hermes opt-in
• treats hosts.hermes or explicit enabled: true as the signal

Risk:
Very small. Pure UX gating.

#1957 — fix(honcho): lazy session init, banner gating, per-directory default

PR: #1957

Current scope note:
The PR title is a little stale relative to the branch contents. The branch currently contains two commits:

• ac796da8 — default session strategy to per-directory
• 2bc05947 — lazy session init in tools mode

So the meaningful remaining substance here is lazy init, plus the session-strategy default change that is already also present in #1962.

Problem:
Even with recallMode: "tools", Hermes still did blocking Honcho session work on startup, which defeated the point of tools mode and made /new feel slower than it should.

User-facing symptom:
"tools mode is still doing Honcho work before I ask for any Honcho tool"

What it changes:

• defers Honcho session creation until first actual Honcho tool invocation
• adds ensure_session() path for lazy init
• changes default session strategy from per-session to per-directory

Overlap:

• the per-directory default is already included in feat(honcho): support instance-local config via HERMES_HOME #1962
• the lazy-init change is not included in feat(honcho): support instance-local config via HERMES_HOME #1962 and is still independently valuable

Recommendation:
If you want the cleanest merge path, treat this PR as:

• merge/cherry-pick 2bc05947 for lazy init
• do not worry about ac796da8 separately if feat(honcho): support instance-local config via HERMES_HOME #1962 is merging, because feat(honcho): support instance-local config via HERMES_HOME #1962 already contains the same session-strategy default change

#1962 — feat(honcho): support instance-local config via HERMES_HOME

PR: #1962

This PR is now the main Honcho bundle.
It includes both the original instance-local-config work and the later stacked tools-startup-context work.

Problems it solves:

1. Multiple Hermes instances / frameworks need isolated Honcho config
2. Hermes should still be able to consume a shared global Honcho config when no instance-local config exists
3. recallMode=tools can feel too cold on first turn after /new
4. Hermes workflow settings should write under hosts.hermes without trampling shared root defaults
5. gateway reset needed the startup-prewarm path fully wired, not just partially cached

User-facing symptoms:

• "I need separate Honcho config per Hermes instance / HERMES_HOME"
• "tools mode is too blank right after reset/new"
• "Hermes should own hosts.hermes, not stomp global root settings by default"

What it changes:

• resolves Honcho config from $HERMES_HOME/honcho.json first, then falls back to ~/.honcho/config.json
• adds optional toolsStartupContext for lightweight first-turn memory in tools mode
• wires gateway startup prewarm through to the fresh AIAgent
• updates hermes honcho setup and related CLI commands to respect host-scoped config with root fallback
• includes the per-directory default-session change already

Overlap:

• supersedes the session-strategy-default commit from fix(honcho): lazy session init in tools mode #1957
• does not supersede lazy-init from fix(honcho): lazy session init in tools mode #1957

Recommendation:
This is the main Honcho config PR to merge as a unit.

#1969 — fix(honcho): sync aiPeer with SOUL.md identity at runtime

PR: #1969

Problem:
If the agent identity was renamed in SOUL.md (for example You are Atlas), Honcho still kept aiPeer="hermes", which leaked the old name back into memory context and could create duplicate peer identities.

User-facing symptom:
"I renamed the agent but Honcho keeps talking about hermes / duplicate identity entities appear"

What it changes:

• parses SOUL.md for You are <Name>
• overrides hcfg.ai_peer at runtime only
• keeps Honcho peer identity aligned with visible agent identity without mutating config

Risk:
Small, isolated correctness fix.

#1749 — refactor(cli): add protected TUI extension hooks for wrapper CLIs

PR: #1749

This one is not really part of the Honcho cluster.

Problem:
Wrapper CLIs currently have to override HermesCLI.run() wholesale just to extend the TUI.

What it changes:

• extracts protected hooks for extra widgets, extra keybindings, and layout assembly
• keeps default behavior unchanged

Recommendation:
Can be reviewed independently from the Honcho PRs.

Suggested merge path

Fastest path with least cognitive overhead

1. Merge fix(honcho): hide session banner when not explicitly configured #1960

   • tiny UX fix
   • easy to reason about

2. Merge feat(honcho): support instance-local config via HERMES_HOME #1962

   • main Honcho config / multi-instance / startup-context bundle
   • already contains the per-directory default-session change from fix(honcho): lazy session init in tools mode #1957

3. Merge or cherry-pick the lazy-init commit from fix(honcho): lazy session init in tools mode #1957

   • specifically 2bc05947
   • this is the only important remaining runtime/perf change from that PR once feat(honcho): support instance-local config via HERMES_HOME #1962 is in

4. Merge fix(honcho): sync aiPeer with SOUL.md identity at runtime #1969

   • small Honcho identity correctness fix
   • should be straightforward after the main Honcho bundle is in

5. Merge refactor(cli): add protected TUI extension hooks for wrapper CLIs #1749 whenever convenient

   • separate concern, no need to couple it to Honcho review

At a glance

• fix(honcho): hide session banner when not explicitly configured #1960 = don't show Honcho banner unless Hermes was actually configured
• fix(honcho): lazy session init in tools mode #1957 = tools mode should not block on startup; only the lazy-init part is still uniquely important after feat(honcho): support instance-local config via HERMES_HOME #1962
• feat(honcho): support instance-local config via HERMES_HOME #1962 = main Honcho config PR: instance-local config + host-scoped Hermes writes + tools-mode startup context
• fix(honcho): sync aiPeer with SOUL.md identity at runtime #1969 = keep Honcho aiPeer aligned with renamed SOUL.md identity
• refactor(cli): add protected TUI extension hooks for wrapper CLIs #1749 = unrelated CLI extension seam

Why I'm writing this down

These Honcho changes are mostly responses to real usage friction:

• accidental activation / confusing banner
• tools mode not actually feeling lazy
• multi-instance config needs
• renamed agent identity leaking stale Honcho peer names
• first-turn tools-mode cold start

None of these are big flashy features, but together they make Honcho feel much less confusing and much more intentional from the user's side.