Skip to content

feat(plugins): add goal lifecycle hooks#27790

Open
clicheman wants to merge 1 commit into
NousResearch:mainfrom
clicheman:feat/goal-lifecycle-hooks
Open

feat(plugins): add goal lifecycle hooks#27790
clicheman wants to merge 1 commit into
NousResearch:mainfrom
clicheman:feat/goal-lifecycle-hooks

Conversation

@clicheman

Copy link
Copy Markdown

Summary

Add four new fire-and-forget plugin hooks fired by GoalManager when the /goal state machine transitions:

Hook Trigger Payload
on_goal_set New goal created session_id, goal_text, max_turns
on_goal_pause Goal paused (user/judge parse failure/etc.) session_id, reason
on_goal_resume Goal resumed session_id, reset_budget
on_goal_complete Goal marked done session_id, reason, turns_used

Plugin callbacks are observers — return values are ignored, and any exception raised inside a callback is swallowed (logged at DEBUG) so a misbehaving plugin cannot wedge the goal mutation that fired the hook. Consistent with the existing hook contract used by pre_api_request etc.

Changes

  • hermes_cli/plugins.py — add the four hook names to VALID_HOOKS
  • hermes_cli/hooks.py — add synthetic _DEFAULT_PAYLOADS entries so hermes plugins test on_goal_set (and friends) work
  • hermes_cli/goals.py — new _fire_goal_hook() helper invoked from set(), pause(), resume(), and mark_done()
  • tests/hermes_cli/test_goals.py — new TestGoalLifecycleHooks class with 7 tests covering each hook payload, no-op on inactive state, and the error-isolation contract

Tests

$ pytest tests/hermes_cli/test_goals.py tests/cli/test_session_boundary_hooks.py tests/hermes_cli/test_plugins.py -q
133 passed in 5.92s

$ ruff check hermes_cli/goals.py hermes_cli/plugins.py hermes_cli/hooks.py tests/hermes_cli/test_goals.py
All checks passed!

No existing tests had to be modified — this is a pure addition.

Closes #27777

Expose four new fire-and-forget hooks fired by GoalManager when the
/goal state machine transitions:

  on_goal_set       - new goal created
  on_goal_pause     - goal paused (user, judge parse failure, etc.)
  on_goal_resume    - goal resumed
  on_goal_complete  - goal marked done

Plugin callbacks are observers; return values are ignored and
exceptions are caught so a misbehaving plugin can't wedge the goal
mutation that fired the hook. Adds VALID_HOOKS entries, synthetic
_DEFAULT_PAYLOADS for `hermes plugins test`, and 7 tests covering
each hook payload plus the error-isolation contract.

Closes NousResearch#27777
@alt-glitch alt-glitch added type/feature New feature or request comp/plugins Plugin system and bundled plugins comp/cli CLI entry point, hermes_cli/, setup wizard P3 Low — cosmetic, nice to have labels May 18, 2026
@teknium1

Copy link
Copy Markdown
Contributor

Thanks for adding this hook surface — the underlying gap is still real on current main: VALID_HOOKS has no on_goal_* events (hermes_cli/plugins.py:128), and GoalManager currently mutates goal state without plugin dispatch (hermes_cli/goals.py:522).

Problems

  • on_goal_complete would miss the normal judge-driven completion path. evaluate_after_turn() directly sets state.status = "done" and saves at hermes_cli/goals.py:669-671; it does not call mark_done(), which is where this PR adds the hook.
  • on_goal_pause would miss the key auto-pause paths called out in [Feature]: Add goal lifecycle plugin hooks (on_goal_set/pause/resume/complete) #27777. Repeated judge parse failures pause at hermes_cli/goals.py:687-692, and turn-budget exhaustion pauses at hermes_cli/goals.py:711-714; neither path calls pause().
  • The public hook reference would need to mention these new hook names/payloads. The current quick-reference table starts at website/docs/user-guide/features/hooks.md:376 and does not include goal hooks.

Suggested changes

  • Fire hooks from the judge-driven evaluate_after_turn() status transitions too, ideally by routing all status changes through shared transition helpers.
  • Add tests for judge-complete, parse-failure auto-pause, and budget-exhaustion auto-pause hook emissions.
  • Add docs for the four observer-only on_goal_* hooks and payload fields.

This is an automated hermes-sweeper review.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

comp/cli CLI entry point, hermes_cli/, setup wizard comp/plugins Plugin system and bundled plugins P3 Low — cosmetic, nice to have type/feature New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature]: Add goal lifecycle plugin hooks (on_goal_set/pause/resume/complete)

3 participants