feat(code): integrate Hooks v2 client lifecycle events by johannes117 · Pull Request #5010 · langchain-ai/deepagents

Johannes du Plessis (johannes117) · 2026-07-23T22:50:43Z

Depends on #4997
Related: DCD-71

dcode now runs client-owned Hooks v2 lifecycle events consistently in interactive and headless sessions, including hook-driven approval decisions before permission prompts are shown.

Invokes SessionStart and SessionEnd at startup, resume, clear, compact, switch, and exit boundaries.
Applies PermissionRequest allow, deny, ask, interrupt, notice, terminal, and stop effects before client approval resolution.
Routes supported dcode notifications through one typed service with explicit wire mappings while avoiding migrated legacy duplicates.
Preserves session-start context for the next model turn and adds TUI/headless decision-parity coverage.
Ignores generated local transcript state through .gitignore.

Review Guide

hooks/client_lifecycle.py — ClientHookService, context, permission outcomes
app.py — SessionStart/End boundaries + service wiring
tui/textual_adapter.py, client/non_interactive.py — interactive vs headless parity
Skim: transcript.py, server_middleware.py (PermissionRequest), runtime.py / projection.py
Tests: test_client_lifecycle.py, then adapter / non-interactive / server-lifecycle deltas

Test plan

make lint
Hooks lifecycle, engine, headless, Textual adapter, and app unit suites
Full make test: 10,618 passed; three unrelated terminal-width rendering assertions fail in this local terminal environment

main
- feat(code): integrate Hooks v2 server lifecycle events #4997
  - feat(code): integrate Hooks v2 client lifecycle events 👈
    - feat(code): add project hooks workspace trust #5044
      - feat(code): surface Hooks v2 runtime feedback #5045

^{Stack generated by Git Town}

Wire PreToolUse, PostToolUse, Stop, SubagentStart, and SubagentStop through LangGraph interrupts so the client HooksRuntime can execute handlers and return typed decisions. Co-authored-by: Johannes du Plessis <johannesduplessis117@gmail.com>

Co-authored-by: Johannes du Plessis <johannesduplessis117@gmail.com>

Apply PreToolUse ask/context/continue, surface notices, wire workspace trust, mount middleware on subagents, and harden Stop/SubagentStop decision handling. Co-authored-by: Cursor <cursoragent@cursor.com>

Enforce SubagentStart denies, skip Stop on subagent graphs, and require `--trust-project-hooks` before loading project hook commands headlessly. Co-authored-by: Cursor <cursoragent@cursor.com>

Co-authored-by: Cursor <cursoragent@cursor.com>

Wire SessionStart/End, Notification, PermissionRequest, and compact SessionStart through the client HooksRuntime, and keep project hooks behind `--trust-project-hooks` after rebasing onto the server-lifecycle hardening. Co-authored-by: Cursor <cursoragent@cursor.com>

Initialize session state inline before SessionStart instead of waiting on a Textual worker Event that never progresses under that wait. Co-authored-by: Cursor <cursoragent@cursor.com>

Stop deriving the transcript store from `config_dir`, which let tests and project-local overrides create `.deepagents/transcripts` under the package tree. Transcripts now always default to `~/.deepagents/transcripts`. Co-authored-by: Cursor <cursoragent@cursor.com>

Avoid `to_thread` during session start so server-ready startup completes within the same event-loop turns that tests and the UI expect. Co-authored-by: Cursor <cursoragent@cursor.com>

open-swe

Open SWE Review found 1 potential issue.

Open in Web • View Open SWE trace

Preserve server hook identity across graph replay, run pre-tool policy before HITL, and deduplicate client fulfillment side effects. Co-authored-by: Cursor <cursoragent@cursor.com>

…es/code/dcd-71-client-lifecycle

Populate production transcripts and place prompt and compaction compatibility events at replay-safe lifecycle boundaries across interactive and headless clients. Co-authored-by: Cursor <cursoragent@cursor.com>

…es/code/dcd-71-client-lifecycle

