Runtime instructions for managed sessions

devctrl generates DEVCTRL.AGENTS.MD in the repository and a copy in Exchange. It describes the actual environment around a session. Repository-owned devctrl.md, AGENTS.md and CLAUDE.md remain separate and are not overwritten.

The generated document begins with the controlled Docker environment, observed resource limits, network boundary status and detected standard executables. Configured values are explicitly marked as unobserved until the container exists. CPU/RAM/process limits apply to all sessions and subprocesses sharing that container, not independently to each session. The guide does not enumerate the full public-domain allowlist; inspect_current_project supplies current configuration and grants.

Each enabled context tool appears with its executable, purpose, usage and limitations. Template selection is not proof of installation: agents check get_context_tools for observed versions and operation results. The guide also covers runtime Features, session folders, host volumes, Exchange, credential-file paths, service routes and owned-resource cleanup. Credential values are never included.

Startup delivery

Before a new managed Claude or Codex process starts, devctrl creates a session-private DEVCTL.RULES.md containing the approved configuration snapshot, a requirement to read the live runtime guide before work, and the guide's current contents.

Instructions are model context, not a synthetic task typed into the composer. They instruct the agent to read the live file, but they do not prove that the agent has obeyed every instruction. Native repository instruction discovery remains independent.

After a live tool install/update, including context tools refreshed through a general toolchain update, or a permission change, devctrl regenerates the relevant document and uses safe, generation-fenced native delivery to ask the running session to reread it. It does not restart the provider process or silently change that process's environment. For shared-container sessions, tool notifications refresh the Context tools section in each session’s repository/worktree without copying another repository’s grants. Generated guide writes do not follow supplied symlinks or modify linked files outside the generated guide.

A startup copy can be stale; the live guide and actual MCP grants take precedence for runtime availability.

Permission workflow

Discover catalog resources with list_available_services and match_service_capabilities. An existing Service is requested with grant_service without approvalId; after approval, retry identical arguments with the returned ID. Use request_permission for scoped policy needs such as a direct HTTPS destination or database operation. That request is applied automatically after operator approval; poll get_permission_status and reread the delivered live rules.

The port returned by list_available_services is the workspace-facing port (consumerPort when configured). Use it with the granted alias; a gateway's host listener can use a different port. An active transport grant does not itself add the Project to an upstream gateway's project or method allowlist.

Approval does not itself provision credentials, change an upstream role or repair a gateway. Agents must distinguish policy permission from working transport and upstream authorization. A chat response alone does not apply a managed permission.

Use list_access_attempts and get_access_summary for bounded access-history diagnostics when available. The tools derive repository/session scope from the authenticated session. HTTP/CONNECT observations may be shared-workspace traffic; MCP calls carry exact session scope. A policy-allowed upstream error does not need a new policy grant, and an empty page is not proof of zero network activity. Coverage and privacy remain explicit.

Example opening

Values below illustrate a container; they are not defaults or measurements of a particular server.

# DEVCTRL

## Controlled execution environment

- You run inside a devctrl-managed Docker development container.
- Observed Docker CPU limit: 2 CPU cores. RAM limit: 4 GiB.
- Resources are shared by all sessions and subprocesses in this container.
- Public-network policy: restricted. Container enforcement: restricted.
- Inspect current configuration and grants with inspect_current_project.
- Do not bypass network restrictions or change host resource limits yourself.

## Available devcontainer tools

- Detected executables: bash, git, gh, rg, curl, jq, node, npm, pnpm.
- Availability is not authorization or proof of valid credentials.
- Managed skills: $DEVCTL_SKILLS_PATH; read the relevant SKILL.md before use.

## Context tools

- RTK: compact command output; rtk gain reports measured compression.
- sgrep: local semantic search with prepared offline public models.
- ast-grep: structural code search; preview matches before rewriting.
- Repomix: pack selected files; keep secret checks enabled and inspect tokens.
- Graphify: query a persistent code graph; follow the configured manual,
  after-commit or before-push refresh policy. Automatic refresh is code-only.
- Verify installed versions with get_context_tools.
- Request updates with configure_context_tools through devctrl approvals.

The full generated document contains concrete commands for the enabled tools, scoped permission-request instructions and the Project's actual routes, folders and paths. Disabled tools are not advertised as enabled.