Skip to content

fix(mcp): default algorithm_spec's out inside the write allowlist (#1108) - #1116

Open
HugoXK wants to merge 1 commit into
mainfrom
agent/1108-algorithm-spec-default-out
Open

HugoXK wants to merge 1 commit into
mainfrom
agent/1108-algorithm-spec-default-out

Conversation

@HugoXK

@HugoXK HugoXK commented Nov 16, 2026

Copy link
Copy Markdown
Collaborator

Closes #1108

algorithm_spec told hosts — in its tool description and in the shared SKILL.md — that an omitted out writes the starter spec beside the user's target. The default write allowlist is the server's cwd plus $AGENTDESCENT_HOME, so for any target outside those two roots the shortest documented path was refused. Measured at base 5048349a, clean worktree, both variables unset, target in a directory that is neither:

ok: False
error: out '/…/repro/user-project/agentdescent.gepa.spec.json' is outside the
       operator's write allowlist (AGENTDESCENT_SURFACE_WRITE_DIRS)
write_dirs: ('/…/repro/server', '/home/xuke/.agentdescent')

What changed

  • agentdescent/mcp.py — an omitted out now resolves through default_write_root(...): $AGENTDESCENT_HOME/agentdescent.<name>.spec.json when the operator's allowlist contains that home (it does when the variable is unset), otherwise the first allowed root. The explicit-out check is untouched (fix(mcp): algorithm_spec writes its spec without the server's write allowlist #1018). A refused explicit out now appends the allowed roots and an out under one of them, so the error is actionable rather than only naming the variable. The tool description says where the default lands.
  • agentdescent/surface_common.py — surface_home() (one normalisation shared with the default roots) and default_write_root(allow), which raises an explicit "no write directory is allowed" when the allowlist is empty instead of inventing a root. ensure_write_path names the allowed roots in its message.
  • agentdescent/integrations/SKILL.md and the two host trees rendered from it (integrations/claude-code/skills/agentdescent/SKILL.md, integrations/dsh-agentdescent/lib/index.js) — the sentence now says $AGENTDESCENT_HOME / an allowed root, never beside the target.
  • tests/test_mcp_algorithm_spec_default_out.py (new) — the default lands under the home root, under the first explicit root, never beside the target; an explicit outside out is still refused and names a usable one; an empty allowlist says so; description and skill stop teaching the beside-the-target default.
  • tests/test_mcp_algorithm_spec_allowlist.py — the row that pinned "default out outside an explicit allowlist is refused" becomes "the default goes to the allowed root": under this fix the default never lands outside, and that row was pinning the bug. The explicit-out refusal row is unchanged.
  • changelog.d/1108-algorithm-spec-default-out.md — one Fixed fragment.

Red at base 5048349a

Clean worktree at 5048349aaceb1ad4c93318581f9a2b49481a5a99, only the new test file copied in (git status: one untracked file):