Depends on #4971 Closes DCD-69 Server-owned Hooks v2 events now pause the agent over LangGraph interrupts, run on the client `HooksRuntime`, and resume with typed decisions. --- This starts the DCD-69 stack on top of the DCD-70 leaf (#4971). - Adds a versioned `hook_invocation` interrupt/resume transport around `HookInvocationRequest` / `HookInvocationResponse`. - Installs `ServerHooksMiddleware` for `PreToolUse`, `PostToolUse`, `Stop`, `SubagentStart`, and `SubagentStop`, gated by the session's configured server events so idle sessions skip the round-trip. - Creates a session-scoped client `HooksRuntime` and fulfills server interrupts from both the Textual adapter and headless runner. - Applies `deny`/`ask` as blocking tool errors for now; `ask` approval UX remains for DCD-71. ## Review Guide 1. `hooks/server_middleware.py` — middleware, gating, interrupt raise, decision apply 2. `hooks/interrupt.py` — `hook_invocation` pause/resume contract 3. `hooks/client.py` — client fulfillment + resume ledger 4. `agent.py` — middleware install (main + subagents) 5. `tui/textual_adapter.py`, `client/non_interactive.py` — interrupt fulfillment call sites 6. Skim: `envelope.py`, `context.py`, `runtime.py`, `_cli_context.py`, small `app`/`auto_mode`/`main`/`snapshot`/`engine` touches 7. Tests: `test_server_lifecycle.py`, then `test_agent` / `test_non_interactive` / `test_engine` <details> <summary>Test plan</summary> - `uv run --group test pytest tests/unit_tests/hooks` — 133 passed - `make lint` in `libs/code` </details>  ------------------------- - main - **feat(code): integrate Hooks v2 server lifecycle events** :point_left: - #5010 - #5044 - #5045 [Stack](https://www.git-town.com/how-to/proposal-breadcrumb.html) generated by [Git Town](https://github.com/git-town/git-town)  --------- Co-authored-by: Cursor Agent <cursoragent@cursor.com> Co-authored-by: open-swe[bot] <open-swe@users.noreply.github.com>

dcode now runs client-owned Hooks v2 lifecycle events consistently in interactive and headless sessions, including hook-driven approval decisions before permission prompts are shown. Re-anchored onto main after #4997 squash-merged; this commit carries the full PR #5010 delta.

Supersedes #5010 (auto-closed when #4997 squash-merged; GitHub seals force-pushed closed PRs). Related: [DCD-71](https://linear.app/langchain/issue/DCD-71/hooks-v2-integrate-client-owned-lifecycle-events) dcode now runs client-owned Hooks v2 lifecycle events consistently in interactive and headless sessions, including hook-driven approval decisions before permission prompts are shown. --- - Invokes `SessionStart` and `SessionEnd` at startup, resume, clear, compact, switch, and exit boundaries. - Applies `PermissionRequest` allow, deny, ask, interrupt, notice, terminal, and stop effects before client approval resolution. - Routes supported dcode notifications through one typed service with explicit wire mappings while avoiding migrated legacy duplicates. - Preserves session-start context for the next model turn and adds TUI/headless decision-parity coverage. - Ignores generated local transcript state through `.gitignore`. This branch was re-anchored onto `main` after #4997 squash-merged; the diff is identical to the approved #5010 head (`f4e8ee672`), minus a stale resurrection of `todo_list_prompt.md` that #5098 deleted on main. ## Review Guide 1. `hooks/client_lifecycle.py` — `ClientHookService`, context, permission outcomes 2. `app.py` — SessionStart/End boundaries + service wiring 3. `tui/textual_adapter.py`, `client/non_interactive.py` — interactive vs headless parity 4. Skim: `transcript.py`, `server_middleware.py` (PermissionRequest), `runtime.py` / `projection.py` 5. Tests: `test_client_lifecycle.py`, then adapter / non-interactive / server-lifecycle deltas <details> <summary>Test plan</summary> - 266 hooks unit tests pass on the rebuilt tip - 412 non-interactive / Textual adapter / status widget tests pass </details>  ------------------------- - main - **feat(code): integrate Hooks v2 client lifecycle events** :point_left: - #5105 - #5045 [Stack](https://www.git-town.com/how-to/proposal-breadcrumb.html) generated by [Git Town](https://github.com/git-town/git-town)  --------- Co-authored-by: Cursor <cursoragent@cursor.com>

