deepagents-code 0.1.49__tar.gz → 0.1.51__tar.gz

{deepagents_code-0.1.49 → deepagents_code-0.1.51}/.gitignore

@@ -162,6 +162,16 @@ Cookies
 Cookies.db
 cookies.sqlite
 cookies.txt
+# OpenSSH private keys (no extension, so *.key never matches);
+# .pub counterparts are not secrets and stay committable.
+id_rsa
+id_dsa
+id_ecdsa
+id_ed25519
+*_rsa
+*_dsa
+*_ecdsa
+*_ed25519
 
 # Spyder project settings
 .spyderproject

{deepagents_code-0.1.49 → deepagents_code-0.1.51}/AGENTS.md

@@ -30,6 +30,15 @@ IMPORTANT: `Content` requires **Textual's** `Style` (`textual.style.Style`) for
 
 **Decision rule:** if the value could ever come from outside the codebase (user input, tool output, API responses, file contents), use `from_markup` with `$var`. If it's a hardcoded string, glyph, or computed int, `styled` is fine.
 
+### Markdown messages take a different escape path
+
+The above applies to Rich **markup**. A message mounted as markdown — `AppMessage(source, markdown=True)`, used by `/version` and `/tools` — is parsed as markdown instead, so `from_markup`/`$var` does not apply and offers no protection there. Build the source with the helpers in `app.py`:
+
+- `_escape_markdown(text)` — backslash-escapes markdown punctuation **and** collapses line breaks to spaces. Both matter: unescaped punctuation is parsed (`<b>x</b>` is swallowed as HTML, `[d](u)` collapses to its link text), and an embedded newline ends the current block, so external text could otherwise inject its own headings, lists, and tables.
+- `_markdown_table(headers, rows)` — builds a pipe table, escaping every header and cell, so a `|` cannot forge an extra column.
+
+**Decision rule:** any string reaching markdown source from outside the codebase goes through `_escape_markdown` (or `_markdown_table`, which applies it per cell). Only internal literals and computed ints may be interpolated raw.
+
 ### `App.notify()` defaults to `markup=True`
 
 Textual's `App.notify(message)` parses the message string as Rich markup by default. Any dynamic content (exception messages, file paths, user input, command strings) containing square brackets is unsafe: tag-shaped text like `[bold]` is silently swallowed, and closing-tag-shaped text like `[/tmp/x]` raises a `MarkupError` crash in Textual's Toast renderer. Always pass `markup=False` when the message contains f-string interpolated variables. Hardcoded string literals are safe with the default.
@@ -70,7 +79,8 @@ Apply these rules to new UI; do not treat them as a mandate to refactor existing
 - Snapshot testing available for visual regression - see repo `notes/snapshot_testing.md`
 - For modal flows, test the real interaction path with keypresses when possible. Unit tests that call action methods or resume handlers directly can miss focus and modal-stack bugs.
 - Do not open another modal or refocus the base chat input directly inside a modal dismiss callback. Preserve the non-blocking `push_screen(..., callback)` flow and schedule follow-up UI work with `call_after_refresh` so the dismissing modal fully unwinds first.
-- Be cautious replacing `push_screen(..., callback)` with an awaited modal result inside slash-command handlers; awaiting can block the Textual message pump and break keyboard navigation in the active modal.
+- Be cautious replacing `push_screen(..., callback)` with an awaited modal result inside slash-command handlers; awaiting can block the Textual message pump and break keyboard navigation in the active modal. Slash commands are dispatched from `on_chat_input_submitted`, which is awaited inline on that pump, so a modal awaited anywhere in the call chain never receives the keys that would resolve it and looks frozen.
+- When a command genuinely needs an awaited modal result, hand the continuation to `_schedule_off_message_pump` so the handler returns first. A detached continuation runs outside the handler's `try/except` and is cancelled at app exit, so it must catch its own exceptions and mount its own failure message — otherwise the failure reaches only `_log_task_exception` and the user sees no outcome at all — and it must tolerate cancellation part-way through, including mid-subprocess. Anything that mutates the running tool environment must also take `_environment_mutation_lock`, since the handler no longer serializes commands by blocking.
 
 ### Typing and test doubles
 
