ci(upstream-merge): expand agent context with fork enhancements + generic guards

- Add docs/fork-enhancements.md (initial list; instruct agent to scan repo for more)
- Inject the overview into the merge prompt
- Generalize verify guards to handler↔tool parity by family (browser_*, agent_*, web_fetch), and keep UA/version check

Prevents silent loss of fork features and gives the agent richer context.

.github/workflows/upstream-merge.yml

@@ -518,6 +518,13 @@ jobs:
             echo '- Make granular decisions commit-by-commit or by bucket; do not blanket-drop upstream changes without review.';
             echo '- Preserve our added functionality in core: model-driven browser tools, agent tools, screenshot handling, and version/UA semantics.';
             echo '';
+            echo 'Fork Enhancements (initial, not exhaustive)';
+            if [ -f docs/fork-enhancements.md ]; then
+              sed -n '1,200p' docs/fork-enhancements.md;
+            else
+              echo '- (fork overview file missing)';
+            fi
+            echo '';
             echo 'Artifacts';
             echo '- .github/auto/COMMITS.json: upstream commits not in default (sha, title, files, stats).';
             echo '- .github/auto/DELETED_ON_DEFAULT.txt: crates/paths removed on our default; avoid re-introducing.';
@@ -544,10 +551,10 @@ jobs:
              - Default: adopt upstream outside prefer_ours_globs. In protected areas (prefer_ours_globs), keep ours unless you identify a clearly beneficial, compatible upstream change.
              - For files matching prefer_theirs_globs, lean towards upstream unless it breaks our build or documented behavior.
              - Explicit invariants to preserve in this fork (must not regress):
-               • openai_tools::get_openai_tools must continue to register our browser_* tools (at least browser_open + browser_status when disabled; full set when enabled) and our agent_* tools.
-               • run_turn must not drop the browser gating that controls when browser tools are advertised; if upstream refactors, adapt but keep the behavior.
-               • Screenshot handling: do not remove queuing of pending screenshots across turns unless you also update callers to preserve UX; prefer keeping our pending queue + TUI updates.
-               • Version handling: keep codex_version::version() usage for UA/build and ensure get_codex_user_agent_default() remains the single point used by MCP server where appropriate.
+               • Tool families: any custom handlers with names starting with `browser_` or `agent_`, and `web_fetch` if present, must have corresponding tool schemas exposed by openai_tools (verify.sh enforces handler↔tool parity generically).
+               • Exposure gating: do not drop the browser gating logic that controls when browser tools are advertised (adapt to upstream refactors without removing the behavior).
+               • Screenshot UX: do not change screenshot queuing semantics across turns unless you update both producer/consumer paths to preserve UX; prefer preserving our pending queue + TUI updates.
+               • Version/UA: keep codex_version::version() usage for UA/build and keep get_codex_user_agent_default() for MCP server user agent.
              - Do NOT blanket-delete new crates or reintroduced paths. Surface noteworthy cases in MERGE_REPORT.md and make a reasoned choice.
              - For any path listed in purge_globs or perma_removed_paths, ensure it remains deleted if upstream reintroduced it.
              - Review the upstream commit range (e.g., via `git rev-list upstream/UPSTREAM_BRANCH ^origin/DEFAULT_BRANCH`). Use repo context and the provided artifacts to make sensible, minimal decisions. Prefer preserving our local UX/branding and workflows; adopt upstream when it improves correctness, security, or compatibility. Record notable decisions in MERGE_REPORT.md.

docs/fork-enhancements.md

@@ -0,0 +1,39 @@
+# Fork Enhancements (Initial, Not Exhaustive)
+
+This fork extends upstream `openai/codex` in several areas. These bullets are a starting point — not a complete list. Before merging, scan the codebase and history (CHANGELOG.md, recent commits) to discover additional or newer fork‑only behavior and preserve it.
+
+- Browser Integration (codex-rs/browser, TUI + core wiring)
+  - Internal CDP browser manager with global access and /browser command.
+  - Tool family: `browser_*` (open, status, click, move, type, key, javascript, scroll, history, inspect, console, cleanup, cdp).
+  - Screenshot capture with segmentation, cursor overlay, asset storage, and per‑turn injection/queueing; TUI rendering with friendly titles.
+  - External Chrome attach via `/chrome` and headless profile management.
+
+- Multi‑Agent Orchestration (core/agent_tool.rs, TUI panel)
+  - Tool family: `agent_*` (run, check, result, cancel, wait, list) with persisted outputs under `.code/agents/<id>` and TUI agent panel.
+  - Batch and per‑agent status updates; file emission (result/error/status logs).
+
+- Tooling Extensions and Policy Integration
+  - `web_fetch` custom tool with markdown‑aware TUI rendering and UA override.
+  - `view_image` tool to attach local images.
+  - Local shell + sandbox policy with escalation request (`with_escalated_permissions`, `justification`) and WorkspaceWrite flags (network access, allow_git_writes, tmpdir controls).
+  - Streamable exec tool support kept off by default; preserved compatibility with classic shell tool.
+
+- Protocol/Model Compatibility Tweaks
+  - Responses/Chat Completions parity for tools; MCP tool schema sanitization to a safe subset.
+  - FunctionCallOutput serialization kept as a plain string for Responses API compatibility.
+  - Web search event mapping and `WebSearchCall` rendering in TUI; optional upstream web_search tool gated by policy.
+
+- TUI Enhancements
+  - Strict streaming ordering invariants (request_ordinal, output_index, sequence_number) and delta rendering.
+  - Markdown renderer improvements and code‑block snapshots; theme selection view; bottom pane chrome selection.
+  - History cells with richer tool‑specific titles and previews (browser_*, web_fetch, agents).
+
+- Version and User‑Agent Handling
+  - Consistent `codex_version::version()` usage; `get_codex_user_agent(_default)` helper; MCP server/client UA tests.
+
+- Build/CI/Workflow
+  - `build-fast.sh` portability (exec bin autodetect, deterministic link tweaks) and zero‑warning policy.
+  - Upstream merge guards and policy to prefer our core files; static verify checks (handlers↔tools parity, UA/version) to prevent regressions.
+
+Note: These are representative areas. You must still scan for newer fork‑only behavior (e.g., additional TUI UX, new tools, rollout metrics, protocol fields) and preserve them when resolving conflicts.
+