…4997)  Depends on langchain-ai#4971 Closes DCD-69 Server-owned Hooks v2 events now pause the agent over LangGraph interrupts, run on the client `HooksRuntime`, and resume with typed decisions. --- This starts the DCD-69 stack on top of the DCD-70 leaf (langchain-ai#4971). - Adds a versioned `hook_invocation` interrupt/resume transport around `HookInvocationRequest` / `HookInvocationResponse`. - Installs `ServerHooksMiddleware` for `PreToolUse`, `PostToolUse`, `Stop`, `SubagentStart`, and `SubagentStop`, gated by the session's configured server events so idle sessions skip the round-trip. - Creates a session-scoped client `HooksRuntime` and fulfills server interrupts from both the Textual adapter and headless runner. - Applies `deny`/`ask` as blocking tool errors for now; `ask` approval UX remains for DCD-71. ## Review Guide 1. `hooks/server_middleware.py` — middleware, gating, interrupt raise, decision apply 2. `hooks/interrupt.py` — `hook_invocation` pause/resume contract 3. `hooks/client.py` — client fulfillment + resume ledger 4. `agent.py` — middleware install (main + subagents) 5. `tui/textual_adapter.py`, `client/non_interactive.py` — interrupt fulfillment call sites 6. Skim: `envelope.py`, `context.py`, `runtime.py`, `_cli_context.py`, small `app`/`auto_mode`/`main`/`snapshot`/`engine` touches 7. Tests: `test_server_lifecycle.py`, then `test_agent` / `test_non_interactive` / `test_engine` <details> <summary>Test plan</summary> - `uv run --group test pytest tests/unit_tests/hooks` — 133 passed - `make lint` in `libs/code` </details>  ------------------------- - main - **feat(code): integrate Hooks v2 server lifecycle events** :point_left: - langchain-ai#5010 - langchain-ai#5044 - langchain-ai#5045 [Stack](https://www.git-town.com/how-to/proposal-breadcrumb.html) generated by [Git Town](https://github.com/git-town/git-town)  --------- Co-authored-by: Cursor Agent <cursoragent@cursor.com> Co-authored-by: open-swe[bot] <open-swe@users.noreply.github.com>

…5104) Supersedes langchain-ai#5010 (auto-closed when langchain-ai#4997 squash-merged; GitHub seals force-pushed closed PRs). Related: [DCD-71](https://linear.app/langchain/issue/DCD-71/hooks-v2-integrate-client-owned-lifecycle-events) dcode now runs client-owned Hooks v2 lifecycle events consistently in interactive and headless sessions, including hook-driven approval decisions before permission prompts are shown. --- - Invokes `SessionStart` and `SessionEnd` at startup, resume, clear, compact, switch, and exit boundaries. - Applies `PermissionRequest` allow, deny, ask, interrupt, notice, terminal, and stop effects before client approval resolution. - Routes supported dcode notifications through one typed service with explicit wire mappings while avoiding migrated legacy duplicates. - Preserves session-start context for the next model turn and adds TUI/headless decision-parity coverage. - Ignores generated local transcript state through `.gitignore`. This branch was re-anchored onto `main` after langchain-ai#4997 squash-merged; the diff is identical to the approved langchain-ai#5010 head (`f4e8ee672`), minus a stale resurrection of `todo_list_prompt.md` that langchain-ai#5098 deleted on main. ## Review Guide 1. `hooks/client_lifecycle.py` — `ClientHookService`, context, permission outcomes 2. `app.py` — SessionStart/End boundaries + service wiring 3. `tui/textual_adapter.py`, `client/non_interactive.py` — interactive vs headless parity 4. Skim: `transcript.py`, `server_middleware.py` (PermissionRequest), `runtime.py` / `projection.py` 5. Tests: `test_client_lifecycle.py`, then adapter / non-interactive / server-lifecycle deltas <details> <summary>Test plan</summary> - 266 hooks unit tests pass on the rebuilt tip - 412 non-interactive / Textual adapter / status widget tests pass </details>  ------------------------- - main - **feat(code): integrate Hooks v2 client lifecycle events** :point_left: - langchain-ai#5105 - langchain-ai#5045 [Stack](https://www.git-town.com/how-to/proposal-breadcrumb.html) generated by [Git Town](https://github.com/git-town/git-town)  --------- Co-authored-by: Cursor <cursoragent@cursor.com>