@@ -122,6 +132,10 @@ Debug logging is configured **once**, on the `deepagents_code` package logger, b
 
 The `deepagents-code --help` screen is hand-maintained in `ui.show_help()`, separate from the argparse definitions in `main.parse_args()`. When adding a new CLI flag, update **both** files. A drift-detection test (`test_args.TestHelpScreenDrift`) fails if a flag is registered in argparse but missing from the help screen.
 
+## Command name in hints
+
+Hints that tell the user to run something (for example the teardown `-r <thread>` resume hint) must render `_invocation.invoked_name()` rather than a literal `dcode`. The package ships two console scripts (`dcode` and `deepagents-code`), and per-checkout shims — a renamed symlink pointing at a worktree's `bin/dcode` — are a common way to run several installs side by side, so a hardcoded name sends those users to a command they do not have. `invoked_name()` resolves from `sys.argv[0]` (an internal env sentinel carries it across the auto-update re-exec, which drops argv[0]) and falls back to `dcode` when the launch name is not a plausible command. The hand-maintained `--help` usage lines still hardcode `dcode`.
+
 ## Splash screen tips
 
 When adding a user-facing CLI feature (new slash command, keybinding, workflow), add a corresponding entry to the `_TIPS` dict in `deepagents_code/tui/widgets/startup_tip.py`, mapping the tip text to a relative selection weight (higher = shown more often). One tip is chosen at random above the input on startup to help users discover features. Keep tips short and action-oriented (e.g., `"Press ctrl+x to compose prompts in your external editor"`).

{deepagents_code-0.1.49 → deepagents_code-0.1.51}/ARCHITECTURE.md

@@ -66,5 +66,6 @@ The main cost is the client/server boundary. When debugging, first decide which
 
 - For local setup and debugging, see [`DEVELOPMENT.md`](./DEVELOPMENT.md).
 - For command behavior, see [`COMMANDS.md`](./COMMANDS.md).
+- For lifecycle hooks (`hooks.json`), see [`HOOKS.md`](./HOOKS.md).
 - For security boundaries, see [`THREAT_MODEL.md`](./THREAT_MODEL.md).
 - For package-specific coding conventions, see [`AGENTS.md`](./AGENTS.md).

{deepagents_code-0.1.49 → deepagents_code-0.1.51}/CHANGELOG.md

@@ -2,6 +2,49 @@
 
 # Deep Agents Code Changelog
 
