Resource reuse can avoid sending the same file body to the model twice. It also records what the session observed before a proposed write. It does not start a tool, grant access, preserve a browser login or turn a conversation summary into a durable source.
This guide targets Sonny 0.12.7, source/build commit
192e590345c6a4bf1ef8f72b043b318084ea84d6. Controlled Linux tests used the
installed TUI, a real signed worker with required Docker isolation, a synthetic
provider and disposable files. Reads, explicit refresh, partial-read refusal,
new-file creation and fresh-session scope were observed. Existing-file
replacement and its recovery did not qualify; child launch also failed before
a child model request. These limits matter when reviewing the steps below.
You need an approved installation, Recipe, provider and workspace. Your operator
must provision the required execution boundary; sonny isolation doctor --json
can check that deployment. The fixture passed its doctor before running file
tools. A passing doctor establishes the checked boundary, not that every later
tool succeeds. See tools and permissions
and
security
for access and isolation setup.
Read a small source twice
Create a new private example directory and download the small note. Replace the absolute path with an approved location you own:
umask 077
RESOURCE_EXAMPLE_DIR=/absolute/private/sonny-resource-example
mkdir -m 700 "$RESOURCE_EXAMPLE_DIR"
curl --fail --location 'https://sonny.sh/examples/resources/notes.txt' -o "$RESOURCE_EXAMPLE_DIR/notes.txt"
Review the file, then start an approved session whose workspace is that
directory. Ask Sonny to use read_file on notes.txt twice, without editing it.
The controlled test’s first result contained both lines, a content digest and
coverage: full. Its second result had reused: true, an empty content field
and reused_from_call pointing to the first read. The earlier body remained in
the conversation; the compact result referred to it.
That compact record is not a new copy of the document. If you need the body
again, ask for read_file with these arguments:
{"path":"notes.txt","refresh":true}
The tested refresh returned both lines again. An isolated read still passes through tool admission and native file inspection before the session can substitute a compact record. Reuse is not permission to skip those checks. Its estimated byte saving is not a measured provider-token or billing saving.
Identify whose file version you are reading
The tested realm imported a copy of the workspace. A controlled edit to the
host’s notes.txt after that import did not change the active realm’s file:
even refresh: true returned the original realm bytes. A new session imported
the changed host file and returned its full body.
Keep the host workspace and the active realm separate in your reasoning.
refresh asks for the current file in the tool’s execution environment; it
does not synchronize the host checkout into an already running realm. Review
any intended export or handoff before starting another session. The
session guide
explains continuation and export boundaries. Check which
version contains the changes you need, and retain the source and task objective.
A new session is not evidence that a previous write reached the host.
The fixture’s realm-created files remained inside the realm. Native readbacks confirmed their contents, and the original host files were unchanged except for the explicitly controlled host edit. The fixture did not approve an export. Do not infer host publication from a successful isolated create response.
Review the basis of a write
A file observation includes its version and how much content the model saw.
An entire file and one displayed line give different bases for a replacement.
In the test, read_file with limit: 1 returned coverage: partial; a full
write_file replacement was refused with partial_basis. A later full read
returned both original lines.
The source defines these write conditions. The installed results distinguish what was actually exercised:
| Condition | Meaning and recovery | Tested 0.12.7 boundary |
|---|---|---|
partial_basis | A full replacement needs a complete basis; read the full file or review a targeted edit. | Partial-read replacement was refused. A full read succeeded, but replacement afterward still failed at publication. |
| No observation of an existing isolated file | An unobserved write is create-only under the strict defaults; it must not replace an existing target. | The existing target returned resource_exists; its original body remained readable. |
stale_resource | The proposed digest no longer describes the target; obtain the current content and review the change again. | The fixture could not change the prerequisite file through the native writer, so the stale-write and recovery positives remain unqualified. |
| Unknown or untrusted recorded state | Re-read the target before relying on that record for a write. | After an uncertified write result, a following attempt reported missing_observation with an unparseable_result reason. |
| New isolated file | A create-only condition must refuse an existing name. | Creating a new name and reading its body succeeded. A preceding missing-file read returned uncertified io_failed diagnostics; those diagnostics were not treated as trusted absence evidence. |
| Identical replacement | Source behavior can report no_change instead of claiming a mutation. | The tested replacement path failed, so no-change behavior is not certified here. |
Existing-file writes returned path_scope_denied: catalog: tool output was not certified, both for imported files and for a file the same realm had created
and read. Fresh readbacks still contained the old bytes. A full read did not
recover that failure in the tested deployment. The result does not establish
that the Recipe’s allowlist is wrong: the shared file writer can also map a
publication refusal to this code. Related workspace-write tracking
retains the installed evidence.
If you encounter this boundary, inspect the target before retrying, retain the
version and tool result, and use the supported operator/support route. Do not
widen permissions or switch to shell edits to make the refusal disappear. The
fixture’s attempted shell redirection was independently refused by the native
exec write guard. Neither a refusal nor a timeout is a general rollback
promise for other tools.
Write observations are local conflict checks, not a promise to coordinate every editor, session, filesystem or network mount. Keep a reviewed source and inspect the resulting file before depending on a write.
Inspect the effective configuration
The complete resource-reuse configuration contains the tested 0.12.7 defaults. Merge the block into the intended Sonny configuration, rather than replacing unrelated settings, then inspect it:
sonny config resource-reuse --json
The successful report contains the effective settings and a digest. It labels itself local configuration resolution; it is not proof that reuse or a write condition was applied to a tool call. Repeating the default report returned the same configuration digest, and the downloaded example resolved to those exact defaults.
| Setting | Default and scope |
|---|---|
enabled | true; controls read reuse and the tool-result pilot. Setting it false does not change the strict write-condition values in the report. |
file_versions.write_preconditions | required; advisory relaxes some missing-basis cases, not every conflict. |
file_versions.unobserved_replace | refuse; changing it is an operator policy choice. |
file_versions.max_bytes | 10 MiB bound for hashing one file. |
read_results.representation | auto; source currently treats it like compact. full requests full bodies instead of compact reuse. Both explicit values resolved successfully. |
read_results.max_entries / max_bytes | 4096 entries / 64 MiB retained-read budget. |
read_results.persist | false; a true value was refused. This release does not offer a persistent resource-body cache. |
tool_results.enabled / shadow | false / true; the separate directory/immutable-Git-result pilot is disabled by default. Inspecting its settings does not qualify pilot execution. |
telemetry.include_content | false; a true value was refused. This setting does not erase bodies already present in history, traces or exports. |
Configuration uses defaults, the selected file, then the supported environment
variables. In the controlled test, a project’s .sonny.yaml supplied these
resource settings even in an untrusted workspace and shadowed the home file.
Review a repository’s block before running Sonny there. These two environment
variables overrode weaker values in that file:
export SONNY_RESOURCE_REUSE_WRITE_PRECONDITIONS=required
export SONNY_RESOURCE_REUSE_UNOBSERVED_REPLACE=refuse
The other supported variables are SONNY_RESOURCE_REUSE_ENABLED,
SONNY_RESOURCE_REUSE_REPRESENTATION and SONNY_RESOURCE_REUSE_TOOL_RESULTS.
Use literal true or false for booleans; on was refused. No resource-reuse
command-line flags were found in the tested configuration command.
Invalid persistence, content telemetry, enum, bound and boolean inputs exited with code 3 in the installed fixture, with no setting name on stdout or stderr. Do not expect the source-described dotted-path diagnostic in that situation. Compare the changed setting with a known-good block and rerun the report. An empty output is not a successful configuration check; inspect the exit status.
Resource lifetime and child sessions
The pinned implementation keys file observations by tenant, principal, session, canonical workspace and realm incarnation. The service may exist for a whole process while retaining separate records for those scopes. A shared process or provider does not make observations interchangeable. In-memory records can also be evicted; retaining a record is not a durable-data guarantee.
| Resource | Ownership and lifetime boundary | Qualification here |
|---|---|---|
| File observation and retained read body | Session/workspace/realm-scoped; persist: true is unsupported. | Same-session compact reuse and full reads in a new session observed. |
| Isolated workspace files | Belong to the active realm copy; host publication is a separate reviewed operation. | Host/realm divergence, isolated creation and unchanged host targets observed. |
| Truncated tool output | Separate output/artifact cache, not a file observation or durable Memory record. | Source boundary; not a new output-cache lifecycle test. |
| Background job, language server or MCP connection | Owned by its configured session/service and execution node; inspect the live handle before reusing or stopping it. | Use the MCP lifecycle guide and the exact discovered tool schema. A file-cache hit does not establish process or connection reuse. |
| Child-session observations | A distinct child identity has its own scope; do not assume it received a parent’s retained body or open resource handle. | Native spawn_agent returned isolation_evidence_invalid before any child model request. Cross-child reuse remains unqualified. |
| Browser profile or system resource | Separate integration, permission and teardown lifecycle. | See the browser availability boundary ; no browser resource reuse is certified. |
After the refused child launch, the parent received a full read again. That is not evidence of a running child, a shared child cache or a successful handoff. The source also retires compact-delivery references when context is reset or compacted, so a later read can re-deliver a body the model may no longer hold; that lifecycle path is not newly certified by these file tests.
Closing a session’s in-memory record does not delete source files, history, traces, exports or Memory . Use the appropriate backup and privacy procedures for those artifacts. For custom resources, start with MCP and APIC , and review their access and lifetime contracts.