---
title: "List agent-touched file paths under a workspace root"
method: GET
path: "/v1/agent/touched"
tags: ["Agent"]
---

# List agent-touched file paths under a workspace root

`GET /v1/agent/touched`

## Request

- Base URL: `http://localhost:9998`
- URL: `http://localhost:9998/v1/agent/touched`
- Auth: HTTP bearer

The durable agent-touched set (the paths the interactive kernel's
`file_write` / `file_edit` / `file_delete` / move / copy / observed
exec-class executions mutated) whose path lies under `root` — prefix
match on `root + "/"`, or exact. The late-subscriber replay for the
explorer surfaces' agent-touch decorations: a tree mounting after a
kernel run — or after a ToolPiper restart — learns the touched set
without having listened to the live `agent.file-touched` events on
`GET /v1/events`. Path-only by design; the captured old/new mutation
content rides `GET /v1/agent/touched/review`. Touches persist on disk
until reviewed, bounded by an explicit retention policy (30-day age at
boot, 64 runs, 32 MB of snapshot bytes — content degrades
oldest-first, rows survive).

## Query parameters

- `root` string, required

## Response `200`

The touched paths under the root, sorted by path then runId

- object
  - `touched` object[]
    - `path` string: Absolute path the agent mutated
    - `op` string: Last mutation kind (write | edit | delete | move | rename; tolerate unknown values)
    - `runId` string: The driving agent session id

## Other responses

- `400`: Missing or non-absolute root query param

---

[API](https://skmtc.dev/modelpiper/apis/toolpiper-api.md) · [All operations](https://skmtc.dev/modelpiper/apis/toolpiper-api/llms.txt) · [OpenAPI document](https://skmtc.dev/modelpiper/apis/toolpiper-api/revisions/6722bf56385c?raw)