maestro/docs/tools/file-provenance.md

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.