fix(sandbox): preserve workdir for shell command lists

.agents/references/local-mcp-server-lifecycle.md

@@ -7,6 +7,8 @@ Use this reference for changes to Python-managed MCP servers, `MCPServerManager`
 - A local `MCPServer` owns its transport, `ClientSession`, and `AsyncExitStack` from `connect()` through `cleanup()`. Partial connection failure still requires closing every context already entered.
 - Some MCP transports use AnyIO cancel scopes that require connection and cleanup in the same task. Do not wrap either operation in a helper that silently creates another task.
 - `MCPServerManager` preserves task affinity in sequential mode and uses one long-lived worker task per server in parallel mode. Timeouts must run inside that owning task; on Python versions without `asyncio.timeout()`, cancel the current worker task and translate only timer-originated cancellation to `TimeoutError`.
+- `MCPServerManager` lifecycle timeouts are validated during construction and assignment. They accept positive finite seconds or `None` to disable the timeout. Reject zero rather than relying on `asyncio.timeout(0)`, whose immediate deadline can depend on whether the lifecycle coroutine yields control. Parallel workers receive the current timeout with each command instead of retaining a stale snapshot.
+- `client_session_timeout_seconds` uses positive finite values representable by `datetime.timedelta` and at least one microsecond for MCP read timeouts. Both `None` and zero disable that timeout; reject other values during server construction instead of passing an immediate or invalid deadline to `ClientSession`.
 - Cleanup runs servers in reverse order and continues across ordinary cleanup failures. Cancellation suppression is an explicit manager policy; do not accidentally convert unrelated `BaseException` failures into recoverable connection errors.
 - Server cleanup must clear session and transport-visible state even when exit-stack cleanup raises, so the same server object can reconnect without exposing stale session handles or workers.
 

.agents/references/model-provider-boundaries.md

