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

{"action":"list"}

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

{
  "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:

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.
Attach files. Use attach with roles source, working or output. Metadata changes require the session’s integer expected_revision; inspect again when stale.
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.
Open work. open normally uses background tabs; present: true brings the requested file forward for review. Do not keep stealing focus on every save.
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.
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.

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.