relay-shell: Instructions file for Codex

Agent development guidance: relay-shell

Repository-specific workflow

MCP shell/SSH operator infrastructure. Read docs/runbook.md (especially its audit/review/validation sections), relevant docs/adr/, and SECURITY.md.

• Preserve intentional scoped and privileged/root deployment modes, shell/SSH, sessions, transfers and forwarding. The executor has no internal sandbox. Do not silently remove capabilities or introduce a sandbox; changes to posture need explicit scope and design review.
• Every execution path passes through the central audited runner. Preserve deny-first precedence across open/guarded/readonly modes, tier classification, confirmation-token binding/expiry/single-use semantics, redaction, timeout/output/session caps, and SSH host verification.
• The default posture is open: with default settings no command is refused for what it does (ADR 0013, pinned by tests/test_notices.py). Do not add a default-on refusal, deny pattern or confirmation step; add opt-in controls instead. Risky admitted calls are answered with a [NOTICE ...] line and server_info.warnings lists permissive settings; both are information, are not written into the audit record, and must never be described as a boundary. A new permissive setting needs a matching entry in notices.config_warnings.
• Classification regexes are heuristics, not a complete shell-language security boundary. Never claim that a permitted shell command or privileged client is contained by the classifier.
• Audit arguments must be redacted; output bodies must not be logged, only length/hash. Preserve chain limitations, rotation continuity, off-host integrity requirements, and secret-prompt handling. Redaction is heuristic and must be tested with synthetic secrets.
• Tool errors use existing bounded structured error helpers, not raw tracebacks or uncaught transport failures. Preserve cancellation and cleanup, close only owned sessions, and reconcile timeouts before retrying mutations.
• Technical map: src/relay_shell/server.py registers tools; config, policy, broker, audit, redaction, patterns, sessions and sshpool define the principal boundaries. tests/test_server.py::_EXPECTED is the tool-registration contract.
• Setup: python -m pip install -e ".[dev]". Run ruff check ., ruff format --check ., mypy, pytest -q. For classifier/redactor changes also run pytest -m fuzz -v; update PATTERNS_VERSION when required by the existing contract. Preserve CodeQL, dependency review, dependency audit and secret-scanning gates.
• Use async I/O in tool paths; do not add requests/urllib3 blocking calls. Live shell/SSH smokes require explicit targets and bounded effects. Editing this repo does not authorize restarting or deploying its running service.