Profile patch layer cannot override nested preset entries (e.g. enabling optional subagent-codex provider)

[kuangjl2012]

Summary

The profile patch layer ($DSH_HOME/profiles/<name>/cordis.patch.yml) can only target
top-level loader entries. It cannot override entries nested inside an agent preset
(e.g. preset-standard → config.plugins → delegation → tool-subagent-codex).

As a result, enabling an optional subagent provider shipped as disabled: true in a
preset requires editing the preset file inside the repo checkout, which is then
reverted by pnpm run build / git pull.

Environment

• OS: Windows 10.0.19045
• DSH: 0.2.0-rc.2 (built from source at C:\Tools\deepseek-harness)
• profile: web at C:\Users\Administrator\.dsh\profiles\web

Reproduction

Goal: enable subagent_codex (provider codex).

1. Install the provider bundle into the profile so the host-level provider registers:

   profiles/web/package.json:

   {
     "dependencies": {
       "@deepseek-ai/dsh-subagent-codex": "link:<repo>/packages/subagent/subagent-codex"
     },
     "dsh": {
       "profile": {
         "bundles": [
           "@deepseek-ai/dsh-base",
           "@deepseek-ai/dsh-web-app",
           "@deepseek-ai/dsh-subagent-codex"
         ]
       }
     }
   }

2. Try to enable the model-facing tool from the profile patch layer instead of editing
   the preset:

   profiles/web/cordis.patch.yml:

   - id: tool-subagent-codex
     name: '@deepseek-ai/dsh-tool-subagent'
     config:
       provider: codex
       toolName: subagent_codex
       backgroundMode: one-shot
       maxDepth: provider-managed

3. Boot:

   dsh --profile web --dump-config
   

Observed:

dsh: [C:\Users\Administrator\.dsh\profiles\web\cordis.patch.yml] patch: entry "tool-subagent-codex" not found

The entry is defined only inside preset-standard's nested delegation group, not at
the top level, so the id match fails.

4. To actually enable it, we must edit the shipped preset:

   packages/bundle/web-app/presets/standard.patch.yml:

   - id: tool-subagent-codex
     name: '@deepseek-ai/dsh-tool-subagent'
     # disabled: true   <-- removed manually
     config:
       provider: codex
       toolName: subagent_codex
       backgroundMode: one-shot
       maxDepth: provider-managed

   This works, but pnpm run build / git pull restores disabled: true and the tool
   silently disappears.

Evidence that this is a loader limitation, not a config mistake

• vendor/include/src/index.ts warns patch: entry %C not found for unmatched ids.
• packages/boot/app-boot/tests/user-patches.spec.ts only exercises top-level id
  overrides and insert entries; there is no test covering an override of an entry
  nested inside a preset's config.plugins tree.

Proposal

One of:

1. Allow profile patches to target nested entries by path, e.g.:

   - target: preset-standard/delegation/tool-subagent-codex
     disabled: false

   or a dotted id syntax.

2. Expose a stable, overridable switch for optional provider tools (e.g. a
   presets.standard.tools.subagent_codex.enabled key) that a profile patch can flip.

3. Document the intended way to enable optional subagent providers without editing
   files under packages/bundle/..., if such a way already exists.

Impact

Every user who wants subagent_codex (or subagent_claude_code) has to maintain a
local patch against the repo checkout, and re-apply it after every build. This makes
optional-provider enablement fragile and easy to lose silently.

[MentalOfCrow]

There is a persistent profile-level workaround for this layout: override the enclosing preset-standard declaration with a complete copy of its configuration, and enable the Codex tool inside that copy. You do not need to keep modifying the preset under packages/bundle/....

Your report does identify a useful limitation, but the precise boundary is the preset's config.plugins field, rather than all nested loader entries. There is also a second detail in the attempted patch: replacing a tool's config would not, by itself, remove its separate disabled: true flag.

I reviewed the source at 639ed015397290b3745d163aafe02ffee4aa3f84. Please compare this with the exact commit used for your source build: the version label 0.2.0-rc.2 alone does not establish that the implementations are identical. The checks below are source review and an isolated test of the patch helper; I have not booted your Windows installation or run a Codex subagent through it.

1. Why the direct tool ID is not found

In applyEntryPatches, the ID index is recursive, but only through rows satisfying:

if (entry.group && Array.isArray(entry.config)) {
  buildMap(entry.config)
}

Consequently, a child inside an ordinary loader group can be patched by its ID. However, the shipped Standard preset is a loader declaration whose configuration is an object containing the preset definition:

Loader entry: preset-standard
  config:
    id: standard
    order: 1
    plugins:
      ...
      delegation (group)
        config:
          ...
          tool-subagent-codex

The index reaches preset-standard, but does not enter its config.plugins. It therefore never reaches delegation or the Codex tool in that preset. The group's recursive behavior cannot help until the traversal has crossed that outer boundary.

This also explains why adding a slash-separated or dotted target does not currently solve it: this helper looks up an ID string in its map; it does not interpret a nested path. Such syntax would need an implementation change.

2. Use a complete preset override in the profile

For the checkout and profile paths in your report, the source to copy is:

C:\Tools\deepseek-harness\packages\bundle\web-app\presets\standard.patch.yml