@@ -31,10 +31,18 @@ Do not infer that a feature available in one adapter is supported by every `Mode
 
 Validate capabilities at the adapter boundary where the resolved model and complete request are known. Avoid public flags that appear accepted by the SDK but are silently dropped before the provider request.
 
+## Provider Validation and Error Ownership
+
+Do not duplicate provider-side request validation in the SDK merely to fail earlier. When the provider already rejects an invalid value with an actionable error, preserve that single source of truth instead of copying provider grammar, length limits, enum membership, or other request constraints into SDK runtime code. Duplicated validation can drift as provider contracts evolve, can reject values accepted by another provider, and can turn a provider-neutral SDK type into an accidental provider-specific contract.
+
+Add SDK-side validation only when it enforces an SDK-owned invariant or prevents a concrete risk that provider validation cannot address. Examples include ambiguous local routing, collisions before request serialization, invalid persisted state, unsafe local side effects, or a provider error that cannot identify the offending SDK input. A generic preference for earlier failure or a different error message is not sufficient.
+
+When local validation is justified and the constraint is provider-specific, keep it at the owning adapter boundary and derive it from an authoritative provider contract. Do not apply it to shared `Model` interfaces, provider-neutral tool types, or third-party adapters. Tests should distinguish the SDK-owned invariant from values that are intentionally left for the provider to validate.
+
 ## Provider Data and Terminal Semantics
 
 - Preserve provider-supplied string IDs, request IDs, usage, and opaque provider data when the public SDK contract exposes them.
-- Normalize provider objects and mapping payloads without relying on truthiness for valid empty or zero values.
+- Normalize provider objects and mapping payloads without relying on truthiness for valid empty or zero values. When a field intentionally treats zero like `None`, make that field-specific contract explicit in the normalization, documentation, and tests rather than applying a generic optional-number rule.
 - A transport stream ending is not automatically a successful model response. Responses `failed` and `incomplete` terminals, explicit error events, and a missing terminal payload must produce the documented failure behavior in both HTTP and websocket paths.
 - Keep semantically equivalent HTTP, websocket, streaming, and non-streaming paths aligned on final `ModelResponse`, errors, request IDs, and usage.
 
@@ -55,11 +63,12 @@ Validate capabilities at the adapter boundary where the resolved model and compl
 ## Review Checklist
 
 1. Identify which adapter owns the feature and how unsupported adapters behave.
-2. Verify model and implicit-settings resolution when run config overrides the agent.
-3. Compare HTTP/websocket and streaming/non-streaming terminal behavior when applicable.
-4. Preserve request IDs, usage, provider data, and error semantics through normalization.
-5. Prove retries are safe for the request's state ownership and side effects.
-6. Test transport reuse, cross-loop access, closed-loop pruning, and provider shutdown when persistent connections are involved.
+2. Before adding validation, determine whether it protects an SDK-owned invariant or only duplicates an actionable provider error.
+3. Verify model and implicit-settings resolution when run config overrides the agent.
+4. Compare HTTP/websocket and streaming/non-streaming terminal behavior when applicable.
+5. Preserve request IDs, usage, provider data, and error semantics through normalization.
+6. Prove retries are safe for the request's state ownership and side effects.
+7. Test transport reuse, cross-loop access, closed-loop pruning, and provider shutdown when persistent connections are involved.
 
 ## Sources
 

.agents/references/sandbox-runtime-boundary.md

@@ -31,6 +31,9 @@ Resolve the session source in this order: injected live session, resumable sandb
 ## Filesystem Trust Boundary
 
 - Manifest entry destinations are workspace-relative and must not escape the workspace. The workspace root itself must be absolute where the backend requires an absolute runtime root.
+- Treat every path visible inside a sandbox as a POSIX path, regardless of the host operating system. Do not use `str(Path(...))` or `str(PurePath(...))` to produce, validate, compare, or serialize a sandbox path because those calls emit backslashes on Windows. Convert typed path objects with `PurePath.as_posix()` or the canonical helpers in `workspace_paths.py`.
+- Preserve the trust distinction between typed path objects and raw string input. A native Windows `Path` or `PurePath` may be converted to its POSIX sandbox representation, while a raw string containing backslashes may still need to be rejected when the public contract requires explicit POSIX syntax. Do not make an input-validation failure disappear by silently canonicalizing every string.
+- Keep host filesystem conversion at an explicit host/backend boundary. Code that resolves manifests, mount targets, archive exclusions, snapshots, grants, or provider paths must not let the host implementation of `Path` change the identity of a sandbox path.
 - `LocalFile` and `LocalDir` sources are host-side inputs. Resolve them against a trusted base directory, require explicit application-controlled `extra_path_grants` outside that base, and reject untrusted manifests that try to authorize their own host access.
 - Validate local sources at use time, not only when parsing the manifest. Defend against symlinked sources, parent-directory swaps, platform path aliases, and archive members that change meaning between validation and extraction.
 - Archive extraction must reject traversal, unsafe links, and unsupported member types before writing, and enforce entry, byte, and expansion limits without materializing an unbounded member list.
@@ -59,6 +62,7 @@ Provider adapters may deliberately support a narrower lifecycle. Document that b
 3. Verify handoffs, duplicate agent names, interruption resume, and cleanup failure preserve the intended session mapping.
 4. Test host-path, symlink, traversal, archive-limit, and credential-redaction boundaries on applicable platforms.
 5. Exercise the public `Runner` path so agent preparation, capability binding, persistence, and cleanup run together.
+6. For every new sandbox-path validation, normalization, comparison, or serialization path, test a `PureWindowsPath` input on every host and confirm that raw backslash strings retain their intended validation behavior.
 
 ## Sources
 

.agents/references/tool-identity.md

@@ -18,6 +18,8 @@ One tool can have several related identifiers. They are not interchangeable.
 
 Do not collapse these layers into one string or introduce local rules that only one caller uses.
 
+Provider wire-name grammar and length limits remain provider-owned validation unless an SDK-owned routing invariant requires local enforcement. Follow [Model and Provider Boundaries](model-provider-boundaries.md#provider-validation-and-error-ownership) before adding name validation to shared tool types or canonical identity helpers.
+
 ## Canonical Helpers
 
 Use `src/agents/_tool_identity.py` as the single implementation layer. Important helpers include:

.agents/skills/code-change-verification/SKILL.md

@@ -1,23 +1,39 @@
 ---
 name: code-change-verification
-description: Run the mandatory verification stack when changes affect runtime code, tests, or build/test behavior in the OpenAI Agents Python repository.
+description: Run the required final formatting, lint, type, and test checks after eligible SDK changes pass review.
 ---
 
 # Code Change Verification
 
 ## Overview
 
-Ensure work is only marked complete after formatting, linting, type checking, and tests pass. Use this skill when changes affect runtime code, tests, or build/test configuration. You can skip it for docs-only or repository metadata unless a user asks for the full stack.
+Ensure work is only marked complete after formatting, linting, type checking, and tests pass. Use this skill when changes affect runtime code, tests, or build/test configuration. You can skip it for docs-only or repository metadata unless a user asks for the full stack. This is a post-review final gate: when `$implementation-final-review` applies, do not invoke the broad stack until its clean-review condition applies to the stable task diff.
 
 ## Quick start
 
 1. Keep this skill at `./.agents/skills/code-change-verification` so it loads automatically for the repository.
-2. macOS/Linux: `bash .agents/skills/code-change-verification/scripts/run.sh`.
-3. Windows: `powershell -ExecutionPolicy Bypass -File .agents/skills/code-change-verification/scripts/run.ps1`.
-4. The scripts run `make format` first, then run `make lint`, `make typecheck`, and `make tests` in parallel with fail-fast semantics.
-5. While the parallel steps are still running, the scripts emit periodic heartbeat updates so you can tell that work is still in progress.
-6. If any command fails, fix the issue, rerun the script, and report the failing output.
-7. Confirm completion only when all commands succeed with no remaining issues.
+2. Codex on macOS/Linux: `/usr/bin/env -u OPENAI_API_KEY OPENAI_AGENTS_TEST_IN_CODEX_SANDBOX=1 UV_DEFAULT_INDEX=https://pypi.org/simple bash .agents/skills/code-change-verification/scripts/run.sh`.
+3. Other macOS/Linux environments: `env UV_DEFAULT_INDEX=https://pypi.org/simple bash .agents/skills/code-change-verification/scripts/run.sh`.
+4. Windows: `powershell -ExecutionPolicy Bypass -File .agents/skills/code-change-verification/scripts/run.ps1`.
+5. The scripts run `make format` first, then run `make lint`, `make typecheck`, and `make tests` in parallel with fail-fast semantics.
+6. While the parallel steps are still running, the scripts emit periodic heartbeat updates so you can tell that work is still in progress.
+7. If any command fails, fix the issue, rerun the script, and report the failing output.
+8. Confirm completion only when all commands succeed with no remaining issues.
+
+## Start condition and host capacity
+
+- During iterative review, use only focused tests and a narrowly targeted static check when the changed typing boundary requires one. Defer repository-wide `make typecheck` and the rest of this complete stack until review is clean.
+- Immediately before starting the complete stack, use available read-only task or process evidence to check whether another repository-wide test, typecheck, build, examples runner, or integration command is already active on the same host.
+- When concrete contention is visible, continue useful non-heavy work such as review, remediation, evidence preparation, or focused checks, then check again later. Do not create or wait on a repository lock, host-wide mutex, or sentinel file.
+- Start automatically once review is clean, the diff is stable, and observable host capacity is available. Do not require a user-triggered `finalize` message. If host telemetry is unavailable, do not block solely because capacity cannot be measured.
+
+## Codex execution policy
+
+Repository verification and all child processes must remain in the normal Codex workspace sandbox. Never request elevated sandbox permissions for the verification wrapper, and never retry the wrapper with broader host access after a failure.
+
+On macOS, tests marked `requires_native_macos_sandbox` need to start their own `sandbox-exec` process. The Codex command sets `OPENAI_AGENTS_TEST_IN_CODEX_SANDBOX=1`, which skips only that marker before nested sandbox creation. All other tests remain enabled. Ordinary local and CI runs do not set this variable and therefore keep the marked tests enabled.
+
+The marked tests run separately on a disposable GitHub-hosted macOS runner. If that trusted runner is unavailable, report the missing native-macOS coverage; do not compensate by weakening the Codex sandbox boundary.
 
 ## Environment setup
 

