sync: update from private repo (edc775f2)

docs/tools/file-provenance.md

@@ -0,0 +1,50 @@
+# GetFileProvenance / ListWorkspaceFiles
+
+Workspace file provenance tools. In a persistent (shared) workspace, files can
+outlive a single task: an old task's inputs and outputs stay visible to later
+tasks. These tools let you tell WHO a file belongs to before you edit or rely on
+it.
+
+Both are META tools — always available regardless of the workspace tool policy.
+
+## When to use
+
+- Before editing a file whose relevance to the current task is unclear.
+- When you see a file in `input/` or `output/` that you did not create this run.
+- To find which files the current task actually produced vs. inherited.
+
+## GetFileProvenance({ path })
+
+Returns a compact record for one file (workspace-relative path, e.g.
+`output/report.md`):
+
+- `source_kind` — one of `user_input`, `agent_output`, `agent_edit`,
+  `bash_generated`, `subtask_output`, `imported_existing`, `unknown`.
+- `created_by_task_id` — the task that first created/uploaded the file.
+- `created_by_piece` / movement — the piece + movement that created it.
+- `last_modified_by_task_id` + `last_modified_at`.
+
+If there is no record (a file that pre-dates the ledger), you get an
+`unknown`-equivalent message — treat the file as possibly belonging to another
+task and verify its contents before overwriting.
+
+## ListWorkspaceFiles({ path?, sourceKind?, createdByTaskId?, lastModifiedByTaskId?, includeUnknown?, limit? })
+
+Returns a bounded listing (default 50, max 200 rows) of known files with a
+one-line provenance summary each. It never returns file contents.
+
+Filters:
+
+- `path` — path prefix, e.g. `output/`.
+- `sourceKind` — filter by source kind.
+- `createdByTaskId` / `lastModifiedByTaskId` — filter by task.
+- `includeUnknown` — set `false` to hide `unknown` / `imported_existing` files.
+
+## Guidance
+
+- Do NOT blindly edit files whose `source_kind` is `user_input` or whose
+  `created_by_task_id` differs from the current task. Prefer creating a new file
+  under `output/`.
+- These tools report task/job IDs only — never task titles or user identities.
+- The tools are scoped to the current run's workspace; you cannot inspect other
+  workspaces.