---
title: Live human review, sessions and audit trails
description: Keep agent work visible in FileHop windows with editable projects, session handoffs, revision-aware refresh and operation history.
order: 8
---

# Live human review, sessions and audit trails

FileHop lets an agent work on files that a person can open, inspect and continue editing in the desktop app. An agent can show its work **while it progresses**, rather than delivering only a final flattened export. Portable `.fhproject` projects retain editable content and assets; sessions organize the task and its review window; activity logs and histories explain what changed.

These capabilities require a compatible installed FileHop app and MCP server, appropriate shared-folder access and supported file/editor types. Discover the tools and schemas on that build first.

## Keep the working project editable

Use `project_create` for new work or `project_migrate` for supported existing editor projects. Keep the returned `project.fhproject` manifest and its asset directory together. Choose a full editor profile such as `imageEditor` or `videoEditor` when the person should continue in that editor. A rendered PNG or MP4 alone does not retain the editable layers or timeline.

Read `filehop://project-guide`, inspect the project, and use typed revision-checked edits. Save coherent batches with summaries. Each successful save becomes a reviewable point; this is saved-state refresh, not a live stream of every unsaved agent thought or keystroke.

**A clean open editor refreshes automatically after valid external project updates.** A person can see the saved changes appear while the agent continues working. If the person has unsaved edits, FileHop preserves their draft and shows a conflict instead of silently replacing it. Re-inspect and reconcile; do not close the tab or discard their work to force a refresh.

Project exports have different support from desktop editing. See [project capabilities and limitations](/docs/images-projects-archives/). Render and inspect the relevant output as well as preserving the working source.

## Show work in a desktop window

Discover `desktop_tabs`, then list running windows:

```json
{"action":"list"}
```

Use a returned window ID to open the actual manifest path:

```json
{
  "action": "open",
  "window_id": "<window ID returned by list>",
  "path": "/Users/me/Shared/Poster/project.fhproject",
  "background": false
}
```

A matching single-pane tab is reused. `background: true` opens without switching focus. Activate/close require the current tab ID and matching path; unsaved work prevents close. Only authorized files/tabs are exposed, and split tabs have additional restrictions.

Opening a tab confirms a UI action. It does not establish that its content has loaded, finished rendering or been reviewed by the person.

## Organize a task with sessions

`desktop_sessions` is persistent task metadata around sources, working files and outputs. A **session is not a window**: it can survive a window closing and later be bound to a suitable live window. Attaching a file records its role; it neither moves it nor grants access.

Use the installed action schemas for this sequence:

1. **Create or resume.** `create` takes a unique `key` and a title; retrying the same creation key resumes that task. Use `list`/`inspect` for ongoing work.
2. **Attach files.** Use `attach` with roles `source`, `working` or `output`. Metadata changes require the session's integer `expected_revision`; inspect again when stale.
3. **Choose a review window.** `bind` selects an existing window ID from `desktop_tabs`; discover `window` for the session-window action supported by that build. `unbind` releases the binding without closing files. A closed window requires explicit rebinding.
4. **Open work.** `open` normally uses background tabs; `present: true` brings the requested file forward for review. Do not keep stealing focus on every save.
5. **Check readiness.** `wait` takes the expected file revision and, for projects when relevant, dependency revision. Optional `tab_id` targets the intended view. Dirty, conflicted or error panes cannot satisfy a rendered wait.
6. **Hand off or resume.** Discover `handoff` for presenting the task's deliverable. `restore` reopens permitted attached files and reports partial failures. `transition` marks a task active, completed or archived; lifecycle state is not a person's approval.

Do not confuse the session's metadata revision, a file's content revision and a project's dependency revision. They protect different state. Opening or restoring existing views also does not guarantee that every attached file rendered successfully.

## Know what was actually reviewed

| Signal | What it establishes | What it does not establish |
| --- | --- | --- |
| Tab opened | A permitted UI tab exists or was activated | Content readiness or approval |
| `wait` with `loaded_only: true` | Expected content loaded | Rendering; it cannot record render evidence |
| Rendered `wait` | The matching native surface rendered at the expected revision | Every slide/page/frame/audio segment was inspected |
| `wait` with `record_preview: true` | Revision-bound native surface evidence, with its reported scope | A captured screenshot or human sign-off |
| `session_preview` | Images and recorded evidence for a saved attached ordinary file | Complete-file coverage or human sign-off |
| `project_render` / `project_video_preview` | A supported project preview or bounded audiovisual range | Inspection of the whole project/movie |
| Session completed/handoff | Agent workflow state or presentation of the result | The person accepted the work |

Evidence must be regenerated after changes. Read the renderer's fidelity and scope, particularly approximate Word pagination and selected-slide/video-range previews.

Use session `checkpoint` to save an explicit review location: a slide, page, sheet/cell, text cursor, media position or supported project view. Restore by the named `view_id` where supported. A checkpoint is a navigation bookmark, not document bytes or evidence that the content was reviewed.

## Trace what the agent did

FileHop records tool calls in its Agent activity log, including refused calls. `tool_run` uses the actual tool's identity and normal checks; it does not bypass logging. `activity_log` gives the connected MCP session's calls, statuses, timing, input/output paths, errors and whether Undo is still available. Follow its cursor to continue.

| Record | Use |
| --- | --- |
| Agent activity log / `activity_log` | Trace operations, failures, output paths and available Undo |
| File history / `history_list`, `history_diff` | Review saved content changes, revisions, author/source and summaries |
| `history_checkpoint` | Capture before/after states when using an external editor; uncaptured bytes cannot be restored |
| Named versions / `history_save_version` | Mark meaningful milestones without naming every small edit |
| Project journal / `project_journal`, `project_note` | Resume decisions, notes, todos, saves, exports and reversions |
| Project history / `project_history`, `project_diff`, `project_revert` | Compare or restore retained project revisions and available assets |
| File context / `context_read`, `context_write` | Leave review comments and decisions without changing the file's bytes |

The audit log is **tamper-evident, not tamper-proof**. It is not a recording of everything an agent does outside FileHop. Logged arguments are bounded and secrets/sensitive fields are redacted or summarized; this is an operation record, not a complete backup of file contents. A successful save can report a history warning if recording the entry failed; distinguish saved content from a recorded checkpoint. History restoration depends on retained snapshots and assets. Avoid promises of permanent retention or universal Undo.

## Related files and multiple participants

Session `link`/`unlink` can record supported source-to-output dependencies. `session_refresh` explicitly refreshes a recorded relationship, such as table data feeding a document or deck chart, or an editable image composition feeding a video graphic. Inspect current source and target revisions first. A target changed since its baseline refuses automatic refresh; preview again afterward. This is an explicit refresh operation, not an unrestricted live synchronization guarantee.

Where available, `session_participants` supports explicit reader/editor participation. A client label is not authorization for a shared session, and joining does not expand file grants. Follow the installed token/invite schema and keep credentials out of comments or exported project content.

The useful handoff is the editable working file, relevant rendered output, a visible review location and a short account of changes and remaining issues. These let the person inspect and continue the work with its context intact.