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

{deepagents_code-0.1.49 → deepagents_code-0.1.50}/.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.50}/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.50}/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.50}/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 # Deep Agents Code Changelog
 
+## [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.50}/COMMANDS.md

@@ -30,7 +30,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.50/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.50/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.50}/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.50}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepagents-code
-Version: 0.1.49
+Version: 0.1.50
 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,10 @@ 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.0
 Requires-Dist: filelock<3.30,>=3.29.7
 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 +64,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 +92,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.50}/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` |

deepagents_code-0.1.50/deepagents_code/_ask_user_types.py

@@ -0,0 +1,257 @@
+"""Lightweight types and shared rendering for the ask-user interrupt protocol.
+
+Extracted from `ask_user` so `textual_adapter` can import `AskUserRequest` at
+module level — and `app` can reference the types at type-check time — without
+pulling in the langchain middleware stack.
+
+This is the shared wire format for the tool, the TUI, and `auto_mode`, colocated
+so no consumer has to import another. Each symbol's own docstring records which
+side produces it and which reads it.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Literal, NotRequired
+
+from pydantic import Field
+from typing_extensions import TypedDict
+
+
+class Choice(TypedDict):
+    """A single choice option for a multiple choice question."""
+
+    value: Annotated[str, Field(description="The display label for this choice.")]
+
+
+class Question(TypedDict):
+    """A question to ask the user."""
+
+    question: Annotated[str, Field(description="The question text to display.")]
+
+    type: Annotated[
+        Literal["text", "multiple_choice"],
+        Field(
+            description=(
+                "Question type. 'text' for free-form input, 'multiple_choice' for "
+                "predefined options."
+            )
+        ),
+    ]
+
+    choices: NotRequired[
+        Annotated[
+            list[Choice],
+            Field(
+                description=(
+                    "Options for multiple_choice questions. An 'Other' free-form "
+                    "option is always appended automatically."
+                )
+            ),
+        ]
+    ]
+
+    required: NotRequired[
+        Annotated[
+            bool,
+            Field(
+                description="Whether the user must answer. Defaults to true if omitted."
+            ),
+        ]
+    ]
+
+
+class AskUserRequest(TypedDict):
+    """Request payload sent via interrupt when asking the user questions."""
+
+    type: Literal["ask_user"]
+    """Discriminator tag, always `'ask_user'`."""
+
+    questions: list[Question]
+    """Questions to present to the user."""
+
+    tool_call_id: str
+    """ID of the originating tool call, used to route the response back."""
+
+
+ASK_USER_AUTHORIZATION_METADATA_KEY = "deepagents_code_ask_user_authorization"
+MAX_ASK_USER_AUTHORIZATION_ANSWER_CHARS = 4000
+
+
+class AskUserAuthorizationReceipt(TypedDict):
+    """Trusted same-turn authorization recorded after an ask_user response."""
+
+    version: Literal[1]
+    thread_id: str
+    turn_id: str
+    tool_call_id: str
+    answers: list[str]
+
+
+class AskUserAnswered(TypedDict):
+    """Widget result when the user submits answers."""
+
+    type: Literal["answered"]
+    """Discriminator tag, always `'answered'`."""
+
+    answers: list[str]
+    """User-provided answers, one per question."""
+
+
+class AskUserCancelled(TypedDict):
+    """Widget result when the user cancels the prompt."""
+
+    type: Literal["cancelled"]
+    """Discriminator tag, always `'cancelled'`."""
+
+
+AskUserWidgetResult = AskUserAnswered | AskUserCancelled
+"""Discriminated union for the ask_user widget Future result."""
+
+
+ASK_USER_NO_ANSWER = "(no answer)"
+"""Placeholder for a question with no positionally matching answer.
+
+Unreachable from `_parse_answers` today: every branch there emits exactly
+`len(questions)` answers, and the answered branch rejects a mismatch outright
+rather than formatting it. Kept as a guard for any future caller that formats a
+transcript without that check. A question the user deliberately left blank
+renders as an empty `A:` line instead, never as this placeholder.
+"""
+
+ASK_USER_CANCELLED_ANSWER = "(cancelled)"
+"""Placeholder recorded for every question when the user cancels the prompt."""
+
+ASK_USER_ERROR_ANSWER_PREFIX = "(error: "
+"""Prefix of the placeholder recorded for every question when the prompt fails.
+
+The full placeholder is `(error: <detail>)`. Producer-side only: no production
+code matches on it — `test_ask_user_types` is the only consumer, and it asserts
+against this constant. The TUI derives its row summary from the recorded tool
+status instead, because the placeholder is in-band — the prefix alone cannot
+distinguish a failed prompt from a user who typed `(error: ...)` as their answer.
+"""
+
+AskUserRowSummary = Literal["User answered", "Question failed"]
+"""The summaries an `ask_user` row may collapse to.
+
+Narrows `ToolCallMessage.defer_success` so the transcript cannot be passed where
+a summary belongs — the constraint that keeps user-typed answers out of
+`tool.result` hook payloads.
+
+Of the four `*_SUMMARY` constants below, only `ASK_USER_ANSWERED_SUMMARY` and
+`ASK_USER_FAILED_SUMMARY` are members: the other two are hook bodies that no row
+ever renders. `Literal[...]` cannot reference a plain string constant, so those
+two values are restated here; both are annotated with this alias, so `ty` rejects
+a reword that drifts. `test_row_summary_alias_matches_its_constants` pins it too.
+"""
+
+ASK_USER_ANSWERED_SUMMARY: AskUserRowSummary = "User answered"
+"""One-line summary shown for an answered `ask_user` row before it is expanded.
+
+Doubles as the `tool.result` hook payload's `tool_output` for an answered prompt
+whose `ToolMessage` arrived, deliberately in place of the transcript, so
+user-typed answers are not forwarded to hook scripts. When no `ToolMessage`
+arrives the hook reports `ASK_USER_ANSWERED_NO_RESULT_SUMMARY` instead, while
+the row still settles to this string. Rewording changes that hook contract as
+well as the row; see `textual_adapter` and its `tool.result` tests.
+"""
+
+ASK_USER_ANSWERED_NO_RESULT_SUMMARY = "User answered (no tool result)"
+"""The `tool.result` hook payload for an answered prompt that never completed.
+
+Reported by `_dispatch_terminal_tool_result_hooks` when a teardown closes out a
+row carrying a deferred success — the agent crashed, the stream ended, or the
+user cancelled the turn. The guard there matches an already-settled row too, not
+only one still awaiting its `ToolMessage`; see
+`ToolCallMessage.deferred_success_output`.
+
+The status stays `"success"` because the answers did reach the graph and only the
+tool's own completion was lost, and `ask_user` results double as authorization
+records; this distinct body is what lets an audit consumer tell "answers
+delivered and the tool completed" from "answers delivered, then the turn died".
+When the answers were never delivered at all the hook reports
+`ASK_USER_ANSWERED_NOT_DELIVERED_SUMMARY` with `tool_status="error"` instead.
+Hook contract: rewording it changes what those consumers see.
+"""
+
+ASK_USER_ANSWERED_NOT_DELIVERED_SUMMARY = "User answered (answers not delivered)"
+"""The `tool.result` hook payload for answers the turn discarded before resuming.
+
+Reported with `tool_status="error"` when a sibling question in the same batch was
+cancelled: `textual_adapter` aborts the turn *before* `Command(resume=...)`, so
+the resume payload — including this prompt's answers — is dropped, and the inline
+widget is already unmounted, making the answers unrecoverable. The user answered,
+but nothing downstream ever saw it.
+
+Distinct from `ASK_USER_ANSWERED_NO_RESULT_SUMMARY`, and an error rather than a
+success, precisely because `ask_user` results double as authorization records: a
+`"success"` here would record an authorization that never took effect. Hook
+contract: rewording it changes what audit consumers see.
+"""
+
+ASK_USER_CANCELLED_SUMMARY = "Question cancelled"
+"""The `tool.result` hook payload's `tool_output` for the cancelled path.
+
+Rewording it changes that hook contract. Not rendered on any row: a live cancel
+calls `set_rejected` (which records no output), and a transcript of `(cancelled)`
+placeholders from a non-TUI client is summarized from the recorded status like
+any other, so it reads as `ASK_USER_ANSWERED_SUMMARY`. The cancel banner in
+`textual_adapter` shares this wording but deliberately not this constant — it is
+user-facing prose, not the hook contract.
+"""
+
+ASK_USER_FAILED_SUMMARY: AskUserRowSummary = "Question failed"
+"""One-line summary shown for an `ask_user` prompt the middleware reported failed.
+
+Also the `tool.result` hook payload's `tool_output` on that path — an answered
+prompt whose `ToolMessage` came back with `status="error"` — deliberately in
+place of the transcript, whose `(error: ...)` placeholders carry an arbitrary
+detail string. Live widget failures are not this: they report their own error
+text (see `textual_adapter`'s invalid-payload and cancel branches). Rewording
+changes that hook contract as well as the row.
+"""
+
+
+def format_ask_user_error_answer(detail: str) -> str:
+    """Render the placeholder answer recorded for every question on failure.
+
+    Args:
+        detail: Human-readable reason the prompt failed.
+
+    Returns:
+        The `(error: <detail>)` placeholder.
+    """
+    return f"{ASK_USER_ERROR_ANSWER_PREFIX}{detail})"
+
+
+def format_ask_user_transcript(questions: list[Question], answers: list[str]) -> str:
+    r"""Render questions and answers as the `Q:`/`A:` transcript.
+
+    This is the text the `ask_user` tool returns to the model and persists in the
+    thread. The TUI renders that authoritative text literally rather than trying
+    to parse the unrestricted answer content back into structured data.
+
+    Answers are interpolated unescaped, so the encoding is not unambiguously
+    decodable: an answer containing a blank line followed by a literal
+    `Q: <text>\nA:` header is indistinguishable from a real block boundary. Only
+    the model reads it that way today. Any future decoder must anchor on the known
+    question text rather than on a generic `Q: ` pattern, or a crafted answer can
+    fabricate an extra question/answer pair.
+
+    Args:
+        questions: Questions that were asked. Callers must pass questions whose
+            `question` text is a non-empty string; `ask_user._validate_questions`
+            enforces that before interrupting. The empty default below only
+            keeps a caller that skips validation from raising `KeyError`.
+        answers: Answers, positionally matched to `questions`. A missing entry
+            falls back to `ASK_USER_NO_ANSWER`; extra entries are dropped.
+
+    Returns:
+        Blank-line separated `Q: ...\nA: ...` blocks, one per question.
+    """
+    blocks = [
+        f"Q: {question.get('question', '')}\n"
+        f"A: {answers[i] if i < len(answers) else ASK_USER_NO_ANSWER}"
+        for i, question in enumerate(questions)
+    ]
+    return "\n\n".join(blocks)

{deepagents_code-0.1.49 → deepagents_code-0.1.50}/deepagents_code/_build_info.py

@@ -1,3 +1,3 @@
 """Generated at build time. Do not edit or commit."""
 
-BUILD_COMMIT = "44910bc"
+BUILD_COMMIT = "63adb96"