deepagents-code 0.1.44__tar.gz → 0.1.46__tar.gz

{deepagents_code-0.1.44 → deepagents_code-0.1.46}/AGENTS.md

@@ -62,6 +62,7 @@ Apply these rules to new UI; do not treat them as a mandate to refactor existing
 - Co-locate a screen's `.tcss` file with its root component and set `CSS_PATH` relative to that module. Its styles may target sibling and small nested components, but a large nested component should generally own its own stylesheet.
 - Widgets cannot use `CSS_PATH`; put intrinsic, auto-scoped defaults in `DEFAULT_CSS`. The mounting screen owns the widget's sizing and placement.
 - Children must not import parent components. They may import shared utilities and data models; send events up and pass state/data down.
+- A `ModalScreen` root inherits Textual's default translucent backdrop (`background: $background 60%`, which degrades to transparent under ansi themes) so it dims and composites the content underneath. Don't override it with `background: transparent` unless the modal is deliberately a non-dimming popover (as some selector overlays are); doing so by accident removes the dim.
 
 ### Testing Textual apps
 

{deepagents_code-0.1.44 → deepagents_code-0.1.46}/CHANGELOG.md

@@ -2,6 +2,62 @@
 
 # Deep Agents Code Changelog
 
+## [0.1.46](https://github.com/langchain-ai/deepagents/compare/deepagents-code==0.1.45...deepagents-code==0.1.46) (2026-07-24)
+
+### Highlights
+
+- Auto mode is now generally available. [#4957](https://github.com/langchain-ai/deepagents/issues/4957)
+- Added configurable Auto goal-criteria acceptance. [#4940](https://github.com/langchain-ai/deepagents/issues/4940)
+- Improved Auto behavior by authorizing actions from active goal/rubric directives, avoiding redundant approval prompts, showing the enable notice only on first global enable, deduplicating classifier-unavailable transcript spam, logging underlying classifier failures, and reporting classifier timeout budgets. [#5017](https://github.com/langchain-ai/deepagents/issues/5017) [#4993](https://github.com/langchain-ai/deepagents/issues/4993) [#5012](https://github.com/langchain-ai/deepagents/issues/5012) [#5013](https://github.com/langchain-ai/deepagents/issues/5013) [#5011](https://github.com/langchain-ai/deepagents/issues/5011) [#5025](https://github.com/langchain-ai/deepagents/issues/5025)
+- Added Hooks v2 capability snapshots and session transcripts, and hardened Hooks v2 command execution. [#4916](https://github.com/langchain-ai/deepagents/issues/4916) [#4918](https://github.com/langchain-ai/deepagents/issues/4918) [#4917](https://github.com/langchain-ai/deepagents/issues/4917)
+- Raised the agent recursion limit to 2000 and made it configurable. [#4994](https://github.com/langchain-ai/deepagents/issues/4994)
+
+### Improvements and fixes
+
+- Let the rubric grader inspect working-directory files, show rubric grader defaults, and improved `/rubric` help and empty-state messaging. [#4835](https://github.com/langchain-ai/deepagents/issues/4835) [#4966](https://github.com/langchain-ai/deepagents/issues/4966) [#5015](https://github.com/langchain-ai/deepagents/issues/5015)
+- Unified goal activation signaling. [#4980](https://github.com/langchain-ai/deepagents/issues/4980)
+- Made Version, Model, and CWD copyable in the Debug Console. [#4975](https://github.com/langchain-ai/deepagents/issues/4975)
+- Improved `config get` output when a key is missing. [#4976](https://github.com/langchain-ai/deepagents/issues/4976)
+- Aborted YOLO launch on `Ctrl+C`/`Ctrl+D` and made the YOLO warning friendlier for new users. [#4953](https://github.com/langchain-ai/deepagents/issues/4953) [#4950](https://github.com/langchain-ai/deepagents/issues/4950)
+- Updated LangSmith handling: secret redaction is disabled by default, `/trace` now flags empty env overrides that shadow the LangSmith key, and the default US endpoint is no longer treated as a custom target. [#4970](https://github.com/langchain-ai/deepagents/issues/4970) [#4996](https://github.com/langchain-ai/deepagents/issues/4996) [#5022](https://github.com/langchain-ai/deepagents/issues/5022)
+- Injected OpenAI `prompt_cache_key` for any OpenAI-provider endpoint. [#4995](https://github.com/langchain-ai/deepagents/issues/4995)
+- Improved tool and schema presentation: finished calls stay on the live tool-group line, first-party tool schemas now include field descriptions, and `web_search`/`fetch_url` tool descriptions were trimmed. [#4927](https://github.com/langchain-ai/deepagents/issues/4927) [#5019](https://github.com/langchain-ai/deepagents/issues/5019) [#5016](https://github.com/langchain-ai/deepagents/issues/5016)
+- Omitted `plugins/` and `conversation_history/` from the `/agent` picker. [#4991](https://github.com/langchain-ai/deepagents/issues/4991)
+- Made selector modal backdrop dimming consistent. [#4990](https://github.com/langchain-ai/deepagents/issues/4990)
+- Restored the `"Server log preserved at:"` notice on exit. [#4999](https://github.com/langchain-ai/deepagents/issues/4999)
+- Used the SDK pin as the effective editable version. [#4949](https://github.com/langchain-ai/deepagents/issues/4949)
+
+## [0.1.45](https://github.com/langchain-ai/deepagents/compare/deepagents-code==0.1.44...deepagents-code==0.1.45) (2026-07-22)
+
+### Features
+
+- Added the Hooks v2 execution engine and typed hooks data models ([#4880](https://github.com/langchain-ai/deepagents/issues/4880), [#4870](https://github.com/langchain-ai/deepagents/issues/4870))
+- Added a filesystem tool allowlist for `dcode` with `--allow-fs-tools` ([#4635](https://github.com/langchain-ai/deepagents/issues/4635))
+- Added a GLM-5.2 harness profile ([#4710](https://github.com/langchain-ai/deepagents/issues/4710))
+- Added a built-in thread inspector skill ([#4769](https://github.com/langchain-ai/deepagents/issues/4769))
+- Replaced Gemini 3.5 Flash with Gemini 3.6 Flash in the model switcher ([#4890](https://github.com/langchain-ai/deepagents/issues/4890))
+- Show experimental mode in the splash screen and debug console ([#4863](https://github.com/langchain-ai/deepagents/issues/4863))
+- Gate debug console click-to-copy behind a checkbox ([#4810](https://github.com/langchain-ai/deepagents/issues/4810))
+
+### Bug Fixes
+
+- Improved scratch-file handling by allowing cleanup of agent-created scratch files and safe OS-temp scratch artifacts ([#4860](https://github.com/langchain-ai/deepagents/issues/4860), [#4869](https://github.com/langchain-ai/deepagents/issues/4869))
+- Skip grading during `/goal` proposals ([#4941](https://github.com/langchain-ai/deepagents/issues/4941))
+- Improved MCP approval handling: Esc now aborts project MCP approval, disabled MCP servers are honored for plugins, remembered approvals are preserved with the env allowlist, and approvals are shared across Git worktrees ([#4888](https://github.com/langchain-ai/deepagents/issues/4888), [#4848](https://github.com/langchain-ai/deepagents/issues/4848), [#4889](https://github.com/langchain-ai/deepagents/issues/4889), [#4939](https://github.com/langchain-ai/deepagents/issues/4939))
+- Hardened installer downloads and paths ([#4871](https://github.com/langchain-ai/deepagents/issues/4871))
+- Fixed forced `dcode update` checks to bust the CDN cache ([#4862](https://github.com/langchain-ai/deepagents/issues/4862))
+- Prevented failed exit setup from stranding the app ([#4913](https://github.com/langchain-ai/deepagents/issues/4913))
+- Fixed routing so `ctrl+x` goes to the focused `ask_user` input ([#4926](https://github.com/langchain-ai/deepagents/issues/4926))
+- Show `-m` prompts as queued immediately on startup ([#4861](https://github.com/langchain-ai/deepagents/issues/4861))
+- Kept harness-profile diagnostics out of terminal output ([#4943](https://github.com/langchain-ai/deepagents/issues/4943))
+- Avoid tracking inline restart callers ([#4894](https://github.com/langchain-ai/deepagents/issues/4894))
+- Fixed debug console thread ID copying on click ([#4945](https://github.com/langchain-ai/deepagents/issues/4945))
+
+### Performance Improvements
+
+- Reduced exit latency by coordinating async shutdown teardown ([#4831](https://github.com/langchain-ai/deepagents/issues/4831))
+- Sped up local context detection ([#4922](https://github.com/langchain-ai/deepagents/issues/4922))
+
 ## [0.1.44](https://github.com/langchain-ai/deepagents/compare/deepagents-code==0.1.43...deepagents-code==0.1.44) (2026-07-20)
 
 ### Bug Fixes

{deepagents_code-0.1.44 → deepagents_code-0.1.46}/DEVELOPMENT.md

@@ -5,6 +5,7 @@ New to the package? Start with [`ARCHITECTURE.md`](./ARCHITECTURE.md) for a high
 ## Contents
 
 - [Quickstart](#quickstart) — get a local checkout running and run the checks CI enforces
+- [LangSmith tracing projects](#langsmith-tracing-projects) — route dev traces away from the shared GA project
 - [Local dev installs](#local-dev-installs) — keep an editable `dcode-dev` separate from a released install
 - [Debugging](#debugging) — diagnose startup crashes and client-side issues
 - [Live CSS development with Textual devtools](#live-css-development-with-textual-devtools) — UI/CSS hot-reload
@@ -68,6 +69,26 @@ make lint
 
 Run `make help` to see every available target.
 
+## LangSmith tracing projects
+
+When LangSmith tracing is enabled and a `LANGSMITH_API_KEY` is available, `deepagents-code` traces its own agent runs to LangSmith. A key alone is not enough for environment-supplied keys — set `LANGSMITH_TRACING=true`. Keys stored via `/auth` auto- enable tracing unless you explicitly opt out (for example `DEEPAGENTS_CODE_LANGSMITH_TRACING=false`).
+
+By default those runs land in the `deepagents-code` project, but the team routes shared runs to a GA project (`shared-deepagents-code`) that is monitored by LangSmith Engine, which raises high-priority Slack alerts on suspected issues.
+
+**Do not point local development at the GA project.** Active development produces failures, half-finished branches, and experiments that Engine flags as issues — noise that buries the alerts that matter for the production project and costs the team triage time. Keep dev and prod runs in separate projects so Engine alerting on the GA project stays high-signal (this also mirrors LangSmith best practice of splitting dev and prod environments into distinct projects).
+
+Route your local runs to a dev-scoped project via `DEEPAGENTS_CODE_LANGSMITH_PROJECT` (this overrides only the agent's own traces, leaving your shell's `LANGSMITH_PROJECT` for user code untouched):
+
+```bash
+# A shared dev bucket, or your own personal project — anything but the GA project
+export DEEPAGENTS_CODE_LANGSMITH_PROJECT=shared-deepagents-code-dev
+uv run deepagents-code
+```
+
+Set the same override for [local dev installs](#local-dev-installs) (`dcode-dev`), not only ad-hoc `uv run` sessions. You can also set it persistently under `[tracing]` in the config file (`tracing.langsmith_project`) or from the `/auth` screen. The startup splash and `/trace` show the project a run is writing to — confirm it is not the GA project before doing noisy work.
+
+When onboarding a new tracing project to Engine, capture the nature of that project first: a production/GA app warrants high-priority alerts, while a staging or active-dev project should use looser thresholds (or stay off Engine) so it does not generate false positives.
+
 ## Debugging
 
 Deep Agents Code runs as two processes: the **Textual TUI** you interact with, and a **`langgraph dev` subprocess** that hosts the agent graph. Each writes its own log, and a single switch turns both on:
@@ -94,7 +115,7 @@ Then pick the log you need by symptom:
 
 The TUI only surfaces a one-line banner; the actual exception lives in the subprocess's combined stdout/stderr. To get it:
 
-1. **Re-run with debugging on** (see above). On exit, the log is preserved and its path is printed to stderr as `Server log preserved at: ...`. Textual's fullscreen mode can hide that line, but the file is still on disk.
+1. **Re-run with debugging on** (see above). After the app exits and the terminal is restored, the log is preserved and its path is printed to stderr as `Server log preserved at: ...`.
 2. **Open the newest log.** On macOS, `tempfile` resolves to `$TMPDIR` (a path under `/var/folders/.../T/`):
 
    ```bash

{deepagents_code-0.1.44 → deepagents_code-0.1.46}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepagents-code
-Version: 0.1.44
+Version: 0.1.46
 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/
@@ -26,26 +26,26 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Terminals
 Requires-Python: <4.0,>=3.11
 Requires-Dist: aiosqlite<1.0.0,>=0.22.1
-Requires-Dist: anyio<5.0.0,>=4.0.0
-Requires-Dist: deepagents-acp<1.0.0,>=0.0.8
-Requires-Dist: deepagents==0.7.0a7
-Requires-Dist: filelock<3.30,>=3.12
+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: filelock<3.30,>=3.29.7
 Requires-Dist: httpx<1.0.0,>=0.28.1
-Requires-Dist: langchain-anthropic<2.0.0,>=1.4.8
-Requires-Dist: langchain-google-genai<5.0.0,>=4.2.7
+Requires-Dist: langchain-anthropic<2.0.0,>=1.5.1
+Requires-Dist: langchain-google-genai<5.0.0,>=4.3.1
 Requires-Dist: langchain-mcp-adapters<1.0.0,>=0.3.0
-Requires-Dist: langchain-openai<2.0.0,>=1.3.5
+Requires-Dist: langchain-openai<2.0.0,>=1.4.1
 Requires-Dist: langchain-quickjs<0.4.0,>=0.3.3
-Requires-Dist: langchain<2.0.0,>=1.3.13
+Requires-Dist: langchain<2.0.0,>=1.3.14
 Requires-Dist: langgraph-checkpoint-sqlite<4.0.0,>=3.1.0
-Requires-Dist: langgraph-cli[inmem]<1.0.0,>=0.4.30
-Requires-Dist: langgraph-runtime-inmem<1.0.0,>=0.31.0
+Requires-Dist: langgraph-cli[inmem]<1.0.0,>=0.4.31
+Requires-Dist: langgraph-runtime-inmem<1.0.0,>=0.31.1
 Requires-Dist: langgraph-sdk<1.0.0,>=0.4.2
-Requires-Dist: langsmith[sandbox]>=0.9.3
-Requires-Dist: markdownify<2.0.0,>=1.2.2
+Requires-Dist: langsmith[sandbox]>=0.10.10
+Requires-Dist: markdownify<2.0.0,>=1.2.3
 Requires-Dist: mcp<2.0.0,>=1.28.1
 Requires-Dist: packaging>=26.2
-Requires-Dist: pillow<13.0.0,>=12.2.0
+Requires-Dist: pillow<13.0.0,>=12.3.0
 Requires-Dist: prompt-toolkit<4.0.0,>=3.0.52
 Requires-Dist: pydantic<2.14.0a0,>=2.12.5
 Requires-Dist: pyperclip<2.0.0,>=1.11.0
@@ -56,20 +56,20 @@ Requires-Dist: rich<16.0.0,>=15.0.0
 Requires-Dist: tavily-python<1.0.0,>=0.7.26
 Requires-Dist: textual-autocomplete<5.0.0,>=4.0.6
 Requires-Dist: textual-speedups<1.0.0,>=0.2.1
-Requires-Dist: textual<9.0.0,>=8.2.7
+Requires-Dist: textual<9.0.0,>=8.2.8
 Requires-Dist: tomli-w<2.0.0,>=1.2.0
-Requires-Dist: uuid-utils<1.0.0,>=0.16.2
+Requires-Dist: uuid-utils<1.0.0,>=0.17.0
 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.1; extra == 'all-providers'
-Requires-Dist: langchain-anthropic<2.0.0,>=1.4.8; extra == 'all-providers'
-Requires-Dist: langchain-aws<2.0.0,>=1.6.2; extra == 'all-providers'
+Requires-Dist: aiohttp<3.15.0,>=3.14.3; extra == 'all-providers'
+Requires-Dist: langchain-anthropic<2.0.0,>=1.5.1; 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.1; extra == 'all-providers'
 Requires-Dist: langchain-cohere<1.0.0,>=0.6.0; extra == 'all-providers'
 Requires-Dist: langchain-deepseek<2.0.0,>=1.1.0; extra == 'all-providers'
-Requires-Dist: langchain-fireworks<2.0.0,>=1.4.4; extra == 'all-providers'
-Requires-Dist: langchain-google-genai<5.0.0,>=4.2.7; extra == 'all-providers'
+Requires-Dist: langchain-fireworks<2.0.0,>=1.5.1; extra == 'all-providers'
+Requires-Dist: langchain-google-genai<5.0.0,>=4.3.1; extra == 'all-providers'
 Requires-Dist: langchain-google-vertexai<4.0.0,>=3.2.4; extra == 'all-providers'
 Requires-Dist: langchain-groq<2.0.0,>=1.1.3; extra == 'all-providers'
 Requires-Dist: langchain-huggingface<2.0.0,>=1.2.2; extra == 'all-providers'
@@ -79,11 +79,11 @@ Requires-Dist: langchain-meta<2.0.0,>=0.5.0; extra == 'all-providers'
 Requires-Dist: langchain-mistralai<2.0.0,>=1.1.6; extra == 'all-providers'
 Requires-Dist: langchain-nvidia-ai-endpoints<2.0.0,>=1.4.3; extra == 'all-providers'
 Requires-Dist: langchain-ollama<2.0.0,>=1.1.0; extra == 'all-providers'
-Requires-Dist: langchain-openai<2.0.0,>=1.3.5; extra == 'all-providers'
-Requires-Dist: langchain-openrouter<2.0.0,>=0.2.6; extra == 'all-providers'
+Requires-Dist: langchain-openai<2.0.0,>=1.4.1; extra == 'all-providers'
+Requires-Dist: langchain-openrouter<2.0.0,>=0.2.7; extra == 'all-providers'
 Requires-Dist: langchain-perplexity<2.0.0,>=1.4.0; extra == 'all-providers'
 Requires-Dist: langchain-together<2.0.0,>=0.4.0; extra == 'all-providers'
-Requires-Dist: langchain-xai<2.0.0,>=1.2.2; extra == 'all-providers'
+Requires-Dist: langchain-xai<2.0.0,>=1.3.0; extra == 'all-providers'
 Provides-Extra: all-sandboxes
 Requires-Dist: langchain-agentcore-codeinterpreter<1.0.0,>=0.0.5; extra == 'all-sandboxes'
 Requires-Dist: langchain-daytona>=0.0.7; extra == 'all-sandboxes'
@@ -91,11 +91,11 @@ 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.4.8; extra == 'anthropic'
+Requires-Dist: langchain-anthropic<2.0.0,>=1.5.1; extra == 'anthropic'
 Provides-Extra: baseten
 Requires-Dist: langchain-baseten<1.0.0,>=0.2.1; extra == 'baseten'
 Provides-Extra: bedrock
-Requires-Dist: langchain-aws<2.0.0,>=1.6.2; extra == 'bedrock'
+Requires-Dist: langchain-aws<2.0.0,>=1.6.3; extra == 'bedrock'
 Provides-Extra: cohere
 Requires-Dist: langchain-cohere<1.0.0,>=0.6.0; extra == 'cohere'
 Provides-Extra: daytona
@@ -103,9 +103,9 @@ Requires-Dist: langchain-daytona>=0.0.7; extra == 'daytona'
 Provides-Extra: deepseek
 Requires-Dist: langchain-deepseek<2.0.0,>=1.1.0; extra == 'deepseek'
 Provides-Extra: fireworks
-Requires-Dist: langchain-fireworks<2.0.0,>=1.4.4; extra == 'fireworks'
+Requires-Dist: langchain-fireworks<2.0.0,>=1.5.1; extra == 'fireworks'
 Provides-Extra: google-genai
-Requires-Dist: langchain-google-genai<5.0.0,>=4.2.7; extra == 'google-genai'
+Requires-Dist: langchain-google-genai<5.0.0,>=4.3.1; extra == 'google-genai'
 Provides-Extra: groq
 Requires-Dist: langchain-groq<2.0.0,>=1.1.3; extra == 'groq'
 Provides-Extra: huggingface
@@ -115,8 +115,8 @@ Requires-Dist: langchain-ibm<2.0.0,>=1.1.0; extra == 'ibm'
 Provides-Extra: litellm
 Requires-Dist: langchain-litellm<2.0.0,>=0.7.0; extra == 'litellm'
 Provides-Extra: media
-Requires-Dist: av<18.0.0,>=17.0.0; extra == 'media'
-Requires-Dist: pillow<13.0.0,>=12.2.0; extra == 'media'
+Requires-Dist: av<19.0.0,>=18.0.0; extra == 'media'
+Requires-Dist: pillow<13.0.0,>=12.3.0; extra == 'media'
 Provides-Extra: meta
 Requires-Dist: langchain-meta<2.0.0,>=0.5.0; extra == 'meta'
 Provides-Extra: mistralai
@@ -124,14 +124,14 @@ Requires-Dist: langchain-mistralai<2.0.0,>=1.1.6; extra == 'mistralai'
 Provides-Extra: modal
 Requires-Dist: langchain-modal>=0.0.5; extra == 'modal'
 Provides-Extra: nvidia
-Requires-Dist: aiohttp<3.15.0,>=3.14.1; extra == 'nvidia'
+Requires-Dist: aiohttp<3.15.0,>=3.14.3; extra == 'nvidia'
 Requires-Dist: langchain-nvidia-ai-endpoints<2.0.0,>=1.4.3; extra == 'nvidia'
 Provides-Extra: ollama
 Requires-Dist: langchain-ollama<2.0.0,>=1.1.0; extra == 'ollama'
 Provides-Extra: openai
-Requires-Dist: langchain-openai<2.0.0,>=1.3.5; extra == 'openai'
+Requires-Dist: langchain-openai<2.0.0,>=1.4.1; extra == 'openai'
 Provides-Extra: openrouter
-Requires-Dist: langchain-openrouter<2.0.0,>=0.2.6; extra == 'openrouter'
+Requires-Dist: langchain-openrouter<2.0.0,>=0.2.7; extra == 'openrouter'
 Provides-Extra: perplexity
 Requires-Dist: langchain-perplexity<2.0.0,>=1.4.0; extra == 'perplexity'
 Provides-Extra: quickjs
@@ -144,7 +144,7 @@ Requires-Dist: langchain-vercel-sandbox>=0.0.1; extra == 'vercel'
 Provides-Extra: vertex
 Requires-Dist: langchain-google-vertexai<4.0.0,>=3.2.4; extra == 'vertex'
 Provides-Extra: xai
-Requires-Dist: langchain-xai<2.0.0,>=1.2.2; extra == 'xai'
+Requires-Dist: langchain-xai<2.0.0,>=1.3.0; extra == 'xai'
 Description-Content-Type: text/markdown
 
 # 🧠🤖 Deep Agents Code

{deepagents_code-0.1.44 → deepagents_code-0.1.46}/THREAT_MODEL.md

@@ -231,7 +231,7 @@
 
 #### TB4: MCP Config → Process / Network
 
-- **Inside**: `mcp_tools._validate_server_config` validates JSON structure and field types. Project-level servers (stdio and remote) require approval: an interactive prompt (`main._check_mcp_project_trust`) that offers allow-for-this-session ("y"), remember a chosen subset of servers ("r"), or deny ("N") — unless `--trust-project-mcp` is set, which trusts the whole config for the run. Whole-config trust is never persisted; it exists only as in-memory run state, set by `--trust-project-mcp` or by an interactive allow-once/remember decision. The remembered subset governs only what is persisted for future runs — both allow-once and remember load every prompted server for the current session. Persistent "remember" (a.k.a. "always allow") decisions are stored in `[mcp].enabled_project_server_approvals` with project root, server name, and server definition fingerprint, so a different project or changed command/URL under the same name requires re-approval. Users can reject individual project server names via `[mcp].disabled_project_servers` (or `DEEPAGENTS_CODE_DISABLED_PROJECT_MCP_SERVERS`). There is also an explicit process-wide escape hatch, `DEEPAGENTS_CODE_DANGEROUSLY_ENABLE_PROJECT_MCP_SERVERS`, that approves matching names globally and intentionally bypasses the project/fingerprint binding. Reject wins over approval and over full trust, with one documented exception: if the user's `config.toml` is unreadable (see below), any deny defined *only* there is lost, so a name that is both TOML-`disabled` and exported in `DEEPAGENTS_CODE_DANGEROUSLY_ENABLE_PROJECT_MCP_SERVERS` survives — an accepted footgun (`load_mcp_server_trust_lists` documents it inline) that requires a self-contradicting config plus the explicit dangerous opt-in, and the read error is surfaced to the user. These policies are read by `model_config.load_mcp_server_trust_lists` only from user-controlled sources — the user-level `~/.deepagents/config.toml`, the global `~/.deepagents/.env`, and shell-exported env — never from `.mcp.json` or any repo-committed file, so a committed config cannot self-approve its own servers. In particular, the env forms (`DEEPAGENTS_CODE_DANGEROUSLY_ENABLE_PROJECT_MCP_SERVERS` / `..._DISABLED_...`) are added to `config._PROJECT_DOTENV_DENIED_ENV_KEYS`, so a committed *project* `.env` cannot inject them into `os.environ` even though it is loaded at bootstrap. The dangerous enable env var replaces TOML approvals when set, while disabled *unions* TOML and env so a deny can never be silently emptied by the other source. If the user's `config.toml` exists but cannot be read or parsed, the loader fails closed (project configs are treated as untrusted and the error is surfaced) rather than proceeding with an empty deny list. Only scoped-approved, dangerously env-enabled, or fully trusted names survive into the merged config, so a non-approved remote entry is never preflighted and its interpolated headers are never resolved.
+- **Inside**: `mcp_tools._validate_server_config` validates JSON structure and field types. Project-level servers (stdio and remote) require approval: an interactive prompt (`main._check_mcp_project_trust`) that offers allow-for-this-session ("y"), remember a chosen subset of servers ("r"), or deny ("N") — unless `--trust-project-mcp` is set, which trusts the whole config for the run. Whole-config trust is never persisted; it exists only as in-memory run state, set by `--trust-project-mcp` or by an interactive allow-once/remember decision. The remembered subset governs only what is persisted for future runs — both allow-once and remember load every prompted server for the current session. Persistent "remember" (a.k.a. "always allow") decisions are stored in `[mcp].enabled_project_server_approvals` with a local-project identity, server name, and server definition fingerprint. Remote server approvals with fixed URLs are shared by main checkouts and linked worktrees only through validated reciprocal Git common-directory metadata; independent clones remain separate, and non-Git or malformed/forged metadata falls back to the exact resolved root. Remote definitions with interpolated URLs remain exact-worktree scoped because project `.env` files can resolve the same template to different endpoints. Local stdio server approvals always use the exact resolved worktree root because the same command can execute different files in another checkout. A changed command, URL, or transport under the same name requires re-approval. Users can reject individual project server names via `[mcp].disabled_project_servers` (or `DEEPAGENTS_CODE_DISABLED_PROJECT_MCP_SERVERS`). There is also an explicit process-wide escape hatch, `DEEPAGENTS_CODE_DANGEROUSLY_ENABLE_PROJECT_MCP_SERVERS`, that approves matching names globally and intentionally bypasses the project/fingerprint binding. Reject wins over approval and over full trust, with one documented exception: if the user's `config.toml` is unreadable (see below), any deny defined *only* there is lost, so a name that is both TOML-`disabled` and exported in `DEEPAGENTS_CODE_DANGEROUSLY_ENABLE_PROJECT_MCP_SERVERS` survives — an accepted footgun (`load_mcp_server_trust_lists` documents it inline) that requires a self-contradicting config plus the explicit dangerous opt-in, and the read error is surfaced to the user. These policies are read by `model_config.load_mcp_server_trust_lists` only from user-controlled sources — the user-level `~/.deepagents/config.toml`, the global `~/.deepagents/.env`, and shell-exported env — never from `.mcp.json` or any repo-committed file, so a committed config cannot self-approve its own servers. In particular, the env forms (`DEEPAGENTS_CODE_DANGEROUSLY_ENABLE_PROJECT_MCP_SERVERS` / `..._DISABLED_...`) are added to `config._PROJECT_DOTENV_DENIED_ENV_KEYS`, so a committed *project* `.env` cannot inject them into `os.environ` even though it is loaded at bootstrap. The dangerous enable env var and scoped TOML approvals are independent grants: setting the env var, including to an empty value, does not suppress remembered approvals. Disabled *unions* TOML and env so a deny can never be silently emptied by the other source. If the user's `config.toml` exists but cannot be read or parsed, the loader fails closed (project configs are treated as untrusted and the error is surfaced) rather than proceeding with an empty deny list. Only scoped-approved, dangerously env-enabled, or fully trusted names survive into the merged config, so a non-approved remote entry is never preflighted and its interpolated headers are never resolved.
 - **Outside**: Stdio server `command`, `args`, and `env` fields are user-controlled strings passed directly to `StdioConnection`. The `env` dict from MCP config is forwarded without filtering — users can set arbitrary environment variables (including `PATH`, `LD_PRELOAD`, `PYTHONPATH`) for the MCP subprocess.
 - **Crossing mechanism**: `subprocess.Popen` (via `langchain_mcp_adapters`) for stdio; HTTP/SSE for remote servers.
 
@@ -348,6 +348,7 @@
 | T9  | DF23      | —              | `class_path` in config.toml triggers arbitrary Python code execution via `importlib.import_module()` | TB11 | Low | Verified | `config._create_model_from_class`, `model_config.ProviderConfig`      |
 | T10 | DF24      | DC1            | MCP stdio subprocess env dict accepts arbitrary keys including `PATH`, `LD_PRELOAD`, `PYTHONPATH` without filtering | TB4 | Low | Verified | `mcp_tools._validate_server_config`, `mcp_tools._load_tools_from_config` |
 | T12 | DF10      | —              | Project `.env` sets shell startup-hook variables (`BASH_ENV`, `ENV`) that run attacker-controlled scripts when `dcode` spawns Bash, before any HITL approval | TB11 | High | Verified | `config._load_dotenv`, `local_context.build_detect_script` |
+| T13 | DF7       | —              | Configured shell allow-list checks only the first token, so an allow-listed interpreter/wrapper (`python3`, `bash`, `env`, `xargs`, …) runs arbitrary code via its arguments without approval in non-interactive mode | TB2 | Medium | Verified | `config.is_shell_command_allowed`, `config.contains_dangerous_patterns` |
 
 ### Threat Details
 
@@ -360,7 +361,7 @@
 #### T2: Shell Allow-List Bypass via `SHELL_ALLOW_ALL`
 
 - **Flow**: DF7 (LLM tool call) → C4 Tools (execute)
-- **Description**: When `--shell-allow-list all` (or `DEEPAGENTS_SHELL_ALLOW_LIST=all`) is set, `is_shell_command_allowed` returns `True` for any non-empty command without invoking `contains_dangerous_patterns`. In non-interactive mode, any shell command the LLM requests executes unconditionally. Combined with T1, an attacker-controlled page could cause arbitrary command execution.
+- **Description**: When `--shell-allow-list all` (or `DEEPAGENTS_SHELL_ALLOW_LIST=all`) is set, `is_shell_command_allowed` returns `True` for any non-empty command without invoking `contains_dangerous_patterns`. In non-interactive mode, any shell command the LLM requests executes unconditionally. Combined with T1, an attacker-controlled page could cause arbitrary command execution. A configured (non-`all`) allow-list narrows this but is not a robust boundary either — see T13.
 - **Preconditions**: (1) User has configured `--shell-allow-list all`; (2) Non-interactive mode; (3) Successful prompt injection via DF8/DF9.
 
 #### T3: Unicode Homoglyph URL in Approval Dialog
@@ -424,6 +425,12 @@
 - **Description**: `config._load_dotenv` discovers the nearest project `.env` by walking up from the working directory and applies its values to the process environment (`override=False`, so shell-exported values still win). Bash treats several environment variables as startup hooks — `BASH_ENV` and `ENV` name a file that is sourced when a non-interactive shell starts. Because Deep Agents Code runs its own local-context detection through Bash at startup (`local_context.build_detect_script`) and spawns shells for the `execute` tool, a project `.env` that sets one of these keys could run attacker-controlled scripts inside the `dcode` process *before* any model-requested tool call or HITL approval prompt. The broader trust boundary is that running `dcode` in a project directory lets that project influence the process environment.
 - **Preconditions**: (1) User launches `dcode` in a directory containing an attacker-controlled `.env` (for example, a freshly cloned untrusted repository); (2) the `.env` sets a shell startup-hook key that is not already exported in the user's shell (dotenv uses `override=False`).
 
+#### T13: First-Token Shell Allow-List Bypass via Interpreters/Wrappers
+
+- **Flow**: DF7 (LLM tool call) → C4 Tools (execute)
+- **Description**: `is_shell_command_allowed` splits a command on `|`, `;`, `&&`, and `||`, then validates only the *first token* (`tokens[0]`) of each segment against the configured allow-list, after rejecting a set of dangerous patterns (`contains_dangerous_patterns`: command substitution `$(`/backticks, redirects, `${`, bare `$VAR`, background `&`). Because only the executable name is checked, any allow-listed general-purpose interpreter or command wrapper carries arbitrary behavior in its arguments: `python3 -c '<code>'`, `bash script.sh`, `sh -c '<code>'`, `env <cmd>`, `xargs <cmd>`, `uv run <cmd>`, and similar. A user who allow-lists such a program — reasonably believing they have restricted the agent to a "safe" tool — has effectively allowed unrestricted execution, and in headless `-x`/Auto mode those commands run without an approval prompt. This is the same class of weakness as T2 but applies to *normal, non-`all`* allow-lists. The allow-list is an ergonomic auto-approve heuristic, not a security boundary; textual command classification cannot robustly constrain execution.
+- **Preconditions**: (1) User configures a shell allow-list (`--shell-allow-list` / `DEEPAGENTS_SHELL_ALLOW_LIST`) that includes an interpreter or wrapper; (2) non-interactive or Auto mode (interactive Manual mode still shows the human the literal command before it runs); (3) for the injected-command variant, successful prompt injection via DF8/DF9. The intended control is HITL approval; OS-native execution sandboxing would be the robust boundary the string allow-list cannot provide.
+
 ---
 
 ## Input Source Coverage
@@ -431,7 +438,7 @@
 | Input Source          | Data Flows            | Threats       | Validation Points                                                          | Responsibility | Gaps                                                                                         |
 |-----------------------|-----------------------|---------------|----------------------------------------------------------------------------|----------------|----------------------------------------------------------------------------------------------|
 | User direct input     | DF1, DF2              | None (TB1)    | None — prompts accepted verbatim                                           | User           | No content filtering — intentional; HITL gates downstream tool calls                        |
-| LLM output            | DF6, DF7              | T1, T2, T3, T4| HITL gate; shell allow-list; Unicode/URL warnings on tool args             | Project        | LLM-generated tool args not scanned for injection beyond Unicode/URL                        |
+| LLM output            | DF6, DF7              | T1, T2, T3, T4, T13| HITL gate; shell allow-list; Unicode/URL warnings on tool args        | Project        | LLM-generated tool args not scanned for injection beyond Unicode/URL; shell allow-list matches only the command's first token, so allow-listed interpreters/wrappers bypass it (T13)   |
 | Tool/function results | DF9, DF11             | T1            | Unicode warning on URL args; `markdownify` HTML conversion                 | Shared         | Tool *results* pass to context without prompt-injection scan                                 |
 | URL-fetched content   | DF8, DF9              | T1            | `check_url_safety` on URL arg; HTML→markdown conversion                    | Shared         | Markup-embedded instructions survive markdownify; no LLM-layer guardrail                    |
 | Configuration         | DF10, DF12, DF15, DF23| T9, T10, T12  | Dotenv shell-env precedence; TOML schema; MCP schema + allow/deny lists; JSON structure check; `class_path` format check | User | Project `.env` can set shell startup-hook vars; `class_path` executes module code before type check; MCP env dict unfiltered |
@@ -494,3 +501,5 @@ Threats that appear valid in isolation but fall outside project responsibility b
 | 2026-06-25 | manual update                      | Added T12 (project `.env` injects shell interpreter startup hooks) under TB11; extended the TB11 boundary controls and details with the dotenv shell-startup-hook denylist (`BASH_ENV`, `ENV`); clarified the `.env` out-of-scope row to separate ordinary config discovery from the in-scope code-execution implication |
 | 2026-06-25 | manual update                      | Updated T6 and TB10 to reflect the dev server binding an OS-assigned ephemeral port by default (`server._EPHEMERAL_PORT`) instead of squatting the well-known `langgraph dev` port 2024; noted unpredictable-port-across-runs as added defense-in-depth in the port-discovery dismissal row |
 | 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 |

{deepagents_code-0.1.44 → deepagents_code-0.1.46}/deepagents_code/_ask_user_types.py

@@ -69,6 +69,20 @@ class AskUserRequest(TypedDict):
     """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."""
 

{deepagents_code-0.1.44 → deepagents_code-0.1.46}/deepagents_code/_build_info.py

@@ -1,3 +1,3 @@
 """Generated at build time. Do not edit or commit."""
 
-BUILD_COMMIT = "2b9cd08"
+BUILD_COMMIT = "efa86c5"

{deepagents_code-0.1.44 → deepagents_code-0.1.46}/deepagents_code/_cli_context.py

@@ -47,7 +47,7 @@ class CLIContextSchema:
 
     thread_id: str | None = None
 
-    blocked_goal_retry_context: str | None = None
+    turn_id: str | None = None
 
     offload_tool_call_id: str | None = None
 
@@ -98,13 +98,8 @@ class CLIContext(TypedDict, total=False):
     session-affinity headers.
     """
 
-    blocked_goal_retry_context: str | None
-    """One-turn model context for retrying a previously blocked goal.
-
-    This is intentionally carried in runtime context instead of the user
-    message so it is not parsed as a file mention or checkpointed as human
-    input.
-    """
+    turn_id: str | None
+    """Current user-turn ID for binding trusted interactive responses."""
 
     offload_tool_call_id: str | None
     """The sole tool-call ID authorized during a server-driven `/offload` run.

{deepagents_code-0.1.44 → deepagents_code-0.1.46}/deepagents_code/_constants.py

@@ -13,6 +13,31 @@ from typing import Final
 DEFAULT_AGENT_NAME: Final[str] = "agent"
 """Default agent / assistant identifier when no `-a` flag is given."""
 
+FS_TOOL_NAMES: Final[frozenset[str]] = frozenset(
+    {"ls", "read_file", "write_file", "edit_file", "delete", "glob", "grep", "execute"}
+)
+"""Mirror of the SDK's `FsToolName` literal members.
+
+Hardcoded here rather than derived from `deepagents.FsToolName` because
+`deepagents` must not be imported on the arg-parsing hot path (see AGENTS.md
+"Startup performance"); this module is dependency-free and safe for `main.py` to
+import. Consumers (`main._parse_allow_fs_tools_flag`,
+`tool_catalog.collect_built_in_tools`) alias this set, and `get_args(FsToolName)`
+drift guards in `test_main_args` and `test_tool_catalog` pin it so a new or
+renamed SDK filesystem tool fails a test instead of silently diverging.
+"""
+
+SDK_DEFAULT_RUBRIC_MAX_ITERATIONS: Final[int] = 3
+"""Default `RubricMiddleware.max_iterations`, shown without importing the SDK.
+
+Hardcoded rather than read from `deepagents.middleware.rubric.RubricMiddleware`
+because this module is dependency-free and importing the SDK for a display
+string would violate the startup-performance rule (see AGENTS.md). This is a
+hand-maintained duplicate that can rot if the SDK bumps its default, so
+`test_reliable_rubric.py::TestReliableRubricMiddleware::test_displayed_max_iterations_default_matches_sdk`
+is the drift guard that fails when the two diverge.
+"""
+
 FIREWORKS_PROVIDER_ID_PREFIX: Final[str] = "accounts/fireworks/"
 """Prefix used to infer Fireworks from fully-qualified IDs."""
 

{deepagents_code-0.1.44 → deepagents_code-0.1.46}/deepagents_code/_env_vars.py

@@ -67,10 +67,11 @@ file, so it does not weaken the user-level-only trust boundary (a committed
 This dangerous contract is name-based: a different project, command change, or
 URL change under the same server name still matches.
 
-When set, this replaces (takes precedence over) the scoped
-`[mcp].enabled_project_server_approvals` TOML approvals.
-(`DISABLED_PROJECT_MCP_SERVERS` instead *unions* with its TOML list, so a deny
-is never silently emptied.)
+This process-wide allowlist and the scoped
+`[mcp].enabled_project_server_approvals` TOML approvals are independent grants.
+Setting this variable, including to an empty value, does not suppress remembered
+project approvals. (`DISABLED_PROJECT_MCP_SERVERS` instead *unions* with its
+TOML list, so a deny is never silently emptied.)
 """
 
 DEBUG = "DEEPAGENTS_CODE_DEBUG"
@@ -80,6 +81,21 @@ Parsed by `is_env_truthy`: accepts `1`, `true`, `yes`, `on` (case-insensitive)
 as enabled, and `0`, `false`, `no`, `off`, empty string, or unset as disabled.
 """
 
+DEBUG_CONSOLE_CLICK_TO_COPY = "DEEPAGENTS_CODE_DEBUG_CONSOLE_CLICK_TO_COPY"
+r"""Enable click-to-copy in the `Ctrl+\` Debug Console when enabled.
+
+Off by default; toggle the "Click to copy" checkbox in the console or set
+`[ui].debug_console_click_to_copy` in config.toml. A recognized value is parsed
+by `classify_env_bool`; an unrecognized value falls through to the config value.
+An empty/whitespace value is ignored before parsing (rather than being treated
+as falsy) and also falls through, so it never masks the saved preference.
+
+When set, this env var takes precedence over the persisted
+`[ui].debug_console_click_to_copy` config value on launch, so toggling the
+checkbox will not appear to "stick" across restarts while the env var remains
+set.
+"""
+
 DEBUG_FILE = "DEEPAGENTS_CODE_DEBUG_FILE"
 """Path for the debug log file (default: `DEFAULT_DEBUG_FILE`)."""
 
@@ -143,10 +159,8 @@ EXPERIMENTAL = "DEEPAGENTS_CODE_EXPERIMENTAL"
 """Opt into experimental, unstable dcode behavior.
 
 Off by default; parsed by `is_env_truthy` (see there for the accepted truthy
-values). Currently gates dropping the SDK's `TodoListMiddleware` (and its
-`write_todos` tool) from the agent and its subagents, along with the matching
-todo-list prompt guidance. Behavior behind this flag may change or be removed
-without notice.
+values). Marks experimental runs in UI/trace metadata. Behavior behind this
+flag may change or be removed without notice.
 """
 
 EXTERNAL_EVENT_SOCKET = "DEEPAGENTS_CODE_EXTERNAL_EVENT_SOCKET"
@@ -162,6 +176,16 @@ EXTERNAL_EVENT_SOCKET_PATH = "DEEPAGENTS_CODE_EXTERNAL_EVENT_SOCKET_PATH"
 EXTRA_SKILLS_DIRS = "DEEPAGENTS_CODE_EXTRA_SKILLS_DIRS"
 """Colon-separated paths added to the skill containment allowlist."""
 
+GOAL_AUTO_ACCEPT_CRITERIA = "DEEPAGENTS_CODE_GOAL_AUTO_ACCEPT_CRITERIA"
+"""Apply generated goal criteria automatically in Auto mode.
+
+Disabled by default so Auto continues to show the goal review prompt unless the
+user opts in. Manual always reviews criteria and YOLO always applies them.
+Set to a recognized truthy or falsy value; unrecognized values are ignored and
+resolution falls through to `[goals].auto_accept_criteria` in config.toml, then
+the built-in default (disabled).
+"""
+
 HIDE_CWD = "DEEPAGENTS_CODE_HIDE_CWD"
 """Hide local path displays in the TUI footer and the editable-install path in
 the startup splash when enabled.
@@ -189,7 +213,7 @@ LANGSMITH_PROJECT = "DEEPAGENTS_CODE_LANGSMITH_PROJECT"
 """Override LangSmith project name for agent traces."""
 
 LANGSMITH_REDACT = "DEEPAGENTS_CODE_LANGSMITH_REDACT"
-"""Toggle LangSmith secret redaction for agent traces (defaults to on)."""
+"""Toggle LangSmith secret redaction for agent traces (defaults to off)."""
 
 LANGSMITH_REPLICA_PROJECTS = "DEEPAGENTS_CODE_LANGSMITH_REPLICA_PROJECTS"
 """Comma-separated LangSmith project names to *also* write agent traces to.
@@ -258,12 +282,37 @@ Set to a truthy value to bring the standalone integrations screen back into the
 flow. Parsed by `is_env_truthy`: accepts `1`, `true`, `yes`, `on` as enabled.
 """
 
+OPENAI_PROMPT_CACHE_KEY = "DEEPAGENTS_CODE_OPENAI_PROMPT_CACHE_KEY"
+"""Toggle injecting a per-thread OpenAI `prompt_cache_key` (defaults to on).
+
+When enabled, OpenAI-provider model calls receive the active thread ID as a
+top-level `prompt_cache_key`, giving more reliable prompt-cache prefix routing
+across turns. It is attempted for every model whose provider resolves to
+`openai` regardless of base URL (official API, the LangSmith gateway, and other
+OpenAI-compatible endpoints), because the field is optional and additive. Set to
+a falsy value (`0`, `false`, `no`, `off`) to opt out for endpoints that reject
+unknown request fields; an explicitly empty value also opts out because the
+option declares `empty_env_is_false`. Other tokens are parsed by
+`classify_env_bool`, and an unrecognized value falls through to
+`[models].openai_prompt_cache_key` in config.toml, then the default. A
+user-supplied key is always preserved.
+"""
+
 PLUGIN_CACHE_DIR = "DEEPAGENTS_CODE_PLUGIN_CACHE_DIR"
 """Override the plugin install/marketplace cache root.
 
 When unset, plugins are stored under `DEFAULT_CONFIG_DIR / "plugins"`.
 """
 
+RECURSION_LIMIT = "DEEPAGENTS_CODE_RECURSION_LIMIT"
+"""Override the main agent's LangGraph `recursion_limit` (graph step budget).
+
+Parsed as an integer by the config manifest. Values below the LangGraph floor
+(`25`) or above the manifest ceiling are ignored with a logged warning, falling
+back to `config.toml` then the default. See `[runtime].recursion_limit` and the
+`--recursion-limit` CLI flag.
+"""
+
 RESTARTED_AFTER_UPDATE = "DEEPAGENTS_CODE_RESTARTED_AFTER_UPDATE"
 """Internal sentinel recording the target version immediately before the
 startup auto-update re-execs the process.