FACTUAL ACTIVITY RECORD · An activity record based on work that took place
Moving GitHub connections outside the sandbox from the first attempt
Unifying connection paths, authentication checks, and environment blockers without relying on in-sandbox DNS
Purpose
GitHub connections repeatedly failed because DNS or egress could be unavailable inside the sandbox even for allowed domains, forcing a switch to external execution only after failure. The CEO asked for connected operations to start outside the sandbox so the same instruction would no longer be needed each time and the workflow would be predictable.
The change also needed to separate ordinary workspace editing from external-state operations, avoid reporting success when no connection was available, and preserve existing boundaries for authentication, secrets, parent and child workspaces, and approval.
Implementation
.agents/skills/github-external-operations/SKILL.md was added to require reads and writes through GitHub remotes, APIs, gh, and app connectors to begin in a sandbox-external context or through a connector that does not depend on in-sandbox DNS. Domain allowlists were defined as compatibility settings rather than guarantees of availability or permission, so connection probes and retry-after-failure inside the sandbox were prohibited.
- The flow first checks the workspace root, origin, parent-child boundary, and local state with read-only operations, then uses a connector as the first choice for GitHub state.
- For routine external operations, it switches to a sandbox-external CLI only when the connector is unavailable, lacks permission, cannot identify the workspace or work item, or does not provide the required operation.
- Before remote Git or
gh, the authentication helper belonging to the target workspace runs in the same external context; a child workspace cannot borrow its parent's helper. - After an external-state write, the state is retrieved again and completion is withheld until the target and result match.
If neither the connector nor a sandbox-external context is available, the workflow returns an environment blocker. The blocker includes the target workspace and intended operation, unavailable paths and reasons, unchanged or unverified external state, the portion completed locally, gates that cannot be met, the next action, and the return destination. Copy-ready text may be returned as an uncreated draft, but cannot substitute for evidence that external state was created or checked, or for a required gate.
The invariants permit reauthentication only after an authentication failure, prohibit exposing secrets or credentials, preserve workspace-specific helper boundaries, and prevent external execution from weakening approval for high-risk operations. External execution specifies where an operation runs; it does not grant additional authority.
The first implementation check found that the shared Skill allowed CLI fallback only when the connector lacked an operation, while some role definitions and setup guidance also included connector unavailability, insufficient permission, and inability to identify the target. The inconsistency was corrected so all references share the same four conditions for routine operations while preserving no-fallback for high-risk state changes, external execution, and authentication preflight.
The new Skill became a required reference from the existing delivery and change-checking Skills. The same boundary was applied to nine custom roles, execution configuration, command rules, the operating chart, setup guidance, and handoff examples. No role was added, and the maximum concurrent-thread and depth settings were unchanged.
Verification ran the validator for three repository-local Skills and parsed the Skill YAML plus the configuration and nine role TOML files. Searches then checked that all nine roles routed to the new Skill, that fallback and environment-blocker wording agreed across files, and that representative command-policy cases, placeholders, and diff whitespace passed inspection.
- GitHub app / plugin connectorはsandbox内DNSに依存しないsandbox-external pathとして第一候補にする
- CLIが必要な時はcommandを最初からsandbox-external execution contextで実行する。sandbox内で接続可否をprobeせず、DNS / egress failure後の再試行経路にしない
- `.codex/config.toml`のGitHub domain allowlistは他用途との互換設定であり、sandbox内GitHub操作の可用性、許可、fallbackを保証しないRendering diagram…
What was confirmed
Verification results
The change touched 23 files, adding 164 lines and removing 43. It added a 56-line GitHub external-operations Skill and a four-line Skill interface definition.
Validation passed for three Skills, one YAML file, ten TOML files including the configuration, all nine role routings, representative command-policy cases, cross-file searches, and diff checks.
CLI fallback for routine operations was aligned to four conditions—connector unavailability, insufficient permission, inability to identify the target, and an unavailable operation—while no-fallback for high-risk state changes and authentication preflight remained intact.
The boundaries among ordinary workspace editing, external state, secrets, parent and child workspaces, and approval gates were separated, with an environment blocker reached when neither connection path was available.
At the cutoff, the new Skill and related role and operating settings had been applied to the organization's current source. DNS infrastructure, sandbox networking, GitHub permissions, and authentication methods were not changed, and successful connection in every environment was not verified.
Basis for completion
The work was complete when the Skill that moves GitHub connections outside the sandbox from the first attempt, its four fallback conditions, and its authentication and environment-blocker boundaries agreed across roles, configuration, and operating guidance, passed syntax, routing, and policy checks, and were applied to the current source.