# 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.