refactor(skills): report touched paths on observations for path-rule injection

[VascoSch92]

HUMAN:

Refactor path-rule injection.

---

AGENT:

Why

Path-rule injection discovered the touched file via
getattr(action_event.action, "path", None) in
LocalConversation._touched_rule_path — an implicit, untyped contract flagged
while reviewing #3994. It fails in two directions with tools that ship today:

• Misses tools. The Gemini file tools name the field file_path, and
  apply_patch carries only a patch string — so getattr(action, "path")
  returns None and rules silently never fire.
• Fires spuriously. grep / glob / list_directory carry a path that
  is a search directory, not a modified file, so a directory a tool merely
  searched can trigger {dir}/** or ** rules.

It also can't express an operation that touches several files (a rename touches
source and destination; a patch can touch many).

Summary

• Add an affected_paths property to the Observation base (empty by default);
  file-touching observations override it to declare the paths they modified.
• The injection seam now reads observation.affected_paths directly — dropping
  the action-correlation lookup and the getattr string-name guess, and
  supporting multiple paths.
• Producers populate it: file_editor, Gemini read/write/edit, and
  apply_patch (changed files + rename destinations). grep/glob/list
  report nothing, so rules no longer fire on a directory that was only searched.

This follows Option C from the issue, adapted: the value is a derived
property, not a stored/serialized field, so it needs no event-schema migration
and recomputes correctly after deserialization (the base is frozen with
extra="forbid", so a serialized computed field would break round-trip
validation).

Issue Number

Closes #4038

How to Test

Unit + producer coverage:

uv run pytest tests/sdk/conversation/test_path_rules_injection.py \
              tests/tools/test_path_rules_file_editor.py \
              tests/tools/test_affected_paths.py -q
# 22 passed

Broader regression sweep (base-schema + producer changes):

uv run pytest tests/sdk/tool tests/tools/{file_editor,apply_patch,gemini,grep,glob} \
              tests/sdk/conversation -q
# 1226 passed

End-to-end (the previously-missed case) — drive a real Gemini write_file
observation through a live LocalConversation and confirm the rule fires:

getattr(action, 'path'): None            <- what the old seam saw (missed it)
observation.affected_paths: ['/.../src/api/users.ts']
...
RESULT: rule fired for a Gemini write_file. activated_path_rules = ['api']

pre-commit run --all-files scoped to the changed files passes (ruff, pyright,
import-dependency rules, tool-registration).

Type

• Bug fix
• Feature
• Refactor
• Breaking change
• Docs / chore

Notes

• Producer + consumer land together (by design). Once the seam reads
  affected_paths, any file-mutating observation that doesn't override the
  property reports nothing — so all producers are updated in this PR. Third-party
  tools that want path rules should override affected_paths on their
  observation.
• Reads count as touches. read_file / file-editor view report their path
  (consistent with the pre-existing file-editor behaviour). Erroring ops report
  nothing. Happy to gate reads out if reviewers prefer writes-only.
• The core openhands-sdk → openhands-tools layering is preserved (no new
  cross-package imports; verified by the import-rules hook).

[enyst]

should this be a protocol…? 🤔

[VascoSch92]

@enyst

Kept it as a property on the Observation base rather than a Protocol.

A Protocol makes sense when types don't share a base, but every observation already subclasses Observation, and the seam already gets it typed (ObservationEvent.observation: Observation).

The base default (return []) makes affected_paths total, so the consumer just iterates with no isinstance/hasattr guard.

Or wdyt?