FAILED tests/test_mcp_algorithm_spec_default_out.py::test_an_omitted_out_lands_under_the_home_root
E   AssertionError: {'ok': False, 'error': "out '…/user-project/agentdescent.rrsi.spec.json'
E   is outside the operator's write allowlist (AGENTDESCENT_SURFACE_WRITE_DIRS)"}
FAILED …::test_an_omitted_out_honours_an_explicit_allowlist
FAILED …::test_an_explicit_out_outside_the_allowlist_names_where_it_may_write
FAILED …::test_an_empty_allowlist_says_so_instead_of_naming_a_target_directory
FAILED …::test_the_description_no_longer_documents_a_beside_the_target_default
FAILED …::test_the_shared_skill_writes_the_default_spec_under_the_home

6 failed in 0.88s

Verification at the tip

Tip SHA: f1677e9

  • pytest -q tests/test_mcp_algorithm_spec_default_out.py → 6 passed
  • the issue's acceptance pair, pytest -q tests/test_mcp_algorithm_spec_allowlist.py tests/test_mcp_algorithm_spec.py → 11 passed
  • the files asserting the allowlist message (test_cli_governed, test_cli_tenant, test_cli_meta_campaign, test_cli_surface_p1, test_persistent_tenancy, test_cli_experience_cycle) → 40 passed
  • pytest -q tests/test_integrations.py → 137 passed, 2 skipped, 8 failed; the same 8 fail in a pristine worktree at 5048349a (they run the venv's agentdescent launcher while the checkout shadows it: RuntimeError: shadowed by the host cwd), so they are this box, not this diff
  • the filed scenario re-run at the tip: omitted out → ok: True, spec_path: $AGENTDESCENT_HOME/agentdescent.gepa.spec.json, nothing beside the target; explicit /tmp/outside/spec.json → ok: False, error names both allowed roots and pass \out` under one of those roots, e.g. '…/server/agentdescent.gepa.spec.json'`
  • python -m tools.gen_api_docs --check → docs/api.md is up to date
  • python -m tools.changelog_fragments check → 50 changelog fragment(s) OK

Not run:

  • mkdocs build --strict — mkdocs is not installed in this clone's venv; CI's build leg is the line
  • a real host install (agentdescent install …) end to end — the rendered trees are asserted equal to the package by test_integrations, which ran
  • tests/test_docs_links.py — markdown is not installed here (environment, not this diff)
  • the 3.9–3.13 matrix — this PR's own test (3.9)–test (3.13) runs are that confirmation

Size: 8 files, +211/−17 against base 5048349a; T2 by .github/agent/risk-rules.json (agentdescent/mcp.py and surface_common.py are package code; docs, tests and changelog.d/ are lower).

Same-repo head: maintainer_can_modify is requested; this branch is in the same repository, and GitHub only tracks that flag for fork heads, so it reports null here — recorded rather than worked around.

Written-by: AgentDescent Dev-3
Bot: AgentDescent Dev-3

)

An omitted `out` was documented — tool description and the shared SKILL.md — as
writing the starter spec beside the target. The default write allowlist is the
server's cwd plus $AGENTDESCENT_HOME, so for the user's file outside both roots
the shortest documented path was refused: measured at 5048349 with both
variables unset, `algorithm_spec(gepa, …)` returned `ok=false`, "out
'…/user-project/agentdescent.gepa.spec.json' is outside the operator's write
allowlist".

The default now goes under $AGENTDESCENT_HOME when the operator allows it (else
the first allowed root), an empty allowlist says there is no default instead of
naming a directory, and a refused explicit `out` names the allowed roots plus an
`out` that works. The explicit-`out` check itself is unchanged (#1018). The
description and SKILL.md say where the default lands; the rendered host trees
are regenerated from the package.
@HugoXK HugoXK added bug Something isn't working area:plugins Host plugins and installers: Claude Code, Codex, DSH, OpenCode, MCP server agent-pr Pull request opened by an agent labels Nov 16, 2026
@HugoXK

HugoXK commented Nov 16, 2026

Copy link
Copy Markdown
Collaborator Author

Reviewed tip: f1677e970a709834af0ed5f9d32cd32b2e4176c4 — ready to judge at this sha.

  • build, test (3.9)–test (3.13), otel-wire all success, deploy skipped, both report-only checks success. mergeable_state: clean.
  • Flake on the record, stated plainly: the first run of test (3.11) failed on this same sha at tests/test_sandbox.py::test_a_recycled_pid_does_not_keep_a_dead_run_alive_forever with AssertionError: a late renewal deserves one grace (assert 1 == 0). The rerun on the identical sha came back success. I am recording that as an unresolved flake, not as a cleared defect and not as a pass for the test: no code was changed for it, and if it reappears the same assertion gets reproduced locally at this tip and root-caused rather than re-run away.
  • Scope, red evidence at base 5048349a, the one test-contract change and the not-run legs are all in the body above; nothing has moved since.

A review on this sha is what this comment asks for; it is not a verdict and it is not a merge.

@HugoXK HugoXK left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review tip: f1677e9

Verdict: PASS — no must-fix items.

This is an internal AgentDescent Security review. It is not the PASS that .github/agent/review-policy.json counts — that file lists only login Birfy — and it is not the merge gate or an approval of the merge; the tip still needs the reviewer's PASS and the owner's click.

Read at the exact head f1677e9 in a fresh clone (single commit, base 5048349a, 8 files +211/−17).

  1. The renamed row retires a bug-pinning assertion; it does not delete a reachable refusal. tests/test_mcp_algorithm_spec_allowlist.py:42-55 now asserts the omitted-out call succeeds with spec_path == allowed/agentdescent.rrsi.spec.json and nothing written beside the target. The old assertion could only hold because the default path itself was outside the allowlist — the bug being fixed. The security property it observed (an implicit write stays inside the operator's allowlist) is now asserted positively, and a default outside the allowlist is unreachable by construction: mcp.py:558-565 chooses the default from allow (surface_common.py:226-246) and mcp.py:574-576 still routes the result through _check_write. The explicit-out rows are untouched (:27-40, :58-70).
  2. Only the default path is widened; the explicit-out refusal is behaviourally identical to #1018. mcp.py:567 still resolves the caller's path and mcp.py:574-576 still checks it; the refusal condition in surface_common.py:353-361 is unchanged from base and only the message gained the roots and the example (surface_common.py:362-364, mcp.py:579-585). Probed at head: out outside the allowlist → ok False, no file; empty allowlist → ok False with "no write directory is allowed"; out inside a root still plans. No caller-supplied path bypasses the check.
  3. The test (3.11) flake does not intersect this diff. It is tests/test_sandbox.py::test_a_recycled_pid_does_not_keep_a_dead_run_alive_forever, tests/test_sandbox.py:369: the lease is set to time.time() - 0.3 with ttl=0.2, so the one-grace window closes 0.1 s after the assertion begins; a slow CI step flips reap() 0 → 1. Same lease data, no delay → reap() == 0; +0.15 s → reap() == 1 (deterministic probe at this tip), and 15 local repeats pass. tests/test_sandbox.py imports evolution/filetree/runners/policies/metrics/sandbox, and agentdescent/sandbox.py imports neither mcp nor surface_common; the diff touches neither file. Unresolved flake, not this PR's failure path, not a must-fix here — it deserves its own card.

Reproduction and gates: base 5048349a with only the new test file → 6 failed, matching the body; head → 17 passed for the new file plus the allowlist and algorithm_spec files; the six allowlist-message CLI files → 40 passed; the skill-render integration rows pass, the package skill body is embedded exactly in the Claude Code tree and in the DSH plugin, and gen_api_docs --check is up to date with 50 changelog fragments OK; the checks at this head are 9 success with deploy skipped.

Non-blocking observations, not must-fix:

  • The message change is wider than this tool: ensure_write_path (surface_common.py:362-364) is shared by every _check_write call site, so every MCP write refusal now prints the operator's allowed roots. Low risk and asked for by #1108, but if scope discipline matters the hint could stay inside algorithm_spec.
  • A directory target can now contain the default spec. When the chosen root is the target directory or inside it, mcp.py:562-565 writes the spec inside the target: probed with kind="skill_dir" and archive_selection, allowlist (target,) → <target>/agentdescent.archive_selection.spec.json written; target == $AGENTDESCENT_HOME with the variable unset → same; allowlist (target/sub,) → written there. Base refused all three, and the dropped comment mcp.py:541-543 at base said never inside a directory target. The file stays inside the allowlist, so this is a lost property in a corner, not a bypass; the tool description at mcp.py:146 should either keep that promise (pick a root outside the target, or refuse when none exists) or drop it. No test covers a directory target.
  • mcp.py:580-585 builds the example from surface_write_dirs[0] and the raw name argument when out is supplied, not the registered name. It is an error string, never a write path, so harmless, but the example can name an unregistered spelling.

@HugoXK HugoXK added the awaiting-approval Green T2/T3 PR: waits for a PASS at its tip and Danyang's merge click label Nov 16, 2026
@github-actions github-actions Bot added the risk:T3 Risk tier T3 (core loop, release, process; needs Danyang's click), set by the controller label Nov 16, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

agent-pr Pull request opened by an agent area:plugins Host plugins and installers: Claude Code, Codex, DSH, OpenCode, MCP server awaiting-approval Green T2/T3 PR: waits for a PASS at its tip and Danyang's merge click bug Something isn't working risk:T3 Risk tier T3 (core loop, release, process; needs Danyang's click), set by the controller

Projects

None yet

Development

Successfully merging this pull request may close these issues.

plugin/MCP: algorithm_spec's default out (beside the target) is refused by the default write allowlist

1 participant