feat: workspace injection contract — entrypoint section 5.5 + WorkspaceFiles helper + docs

[NeuralEmpowerment]

Summary

Implements the workspace injection contract in agentic-primitives — a small inbound seam every orchestrator (agentic-domain-runner, Syntropic137, future Codex/Gemini wrappers) can target to hand a workspace its context, plugins, and subagents before the agent starts.

What changed

Entrypoint

• providers/workspaces/claude-cli/scripts/entrypoint.sh — new section 5.5 (Workspace Context Composition) reads /etc/agentic/workspace/ bind-mount + three AGENTIC_WORKSPACE_* env vars, then copies into /workspace/CLAUDE.md, /workspace/.agentic-plugins/<name>/, ~/.claude/agents/<name>.md. Path constants INJECT_* declared once at the top.

Python helper

• lib/python/agentic_isolation/agentic_isolation/workspace_files.py — WorkspaceFiles class with bind_mount() + inject() primitives. Library import only (no daemon). Exported from package root.

Docs

• docs/workspace.md — canonical workspace reference (inject/isolate/observe responsibility framing)
• docs/adrs/035-workspace-injection-contract.md — ADR (4 alternatives considered, positive/negative/neutral consequences)
• docs/superpowers/specs/2026-05-12-workspace-injection-contract-design.md — design spec
• docs/superpowers/plans/2026-05-12-workspace-injection-contract.md — implementation plan
• README.md — focused Workspace section signposting docs/workspace.md
• CLAUDE.md — breadcrumb at the top for fresh agent sessions
• docs/issues/{001,002} — captured wrinkles (pre-existing LSP test bug, plan's build cmd mismatch)

Tests

• 7 integration tests in tests/integration/test_entrypoint_workspace_injection.py against the built image (context copy, plugin copy + flag append, loose subagent copy, env filter, no-mount skip, invalid-plugin skip, plugin-flags append-not-replace)
• 3 unit tests for WorkspaceFiles + 1 export test = 174 Python tests passing (was 170)

Coordinated change in agentic-domain-runner

Phase A — env-var + path rename — landed on branch feat/workspace-env-rename. Should merge BEFORE this PR's image gets adopted by the runner (Phase E in the plan).

What's deliberately NOT here

• No AGENTIC_WORKSPACE_ALLOWED_TOOLS env var — tool restrictions live inside subagent frontmatter / plugin permissions (ADR-035 alternative feat(examples): 002-observability-dashboard #3)
• No identity vars (task id, runner URL, etc.) — orchestrator-specific, not part of the workspace contract
• No preamble templating in the entrypoint — orchestrator pre-composes any preamble into the bind-mounted CLAUDE.md before mounting

Test plan

• pytest tests/integration/test_entrypoint_workspace_injection.py -v → 7 passing
• cd lib/python/agentic_isolation && uv run pytest -v → 174 passing
• After merge: build the workspace image (just build-workspace-claude-cli), tag a release (next version after 2.1.126), update runner's examples/domains/homelab/domain.toml image tag, run the previously-blocked live_claude_sees_domain_claude_md smoke

Spec / ADR / Plan

• Spec: docs/superpowers/specs/2026-05-12-workspace-injection-contract-design.md
• ADR: docs/adrs/035-workspace-injection-contract.md
• Plan: docs/superpowers/plans/2026-05-12-workspace-injection-contract.md
• Canonical doc: docs/workspace.md

[Copilot]

Pull request overview

This PR introduces a cross-orchestrator “workspace injection contract” for the agentic-workspace-claude-cli image: orchestrators can provide context, plugins, and subagents via a fixed bind-mount location plus a small set of env vars, and the workspace entrypoint composes these into agent-visible locations before executing the command.

Changes:

• Adds entrypoint section 5.5 to copy injected context/plugins/subagents from /etc/agentic/workspace/ into /workspace/ and ~/.claude/agents/, while appending plugin flags.
• Adds a Python WorkspaceFiles helper (bind-mount + archive injection primitives) and accompanying tests/exports.
• Adds canonical documentation (workspace doc + ADR + README section) and integration tests validating the contract.

Reviewed changes

Copilot reviewed 18 out of 19 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
providers/workspaces/claude-cli/scripts/entrypoint.sh	Implements the entrypoint-side workspace injection/composition behavior (section 5.5).
tests/integration/test_entrypoint_workspace_injection.py	Integration tests covering context/plugin/subagent copy behavior and env-var filtering.
lib/python/agentic_isolation/agentic_isolation/workspace_files.py	Adds WorkspaceFiles helper for orchestrators to stage files via bind-mount or tar injection.
lib/python/agentic_isolation/agentic_isolation/__init__.py	Exports WorkspaceFiles from the package root.
lib/python/agentic_isolation/tests/test_workspace_files.py	Unit tests for WorkspaceFiles.
lib/python/agentic_isolation/tests/test_package_exports.py	Verifies WorkspaceFiles is exported.
docs/workspace.md	Canonical workspace contract reference and usage examples.
docs/adrs/035-workspace-injection-contract.md	ADR documenting the decisions behind the injection contract.
README.md	Adds a top-level “Workspace” section pointing to canonical docs/ADR/source.
docs/superpowers/specs/2026-05-12-workspace-injection-contract-design.md	Design spec describing the contract and rationale in detail.
docs/superpowers/plans/2026-05-12-workspace-injection-contract.md	Implementation plan for rolling out the contract across repos.
docs/issues/README.md	Introduces a lightweight “issues” note format for follow-ups.
docs/issues/001-lsp-entrypoint-test-stdout-pollution.md	Captures a pre-existing integration-test issue for later resolution.
docs/issues/002-build-command-mismatch-in-plan.md	Captures an incorrect build command in the plan for later correction.
docs/handoff-workspace-files-primitive.md	Adds a handoff doc describing earlier runner-driven staging expectations.
CLAUDE.md	Adds a breadcrumb pointing to the new workspace documentation and ADR.
cspell.json	Adds spellchecker configuration/wordlist.
.gitignore	Ignores additional local Claude config artifacts.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 18 out of 19 changed files in this pull request and generated 5 comments.

[Copilot]

Pull request overview

Copilot reviewed 16 out of 17 changed files in this pull request and generated 6 comments.

Comments suppressed due to low confidence (3)

providers/workspaces/claude-cli/scripts/entrypoint.sh:268

• cp -a preserves ownership; since the entrypoint runs as the non-root agent user, copying from a bind-mount where files are owned by a different uid/gid can fail with EPERM and abort the entrypoint (because set -e). Use a copy mode that does not attempt to preserve ownership (e.g., avoid -a or use --no-preserve=ownership) so workspace injection can't brick container startup.

            # rm first → idempotent across re-runs when /workspace is a
            # persistent named volume. Without the rm, `cp -a src dst`
            # against an existing dst/ creates a nested dst/<basename>/
            # tree instead of overwriting.
            rm -rf "${INJECT_TARGET_PLUGINS}/${plugin}"
            cp -a "${src}" "${INJECT_TARGET_PLUGINS}/${plugin}"
            AGENTIC_PLUGIN_FLAGS="${AGENTIC_PLUGIN_FLAGS} --plugin-dir ${INJECT_TARGET_PLUGINS}/${plugin}"

providers/workspaces/claude-cli/scripts/entrypoint.sh:249

• AGENTIC_WORKSPACE_CONTEXT is interpolated directly into ctx_src without any traversal guard. Values like ../../etc/passwd would escape /etc/agentic/workspace and copy an arbitrary in-container file into /workspace/CLAUDE.md. Consider rejecting values containing '/' or '..' (or resolving and asserting the real path stays under the mount) to keep the contract confined to the bind-mount.

if [ -d "${INJECT_MOUNT}" ]; then
    ctx_src="${INJECT_MOUNT}/${AGENTIC_WORKSPACE_CONTEXT:-${INJECT_DEFAULT_CONTEXT}}"
    if [ -f "${ctx_src}" ]; then
        cp "${ctx_src}" "${INJECT_TARGET_CONTEXT}"

CHANGELOG.md:26

• The changelog claims there are "5 unit tests" for WorkspaceFiles, but lib/python/agentic_isolation/tests/test_workspace_files.py currently defines 6 tests (plus the separate export test in test_package_exports.py). Update the counts to match the actual test suite so the release notes stay accurate.

- **7 integration tests** in `tests/integration/test_entrypoint_workspace_injection.py` covering CLAUDE.md copy, plugin copy + flag append, loose subagent copy, env filter, no-mount skip, invalid-plugin skip, plugin-flags append-not-replace.
- **5 unit tests** for `WorkspaceFiles` (descriptor shape, relative-path resolution, `put_archive` call shape, ValueError on non-absolute / empty-basename `container_path`).
- **docs/issues/** convention introduced — numbered enhancement / follow-up notes (003 cosmetic items captured).