Supersedes #5010 (auto-closed when #4997 squash-merged; GitHub seals force-pushed closed PRs). Related: [DCD-71](https://linear.app/langchain/issue/DCD-71/hooks-v2-integrate-client-owned-lifecycle-events) dcode now runs client-owned Hooks v2 lifecycle events consistently in interactive and headless sessions, including hook-driven approval decisions before permission prompts are shown. --- - Invokes `SessionStart` and `SessionEnd` at startup, resume, clear, compact, switch, and exit boundaries. - Applies `PermissionRequest` allow, deny, ask, interrupt, notice, terminal, and stop effects before client approval resolution. - Routes supported dcode notifications through one typed service with explicit wire mappings while avoiding migrated legacy duplicates. - Preserves session-start context for the next model turn and adds TUI/headless decision-parity coverage. - Ignores generated local transcript state through `.gitignore`. This branch was re-anchored onto `main` after #4997 squash-merged; the diff is identical to the approved #5010 head (`f4e8ee672`), minus a stale resurrection of `todo_list_prompt.md` that #5098 deleted on main. 1. `hooks/client_lifecycle.py` — `ClientHookService`, context, permission outcomes 2. `app.py` — SessionStart/End boundaries + service wiring 3. `tui/textual_adapter.py`, `client/non_interactive.py` — interactive vs headless parity 4. Skim: `transcript.py`, `server_middleware.py` (PermissionRequest), `runtime.py` / `projection.py` 5. Tests: `test_client_lifecycle.py`, then adapter / non-interactive / server-lifecycle deltas <details> <summary>Test plan</summary> - 266 hooks unit tests pass on the rebuilt tip - 412 non-interactive / Textual adapter / status widget tests pass </details>  ------------------------- - main - **feat(code): integrate Hooks v2 client lifecycle events** :point_left: - #5105 - #5045 [Stack](https://www.git-town.com/how-to/proposal-breadcrumb.html) generated by [Git Town](https://github.com/git-town/git-town)  --------- Co-authored-by: Cursor <cursoragent@cursor.com>

github-actions Bot added dcode Related to `deepagents-code` feature New feature/enhancement or request for one internal User is a member of the `langchain-ai` GitHub organization size: XL 1000+ LOC labels Jul 23, 2026

Cursor Agent (cursoragent) and others added 5 commits July 24, 2026 08:08

style(code): format HooksSnapshot configured_events

3c4a411

Co-authored-by: Johannes du Plessis <johannesduplessis117@gmail.com>

fix(code): satisfy hooks server-lifecycle type checks

34dd24c

Co-authored-by: Johannes du Plessis <johannesduplessis117@gmail.com>

fix(code): move CLIContext import behind TYPE_CHECKING

8172f40

Co-authored-by: Johannes du Plessis <johannesduplessis117@gmail.com>

fix(code): align server hooks lifecycle with design-doc MVP

54c2175

Apply PreToolUse ask/context/continue, surface notices, wire workspace trust, mount middleware on subagents, and harden Stop/SubagentStop decision handling. Co-authored-by: Cursor <cursoragent@cursor.com>

Johannes du Plessis (johannes117) force-pushed the johannes/code/dcd-69-server-lifecycle-f6bb branch from 2028620 to 54c2175 Compare July 24, 2026 15:10

Johannes du Plessis (johannes117) force-pushed the johannes/code/dcd-71-client-lifecycle branch from 228267c to 20ad754 Compare July 24, 2026 15:10

Johannes du Plessis (johannes117) mentioned this pull request Jul 24, 2026

feat(code): integrate Hooks v2 server lifecycle events #4997

Merged

fix(code): harden server hooks lifecycle review findings

46dc9ba

Enforce SubagentStart denies, skip Stop on subagent graphs, and require `--trust-project-hooks` before loading project hook commands headlessly. Co-authored-by: Cursor <cursoragent@cursor.com>

Johannes du Plessis (johannes117) force-pushed the johannes/code/dcd-71-client-lifecycle branch from 20ad754 to c2492e3 Compare July 24, 2026 15:30

Johannes du Plessis (johannes117) and others added 2 commits July 24, 2026 08:32

test(code): expect ServerHooksMiddleware on subagent stacks

e7eb344

Co-authored-by: Cursor <cursoragent@cursor.com>

