Split 4 of 5 from #844 (see the triage comment there). Parent epic: #847, Phase 3.
Problem
docs/configuration.md:416-425 gives a precedence table for hooks and worker processes and says nothing about what an agent child sees, while the custom-runtime boundary is documented separately at :490-527. An operator therefore reasonably expects a project .env entry to reach the agent — which is exactly how the DOCKER_CONFIG mistake on #825 became plausible.
SYMPHONY_WORKFLOW_HOOK_ENV_ALLOWLIST is also neither validated nor documented, and #844 names it as the precedent that must be fixed before any future declarative channel is considered.
Scope
- Document the agent-child boundary in
docs/configuration.md, next to the existing precedence tables: what the child inherits, what is constructed for it, and what is always stripped.
- State plainly that a project
.env entry does not reach the agent child, and why.
- Validate
SYMPHONY_WORKFLOW_HOOK_ENV_ALLOWLIST (reject unparseable or unknown entries rather than silently ignoring them) and document it.
Out of scope
Acceptance criteria
docs/configuration.md documents the agent-child boundary and the hook allowlist variable.SYMPHONY_WORKFLOW_HOOK_ENV_ALLOWLIST is validated with test coverage for the rejection path.
Sequencing
After splits 1-3, so the documentation describes the end state rather than the transitional one. Needs a changeset only if the allowlist validation changes observable behaviour.
Split 4 of 5 from #844 (see the triage comment there). Parent epic: #847, Phase 3.
Problem
docs/configuration.md:416-425gives a precedence table for hooks and worker processes and says nothing about what an agent child sees, while the custom-runtime boundary is documented separately at:490-527. An operator therefore reasonably expects a project.enventry to reach the agent — which is exactly how theDOCKER_CONFIGmistake on #825 became plausible.SYMPHONY_WORKFLOW_HOOK_ENV_ALLOWLISTis also neither validated nor documented, and #844 names it as the precedent that must be fixed before any future declarative channel is considered.Scope
docs/configuration.md, next to the existing precedence tables: what the child inherits, what is constructed for it, and what is always stripped..enventry does not reach the agent child, and why.SYMPHONY_WORKFLOW_HOOK_ENV_ALLOWLIST(reject unparseable or unknown entries rather than silently ignoring them) and document it.Out of scope
Acceptance criteria
docs/configuration.mddocuments the agent-child boundary and the hook allowlist variable.SYMPHONY_WORKFLOW_HOOK_ENV_ALLOWLISTis validated with test coverage for the rejection path.Sequencing
After splits 1-3, so the documentation describes the end state rather than the transitional one. Needs a changeset only if the allowlist validation changes observable behaviour.