Before an AI Agent Unpacks a File, Check Where It Writes

Before an AI agent unpacks an archive, treat its contents as proposed writes to the filesystem. Inspect the destination, entry types, overwrite behavior and resource limits. Use an isolated intake location, then move accepted files into the project after review. “Unzip this” sounds like reading a file; it is dozens or thousands of writes whose targets were chosen by whoever built the archive.

This is a practical acceptance decision for teams asking agents to import assets, documents or source bundles. It does not require the owner to understand archive internals. The agent should be able to explain what will be written, where it will land and what the extraction process is permitted to replace. This guide sets out the six intake questions, what the standard library documentation itself warns about, why the import belongs in its own folder, why extracting a file is not permission to run it, the imports that looked fine and were not, and how to report a partial extraction honestly.

A compressed bundle arrives as one file, which is why it is treated like one. But the operation an agent performs on it is not a read. Extraction walks a list of members, and for each one creates a path, writes bytes, and sets whatever attributes the format carries. The author of the archive chose those paths. If the agent extracts into the project, the author of the archive has just written to the project.

Reframing the task that way makes the right questions obvious. Where will each write land? What kind of thing is each member? Can a write replace something already there? How much will be written in total? Those are the questions a reviewer would ask of any agent about to write many files, and an archive should not get a pass because the writes arrived pre-packaged.

An archive member is an entry inside the bundle. Some members represent regular files, while others can represent directories or links. A symbolic link redirects a path to another location. The table gives six intake questions; the extractor and operating environment must enforce the resulting policy, because a policy that lives only in the prompt is a policy the extractor has never heard of.

The rows run in the order the agent should ask them. Destination first, because a member that resolves outside the intake boundary ends the conversation. Completion evidence last, because it is the row that turns an extraction into an intake record a reviewer can read.

Python’s tarfile guidance says extraction filters do not prevent every dangerous behavior, including resource exhaustion. It recommends additional checks and a new temporary directory. Those warnings support treating extraction as a bounded operation even when a filter is enabled: the library that ships the filter is the one saying the filter is not enough.

Python’s zipfile documentation describes decompression pitfalls, including resource limits and overwriting files when the same archive is extracted again. That is specific library guidance. Do not assume every archive format or tool has the same defaults; a different language’s library, or a command-line tool, may be stricter or looser on each point.

Check the installed extractor version and its actual controls. The linked Python guidance contains version-dependent behavior; the intake questions do not certify every extractor. The useful habit is to have the agent quote the relevant line of its own extractor’s documentation into the intake record, so the reviewer knows which protections were in force rather than which were assumed.

Consider a hypothetical asset bundle supplied for a website update. The request is to inspect images and copy selected assets into the project. Extracting the entire bundle directly over the working tree grants more write authority than that task needs. A separate intake directory lets the agent compare the proposed files with the intended destinations first, and lets a reviewer delete the whole folder if anything about it looks wrong.

Resolve destinations using the extractor’s actual rules, including links and filesystem behavior. Reject paths outside the intake boundary. A member whose name contains a parent-directory reference, or a link whose target is outside the folder, is not a curiosity to note; it is the archive asking to write somewhere it was not invited.

Our agent sandbox reference covers the broader runtime boundary. Archive inspection is an additional input check: a sandbox can limit reach while still allowing an import to overwrite valuable files inside the permitted workspace. The sandbox decides where the agent may write; the intake folder decides where this archive may.

Move only the content types and members the task needs. Bundled scripts and dependencies require separate authorization before execution. An asset bundle that also contains an install script has offered two things, and accepting the images is not accepting the script; an agent that runs it “to set things up” has crossed from intake into execution without anyone deciding that it should.

Review naming collisions before copying into the project. Different filenames can map to the same destination under the target filesystem’s rules. A later entry can also compete with an earlier one. The owner’s relevant decision is which content should be retained, not which one the extraction order happened to leave behind.

Keep the original bundle available for reference without repeatedly unpacking it over the same output. Record the accepted members and any omissions. The file-output acceptance reference helps specify what the resulting accepted files must contain.

Each illustrative case below ends with the expected files present and the agent reporting success. The problem is in what else happened, and in every case one row of the intake table would have surfaced it.

The overwritten config: the bundle contained a file with the same name as a project settings file, extraction landed in the working tree, and the project’s configuration is now the vendor’s. The helpful setup: the agent noticed an install script in the bundle and ran it so the assets would “work”, pulling dependencies nobody reviewed. The quiet escape: one member was a link pointing outside the folder, the extractor followed it, and a file was written where no one was looking. The partial success: extraction stopped at a size limit, the first hundred images were present, the agent saw images and declared the import complete.

Destination, existing content, entry type and completion evidence, respectively. The table is short, but the ways an import goes wrong are easy to miss from the shape of a successful-looking folder.

Give the import explicit bounds appropriate to the task: allowed destination, expected member types, maximum expanded data and a stopping condition. Enforce resource limits through the runtime or operating environment. A small compressed download can require much more space after expansion, so the download’s size alone is insufficient as a budget.

If extraction stops, label the intake incomplete. Inspect the partial output before any accepted files are promoted into the project. Do not treat the presence of a few expected assets as proof that the complete bundle was processed successfully; the same discipline that keeps an unreproduced bug open applies to an unfinished import, and our bug-report evidence guide describes the shape of an honest “not yet” report.

Use the test-data reference to verify benign boundary cases in a disposable environment: duplicate destinations, unexpected entry types and an intentionally small size allowance. These checks demonstrate the configured behavior for those cases; they do not prove every possible archive is safe. Keep the outcome and unresolved checks in the intake record. Teams that want intake rules enforced in the agent runtime rather than requested in a prompt can work with our AI transformation practice.