Johannes du Plessis (johannes117) force-pushed the johannes/code/dcd-71-client-lifecycle branch from c2492e3 to 8a15a16 Compare July 24, 2026 15:32

Johannes du Plessis (johannes117) and others added 3 commits July 24, 2026 08:53

fix(code): avoid session-start deadlock on hooks init

2d32caf

Initialize session state inline before SessionStart instead of waiting on a Textual worker Event that never progresses under that wait. Co-authored-by: Cursor <cursoragent@cursor.com>

fix(code): initialize session hooks state synchronously

3020826

Avoid `to_thread` during session start so server-ready startup completes within the same event-loop turns that tests and the UI expect. Co-authored-by: Cursor <cursoragent@cursor.com>

Johannes du Plessis (johannes117) marked this pull request as ready for review July 24, 2026 16:32

Johannes du Plessis (johannes117) mentioned this pull request Jul 24, 2026

feat(code): add project hooks workspace trust #5044

Closed

open-swe Bot reviewed Jul 24, 2026

View reviewed changes

Comment thread libs/code/deepagents_code/app.py

Johannes du Plessis (johannes117) mentioned this pull request Jul 24, 2026

feat(code): surface Hooks v2 runtime feedback #5045

Merged

Johannes du Plessis (johannes117) and others added 6 commits July 24, 2026 10:42

fix(code): make Hooks v2 lifecycle replay-safe

8c0c94c

Preserve server hook identity across graph replay, run pre-tool policy before HITL, and deduplicate client fulfillment side effects. Co-authored-by: Cursor <cursoragent@cursor.com>

Merge branch 'johannes/code/dcd-69-server-lifecycle-f6bb' into johann…

cdd186b

…es/code/dcd-71-client-lifecycle

fix(code): complete Hooks v2 client lifecycle wiring

1f00788

Populate production transcripts and place prompt and compaction compatibility events at replay-safe lifecycle boundaries across interactive and headless clients. Co-authored-by: Cursor <cursoragent@cursor.com>

Merge branch 'main' into johannes/code/dcd-69-server-lifecycle-f6bb

06cb318

Merge branch 'johannes/code/dcd-69-server-lifecycle-f6bb' into johann…

25105e1

…es/code/dcd-71-client-lifecycle

cr

6b3b52c

Johannes du Plessis (johannes117) and others added 6 commits July 24, 2026 13:54

Merge branch 'main' into johannes/code/dcd-69-server-lifecycle-f6bb

0041764

Merge branch 'johannes/code/dcd-69-server-lifecycle-f6bb' into johann…

fb16ca9

…es/code/dcd-71-client-lifecycle

Merge branch 'main' into johannes/code/dcd-69-server-lifecycle-f6bb

9943428

Merge branch 'johannes/code/dcd-69-server-lifecycle-f6bb' into johann…

15c5588

…es/code/dcd-71-client-lifecycle

Merge branch 'main' into johannes/code/dcd-69-server-lifecycle-f6bb

29fbb43

Merge branch 'johannes/code/dcd-69-server-lifecycle-f6bb' into johann…

f4e8ee6

…es/code/dcd-71-client-lifecycle

Base automatically changed from johannes/code/dcd-69-server-lifecycle-f6bb to main July 27, 2026 23:20

Johannes du Plessis (johannes117) closed this Jul 27, 2026

Johannes du Plessis (johannes117) deleted the johannes/code/dcd-71-client-lifecycle branch July 27, 2026 23:22

Johannes du Plessis (johannes117) mentioned this pull request Jul 27, 2026

feat(code): integrate Hooks v2 client lifecycle events #5104

Merged

Navigation Menu

Uh oh!

feat(code): integrate Hooks v2 client lifecycle events - #5010

feat(code): integrate Hooks v2 client lifecycle events#5010
Johannes du Plessis (johannes117) wants to merge 23 commits into
mainfrom
johannes/code/dcd-71-client-lifecycle

Johannes du Plessis (johannes117) commented Jul 23, 2026 •

edited

Loading

Uh oh!

open-swe Bot left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

Johannes du Plessis (johannes117) commented Jul 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review Guide

Uh oh!

open-swe Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Johannes du Plessis (johannes117) commented Jul 23, 2026 •

edited

Loading