Plugins Can Now Copy the Agent Into the Background: fork_session and Idle Tasks

You write a plugin that should do one thing after each turn: check whether the session created or changed a skill, and if so, decide whether it is worth recommending to the team.
Sounds small. It is not. Inside post_llm_call you get context but no clean handle on “which tools this turn used, where the counters stand” — so you count yourself. To run the work in the background you spawn a thread, guard re-entry, and handle “the user just sent another message”. What you end up with is a second, worse implementation of the background review core already runs, with different behaviour and no shared vocabulary when it misbehaves.
PR #146732 (49 files, ~4,500 lines, merged November 13) fixes that: the two background patterns core uses for itself are now plugin APIs — ctx.fork_session and ctx.register_idle_task. Here is what they do, where the edges are, and how to write against them without a rewrite in six months.
Two patterns in one sentence
ctx.fork_sessioncopies the session’s agent into the background after a turn, carrying the same system prompt, tool list, memory and conversation, and works through a multi-step prompt. It is the pattern behind Hermes’ own background memory and skill review.ctx.register_idle_taskgives work that has no turn to hang off — re-scoring data daily, compacting a cache, suggesting a cleanup — the skill curator’s idle schedule.
Both are experimental. The docs are explicit that signatures and the fork handle’s shape may change. That gives you one hard code rule: keep the handle inside one small function that returns plain data, and never store it past the turn.
fork_session: a background copy of the turn’s agent
handle = ctx.fork_session(
token, # post_llm_call's side_question_token
prompt, # <= 8192 characters
tools=(), # allowed tool names
max_iterations=8, # 1..16
input_budget=None, # can only tighten the bound
task=None, # run on one auxiliary task lane's model
timeout=None, # seconds, <= 1800
)
It returns a handle, or None when nothing was started.
The important property: a fork shares the live turn’s system prompt and tools[] byte for byte, so its first request is mostly prompt-cache reads. You are paying for “a few more steps in the background”, not for standing up a fresh agent.
What a fork will not do is just as clear:
- Nothing is written to the transcript or the session database. Background work cannot pollute the conversation.
- Dangerous-command approvals are auto-denied. A fork cannot click “approve” on your behalf.
- The next live turn cancels the fork — running, starting, or still deferred.
That last rule is the design centre. A fork is the after-party of one turn, not a daemon. If you need long-lived work across turns, that is cron or an idle task, not a fork.
One token, one chance
token is post_llm_call’s side_question_token, and the rules are stricter than the name suggests:
- One request per turn, side question or fork, shared by every plugin.
- Unattended turns have no token: cron runs and subagent turns get
None. - A plugin without
llm.session_forkgetsNoneand does not spend the token. - Naming a tool outside the allowlist returns
Nonewithout spending the token; every otherNonespends it.
That distinction matters: a typo in a tool name costs you nothing, but a refusal for another reason (say the session agent was released) burns the one chance. So do not probe by trial inside the hook.
The tool allowlist: your own tools, nothing else
A fork may call a narrow set:
- tools your plugin registered with
register_tool(and whose current registration is still yours, dispatched through the tool registry); - core tools Hermes marks fork-safe — currently none.
Everything else is outside: other plugins’ tools, every MCP tool, connectors, memory-provider and context-engine tools, and delegate_task, message_agent, cronjob_manage, and the Kanban tools.
There is a subtler layer too: even a name you registered is outside the allowlist if Hermes dispatches it before the tool registry (agent-level tools, legacy aliases, the Tool Search bridge, any connectors__<connector>__<tool> name), because the call would never reach your handler.
The practical effect: a fork can only do “actions this plugin defines”. It cannot become a back door for spawning a subagent or scheduling a cron job.
Budgets, timeouts, cancellation
max_iterationscaps the fork’s loop between 1 and 16.- Aggregate input tokens are bounded like the background review’s (
auxiliary.background_review.max_input_tokens, default 75% of the context window);input_budgetcan only lower that. timeoutis wall-clock seconds, at most 1800, and cooperative — the fork stops at its next interrupt check.- Next turn starts → queued and running forks are cancelled.
One line in the docs deserves to be copied into your comments: a provider call that ignores the interrupt holds the handle open until it returns. Always use a bounded handle.wait(t); never wait unbounded.
The handle and its outcomes
The handle exposes done, cancelled, outcome, result (the fork’s final text or None), actions (the allowlisted tool names it called, in order), wait(timeout) and cancel(). It never exposes the fork agent itself.
outcome is what you debug with:
| outcome | meaning |
|---|---|
deferred |
waiting for the machine to be idle on a locally managed runtime (bundled llama-server), like the background review |
running |
in flight |
ok |
finished, result holds the text |
cancelled |
cancelled by the next turn or cancel() |
superseded |
a newer deferred fork of the same plugin and session replaced it |
timeout |
wall clock expired |
budget_exhausted |
input budget used up |
error |
runtime error |
error:spawn |
the worker thread could not start (you get a settled handle, not an exception) |
refused:<reason> |
parent_gone, moa, agent_provider or runtime_changed |
Telling a fork from the live agent
A tool handler called inside a fork receives the keyword turn_origin="plugin_fork:<plugin id>". Calls the live agent makes carry no turn_origin.
This closes a real hole: without it, a tool cannot tell “the model chose to share this” from “the background check suggested sharing”. The official example uses exactly that — the tool only offers the share card when it is called from plugin_fork:wisdom.
Billing is separated too: usage is billed to the session as plugin_fork:<plugin id>, and each provider request fires pre_auxiliary_call / post_auxiliary_call with aux_task="plugin_fork" and plugin_id — never the turn-scoped pre_api_request / post_api_request.
register_idle_task: work with no turn to hang off
ctx.register_idle_task(name, fn, interval_hours=24, min_idle_hours=2, first_run="defer")
It returns a PluginRegistration (dispose it to stop polling). Tasks are scheduled from:
- gateway housekeeping, for every served profile;
- CLI / TUI startup;
- the
hermes servemaintenance tick.
fn runs on its own thread, in the profile that registered it. The host does not wait: the poll returns at once, and a second run of the same task never starts while one is in flight.
State lives in the plugin’s data directory at idle-tasks/<name>.json — last_run_at, run_count, paused, last_summary, last_status, last_error — so each profile schedules its own copy.
Three contracts for fn, and breaking them produces overnight mysteries:
- Keep it short. Give it its own time limit, work in small batches, checkpoint into plugin data so the next run continues.
- Keep it idempotent. A run cut off by a restart records nothing and runs again from the start. Running the same batch twice must be harmless.
- Do not wait for a stop signal. On gateway shutdown no new run starts and the gateway waits a few seconds for the one in flight, then stops without it. Plugin code cannot be stopped and
fngets no signal — when it finishes it records nothing (state stays as it was before the run) and releases its claim.
On claims: a run claim records its owner (pid, process start, machine). A crashed owner is taken over at the next poll, not after an hour; only an owner that cannot be checked (a claim written on another machine) counts as abandoned after an hour. The curator shares this implementation — the interval gate and run claim moved into agent/idle_schedule.py in this PR.
Model calls from fn go through ctx.llm and its trust gate. Note what fn does not have: no turn, therefore no side_question_token, therefore no fork.
Managing idle tasks from the CLI
hermes plugins idle-tasks # every idle task in this profile
hermes plugins idle-tasks <plugin> # one plugin's tasks
hermes plugins idle-tasks <plugin> --pause nightly-reindex
hermes plugins idle-tasks <plugin> --resume nightly-reindex
The listing shows status, run count, last and next run, and the last summary or error. It is the fastest way to answer “did my task actually run” — much faster than reading logs.
review_signals: follow the user’s own cadence
post_llm_call now also receives review_signals: whether skill review and memory review are due, the counters, the intervals, and whether background review is on.
This matters because the old workaround — “check every N turns” — counted your turns while the user configured a different cadence. Now you can read the user’s settings and match Hermes’ own self-learning rhythm instead of inventing one.
When it is not available
plugins.isolation: host: a third-party plugin’sctx.fork_sessionexists but raisesPluginHostUnsupported(aRuntimeError), because the handle tracks a thread of the live session agent inside the Hermes process.- Cron and subagent turns: no
side_question_token, so no fork. - MoA and agent-as-provider runtimes: outcome is
refused:moaorrefused:agent_provider.
The documented degradation is plain: treat None and exceptions as “no fork this time” so the plugin works in both environments.
def _try_fork(ctx, token, prompt):
try:
return ctx.fork_session(token, prompt, tools=["wisdom_offer_share"], max_iterations=4)
except Exception: # PluginHostUnsupported, or anything else
return None
A minimal working example
import json
import threading
def register(ctx):
def offer_share(args, turn_origin=None, **kwargs):
if turn_origin != "plugin_fork:wisdom":
return json.dumps({"error": "only the background check may offer a share"})
return json.dumps({"offered": True})
ctx.register_tool("wisdom_offer_share", "wisdom", OFFER_SCHEMA, offer_share)
def on_post_llm_call(side_question_token=None, review_signals=None, **kwargs):
if side_question_token is None or not (review_signals or {}).get("skill_review_due"):
return
handle = ctx.fork_session(
side_question_token,
"Did this session change a skill the team would benefit from? "
"If so, call wisdom_offer_share once; otherwise answer 'no'.",
tools=["wisdom_offer_share"],
max_iterations=4,
)
if handle is not None:
threading.Thread(
target=lambda: handle.wait(600) and ctx.state.set("last_check", handle.outcome),
daemon=True,
).start()
ctx.register_hook("post_llm_call", on_post_llm_call)
And the capability goes in the plugin manifest:
capabilities:
- llm.session_fork
The consent screen users see says roughly: “Run a background copy of your agent after a turn. It sees the whole session, including memory, can use the plugin’s own tools, and spends your main model’s tokens.”
That sentence is the best design note in the whole feature: a fork sees the entire session. If your plugin forwards a fork’s output to a third party, think that through first.
Status: main only, and experimental
PR #146732 merged on November 13, 2026, lives on main, and is not in v0.23.1. Both APIs are explicitly experimental, so signatures may move.
Update (2026-11-17): these changes shipped in v0.23.2 (November 16) —
hermes updatebrings them in. The “not in v0.23.1” wording above is a snapshot from publication time.
Practice:
- The plugin must work when
fork_sessionreturnsNoneor raises (“no fork this time”). - Never keep the handle in state across turns; it does not outlive one.
- Always
waitwith a bound. - Run
hermes plugins validatebefore shipping — see the plugin catalog guide, isolation mode and the plugin public API list.
If all you need is “re-score my data once a day”, register_idle_task is the easier choice: no capability, no token, and you get pause/resume plus crash takeover for free. A fork is for work that must land immediately after this turn and must see this turn’s context. Pick the wrong one and the code fights you the whole way.