scripts/upstream-merge/verify.sh

@@ -49,28 +49,36 @@ fi
 guards_log=.github/auto/VERIFY_guards.log
 : > "$guards_log"
 
-# Guard A: openai_tools must include browser and agent tool registration (schemas)
-if ! rg -n "name:\s*\"browser_open\"" codex-rs/core/src/openai_tools.rs >/dev/null 2>&1; then
-  echo "[guards] missing browser_open tool schema in openai_tools.rs" | tee -a "$guards_log"
-  status_guards="fail"
-fi
-if ! rg -n "name:\s*\"agent_run\"" codex-rs/core/src/openai_tools.rs >/dev/null 2>&1; then
-  echo "[guards] missing agent_run tool schema in openai_tools.rs" | tee -a "$guards_log"
-  status_guards="fail"
-fi
-# Guard B: get_openai_tools should push web_fetch or web_search per fork policy
-if ! rg -n "web_fetch\"|WebSearch" codex-rs/core/src/openai_tools.rs >/dev/null 2>&1; then
-  echo "[guards] neither web_fetch nor web_search tools found in openai_tools.rs" | tee -a "$guards_log"
+# Guard A: Handlers-to-tools parity for our custom families (browser_*, agent_*, web_fetch)
+# Extract handler names from handle_function_call and tool names from openai_tools in a quote-agnostic way
+handlers=$(rg -n '^[[:space:]]*"[a-z_][a-z0-9_]+"[[:space:]]*=>' codex-rs/core/src/codex.rs | sed -E 's/.*"([^"]+)".*/\1/' | sort -u)
+tools_defined=$( {
+  rg -n 'name:[[:space:]]*"[^"]+"' codex-rs/core/src/openai_tools.rs || true;
+  rg -n 'name:[[:space:]]*"[^"]+"' codex-rs/core/src/agent_tool.rs || true;
+} | sed -E 's/.*"([^"]+)".*/\1/' | sort -u )
+
+need_check=$(printf "%s\n" "$handlers" | grep -E '^(browser_|agent_|web_fetch$)' || true)
+while IFS= read -r h; do
+  [ -n "$h" ] || continue
+  if ! printf "%s\n" "$tools_defined" | grep -qx "$h"; then
+    printf "[guards] handler '%s' present in codex.rs but missing tool schema in openai_tools.rs\n" "$h" | tee -a "$guards_log"
+    status_guards="fail"
+  fi
+done <<< "$need_check"
+
+# Guard B: Get-openai-tools should reference at least one browser_* tool to expose family
+if ! rg -n 'browser_' codex-rs/core/src/openai_tools.rs >/dev/null 2>&1; then
+  printf "[guards] no 'browser_' tool references found in openai_tools.rs - tool family likely dropped\n" | tee -a "$guards_log"
   status_guards="fail"
 fi
 # Guard C: default_client should reference codex_version::version for UA
-if ! rg -n "codex_version::version\(\)" codex-rs/core/src/default_client.rs >/dev/null 2>&1; then
-  echo "[guards] codex_version::version() not referenced in core/default_client.rs" | tee -a "$guards_log"
+if ! rg -n 'codex_version::version' codex-rs/core/src/default_client.rs >/dev/null 2>&1; then
+  printf "[guards] codex_version::version not referenced in core/default_client.rs\n" | tee -a "$guards_log"
   status_guards="fail"
 fi
 
 # Summarize guards
-echo "guards=${status_guards}" >> .github/auto/VERIFY_guards.log
+echo "guards=${status_guards}" >> "$guards_log"
 
 rc=0
 if [[ "$status_build" != ok || "$status_api" != ok || "$status_guards" != ok ]]; then