# 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?, since?, until?, 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. Each line
starts with the file's **date**.

Filters:

- `path` — path prefix, e.g. `output/`.
- `sourceKind` — filter by source kind.
- `createdByTaskId` / `lastModifiedByTaskId` — filter by task.
- `since` / `until` — date range, inclusive on both ends. Accepts `YYYY-MM-DD`
  or a full ISO timestamp; a bare `until` date covers that whole day.
- `includeUnknown` — set `false` to hide `unknown` / `imported_existing` files.

### The date

A file's date is `last_modified_at`, falling back to `first_seen_at`. Display,
ordering and `since` / `until` all use that same one date, so a date you read
off a listing can be pasted straight back into a range filter.

### Selecting only this task's files

The job's context block carries `このタスクの番号: <id>`. Pass it as
`createdByTaskId` to see only what this task made, or use it to tell your own
files apart from ones that were already in the workspace.

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