Improve workspace search/edit pairing with grounded match anchors

[chubes4]

Problem

workspace_grep greatly improved code discovery, but agents still have to manually translate search output into exact workspace_read offsets and later exact workspace_edit anchors.

The PHP transformer iterator previously failed because it guessed nonexistent anchors in a large file:

• Guessed class Transform_Registry; actual class HTML_To_Blocks_Transform_Registry.
• Guessed public function register_transforms; actual transform registry uses public static function get_raw_transforms() and many private helper functions.

workspace_grep fixed the immediate issue, but we can make the tool chain more deterministic.

Proposed shape

Return stable match handles from grep/search results and allow downstream tools to consume them:

{
  "matches": [
    {
      "match_id": "m_01",
      "path": "includes/class-transform-registry.php",
      "line": 3159,
      "preview": "return self::class_matches(...)"
    }
  ]
}

Then support:

• workspace_read by match_id with context lines.
• workspace_edit by match_id plus exact old/new string or nearby anchor.
• workspace_edit failure suggestions when old_string not found, returning nearby matching snippets.

Requirements

• Match IDs can be ephemeral within a tool session/result; they do not need durable storage if the agent can pass path/line/context forward.
• Preserve plain path/offset usage for existing callers.
• On failed exact replacement, return likely nearby matches or changed context when safe.
• Support local and remote workspace backends.

Why this matters

This reduces invented anchors and failed exact edits without weakening the safety of exact replacement.

Related context

• DMC PR Add workspace grep tool #307 added workspace_grep and fixed primary read/search support before worktree creation.
• wc-site-generator PR feat(workspace): add hygiene report #150 wires workspace_grep into the transformer iterator.

AI assistance

• AI assistance: Yes
• Tool(s): OpenCode (GPT-5.5)
• Used for: Drafting this issue from iterator edit-anchor failures and the new workspace_grep workflow.