Skip to content

feat(code): migrate legacy hooks to v2 events - #4971

Merged
Johannes du Plessis (johannes117) merged 32 commits into
mainfrom
johannes117/code/dcd-70-hooks-legacy-migration
Jul 24, 2026
Merged

feat(code): migrate legacy hooks to v2 events#4971
Johannes du Plessis (johannes117) merged 32 commits into
mainfrom
johannes117/code/dcd-70-hooks-legacy-migration

Conversation

@johannes117

@johannes117 Johannes du Plessis (johannes117) commented Jul 22, 2026

Copy link
Copy Markdown
Contributor

Depends on #4918

Legacy hooks with prompt, compaction, turn-completion, notification, and session-end subscriptions now migrate into typed Hooks v2 events while retaining their side-effect-only behavior.


This adds typed UserPromptSubmit and PreCompact domain, wire, capability, projection, matching, and reduction support. The migration consolidates legacy aliases, preserves the five-second timeout, and neutralizes stdout and exit status so observational legacy commands cannot unexpectedly block Hooks v2 lifecycle actions.

Legacy tool and permission events remain unmapped because their fire-and-forget, batched, and failure semantics are not equivalent to the current Hooks v2 lifecycle events.


Stack generated by Git Town

Freeze validated hook configuration into deterministic session snapshots backed by one event capability registry.
Apply event-aware output policies and isolate command handlers with sanitized environments, bounded terminal output, and process-group cleanup.
Materialize private versioned transcript projections and expose them through a session-scoped client runtime.
Co-authored-by: Cursor <cursoragent@cursor.com>
# Conflicts:
#	libs/code/deepagents_code/hooks/snapshot.py
#	libs/code/tests/unit_tests/hooks/models/test_models.py
Co-authored-by: Cursor <cursoragent@cursor.com>
@github-actions 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: M 200-499 LOC labels Jul 22, 2026
Co-authored-by: Cursor <cursoragent@cursor.com>

@open-swe open-swe Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Open SWE Review found 3 potential issues.

Open in WebView Open SWE trace

Comment thread libs/code/deepagents_code/hooks/migration.py
Comment thread libs/code/deepagents_code/hooks/migration.py Outdated
Comment thread libs/code/deepagents_code/hooks/reducer.py Outdated
…s117/code/dcd-70-hooks-legacy-migration

# Conflicts:
#	libs/code/deepagents_code/hooks/capabilities.py
#	libs/code/deepagents_code/hooks/projection.py
#	libs/code/deepagents_code/hooks/reducer.py
Co-authored-by: Cursor <cursoragent@cursor.com>
Johannes du Plessis (johannes117) added a commit that referenced this pull request Jul 23, 2026
Depends on #4916
Related DCD-70

Hooks v2 command handlers now execute with event-aware policies, bounded
terminal output, sanitized environments, and complete process cleanup.

---

This is 2/3 in the DCD-70 stack.

- Applies plain-output, exit-code, continuation, permission, and
deferred-field policies without discarding sibling diagnostics.
- Validates terminal sequences and removes ambient secret and telemetry
environment values.
- Cleans up complete process groups on timeout or cancellation and maps
native/MCP tool calls only from trustworthy metadata.
- Keeps materialized filesystem paths outside domain and transport
state.

<details>
<summary>Test plan</summary>

- `uv run --group test pytest tests/unit_tests/hooks` — 95 passed at
this stack layer
- `make lint`

</details>

<!-- branch-stack-start -->

-------------------------
- main
  - **fix(code): harden Hooks v2 command execution** 👈
    - #4918
      - #4971