The destination is the existing profile patch:

C:\Users\Administrator\.dsh\profiles\web\cordis.patch.yml

First make a backup of that profile patch. Then:

1. In the source preset file, copy the entire declaration starting at - id: preset-standard, including its name and the complete config subtree through the end of that declaration.
2. Place that declaration as an ordinary override row in the profile patch. Do not copy the outer - insert: wrapper. In the checked source, removing the wrapper means dedenting the copied declaration by four spaces, so - id: preset-standard becomes a top-level list item.
3. Preserve config.id: standard, order: 1, the whole plugins list, all group settings, and the existing tool configurations. Preserve the source's !!js conditions too; for example, the Bash/PowerShell conditions encode the platform choice.
4. Within that copied list, locate delegation → config → tool-subagent-codex. Change only that tool row's disabled: true to disabled: false. Leave its provider/tool-name/background/depth configuration as shipped.
5. Remove the unsuccessful standalone id: tool-subagent-codex override from the profile patch, so it no longer produces the unmatched-ID warning. Keep your unrelated profile overrides.
6. If you already have an override of preset-standard in that file, incorporate the change into that existing complete configuration. Avoid competing replacement rows for the same preset.

The beginning of the resulting override should be:

- id: preset-standard
  name: '@deepseek-ai/dsh-agent-preset'
  config:
    id: standard
    order: 1
    plugins:

That excerpt is only the header, not a complete patch to paste on its own. Immediately below it must be the entire plugin list copied from the source, at the correct indentation.

Inside that complete list, the Codex row should retain this shape:

- id: tool-subagent-codex
  name: '@deepseek-ai/dsh-tool-subagent'
  disabled: false
  config:
    provider: codex
    toolName: subagent_codex
    backgroundMode: one-shot
    maxDepth: provider-managed

Again, this second excerpt belongs at its existing location inside the copied delegation group; it is not a separate top-level profile override.

The reason for copying the complete configuration is important: the helper applies overrides with target[key] = value. It replaces config; it does not deep-merge it. A patch containing only config.plugins with one delegation/tool row would lose other fields and capabilities. Even an override containing a complete delegation group would still discard the preset's other plugin rows if those are omitted from the replacement list.

The shipped preset's own header explicitly describes profile overrides of this declaration. The project's implementation note on disabled preset tools also describes overriding a shipped preset's plugin composition from the profile patch. The same enclosing-declaration approach applies here.

3. Keep provider registration and tool enablement separate

Your provider dependency/bundle setup and this preset change do different jobs:

Layer	What to check
Profile dependency and bundle	The host can load/register the Codex provider
Standard preset's plugin composition	The model-facing subagent_codex tool row is enabled
Session preset selection	The session actually uses the preset you changed
Provider execution	The Codex executable, authentication and provider-specific requirements work

Keep the provider bundle you installed; overriding the preset does not install that provider.

For a separate custom preset, give its preset identity a new value rather than inserting another definition with config.id: standard. The registry explicitly rejects duplicate preset identities. Note the distinction between the loader entry ID preset-standard, which identifies the override target, and config.id: standard, which identifies the registered preset. For the in-place override above, keep both as originally declared.

4. Verify composition first, then execution

Run your existing diagnostic:

dsh --profile web --dump-config

In the resulting configuration, check the actual preset-standard declaration, its full plugin list, and the nested Codex row. Expected results are:

• no unmatched-ID warning for the removed standalone Codex patch;
• the registered preset is still standard;
• its other tools and group settings remain present;
• tool-subagent-codex is present with disabled: false and the original Codex configuration.

Then start the Web profile through your usual launch command and create a new session using Standard. A new session avoids relying on an already-running session's retained preset revision; the checked registry also prevents selecting a different preset after a session has started its first turn.

Check whether subagent_codex is available, and then try a small, harmless provider operation. A clean configuration dump proves how the overlay was composed; it does not prove that the provider activated successfully or that Codex authentication/execution will succeed. If the tool is still absent, inspect the preset's activation diagnostic and host/provider loading messages before changing more YAML.

For validation of the explanation, I ran the extracted upstream applyEntryPatches helper in isolation on Node 24.19.0. Twelve assertions passed covering the missed preset child, a successfully patched ordinary group child, replacement rather than deep merging, and a full preset configuration replacement that enables the tool while preserving sibling rows and leaving the original input unchanged. This was not a full DSH integration or Windows provider test.

5. What remains worth improving upstream

This approach persists in the profile instead of modifying a file in the checkout. It does have a maintenance tradeoff: your copied preset composition becomes a snapshot. After upgrading Harness, compare it with the new shipped Standard preset and incorporate relevant changes, rather than assuming a full replacement automatically inherits newly added defaults.

A scoped nested override or an explicit optional-tool switch would avoid that snapshot cost. For a nested implementation, scoping matters because different presets can use the same child tool ID. A regression test should distinguish an ordinary loader group from a preset's config.plugins, verify which preset is modified, preserve all unrelated rows, and retain the existing unmatched-ID diagnostics.

So the improvement request is useful, but the current workaround can already live entirely in the profile: target the enclosing preset declaration, preserve its full configuration, and change the nested tool's separate disabled flag.