.agents/skills/code-change-verification/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Code Change Verification"
   short_description: "Run the required local verification stack"
-  default_prompt: "Use $code-change-verification to run the required local verification stack and report any failures."
+  default_prompt: "Use $code-change-verification to run the required local verification stack inside the normal Codex workspace sandbox. On macOS/Linux, use the documented Codex command so only tests that require a native macOS sandbox are skipped locally. Never request elevated sandbox permissions or retry with broader host access. Report any failures."

.agents/skills/docs-sync/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: docs-sync
-description: Analyze main branch implementation and configuration to find missing, incorrect, or outdated documentation in docs/. Use when asked to audit doc coverage, sync docs with code, or propose doc updates/structure changes. Only update English docs under docs/** and never touch translated docs under docs/ja, docs/ko, or docs/zh. Provide a report and ask for approval before editing docs.
+description: Audit or update English SDK documentation against the requested implementation scope.
 ---
 
 # Docs Sync
@@ -9,17 +9,21 @@ description: Analyze main branch implementation and configuration to find missin
 
 Identify doc coverage gaps and inaccuracies by comparing main branch features and configuration options against the current docs structure, then propose targeted improvements.
 
+## Authorization and scope
+
+For an audit or proposal-only request, report findings without editing. When the user requests updates or has already approved a plan, complete those local edits and applicable checks without asking again. Ask only about unresolved scope, behavior, release timing, or additional authority. Keep generated translations untouched. Apply the repository's Documentation Release Timing policy before including unreleased behavior in `docs/`.
+
 ## Workflow
 
 1. Confirm scope and base branch
    - Identify the current branch and default branch (usually `main`).
    - Prefer analyzing the current branch to keep work aligned with in-flight changes.
-   - If the current branch is not `main`, analyze only the diff vs `main` to scope doc updates.
-   - Avoid switching branches if it would disrupt local changes; use `git show main:<path>` or `git worktree add` when needed.
+   - Use a branch diff only for a branch-scoped request. A requested topic or released-doc correction remains in scope even when it is unrelated to the current branch diff.
+   - Avoid switching branches if it would disrupt local changes. Prefer read-only inspection such as `git show main:<path>`. If a separate checkout is genuinely required, stop and obtain the explicit approval required by `AGENTS.md` before creating or switching a worktree.
 
 2. Build a feature inventory from the selected scope
-   - If on `main`: inventory the full surface area and review docs comprehensively.
-   - If not on `main`: inventory only changes vs `main` (feature additions/changes/removals).
+   - Bound the inventory to the requested topic or diff. Inventory the full surface only for an explicitly comprehensive audit.
+   - For branch-scoped work, inspect feature additions, changes, and removals relative to the intended base.
    - Focus on user-facing behavior: public exports, configuration options, environment variables, CLI commands, default values, and documented runtime behaviors.
    - Capture evidence for each item (file path + symbol/setting).
    - Use targeted search to find option types and feature flags (for example: `rg "Settings"`, `rg "Config"`, `rg "os.environ"`, `rg "OPENAI_"`).
@@ -42,16 +46,17 @@ Identify doc coverage gaps and inaccuracies by comparing main branch features an
    - **Incorrect/outdated**: names, defaults, or behaviors that diverge from main.
    - **Structural issues** (optional): pages overloaded, missing overviews, or mis-grouped topics.
 
-6. Produce a Docs Sync Report and ask for approval
-   - Provide a clear report with evidence, suggested doc locations, and proposed edits.
-   - Ask the user whether to proceed with doc updates.
+6. Report findings or continue authorized updates
+   - For audit-only work, provide evidence, suggested locations, and proposed edits, then stop.
+   - For an update request, use the findings to complete the authorized edits.
 
-7. If approved, apply changes (English only)
+7. Apply authorized changes (English only)
    - Edit only English docs in `docs/**`.
    - Do **not** edit `docs/ja`, `docs/ko`, or `docs/zh`.
    - Keep changes aligned with the existing docs style and navigation.
    - Update `mkdocs.yml` when adding or renaming pages.
-   - Build docs with `make build-docs` after edits to verify the docs site still builds.
+   - Classify the complete diff with the Documentation Verification Tiers in `AGENTS.md` and run only the checks required by that tier.
+   - For content or structural changes, run `make build-docs` once after the edits and required review are stable. Do not run it for editorial-only changes.
 
 ## Output format
 
@@ -69,7 +74,7 @@ Docs Sync Report
   - Proposed change + rationale
 - Proposed edits
   - Doc file -> concise change summary
-- Questions for the user
+- Unresolved decisions, only when needed
 
 ## References