+## [0.1.51](https://github.com/langchain-ai/deepagents/compare/deepagents-code==0.1.50...deepagents-code==0.1.51) (2026-07-31)
+
+### Features
+
+- The status bar and usage view now show the running session cost. ([#5036](https://github.com/langchain-ai/deepagents/issues/5036))
+- Removed redundant `shell` and `web_search` prompt guidance. ([#5213](https://github.com/langchain-ai/deepagents/issues/5213))
+- After switching threads, Deep Agents now points back to the previous thread. ([#5172](https://github.com/langchain-ai/deepagents/issues/5172))
+- Leaving `/mcp` with pending toggles now prompts you to reconnect. ([#5211](https://github.com/langchain-ai/deepagents/issues/5211))
+- `dcode config get` now accepts configuration sections. ([#5134](https://github.com/langchain-ai/deepagents/issues/5134))
+
+### Fixes
+
+- Kept the `/goal` criteria prompt responsive. ([#5142](https://github.com/langchain-ai/deepagents/issues/5142))
+- Improved goal handling so underspecified objectives can be resolved from conversation context. ([#5201](https://github.com/langchain-ai/deepagents/issues/5201))
+- Released the turn when an interrupted worker never starts. ([#5196](https://github.com/langchain-ai/deepagents/issues/5196))
+- Hid timestamp footers together with their associated rows. ([#5167](https://github.com/langchain-ai/deepagents/issues/5167))
+- Fixed editable SDK detection by scanning and correlating SDK locations more accurately. ([#5199](https://github.com/langchain-ai/deepagents/issues/5199))
+- Improved `doctor` output to explain why it may not have a latest-version answer. ([#5209](https://github.com/langchain-ai/deepagents/issues/5209))
+
+## [0.1.50](https://github.com/langchain-ai/deepagents/compare/deepagents-code==0.1.49...deepagents-code==0.1.50) (2026-07-30)
+
+### Highlights
+
+- Added project hooks workspace trust and expanded Hooks v2 support with client and server lifecycle events plus runtime feedback ([#5105](https://github.com/langchain-ai/deepagents/issues/5105), [#5104](https://github.com/langchain-ai/deepagents/issues/5104), [#4997](https://github.com/langchain-ai/deepagents/issues/4997), [#5045](https://github.com/langchain-ai/deepagents/issues/5045)).
+- Added an option to mute the “YOLO is active” toast ([#5103](https://github.com/langchain-ai/deepagents/issues/5103)).
+- Made the splash screen `thread` ID clickable to copy it ([#5173](https://github.com/langchain-ai/deepagents/issues/5173)).
+- Show `ask_user` answers directly on the answered tool row ([#5100](https://github.com/langchain-ai/deepagents/issues/5100)).
+- Show a toast when submitting an empty required `ask_user` answer ([#5095](https://github.com/langchain-ai/deepagents/issues/5095)).
+- Added thread message counts to the Debug Console ([#5117](https://github.com/langchain-ai/deepagents/issues/5117)).
+
+### Fixes and improvements
+
+- Gated Hooks v2 behind `DEEPAGENTS_CODE_EXPERIMENTAL` and improved hook resume stability across identity and Command tool results ([#5146](https://github.com/langchain-ai/deepagents/issues/5146), [#5176](https://github.com/langchain-ai/deepagents/issues/5176)).
+- Kept server hook state out of task results ([#5164](https://github.com/langchain-ai/deepagents/issues/5164)).
+- Stopped duplicate Auto transcript events during interrupt replay ([#5157](https://github.com/langchain-ai/deepagents/issues/5157)).
+- Kept `/update` and `/install --package` prompts responsive ([#5127](https://github.com/langchain-ai/deepagents/issues/5127)).
+- Refreshed the `/threads` cache after each turn ([#5174](https://github.com/langchain-ai/deepagents/issues/5174)).
+- Anchored toasts above the chat input and added a toast when media is dropped into a free-text question ([#5101](https://github.com/langchain-ai/deepagents/issues/5101), [#5099](https://github.com/langchain-ai/deepagents/issues/5099)).
+- Improved thread status message styling and links ([#5118](https://github.com/langchain-ai/deepagents/issues/5118)).
+- Made resume hints echo the launched command name ([#5119](https://github.com/langchain-ai/deepagents/issues/5119)).
+- Scoped selection copy to the clicked screen ([#5140](https://github.com/langchain-ai/deepagents/issues/5140)).
+- Ignored mouse hits on detached widgets ([#5114](https://github.com/langchain-ai/deepagents/issues/5114)).
+
 ## [0.1.49](https://github.com/langchain-ai/deepagents/compare/deepagents-code==0.1.48...deepagents-code==0.1.49) (2026-07-27)
 
 ### Features

{deepagents_code-0.1.49 → deepagents_code-0.1.51}/COMMANDS.md

@@ -8,7 +8,7 @@ Regenerate this file with `make commands-catalog` after changing command names,
 aliases, descriptions, visibility, or hidden-command metadata.
 
 
-## Public (37)
+## Public (38)
 
 | Command | Aliases | Description |
 | --- | --- | --- |
@@ -19,6 +19,7 @@ aliases, descriptions, visibility, or hidden-command metadata.
 | `/changelog` |  | Open the changelog in a browser |
 | `/clear` |  | Clear the chat and start a new thread |
 | `/copy` |  | Copy the latest assistant message to clipboard |
+| `/cost` |  | Show estimated thread cost |
 | `/docs` |  | Open the docs |
 | `/editor` |  | Open prompt in an external editor ($EDITOR) |
 | `/effort` |  | Set reasoning effort for the current model |
@@ -30,7 +31,7 @@ aliases, descriptions, visibility, or hidden-command metadata.
 | `/manual` |  | Switch to Manual approval mode |
 | `/mcp` |  | Manage MCP servers and authentication |
 | `/model` |  | Switch models or edit model settings |
-| `/notifications` |  | Configure startup warnings |
+| `/notifications` |  | Configure warning notifications |
 | `/offload` | `/compact` | Summarize and offload older messages to free context |
 | `/plugins` |  | Manage plugins |
 | `/quit` | `/q` | Exit app |

deepagents_code-0.1.51/HOOKS.md

@@ -0,0 +1,121 @@
+# Hooks
+
+Hooks are user-configured shell commands that run at agent lifecycle events. Each matching handler receives a JSON event payload on stdin and may influence the session through its exit code and stdout.
+
+> **Warning:** Hook commands run on your machine with your user privileges. Treat every `hooks.json` entry as code you trust — especially project-scoped hooks checked into a repository.
+
+## Configuration locations and precedence
+
+| Scope | Path | When it loads |
+| --- | --- | --- |
+| User | `~/.deepagents/hooks.json` | Always (when the file exists) |
+| Project | `{project_root}/.deepagents/hooks.json` | Only after workspace trust |
+
+When both scopes load, project matcher groups are applied first, then user groups. A project handler that stops further processing therefore wins over lower-precedence user handlers for the same event.
+
+### Project workspace trust
+
+Project-scoped hooks can execute arbitrary commands from the repository. Before they load:
+
+- Interactive `dcode` prompts for approval when `.deepagents/hooks.json` is present and the workspace is not already trusted.
+- Choosing always-allow persists trust for that canonical workspace root in `~/.deepagents/.state/hooks_trust.json`.
+- Cancelling the prompt (Esc / Ctrl+D) aborts startup.
+- Denying skips project hooks for the session and continues with user hooks only.
+- Headless / CI runs do not prompt; pass `--trust-project-hooks` to opt in for that run.
+
+## Events and matchers
+
+Each top-level key under `"hooks"` is an event name. Values are lists of matcher groups. A group may omit `matcher` (or use `"*"`) to match all values for that event's matcher field. Events with no matcher field reject non-wildcard matchers at load time.
+
+Native tools are matched by their wire names (for example `execute` → `Bash`, `write_file` → `Write`).
+
+| Event | Owner | Matcher field | Fires when |
+| --- | --- | --- | --- |
+| `SessionStart` | client | `cause` | A session starts (`startup`, `resume`, `clear`, `compact`) |
+| `UserPromptSubmit` | client | _(none)_ | The user submits a prompt |
+| `SessionEnd` | client | `cause` | A session ends |
+| `PermissionRequest` | client | `tool_name` | The client is about to ask for tool permission |
+| `Notification` | client | `notification_type` | A client lifecycle notification is emitted |
+| `PreToolUse` | server | `tool_name` | Before a tool call runs |
+| `PostToolUse` | server | `tool_name` | After a tool call completes |
+| `PreCompact` | server | `trigger` | Before conversation compaction |
+| `Stop` | server | _(none)_ | After an agent stop turn |
+| `SubagentStart` | server | `agent_name` | When a subagent starts |
+| `SubagentStop` | server | `agent_name` | When a subagent stops |
+
+## Handler shape
+
+Each matcher group has a `hooks` list of command handlers:
+
+```json
+{
+  "type": "command",
+  "command": "your-shell-command",
+  "timeout": 60,
+  "statusMessage": "Running policy check"
+}
+```
+
+- `type` must be `"command"`.
+- `command` is required and runs through a shell, so pipes, redirects, and `$VAR` expansion work.
+- `argv` is optional; when set, the handler is executed directly from that argument list instead of through a shell.
+- `timeout` is optional seconds; when omitted, the event default applies (600s for most events, 30s for `UserPromptSubmit`).
+- `statusMessage` is optional UI status text while the handler runs.
+- `async: true` is rejected; async command hooks are not supported.
+
+## Examples
+
+### Minimal
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "true"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Deny a destructive shell command
+
+Matchers use wire tool names. `execute` is exposed as `Bash`. Exit code `2` (or JSON `permissionDecision: "deny"`) denies `PreToolUse`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 -c \"import json,sys; d=json.load(sys.stdin); cmd=d.get('tool_input',{}).get('command',''); blocked='rm -rf /' in cmd; print(json.dumps({'hookSpecificOutput':{'hookEventName':'PreToolUse','permissionDecision':'deny','permissionDecisionReason':'Refusing destructive root delete'}}) if blocked else '{}')\""
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## How handler output affects behavior
+
+Handlers communicate through:
+
+- **Exit code `2`**: treated as a synthetic `decision: "block"`. Interpretation depends on the event (for example deny on `PreToolUse` / `PermissionRequest`, block further processing on `UserPromptSubmit` / `PreCompact`, feedback on `PostToolUse`).
+- **Other non-zero exits**: recorded as diagnostics; they do not apply a block decision.
+- **JSON stdout** (`HookWireOutput`): may set `continue` / `stopReason`, `systemMessage` (user-visible notice), `additionalContext` via `hookSpecificOutput`, and event-specific fields such as `permissionDecision` on `PreToolUse`.
+- **Non-JSON stdout**: becomes additional context for events whose plain-output policy is context (`SessionStart`, `UserPromptSubmit`); otherwise it is a diagnostic.
+- **Timeouts**: when a handler exceeds its timeout, it is terminated and recorded as a timeout diagnostic; it does not apply a successful decision.
+
+## Legacy configuration
+
+Older list-shaped `hooks.json` documents are still loaded. Semantically equivalent legacy events are migrated into the Hooks v2 shape automatically; unsupported legacy events are left unmapped and surfaced as load diagnostics.

deepagents_code-0.1.51/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) LangChain, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{deepagents_code-0.1.49 → deepagents_code-0.1.51}/Makefile

@@ -105,13 +105,13 @@ bootstrap: ## Install dev dependencies and git hooks for local development
 check: ## Run the full local CI gauntlet (lint, types, imports, tests, repo gates)
 check: lint check_imports test
 	@echo "🔍 Verifying extras stay in sync with required deps..."
-	uv run --all-groups python "$(REPO_ROOT)/.github/scripts/check_extras_sync.py" pyproject.toml
+	uv run --all-groups python "$(REPO_ROOT)/.github/scripts/checks/check_extras_sync.py" pyproject.toml
 	@echo "🔍 Verifying pyproject.toml and _version.py agree..."
-	uv run --all-groups python "$(REPO_ROOT)/.github/scripts/check_version_equality.py"
+	uv run --all-groups python "$(REPO_ROOT)/.github/scripts/checks/check_version_equality.py"
 	@echo "🔒 Verifying uv.lock is up-to-date..."
 	UV_FROZEN=false uv lock --check
 	@echo "🔗 Checking SDK pin against workspace SDK (advisory)..."
-	@uv run --all-groups python "$(REPO_ROOT)/.github/scripts/check_sdk_pin.py" || \
+	@uv run --all-groups python "$(REPO_ROOT)/.github/scripts/release/check_sdk_pin.py" || \
 		{ rc=$$?; [ $$rc -eq 1 ] && echo "⚠️  Stale SDK pin (advisory, non-fatal)." || exit $$rc; }
 	@echo "✅ All local CI checks passed!"
 

{deepagents_code-0.1.49 → deepagents_code-0.1.51}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepagents-code
-Version: 0.1.49
+Version: 0.1.51
 Summary: Terminal coding agent built on the Deep Agents SDK - works with any model, with persistent memory, customizable skills, subagents, and approval controls.
 Project-URL: Homepage, https://docs.langchain.com/oss/python/deepagents/overview
 Project-URL: Documentation, https://reference.langchain.com/python/deepagents/
@@ -11,6 +11,7 @@ Project-URL: Twitter, https://x.com/langchain_oss
 Project-URL: Slack, https://www.langchain.com/join-community
 Project-URL: Reddit, https://www.reddit.com/r/LangChain/
 License: MIT
+License-File: LICENSE
 Keywords: agents,ai,cli,deep-agent,langchain,langgraph,llm,terminal
 Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Console
@@ -28,10 +29,11 @@ Requires-Python: <4.0,>=3.11
 Requires-Dist: aiosqlite<1.0.0,>=0.22.1
 Requires-Dist: anyio<5.0.0,>=4.14.2
 Requires-Dist: deepagents-acp<1.0.0,>=0.0.9
-Requires-Dist: deepagents==0.7.0b2
+Requires-Dist: deepagents==0.7.1
 Requires-Dist: filelock<3.30,>=3.29.7
+Requires-Dist: genai-prices<0.2.0,>=0.1.0
 Requires-Dist: httpx<1.0.0,>=0.28.1
-Requires-Dist: langchain-anthropic<2.0.0,>=1.5.2
+Requires-Dist: langchain-anthropic<2.0.0,>=1.5.3
 Requires-Dist: langchain-google-genai<5.0.0,>=4.3.2
 Requires-Dist: langchain-mcp-adapters<1.0.0,>=0.3.0
 Requires-Dist: langchain-openai<2.0.0,>=1.4.1
@@ -63,7 +65,7 @@ Provides-Extra: agentcore
 Requires-Dist: langchain-agentcore-codeinterpreter<1.0.0,>=0.0.5; extra == 'agentcore'
 Provides-Extra: all-providers
 Requires-Dist: aiohttp<3.15.0,>=3.14.3; extra == 'all-providers'
-Requires-Dist: langchain-anthropic<2.0.0,>=1.5.2; extra == 'all-providers'
+Requires-Dist: langchain-anthropic<2.0.0,>=1.5.3; extra == 'all-providers'
 Requires-Dist: langchain-aws<2.0.0,>=1.6.3; extra == 'all-providers'
 Requires-Dist: langchain-baseten<1.0.0,>=0.2.3; extra == 'all-providers'
 Requires-Dist: langchain-cohere<1.0.0,>=0.6.0; extra == 'all-providers'
@@ -91,7 +93,7 @@ Requires-Dist: langchain-modal>=0.0.5; extra == 'all-sandboxes'
 Requires-Dist: langchain-runloop>=0.0.6; extra == 'all-sandboxes'
 Requires-Dist: langchain-vercel-sandbox>=0.0.1; extra == 'all-sandboxes'
 Provides-Extra: anthropic
-Requires-Dist: langchain-anthropic<2.0.0,>=1.5.2; extra == 'anthropic'
+Requires-Dist: langchain-anthropic<2.0.0,>=1.5.3; extra == 'anthropic'
 Provides-Extra: baseten
 Requires-Dist: langchain-baseten<1.0.0,>=0.2.3; extra == 'baseten'
 Provides-Extra: bedrock

{deepagents_code-0.1.49 → deepagents_code-0.1.51}/THREAT_MODEL.md

@@ -17,7 +17,7 @@
 - Agent creation (`agent.py`)
 - Built-in tools (`tools.py`: `http_request`, `web_search`, `fetch_url`)
 - MCP config loader and per-server allow/deny lists (`mcp_tools.py`, `model_config.py`)
-- Hook dispatcher (`hooks.py`)
+- Hook runtimes (`hooks/`)
 - Sandbox integration factory (`integrations/sandbox_factory.py`, `integrations/sandbox_provider.py`)
 - Session persistence (`sessions.py`)
 - Configuration system (`config.py`, `model_config.py`)
@@ -126,7 +126,7 @@
 | C3  | Agent Engine                | LangGraph agent graph running inside `langgraph dev` server, assembled by `create_cli_agent`                        | framework-controlled | Yes      | `agent.create_cli_agent`, `agent._add_interrupt_on`, `server_graph.make_graph`                    |
 | C4  | Built-in Tools              | `http_request`, `web_search` (Tavily), `fetch_url` (HTML→markdown)                                                 | framework-controlled | Partial¹ | `tools.http_request`, `tools.web_search`, `tools.fetch_url`                                       |
 | C5  | MCP Loader & Trust          | Discovers/loads `.mcp.json`, validates server configs, applies per-server allow/deny lists + interactive approval    | framework-controlled | No²      | `mcp_tools.resolve_and_load_mcp_tools`, `model_config.load_mcp_server_trust_lists`, `main._check_mcp_project_trust` |
-| C6  | Hook Dispatcher             | Fires subprocess commands on agent lifecycle events                                                                 | framework-controlled | No³      | `hooks.dispatch_hook`, `hooks._run_single_hook`                                                   |
+| C6  | Hook Runtime                | Fires subprocess commands on agent lifecycle events                                                                 | framework-controlled | No³      | `hooks.runtime.HooksRuntime`, `hooks.runner.run_command_handler`                                  |
 | C7  | Sandbox Integration         | Creates/destroys remote sandboxes (Daytona, LangSmith, Modal, Runloop, AgentCore)                                  | framework-controlled | No⁴      | `integrations.sandbox_factory.create_sandbox`                                                     |
 | C8  | Session Persistence         | SQLite checkpoint store for LangGraph thread state                                                                  | framework-controlled | Yes      | `sessions.get_db_path`, `sessions.generate_thread_id`                                             |
 | C9  | Configuration System        | TOML config, env vars, `AGENTS.md` system prompts, model config                                                    | user-controlled      | N/A      | `config.settings`, `model_config.ModelConfig`, `~/.deepagents/config.toml`                        |
@@ -142,7 +142,7 @@
 **Notes:**
 1. `http_request` and `fetch_url` enabled by default; `web_search` requires `TAVILY_API_KEY`.
 2. MCP servers only load if `.mcp.json` config files are present.
-3. Hooks only execute if `~/.deepagents/hooks.json` exists.
+3. User hooks load from `~/.deepagents/hooks.json`. Project hooks load from `.deepagents/hooks.json` only after interactive workspace trust or the headless `--trust-project-hooks` opt-in.
 4. Sandbox mode requires explicit `--sandbox` CLI flag.
 5. Both TUI and non-interactive modes now always spawn a local LangGraph dev server and connect via `RemoteAgent`.
 6. `LocalContextMiddleware` is added whenever `LocalShellBackend` or an `_AsyncExecutableBackend` is in use (`agent.py:create_cli_agent`).
@@ -200,7 +200,7 @@
 | TB2  | LLM Decision → Tool Execution         | HITL gate on all side-effecting tool calls                                 | Interrupt map, allow-list check, auto-approve toggle                            | LLM reasoning; what user approves                             |
 | TB3  | Tool Result → LLM Context             | Tool outputs re-enter the context window                                   | Unicode warnings on URLs in args; markdownify HTML conversion                   | Content of fetched web pages, MCP responses, search results   |
 | TB4  | MCP Config → Process / Network        | `.mcp.json` triggers subprocess spawn or network connection                | Schema validation; per-server allow/deny lists + interactive approval prompt    | What the MCP process does once trusted and running            |
-| TB5  | Hooks Config → Subprocess             | `hooks.json` commands execute as local subprocesses                        | JSON structure validation, 5-second timeout                                     | Command content (user-authored); env vars available to child  |
+| TB5  | Hooks Config → Subprocess             | `hooks.json` commands execute as local subprocesses                        | Workspace trust for project hooks, schema validation, bounded execution, sanitized environment | Command content (user-authored) |
 | TB6  | Setup Script → Sandbox Execution      | User-supplied script runs inside sandbox at startup                        | `shlex.quote()` wrapping; `string.Template.safe_substitute`                     | Script content (user-authored); sandbox network access        |
 | TB7  | External LLM API → Agent State        | LLM API responses drive tool call decisions                                | LLM client configuration, model selection, request params                       | LLM output content; provider-side safety                      |
 | TB8  | CLI → Server Subprocess IPC           | Config passed from CLI to `langgraph dev` subprocess via `DA_SERVER_*` env vars | `ServerConfig.to_env()` serialization; env var scoping to parent+child process | Subprocess environment post-fork; /proc visibility to same-uid processes |
@@ -463,7 +463,7 @@ Threats that appear valid in isolation but fall outside project responsibility b
 | Malicious MCP server injecting prompt instructions                     | Users configure MCP servers and explicitly trust project-level configs. Once trusted, MCP tool outputs are data from a system the user controls.                                     | Interactive approval prompt + per-server allow/deny lists for project-level configs (`main._check_mcp_project_trust`, `model_config.load_mcp_server_trust_lists`). |
 | LLM jailbreak / safety bypass                                          | Model selection and safety configuration are user-controlled. The project routes prompts to the configured LLM but cannot guarantee model behavior.                                   | Correctly routing prompts to the configured LLM; applying the system prompt from `agent.get_system_prompt`.         |
 | Sandbox provider security vulnerabilities                              | Daytona, LangSmith, Modal, Runloop, and AgentCore are third-party services. Their internal security is not this project's responsibility.                                            | Correctly initializing sandbox sessions via `integrations.sandbox_factory.create_sandbox`.                          |
-| Hook commands doing harmful things                                     | Hooks in `~/.deepagents/hooks.json` are 100% user-authored. The payload is data-only (JSON on stdin).                                                                               | JSON structure validation (`hooks._load_hooks`); 5-second timeout.                                                 |
+| Hook commands doing harmful things                                     | User-scoped hooks (`~/.deepagents/hooks.json`) and project-scoped hooks (`.deepagents/hooks.json`, only after interactive workspace trust or `--trust-project-hooks`) are intentionally configured commands. The payload is data-only (JSON on stdin). | Schema validation (`hooks.loading.load_hooks_config`); workspace trust for project hooks (versioned store under `~/.deepagents/.state/hooks_trust.json`; cancelling the trust prompt aborts startup); bounded execution with per-event default timeouts (600s for most events, 30s for `UserPromptSubmit`); sanitized subprocess environment. |
 | Async subagent traffic interception / MitM                             | Async subagents connect to user-configured LangGraph deployment URLs. The project does not control those endpoints or their TLS certificates.                                        | Accepting URL/headers from user config and passing them to the LangGraph SDK (`agent.load_async_subagents`).        |
 | LangGraph dev server port enumeration / discovery                     | Discovering the local dev server port requires local access. Port scanning localhost is a general OS security concern, not a framework vulnerability.                                 | Binding to `127.0.0.1` by default (`server._DEFAULT_HOST`); ephemeral server lifetime; OS-assigned ephemeral port (`server._EPHEMERAL_PORT`) is not predictable across runs. |
 | `.env` file from parent directory changes app/API configuration        | `config._find_dotenv_from_start_path` walks up the directory tree to find `.env` files. Discovering ordinary configuration values (API keys, `DEEPAGENTS_CODE_*` settings) this way is standard `python-dotenv` behavior, and the user controls their filesystem. The *code-execution* implication of a project `.env` (shell startup hooks) is tracked in-scope as T12. | Finding `.env` from the project root (`config._find_dotenv_from_start_path`); `override=False` by default (existing env vars preserved); shell startup / environment-hijack keys (`BASH_ENV`, `ENV`) denied during dotenv loading. |
@@ -503,3 +503,4 @@ Threats that appear valid in isolation but fall outside project responsibility b
 | 2026-07-08 | manual update                      | Removed the SHA-256 config fingerprint trust store (`mcp_trust.py`, `~/.deepagents/.state/mcp_trust.json`, DC4). Project MCP trust is now the interactive approval prompt (allow-for-session / always-allow scoped to project root + server-definition fingerprint / deny), the `--trust-project-mcp` run flag, the `[mcp].enabled_project_server_approvals` and `[mcp].disabled_project_servers` lists, and the process-wide `DEEPAGENTS_CODE_DANGEROUSLY_ENABLE_PROJECT_MCP_SERVERS` name-based escape hatch. The legacy flat `[mcp].enabled_project_servers` key is ignored. Persisted approvals bind to a server definition's fingerprint rather than a whole-config fingerprint. Updated C5, TB4, T10, the configuration input-coverage row, and the malicious-MCP-server dismissal accordingly |
 | 2026-07-21 | manual update                      | Clarified TB4 after process-wide MCP names and scoped remembered approvals changed from replacement semantics to independent grants. An empty process-wide allowlist no longer suppresses remembered approvals; disabled-server precedence is unchanged. |
 | 2026-07-22 | manual update                      | Added T13 (first-token shell allow-list bypass via allow-listed interpreters/wrappers) under TB2, distinguishing it from T2's `--shell-allow-list all` sentinel; cross-referenced it from T2 and extended the "LLM output" input-coverage gap to note that allow-list matching only inspects the command's first token |
+| 2026-07-24 | manual update                      | Corrected the out-of-scope hooks row: Hooks v2 defaults are 600s (30s for `UserPromptSubmit`), not a global 5-second timeout; loading is `hooks.loading.load_hooks_config`; project hooks require workspace trust or `--trust-project-hooks` |