docs(agent): verify edit-format steering against current Codex CLI + Claude Code source

Checked ~/agent-codebases (Codex @ 2026-05-30, Claude Code decompiled src):
- Codex: apply_patch is the only file-edit tool; apply_patch.lark is V4A;
  GPT-5.1/5.2(-codex) prompts mandate it; gated per-model via
  ModelInfo.apply_patch_tool_type. No str_replace editor in the repo.
- Claude Code: FileEditTool is old_string/new_string exact replacement with
  unique-match semantics — current Claude models train against str_replace
  in their first-party harness, not just the 2025 API text-editor tool.

agent/coding_context.py

@@ -98,10 +98,26 @@ _GIT_TIMEOUT = 2.5
 
 
 # Per-model edit-format steering. Matching the edit tool format to how a model
-# was trained reduces mistakes and wasted reasoning (OpenAI/Codex handle
-# patch-style diffs best; Anthropic models — and most open-weight coding
-# models, whose RL scaffolds use str_replace-style editors — do best with
-# string-replacement). Our `patch` tool exposes both: mode="patch" (V4A
+# was trained reduces mistakes and wasted reasoning. Documented sources,
+# verified against current first-party agent source (May–Jun 2026):
+# - GPT/Codex → V4A patch: Codex CLI's ONLY file-edit tool is apply_patch and
+#   its grammar (codex-rs/core/src/tools/handlers/apply_patch.lark) is exactly
+#   the V4A format; the GPT-5.1/5.2(-codex) prompts instruct "Use the
+#   `apply_patch` tool to edit files", and OpenAI gates the tool per model via
+#   ModelInfo.apply_patch_tool_type. No str_replace editor exists in Codex.
+#   (Earlier doc: the GPT-4.1 prompting guide ships apply_patch/V4A —
+#   https://developers.openai.com/cookbook/examples/gpt4-1_prompting_guide)
+# - Claude → str_replace: Claude Code's FileEditTool is exact string
+#   replacement (old_string/new_string/replace_all, unique-match semantics) —
+#   current Claude models are RL'd against str_replace editing in their own
+#   first-party harness. Also Anthropic's API text-editor tool
+#   (`str_replace_based_edit_tool`) is schema-less: the schema is built into
+#   the model.
+#   https://platform.claude.com/docs/en/agents-and-tools/tool-use/text-editor-tool
+# - Open-weight coding models → str_replace: the dominant open RL/agentic
+#   scaffolds (SWE-agent, OpenHands ACI) use str_replace-style editors, and
+#   Qwen Code / Gemini CLI ship old_string/new_string `replace` tools.
+# Our `patch` tool exposes both: mode="patch" (V4A
 # multi-file) and mode="replace" (find-and-swap). We nudge each family toward
 # its native format. Unknown families get nothing (the brief's neutral wording
 # stands). Substrings match the model id; aligned with TOOL_USE_ENFORCEMENT_MODELS.
@@ -657,9 +673,9 @@ def _project_facts(root: Path) -> list[str]:
         deduped = list(dict.fromkeys(verify))[:_MAX_VERIFY_COMMANDS]
         facts.append(f"- Verify: {'; '.join(deduped)}")
 
-    context_files = [c for c in _CONTEXT_FILES if (root / c).is_file()]
-    if context_files:
-        facts.append(f"- Context files: {', '.join(context_files)}")
+    # Note: context files (AGENTS.md / CLAUDE.md / .cursorrules) are NOT listed
+    # here — their full contents are already injected into the system prompt as
+    # the Project Context block, so naming them again is redundant.
 
     return facts
 

tests/agent/test_coding_context.py

@@ -152,11 +152,14 @@ class TestProjectFacts:
         assert "make test" in block
         assert "make deploy" not in block
 
-    def test_context_files_listed(self, tmp_path):
+    def test_context_files_not_listed(self, tmp_path):
+        # Context files (AGENTS.md etc.) are injected into the system prompt
+        # in full as the Project Context block — naming them in the snapshot
+        # would be redundant.
         _git_init(tmp_path)
         (tmp_path / "AGENTS.md").write_text("# rules")
         block = cc.build_coding_workspace_block(tmp_path)
-        assert "Context files: AGENTS.md" in block
+        assert "Context files:" not in block
 
     def test_marker_only_project_gets_snapshot_without_git(self, tmp_path):
         # A non-git project (manifest only) still gets a workspace snapshot —