Skip to content

hooks: session_start and session_end (refs #26) - #36

Merged
blockmandev merged 2 commits into
mainfrom
feat/hook-session
Oct 22, 2026
Merged

blockmandev merged 2 commits into
mainfrom
feat/hook-session

Conversation

@blockmandev

Copy link
Copy Markdown
Member

Operator hooks for the session's own start and end (refs #26).

What

session_start and session_end join the operator's hooks (admin.json, also desktop_hooks, and the operator's own plugins):

  • session_start runs once a session exists, with source: "startup".
  • session_end runs when the session closes. Its reason is prompt_input_exit in the REPL and other for --acp and -t.

The event is JSON on stdin (hook_event_name, session_id, cwd, plus source or reason). The command runs in the workspace and is bounded at 10 s, like the other events.

Neither hook can refuse: exit 2 is an ordinary exit here. Their stdout is shown:

Front end Start End
REPL print_info print_info
-t stderr, kept apart from a JSON run stderr
--acp stderr (stdout is claimed by the protocol) traced, since the client has closed the session by then

Where it fires

  • cli::prepare_session: start. Both the REPL and --acp go through it.
  • Beside each end_memory: end. Covers the REPL (cli/mod.rs) and --acp (acp_agent::drive), so the operator's end is paired with the memory engine's end by construction.
  • task_run: start before user_prompt_submit, end after the engine's end. A refused instruction now also runs session_end, so no start is left without its end. To make that testable, run_task_reporting now hands its runner to a new run_task_hooked.

Project plugins still give only the tool events (allowlist in plugins::hooks_of), so a cloned repo's plugin cannot add a session hook.

.incode/lifecycle.json's on_session_start/on_session_end are marked superseded. They still run.

Tests (each with a control that puts the bug back)

  • hooks::tests::session_start_and_end_are_told_and_cannot_refuse checks the payload fields and that exit 2 does not refuse. Control: making session_end able to refuse fails it ("a session_end hook refused").
  • cli::agent_turn::tests::session_start_and_end_hooks_run_in_the_workspace_and_are_shown checks that the hook runs in the workspace, that its output comes back, and that nothing happens without hooks. Control: passing no cwd fails it (the hook ran in the repo, not the workspace).
  • task_run::tests::a_refused_instruction_still_runs_the_session_end_hook. Control: removing the end call on the refusal path fails it.

Not covered

  • /run ledger workers (cli::run_memory) are sessions with no person behind them. They do not run session_start/session_end, as they already do not run user_prompt_submit.
  • Only source: "startup" is fired. Nothing restarts a session in place yet, so there is no clear.

The method was cfg(test) while its only caller, the bridged-turn test,
is cfg(unix), so a Windows test build held it as dead code and
clippy -D warnings refused the crate.
The operator's hooks gain the session's own start and end. Start fires
once the session exists (cli::prepare_session for the REPL and --acp,
before the first line in -t); end fires beside the memory engine's own
end, so the two stay paired. In -t a line refused by user_prompt_submit
now ends what it started. Neither can refuse; stdout is shown. Project
plugins still give only the tool events. lifecycle.json is marked
superseded and still runs.
@blockmandev
blockmandev merged commit 5a89a3e into main Oct 22, 2026
7 checks passed
@blockmandev
blockmandev deleted the feat/hook-session branch November 15, 2026 20:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant