What I Decided Before Letting an Agent Touch My Files: Folder Boundaries and Guardrails for Gemini Spark

Guardrail 1: Take a content-hash manifest before the run

First, freeze the pre-run workspace state as a table mapping file paths to content hashes. File names alone cannot catch an overwrite where the contents were swapped, so hashing the content itself is the key.

import hashlib
import json
from pathlib import Path
 
def build_manifest(root: Path) -> dict[str, str]:
    """Record every file under the workspace as {relative path: content hash}."""
    manifest: dict[str, str] = {}
    for path in sorted(root.rglob("*")):
        if not path.is_file():
            continue
        # Skip temp files and hidden folders
        if any(part.startswith(".") for part in path.relative_to(root).parts):
            continue
        digest = hashlib.sha256(path.read_bytes()).hexdigest()
        manifest[str(path.relative_to(root))] = digest
    return manifest
 
root = Path.home() / "Workspace"
before = build_manifest(root)
Path("manifest_before.json").write_text(json.dumps(before, ensure_ascii=False, indent=2))
print(f"Files recorded: {len(before)}")

The reason for hashing content here is to distinguish, later, whether a file was moved, overwritten, or deleted. If the same hash appears at a new path, it was moved; if a hash simply disappears, it was deleted; if the path stays but the hash changes, it was overwritten. Watching name matches alone cannot tell these apart.

Guardrail 2: Declare the operating range with an allowlist

Next, explicitly declare the range the agent may touch. Rather than implicitly granting broad permissions on the assumption that "it will probably be fine," write it in the direction of narrowing the allowed operations.

from dataclasses import dataclass, field
 
@dataclass
class Policy:
    # Folders where reordering is allowed (moves permitted only under these)
    movable_roots: list[str] = field(default_factory=lambda: ["_inbox", "_sorting"])
    # Folders that must never be deleted or moved
    protected_roots: list[str] = field(default_factory=lambda: ["_published", "_master"])
 
    def allows_move(self, rel_path: str) -> bool:
        top = rel_path.split("/", 1)[0]
        return top in self.movable_roots and top not in self.protected_roots
 
    def is_protected(self, rel_path: str) -> bool:
        top = rel_path.split("/", 1)[0]
        return top in self.protected_roots

In my workspace, cleanup targets are limited to the intake folder _inbox and the in-progress _sorting, while the published _published and the original _master are protected. I tell the agent to "only reorder inside these two folders," and the verification side enforces that same declaration. Doubling up the request in the prompt with a check in code is essential. A promise made only in words gives you no way to notice when it is broken.

Guardrail 3: Audit the post-run diff and roll back violations

After the agent runs, take the manifest again and reconcile before against after. This is the heart of the mechanism. Mechanically confirm that nothing protected changed, that moves stayed within the allowed range, and that there were no unintended deletions; if a violation appears, route it to human approval.

def audit(before: dict[str, str], after: dict[str, str], policy: Policy) -> list[str]:
    violations: list[str] = []
    before_hashes = set(before.values())
 
    # Vanished files: if a hash is nowhere in 'after', it was deleted
    for path, digest in before.items():
        if digest not in after.values():
            if policy.is_protected(path):
                violations.append(f"Deletion of protected file: {path}")
            elif path not in after:
                violations.append(f"Content lost (deletion, not a move): {path}")
 
    # Newly appearing paths: detect moves/creation outside the allowed range
    for path, digest in after.items():
        if path in before:
            if before[path] != digest:
                violations.append(f"Overwrite of existing file: {path}")
            continue
        if digest in before_hashes:
            # Existing content appeared at a different path = a move
            if not policy.allows_move(path):
                violations.append(f"Move outside allowed range: {path}")
        else:
            if policy.is_protected(path):
                violations.append(f"New creation inside protected folder: {path}")
    return violations
 
after = build_manifest(root)
issues = audit(before, after, Policy())
if issues:
    print("Policy violations detected. Routing to approval.")
    for line in issues:
        print(" -", line)
else:
    print("All changes were within the allowed range.")

Before inserting this check, I would hand off cleanup, open the folders myself, glance around, and settle on "probably fine." Eyeballing works for a few dozen files, but breaks down at a few hundred. Once I handed the verification to the machine, only the violating lines remained in front of me, and the set of things I had to confirm shrank to a handful.

Placing Before and After side by side makes the change in confirmation quality clear.

Results from running it on my own workspace

I actually ran cleanup through this mechanism over roughly 480 image assets and documents that had piled up in the intake folder. The rough measured figures were as follows.

The two detected cases were proposals to create a similarly named temporary folder right next to the published folder. Not bad operations, but off from my intent. Without the mechanism, those two would likely have been buried among hundreds of changes and slipped by. The value of the guardrail, I feel, lies less in stopping accidents outright and more in surfacing the "few items worth confirming."

The line between what to delegate and what to keep

Finally, here is the line I currently use, as a table. This is not a fixed correct answer but a starting point for judging by how recoverable something is.

The smarter the agent gets, the wider the range you can delegate. Even so, keep human approval around the irreversible operations alone. The tools for holding that one line were the content-hash manifest, the allowlist, and the diff audit.

I have only just begun to use Spark in earnest, but because I prepared the tools first, I could take that first step calmly. If you are looking to hand local cleanup to an agent too, I hope this helps with your own design. Thank you for reading.