<sup>[Stack](https://www.git-town.com/how-to/proposal-breadcrumb.html)
generated by [Git Town](https://github.com/git-town/git-town)</sup>

<!-- branch-stack-end -->
Johannes du Plessis (johannes117) added a commit that referenced this pull request Jul 23, 2026
Depends on #4917
Closes DCD-70

Hooks v2 now materializes private versioned transcript projections and
exposes them through a session-scoped client runtime.

---

This is 3/3 in the DCD-70 stack.

- Adds deterministic per-thread and subagent JSONL projections with
redaction, path-safe identities, private permissions, atomic writes,
revisions, and retention.
- Adds a client-owned runtime that freezes one snapshot and materializes
real transcript paths immediately before command execution.
- Keeps lifecycle call-site and server/client dispatch wiring out of
scope for the following tickets.

<details>
<summary>Test plan</summary>

- `uv run --group test pytest tests/unit_tests/hooks` — 101 passed
- `make lint`
- `make check_imports`

</details>

<!-- branch-stack-start -->

-------------------------
- main
  - #4917
    - **feat(code): add Hooks v2 session transcripts** 👈
      - #4971

<sup>[Stack](https://www.git-town.com/how-to/proposal-breadcrumb.html)
generated by [Git Town](https://github.com/git-town/git-town)</sup>

<!-- branch-stack-end -->

---------

Co-authored-by: Cursor <cursoragent@cursor.com>
Base automatically changed from johannes117/code/dcd-70-hooks-transcripts to main July 23, 2026 17:57
…70-hooks-legacy-migration

# Conflicts:
#	libs/code/deepagents_code/hooks/runtime.py
#	libs/code/deepagents_code/hooks/transcript.py
#	libs/code/tests/unit_tests/hooks/test_transcript.py
@github-actions github-actions Bot added size: XL 1000+ LOC and removed size: L 500-999 LOC labels Jul 23, 2026

@corridor-security corridor-security Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Windows process-tree termination routine derives the taskkill.exe path from SYSTEMROOT without validation; however, because dotenv loading uses first-write-wins semantics and SYSTEMROOT is virtually always pre-set in a real Windows environment, a project .env cannot override it in practice, making the exploitability marginal.

Comment thread libs/code/deepagents_code/hooks/runner.py

@open-swe open-swe Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Open SWE Review found 1 potential issue.

Open in WebView Open SWE trace

Comment thread libs/code/deepagents_code/hooks/migration.py
Drop constant-identity and mocked process-group tests that overlapped
existing regressions; fold catch-all and dedupe into the main mapping test.

Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: open-swe[bot] <open-swe@users.noreply.github.com>

@corridor-security corridor-security Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Hooks v2 migration sets inherit_environ=True on all migrated legacy hooks, bypassing sanitize_hook_environ() and passing the full process environment to hook subprocesses; however, the Hooks v2 runtime (HooksRuntime) is not yet wired into the live application, so this code path is not currently reachable in production.

Comment thread libs/code/deepagents_code/hooks/runner.py
Comment thread libs/code/deepagents_code/hooks/models/config.py Outdated
Comment thread libs/code/deepagents_code/hooks/models/domain.py
Comment thread libs/code/deepagents_code/hooks/legacy.py
Co-authored-by: open-swe[bot] <open-swe@users.noreply.github.com>
@johannes117
Johannes du Plessis (johannes117) merged commit fdb585c into main Jul 24, 2026
54 checks passed
@johannes117
Johannes du Plessis (johannes117) deleted the johannes117/code/dcd-70-hooks-legacy-migration branch July 24, 2026 15:02
Mason Daugherty (mdrxy) pushed a commit that referenced this pull request Jul 27, 2026
> [!CAUTION]
> Merging this PR will automatically publish to **PyPI** and create a
**GitHub release**.

For the full release process, see
[`.github/RELEASING.md`](https://github.com/langchain-ai/deepagents/blob/main/.github/RELEASING.md).

---

_Release notes preview: keep this section in sync with the package
`CHANGELOG.md`. Publish reads the merged CHANGELOG via `release.yml`,
not this PR description — keep them aligned anyway so the PR stays an
accurate historical record for reviewers and anyone returning later._

---


##
[0.1.48](deepagents-code==0.1.47...deepagents-code==0.1.48)
(2026-07-27)

### Features

- Added Fireworks `kimi-k3`, GLM-5.2-Fast, and Kimi-K3 to model
selection and recommended models.
([#5082](#5082),
[#5072](#5072))
- Migrated legacy hooks to v2 events.
([#4971](#4971))

### Bug Fixes

- Require an `AGENTS.md` marker for `/agent` discovery, resolving
unintended discovery behavior.
([#5076](#5076), closes
[#4991](#4991))
- Removed the redundant `/restart` hint from the restart prompt.
([#5083](#5083))
- Removed the caret flash in plugin type-to-search.
([#5078](#5078))

_End release notes preview._

---

> [!NOTE]
> A **New Contributors** section is appended to the GitHub release notes
automatically at publish time (see [Release
Pipeline](https://github.com/langchain-ai/deepagents/blob/main/.github/RELEASING.md#release-pipeline),
step 2).

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: langchain-oss-automated-triage[bot] <248757908+langchain-oss-automated-triage[bot]@users.noreply.github.com>
Johannes du Plessis (johannes117) added a commit that referenced this pull request Jul 27, 2026
<!-- CURSOR_AGENT_PR_BODY_BEGIN -->
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>


<!-- branch-stack-start -->

-------------------------
- main
- **feat(code): integrate Hooks v2 server lifecycle events**
:point_left:
    - #5010
      - #5044
        - #5045

<sup>[Stack](https://www.git-town.com/how-to/proposal-breadcrumb.html)
generated by [Git Town](https://github.com/git-town/git-town)</sup>

<!-- branch-stack-end -->

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: open-swe[bot] <open-swe@users.noreply.github.com>
Marcelo5444 pushed a commit to Marcelo5444/deepagents that referenced this pull request Jul 30, 2026
Depends on langchain-ai#4916
Related DCD-70

Hooks v2 command handlers now execute with event-aware policies, bounded
terminal output, sanitized environments, and complete process cleanup.

---

This is 2/3 in the DCD-70 stack.

- Applies plain-output, exit-code, continuation, permission, and
deferred-field policies without discarding sibling diagnostics.
- Validates terminal sequences and removes ambient secret and telemetry
environment values.
- Cleans up complete process groups on timeout or cancellation and maps
native/MCP tool calls only from trustworthy metadata.
- Keeps materialized filesystem paths outside domain and transport
state.

<details>
<summary>Test plan</summary>

- `uv run --group test pytest tests/unit_tests/hooks` — 95 passed at
this stack layer
- `make lint`

</details>

<!-- branch-stack-start -->

-------------------------
- main
  - **fix(code): harden Hooks v2 command execution** 👈
    - langchain-ai#4918
      - langchain-ai#4971

<sup>[Stack](https://www.git-town.com/how-to/proposal-breadcrumb.html)
generated by [Git Town](https://github.com/git-town/git-town)</sup>

<!-- branch-stack-end -->
Marcelo5444 pushed a commit to Marcelo5444/deepagents that referenced this pull request Jul 30, 2026
Depends on langchain-ai#4917
Closes DCD-70

Hooks v2 now materializes private versioned transcript projections and
exposes them through a session-scoped client runtime.

---

This is 3/3 in the DCD-70 stack.

- Adds deterministic per-thread and subagent JSONL projections with
redaction, path-safe identities, private permissions, atomic writes,
revisions, and retention.
- Adds a client-owned runtime that freezes one snapshot and materializes
real transcript paths immediately before command execution.
- Keeps lifecycle call-site and server/client dispatch wiring out of
scope for the following tickets.

<details>
<summary>Test plan</summary>

- `uv run --group test pytest tests/unit_tests/hooks` — 101 passed
- `make lint`
- `make check_imports`

</details>

<!-- branch-stack-start -->

-------------------------
- main
  - langchain-ai#4917
    - **feat(code): add Hooks v2 session transcripts** 👈
      - langchain-ai#4971

<sup>[Stack](https://www.git-town.com/how-to/proposal-breadcrumb.html)
generated by [Git Town](https://github.com/git-town/git-town)</sup>

<!-- branch-stack-end -->

---------

Co-authored-by: Cursor <cursoragent@cursor.com>
Marcelo5444 pushed a commit to Marcelo5444/deepagents that referenced this pull request Jul 30, 2026
Depends on langchain-ai#4918

Legacy hooks with prompt, compaction, turn-completion, notification, and
session-end subscriptions now migrate into typed Hooks v2 events while
retaining their side-effect-only behavior.

---

This adds typed `UserPromptSubmit` and `PreCompact` domain, wire,
capability, projection, matching, and reduction support. The migration
consolidates legacy aliases, preserves the five-second timeout, and
neutralizes stdout and exit status so observational legacy commands
cannot unexpectedly block Hooks v2 lifecycle actions.

Legacy tool and permission events remain unmapped because their
fire-and-forget, batched, and failure semantics are not equivalent to
the current Hooks v2 lifecycle events.

<!-- branch-stack-start -->

-------------------------
- main
  - langchain-ai#4917
    - langchain-ai#4918
      - **feat(code): migrate legacy hooks to v2 events** 👈

<sup>[Stack](https://www.git-town.com/how-to/proposal-breadcrumb.html)
generated by [Git Town](https://github.com/git-town/git-town)</sup>

<!-- branch-stack-end -->

---------

Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: open-swe[bot] <open-swe@users.noreply.github.com>
Marcelo5444 pushed a commit to Marcelo5444/deepagents that referenced this pull request Jul 30, 2026
> [!CAUTION]
> Merging this PR will automatically publish to **PyPI** and create a
**GitHub release**.

For the full release process, see
[`.github/RELEASING.md`](https://github.com/langchain-ai/deepagents/blob/main/.github/RELEASING.md).

---

_Release notes preview: keep this section in sync with the package
`CHANGELOG.md`. Publish reads the merged CHANGELOG via `release.yml`,
not this PR description — keep them aligned anyway so the PR stays an
accurate historical record for reviewers and anyone returning later._

---


##
[0.1.48](langchain-ai/deepagents@deepagents-code==0.1.47...deepagents-code==0.1.48)
(2026-07-27)

### Features

- Added Fireworks `kimi-k3`, GLM-5.2-Fast, and Kimi-K3 to model
selection and recommended models.
([langchain-ai#5082](langchain-ai#5082),
[langchain-ai#5072](langchain-ai#5072))
- Migrated legacy hooks to v2 events.
([langchain-ai#4971](langchain-ai#4971))

### Bug Fixes

- Require an `AGENTS.md` marker for `/agent` discovery, resolving
unintended discovery behavior.
([langchain-ai#5076](langchain-ai#5076), closes
[langchain-ai#4991](langchain-ai#4991))
- Removed the redundant `/restart` hint from the restart prompt.
([langchain-ai#5083](langchain-ai#5083))
- Removed the caret flash in plugin type-to-search.
([langchain-ai#5078](langchain-ai#5078))

_End release notes preview._

---

> [!NOTE]
> A **New Contributors** section is appended to the GitHub release notes
automatically at publish time (see [Release
Pipeline](https://github.com/langchain-ai/deepagents/blob/main/.github/RELEASING.md#release-pipeline),
step 2).

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: langchain-oss-automated-triage[bot] <248757908+langchain-oss-automated-triage[bot]@users.noreply.github.com>
Marcelo5444 pushed a commit to Marcelo5444/deepagents that referenced this pull request Jul 30, 2026
…4997)

<!-- CURSOR_AGENT_PR_BODY_BEGIN -->
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>


<!-- branch-stack-start -->

-------------------------
- main
- **feat(code): integrate Hooks v2 server lifecycle events**
:point_left:
    - langchain-ai#5010
      - langchain-ai#5044
        - langchain-ai#5045

<sup>[Stack](https://www.git-town.com/how-to/proposal-breadcrumb.html)
generated by [Git Town](https://github.com/git-town/git-town)</sup>

<!-- branch-stack-end -->

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: open-swe[bot] <open-swe@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

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

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants