dsh-extra-paths
English | 中文
Let DSH write to a set of configured external paths on the first try, with no approval: this covers the write/edit
tools and bash subprocesses alike. The plugin works by wrapping services (it does not change DSH core) and ships a Web
settings page plus a preview of the effective roots for the current workspace.
Install
Requires DSH 0.1.5 / 0.2.0 / 0.2.1 (outside that range the install gate refuses the package).
dsh plugin --profile <name> add dsh-extra-paths # <name> = your profile
From a checkout instead of the registry:
pnpm install && pnpm build
dsh plugin --profile <name> add /path/to/dsh-extra-paths # path = absolute path to this repo
Then open the Extra paths card under Settings → Plugins, or Extra writable paths in the settings sidebar.
Configuration
Write it into the extra-paths section of the settings document ~/.dsh/settings.yaml, or just use the settings page
(saving takes effect immediately, no restart needed). <work root> below is a placeholder for the directory that
holds your projects (an absolute path, or one starting with ~/) — replace it with a path of your own:
extra-paths:
paths:
- <work root>/notes/home # default scope/surfaces
- path: ../../notes/home # relative paths resolve against the session workspace
scope: always-write
- path: <work root>/some-repo
scope: write
surfaces: [fs] # only the write/edit tools may write here
| scope | session read-only | session workspace-write |
|---|
write (default) | denied | writable |
always-write | writable | writable |
surfaces: fs = the write/edit/str-replace tools; shell = bash subprocesses. Reads and execution are not
sandboxed to begin with.
How relative paths resolve
Relative paths resolve against each session's own workspace (the settings page has a "base workspace" field so you
can preview this):
| Spelling | Resolves to | Notes |
|---|
.. | <work root> | the parent of the workspace; that directory and all of its siblings become writable |
../some-repo | <work root>/some-repo | grants exactly one sibling repository (more precise than .., recommended) |
../../notes/home | <work root>/notes/home | go up a few levels and into another tree |
~/notes/home | under your home | independent of the workspace; ~user is not expanded (same as the host) |
Patterns: anchor a grant to directory structure (no hard-coded paths)
A path can use wildcards to describe a group of directories, turning "a certain directory exists somewhere in this
path" into a condition:
| Spelling | Matches (the granted root) |
|---|
<work root>/**/.worktrees/.. | every repository root that contains .worktrees (the parent of .worktrees) |
<work root>/**/.worktrees/* | each individual worktree (.git and the main checkout are never touched) |
<work root>/<some-repo>/.worktrees/* | every worktree of one repository (zero traversal cost, recommended) |
<work root>/*/notes | the notes directory under every repository/project |
Syntax: * = exactly one level, ** = at most 3 levels (only directories that actually exist match, so
".worktrees must exist" comes for free); a trailing .. moves up after matching (so …/.worktrees/.. is "the
parent of .worktrees", rather than something lexical collapsing eats away).
Safety bounds (hard constraints, not advice):
- the wildcard needs a literal anchor before it, at least two segments long, absolute or starting with
~/ —
/**, ~/**, /srv/** are refused outright
- traversal never enters
node_modules or .git, and ** never enters hidden directories (.worktrees is a
literal, so it still matches at its own level)
- bounded:
** covers at most 3 levels, and more than 4096 directories or more than 256 matches makes the whole
pattern inert (fail closed — never a partial, unpredictable grant); the reason is reported as a warning
- expansions are cached for 30 seconds, so a newly created worktree is picked up within 30 seconds
The settings page shows the resolved absolute path live for every row (symlinks follow the host's canonical
preview) and, for a pattern row, the match count as [active ×N] plus each concrete root below it; zero matches and
blocked patterns are both spelled out — so there is no need to "save first and then check whether it resolved".
Known limits
- Per-path "no restrictions at all" is not achievable: the bash sandbox works at whole-invocation granularity.
- Relative paths resolve against the session workspace, so the same entry points at different directories in different
workspaces — the settings page preview shows the actual resolution.
- The shell side is not widened on Windows;
always-write weakens what the read-only stop button can do for that path.
- Files written outside the workspace do not appear in the
deliverables workspace-changes card.
