dsh-direnv

Workspace-aware direnv support for DeepSeek Harness: every agent-owned shell command automatically receives its workspace's .envrc environment, and a blocked .envrc produces an actionable notice plus a direnv_allow tool that asks the user before authorizing anything.

What it does

Injects	the environment direnv export json reports for the command's directory, merged into the child's environment map
Per workspace	the workspace comes from the calling agent's session cwd; the command's own workdir selects a nested .envrc, like native direnv
Never wraps commands	request.command is byte-identical to what the model asked for — injection is an environment map, so a workspace cannot inject shell syntax
Asks before allowing	direnv_allow routes through DSH's approval channel; the user sees the path, its SHA-256, and a bounded preview
Fails closed	a blocked, denied, or changed .envrc injects nothing and says so; no approval service means no approval

The blocked-workspace UX

An unapproved .envrc does not fail the command and does not leak its contents. The command runs without the environment, and the result's stderr gains a notice the model can act on:

[dsh-direnv] This command ran WITHOUT the workspace direnv environment.
[dsh-direnv] /home/me/proj/.envrc is not approved, so native direnv refused to load it.
[dsh-direnv] Call the direnv_allow tool with this path to ask the user to approve it:
[dsh-direnv]   direnv_allow path=/home/me/proj/.envrc
[dsh-direnv] Workspace: /home/me/proj

The model then calls direnv_allow. The user is shown the path, the file size, its SHA-256, and a bounded preview of the contents, and must approve. Only allowed-once proceeds; rejection, cancellation, and an unreachable answerer all refuse, and the file is written by the host's own direnv allow.

Approval authorizes exactly the current content: editing the .envrc afterwards invalidates it in direnv's own hash, and the next command is blocked again until it is re-approved.

A denied .envrc is reported distinctly, because direnv ≥ 2.33 makes direnv deny revoke authorization silently — direnv export still exits zero, applying nothing. Simply seeing an empty result cannot tell that apart from a legitimately empty file, so the plugin consults direnv's own deny store (whose file name is direnv's pathHash, reproducing it exactly). A denied file gets its own notice pointing at direnv status; an empty one is treated as "nothing to inject" and stays quiet.

Caching and manual reload

Each directory is resolved once and the answer is reused, so a workspace pays for one direnv export rather than one per command. The cache is keyed by the directory that selects the .envrc, and its validity is a cheap stamp over everything that can change the answer:

• the governing .envrc — its size and mtime (an edit also invalidates direnv's own content hash);
• direnv's allow and deny stores — so a direnv allow or direnv deny run in your own terminal is observed, even though it changes no file the plugin could otherwise see.

When that is not enough — a dependency of the .envrc you changed, an environment direnv reads that this plugin cannot observe — call the direnv_reload tool:

direnv_reload                          # re-resolve the calling workspace
direnv_reload directory=/path/to/ws    # re-resolve one directory
direnv_reload                          # with nothing cached: resolves nothing, says so

It reports each directory's resulting state and which variable names were added or removed. It only reads: it never approves a file and needs no user approval.

Configuration

- id: direnv
  name: dsh-direnv
  config:
    executable: direnv          # bare PATH name or absolute path
    enabled: true               # master switch
    probeTimeoutMs: 10000       # budget for one direnv run
    notifyOnBlocked: true       # append the actionable notice to results
    restrictAllowToWorkspace: true  # direnv_allow may only name a file inside the agent's workspace
    followWorkdir: true         # the command's own directory selects the .envrc
    cache: true                 # resolve each directory once; reload on demand
    previewBytes: 2048          # bounded preview shown in the approval prompt

Field	Default	Meaning
executable	direnv	The direnv binary; must be on PATH or absolute.
enabled	true	When off, the adapter is inert and no probe runs.
probeTimeoutMs	10000	One direnv export json run is killed past this.
notifyOnBlocked	true	Off keeps results byte-identical to an un-instrumented run.
restrictAllowToWorkspace	true	On, direnv_allow refuses any path outside the agent's workspace, including via .. or a symlink.
followWorkdir	true	On, a command run in <ws>/packages/api picks up that .envrc. Off, every command uses the session workspace root.
cache	true	Resolve each directory once and reuse the result. The cache refreshes itself when the .envrc changes or when direnv's allow/deny store is rewritten, and direnv_reload forces a refresh. Off, every command pays the probe (about 35 ms for an allowed .envrc).
previewBytes	2048	How much of the .envrc the user sees. 0 shows only the hash.

Installation

From GitHub

dsh plugin --profile web add github:snylonue/dsh-direnv

# If failed, allow the git repo to run its prepare script, then re-run step 1.
cat >> ~/.dsh/profiles/web/pnpm-workspace.yaml <<'EOF'
allowBuilds:
  'dsh-direnv@git+https://github.com/snylonue/dsh-direnv.git': true
EOF

From a local path or tarball

dsh plugin --profile web add /path/to/dsh-direnv        # link:, requires dist/ to exist
dsh plugin --profile web add /path/to/dsh-direnv.tgz    # packed, self-contained
dsh --profile web --dump-config                         # confirm the three rows

The plugin only takes effect after a restart. DSH composes the plugin tree at boot, so an already-running host does not pick up newly installed rows; the settings-page plugin list reflects the live loader and will not show it until then either.

To uninstall, use dsh plugin --profile web remove dsh-direnv.

Requirements and limits

• The shell service must exist. The provider injects into ctx.shell's calls; without a shell there is nothing to inject, so activation fails loudly.
• Approval is required for direnv_allow. With no approval channel composed, the tool refuses rather than approving on its own.
• direnv deny semantics are direnv's. On direnv >= 2.33 a denied .envrc makes direnv export succeed while applying nothing; this plugin reports that case as denied and tells the user to check with direnv status.
• Persistent terminals are out of scope. DSH mounts terminals inside a preset-private realm; this plugin covers the bash tool (ctx.shell).
• direnv export json returns a diff against the environment direnv ran in. The plugin filters it: DSH_* and DIRENV_* names are dropped, as is any name that is not a portable environment identifier.
• unset compiles to removal, not absence. An environment map cannot remove a variable by omitting it — the executor merges the map onto the credential-scrubbed parent environment, so an absent name keeps the inherited value. A .envrc's unset FOO therefore becomes an undefined value, which is the subprocess seam's removal convention, and the child genuinely does not have FOO. The renderer types the map as Record<string, string>, so the widening is narrowed again at that one boundary.

Development

pnpm install
pnpm typecheck   # source AND tests
pnpm test        # builds, then runs vitest

The suite (119 tests) runs in layers:

• pure core logic — RC discovery, diff parsing, filtering, refusals, the cache stamp, and the deny-store hash the plugin reproduces from direnv;
• the method chain, including the non-LIFO disposal case a naive descriptor-restoring wrapper gets wrong;
• the approval gate, asserting that nothing reaches direnv allow without an explicit allowed-once;
• end-to-end runs against the real direnv binary;
• real compositions that boot dsh-subprocess-local + dsh-bash-local + dsh-shell-env + dsh-tool-bash, drive the model-facing bash, direnv_allow, and direnv_reload tools through the actual tool registry, and assert on what a genuine child process received.

Tests never touch the developer's real direnv authorization store: every workspace, HOME, and XDG root lives in one temp tree.

License

MIT.