Skip to content

Define normalized file observations across supported tools #42

Closed

Description

@frap129

Part of #38

Question

What normalized file-observation model should Read, Write, Apply Patch, and LSP events produce so path/glob and fileContains evaluate the same path-associated content from one successful event? Resolve per-tool path ownership, multi-file results, patch hunk parsing, LSP path-associated text, truncation or malformed results, successful-event detection, and strict exclusion of metadata and unsupported content sources.

Activity

  1. self-assigned this
    on Aug 29, 2026
  2. frap129 commented on Aug 29, 2026

    @frap129
    OwnerAuthor

    Normalized file observations across supported tools

    Decision

    One successful file-handling tool event yields one file observation per file: a flat { path, tool, content } record, where content is that file's contribution text. Both globs and fileContains evaluate the same record; no per-segment typing (added/removed/returned) is kept, since matching is case-sensitive substring OR over content and segment kinds would add bookkeeping without changing any match outcome.

    Per tool (successful events only — failed executions never reach tool.execute.after in v1.18.23, so the hook itself already marks success):

    • read — content is reconstructed from the tool output: wrapper tags (<path>, <type>, <content>) and {lineNumber}: prefixes are stripped, returned lines are joined with \n. Continuation reads (offset/limit) contribute only their returned lines; never reconstruct omitted lines. Image/PDF reads yield a path-only observation with empty content (globs can still match; fileContains is fail-closed on it). Directory reads yield no observation (the path is not a file).
    • write — content is the verbatim submitted args.content (the model-visible output is only "Wrote file successfully."). Keyed to args.filePath.
    • edit — a patch-style writer: content is removed oldString plus added newString, keyed to args.filePath. edit and apply_patch are symmetric so fileContains is not model-dependent.
    • apply_patch — parse the verbatim args.patchText (codex-style, N files per call): Add File → full contents; Update File → added + removed + context hunk lines with patch-syntax markers excluded; Move To → hunk lines keyed to the destination path; Delete File → path-only, no content. One observation per file touched.
    • lsp (gated behind OPENCODE_EXPERIMENTAL_LSP_TOOL) — content is the raw successful output text (JSON result or "No results found for {operation}") keyed to args.filePath only. Result URIs pointing at other files are text within this observation, not extra observations.

    Path form: paths are consumed verbatim as the after-hook receives them (pre-decode, possibly relative); no fs resolution, normalization, or existence checks — consistent with current matching and the no-proactive-scan constraint (minimatch matchBase already handles suffix matching).

    Glob source replacement: normalized observations replace today's path sources, including the regex path-scan of message text parts in src/message-paths.ts. Path/glob matching consumes the same normalized observations live and replayed from history — one source of truth. Accepted consequence: a rule whose globs matched path mentions in prose (no tool involvement) stops firing.

    Malformed patchText: if the patch fails to parse, emit path-only observations parsed from the model-visible output summary lines (A/D/M {relpath}) with no content — globs still works, fileContains fails closed silently.

    All other tools (grep, bash, glob, list, task, webfetch, skill, custom/MCP, …) contribute no observations: metadata, diagnostics blocks, and other-file URIs are excluded per the map's standing exclusions.

    Evidence

    • Verified against OpenCode v1.18.23 source: tool.execute.after fires for every registry-built tool with verbatim pre-decode args and the final mutable {title, output, metadata}; failed executions never reach it (packages/opencode/src/session/tools.ts); read/write/edit/apply_patch/lsp arg and output shapes as cited in the research thread; the only LSP-related registry tool is lsp; no multi-file tool other than apply_patch exists.
    • Repo facts: src/message-paths.ts PATH_ARG_TOOLS maps read/edit/write → filePath; text-part path scanning and glob/binary reads established the replacement consequence for prose path mentions.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions