feat(dev-tooling)!: resolve the project root per tool call

[Martin Bens (SpiGAndromeda)]

Each of the three dev-tooling MCP servers captured its project root once at launch (PROJECT_ROOT="${PROJECT_ROOT:-$(pwd)}"), so a session that entered a linked git worktree ran PHPStan, PHPUnit, ESLint and the builds against the main checkout while Claude edited the worktree. The results parsed as valid and described the wrong tree. Closes #181.

Per-call project root

Every tool on all three servers takes an optional project_root. Two new tools manage and report that state per server process: set_project_root sets a sticky default for the process and resets to the launch root when called without an argument, and cwd reports the effective root, where it came from, the resolved working directory and the config files in force. Precedence is per-call argument, then sticky value, then launch root — a subagent or workflow script can pin the root per call and is not redirected by a sticky value set elsewhere in the session.

set_project_root runs the same validation, environment binding and reachability probe a per-call target gets, so a root that would fail on the next call fails at the set, with the same message.

Worktree targeting in every environment

Targeting works under native, docker, docker-compose, vagrant and ddev. The environment layer maps a host root onto the path the environment reaches it by: the configured workdir (docker.workdir, vagrant.workdir, ddev.workdir) plus the worktree's position below the launch root, and under docker-compose a configured docker-compose.workdir or the destination of the longest matching bind mount. Both sides of every containment and mapping comparison are canonicalized, so a worktree reached through a symlink, or macOS's /var spelling of /private/var, is measured by the directory it names rather than its spelling.

A worktree may carry its own .mcp-php-tooling.json / .mcp-js-tooling.json. Its environment and scalars are re-derived for that call inside the dispatch subshell; the server process keeps its launch binding, and a mid-session edit of the launch config stays inert until restart — for a launch-root call and a worktree call alike. An environment name outside the known set is refused for a worktree target rather than run as native — a "docker " typo or "podman" would otherwise skip containment, charset and probe and execute on the host. The container set lives in a single _env_is_container_environment predicate in the shared environment module, read by containment, charset and the probe alike, so an environment added there is picked up by all three guards in one edit.

docker compose invocations run from the launch root. Compose discovers its project from the working directory, and a worktree carrying the checkout's tracked compose file (with a relative .:/… bind and no name:) would otherwise resolve the worktree as the project — refused as not-running, or executed in the launch checkout while the banner names the worktree.

shared/worktree.sh holds the resolution and the validation. A target is accepted only when all of these hold:

Check	Refusal when it fails
The target is a linked worktree of the launch root, by git's registry and the .git back-pointer — a back-pointer written relative by --relative-paths resolves against the per-worktree directory that holds it	names the target and the launch root
git is 2.31 or newer for resolution — effectively 2.48 for the feature, since the mandatory relative linkage and its repair command are 2.48 features	names the version required
The .git file carries a relative gitdir pointer — in every environment, native included	names the repair command (git -c worktree.useRelativePaths=true worktree repair "<path>", git 2.48+), with the path quoted so a root carrying a space survives copy-paste
Under a container environment, the worktree sits inside the launch root (the only tree the container mounts)	names the in-root pattern
The configuration in force declares a recognized environment	names the unknown value and the known set
The root carries no character the wrappers cannot embed: no whitespace or shell metacharacter under the four container environments, no single quote or control character anywhere — checked against the raw and the canonical spelling	names the character
Whichever config is in force parses	names the unreadable file
An existence probe (test -d of the mapped path, through the call's own wrapper) reaches the root inside the environment	names the mapped path — this is what catches an unsynced Vagrant folder
The dependencies the tool needs exist under the resolved directory	names vendor/ or node_modules/ and points at worktree_prepare
No supplied path escapes the effective root	names the offending path

Probe results are cached per environment, root and mapped path for the server process — the mapped path derives from the worktree's own per-call re-read configuration, so an edited workdir probes again instead of reusing a pass recorded for the old mapping. State-file writes update only the key they own, so the sticky root and the probe cache cannot erase each other. Diagnostics name both the host path and the environment-side path when they differ.

Most tool results begin with Project root: <path> (launch|sticky|call), so the tree a result describes is visible in the transcript instead of inferred. A PostToolUse hook on EnterWorktree and ExitWorktree injects a reminder naming all three servers, since each is a separate process carrying its own sticky value; on enter it also reads the worktree's .git file and names the repair command when the pointer is absolute — the linkage Claude Code's native EnterWorktree writes unless the repository sets worktree.useRelativePaths, detected also when the file lacks a trailing newline — and warns that a native worktree branches from the default remote branch unless the worktree.baseRef setting is head.

The native command wrappers no longer embed a cd in the command they emit; exec_command and exec_npm_command enter the working directory themselves. That keeps the project root out of shell program text, so a root containing a space or a shell metacharacter is usable, and it fixes wrap_command's unscoped native branch, which emitted no cd at all and ran in the server process's own directory regardless of PROJECT_ROOT.

Dependency provisioning

A fresh worktree holds tracked files only, so vendor/ and node_modules are missing and every composer- and npm-backed tool refuses. worktree_prepare on each server installs its own toolchain's dependencies through the configured environment — composer install --no-interaction on php-tooling, npm ci in the package directory on the JS servers — which under a container runs the install inside the container at the mapped path. It skips the dependency check it exists to satisfy, and the dependency refusals name it as the remedy. A successful install returns a three-line completion summary instead of the per-package installer output; a failed one returns everything.

The PHP variant installs at the effective root and deliberately resolves no scope: the dependency gate checks vendor/autoload.php there, and a scoped install would land where the gate never looks, so the refusal's named remedy could never clear the refusal. The JS variants stay scope-aware because their install and gate derive the same package directory through get_js_workdir. The dev-tooling-runner agent's disallowedTools blocks all three — a check-only dispatch must not be steered into a node_modules-rewriting install by the refusal text.

Provisioning by symlink is ruled out in the tool descriptions: composer's generated autoloaders resolve __DIR__ through the symlink, so a worktree with a symlinked vendor/ silently autoloads the launch tree's classes. Admin Jest needs two more generated artifacts after the install — unit_setup, plus the gitignored test/_mocks_/entity-schema.json via console_run on php-tooling (framework:schema -s entity-schema <mock path>); both are named in the tool description.

Fixes riding along

lint_all, lint_twig, unit_setup, vite_build, webpack_build and phpunit_coverage_gaps each declared a scope parameter and never called resolve_scope, so a caller's scope was accepted and the tool ran against the project root anyway. All six now resolve it, between worktree_enter and worktree_assert_dependencies.

No tool's inputSchema set additionalProperties, so a misspelled parameter was accepted and silently ignored. Every tool now sets it (39 across the three servers). Every tool function's argument reads were compared against its declared properties first, so no tool refuses a parameter its own code still reads.

console_run resolved a relative output_file against $PWD rather than the project root the parameter has documented since 3.19.0, and $PWD is wherever the server process started. The base is now the effective root.

worktree_assert_paths_within_root measured only paths beginning with /, so ../../../src/Core passed while the absolute spelling of the same directory was refused — and the refusal text recommended the relative form. A relative path carrying a .. segment is now refused in any position.

jest's install_if_missing tested an environment-side path with a host [[ -d ]], so every scoped run under a container paid a full npm ci although node_modules existed; it now measures the host package directory, the same binding the dependency gate uses.

docker-compose workdir resolution required a bind mount whose source equals the project root exactly; an ancestor mount now resolves via the longest matching source. _compose_wrap_npm_command composes its JS working directory through get_js_workdir instead of a duplicate suffix. ddev calls name the resolved workdir with exec -d when targeting a worktree; the ddev composer shortcut stays confined to launch-root calls because it re-execs at ddev's own project root.

Refactor

The three server.sh files carried a byte-identical run_mcp_server call under a byte-identical rationale; shared/server_run.sh now holds both. The EXIT trap stays in each server, because moving it would place run_mcp_server ahead of lib sourcing and environment detection. config.sh's cleanup is now a documented config_cleanup rather than the private _config_cleanup that six callers reached for, and every caller moved with it. get_environment_info is removed from the shared environment module (no callers). tool_cwd and the per-call binding share one mapping prefix (_worktree_map_call_environment) instead of forty duplicated lines, and the three worktree_prepare bodies share one install-and-summarize implementation.

The environment-layer changes are template-synced, so shopware-env ships 1.4.0 (folding the unreleased 1.3.1): ancestor-mount acceptance, launch-root-anchored compose invocations, and path-mapping functions its lifecycle tools never call.

Breaking changes

• Most tool results carry the Project root: banner line ahead of the tool's own output, which changes the shape consumers parse. set_project_root and cwd carry no banner.
• A call carrying a parameter the tool does not declare is refused instead of ignored. The refusal names the offending parameter.
• A worktree whose .git file carries an absolute gitdir pointer is refused in every environment, and git worktree add writes an absolute pointer by default. Relink with git -c worktree.useRelativePaths=true worktree repair <worktree-path> (git 2.48+), or create worktrees with --relative-paths. Setting git config worktree.useRelativePaths true once makes every later worktree relative-linked from the start.

[github-actions]

Agent Skills Export

Built 7 skill packages:

• adr-writing
• ci-log-interpretation
• release-info-writing
• feature-branch-pr-writing
• pr-description-writing
• commit-message-writing
• structuring-documentation