Summary
I attempted to restrict the tools available to an Agent session according to the official Anna developer documentation. The intended policy was to allow only fs_read_file and prevent access to fs_write_file.
After two rounds of testing in a local anna-app dev environment, the session still received the complete Host tool set and successfully executed fs_write_file, even though it was not included in the allowlist.
The session reported:
{
"inherit_host_tools": true,
"granted_tools": ["*"]
}
The subsequent fs_write_file call completed successfully. It is therefore unclear whether quotaCaps.inherit_host_tools, session-level quotaCaps.allowed_tools, or run-level allowed_tools is currently enforced in this environment.
Expected Behavior Based on the Official Documentation
I reviewed the official documentation index at https://staging.anna.partners/llms.txt, as well as the following related pages:
- App-Side LLM & Agent API
agent.*— agent sessions- Platform tools — the agent-session tool universe
- Agent Sessions — Multi-turn Tool-using Runs
My understanding of the documented behavior is as follows:
-
agent.session.createcan restrict a session throughquotaCaps:anna.agent.session.create({ submode: "auto", quotaCaps: { inherit_host_tools: false, allowed_tools: ["fs_read_file"], }, }); -
agent.session.runcan restrict an individual run throughallowed_tools:anna.agent.session.run({ app_session_uuid, content, allowed_tools: ["fs_read_file"], }); -
manifest.ui.host_api.agent.toolsshould define the App-level tool boundary. -
The documentation also states that when a session inherits the Host tool set with
inherit_host_tools: true, per-runallowed_toolsdoes not further narrow the inherited tool surface.
There appears to be some inconsistency between the documentation pages. The detailed agent.session.create signature primarily lists numeric quotaCaps fields, while other pages explicitly describe inherit_host_tools and allowed_tools. This report is intended to clarify the actual support status of these fields in the current staging and development implementations.
Local Test Environment
- Test command:
anna-app dev - Test App:
examples/test-session-app - Runtime: Anna App Runtime
- CLI and schema versions: local
@anna-ai/cli0.1.40 and@anna-ai/app-schema0.18.0 - Invocation method: low-level raw RPC calls
anna.agent.session.create(...)anna.agent.session.run(...)anna.agent.session.delete(...)
- Test objective: allow the session to read files but prevent it from writing files
Manifest Configuration
Both test runs used the same App manifest:
{
"schema": 2,
"permissions": [],
"required_executas": [],
"optional_executas": [],
"ui": {
"host_api": {
"agent": {
"session": {
"auto": true,
"fixed": null
},
"tools": []
}
}
}
}
The complete manifest does not grant additional access through other Host API namespaces. The portion directly relevant to this issue is:
"agent": {
"session": {
"auto": true,
"fixed": null
},
"tools": []
}
Test 1: Applying the Tool Restriction in session.create
Session creation code
const raw = await anna.agent.session.create({
submode: "auto",
quotaCaps: {
inherit_host_tools: false,
allowed_tools: ["fs_read_file"],
},
});
Run code
The first test did not repeat the tool allowlist in run:
const runResult = await anna.agent.session.run({
app_session_uuid: id,
content,
});
Result
The session returned the following run_meta frame:
{
"submode": "auto",
"inherit_host_tools": true,
"granted_tools": ["*"]
}
I then performed two operations:
fs_read_filesuccessfully read a file.fs_write_filesuccessfully modified a file.
Although fs_write_file was not included in the requested allowlist, the server returned a successful result:
{
"success": true,
"data": {
"path": "/Users/leyouming/anna-workspace/.docs/tmp.txt",
"size": 34
}
}
This indicates that the create-level inherit_host_tools: false and allowed_tools: ["fs_read_file"] settings did not produce the expected restriction in this environment.
Test 2: Applying the Tool Restriction Only in session.run
To distinguish session creation behavior from per-run behavior, the second test restored session creation to its default configuration and passed the allowlist only to the individual run.
Session creation code
const raw = await anna.agent.session.create({
submode: "auto",
});
Run code
const runResult = await anna.agent.session.run({
app_session_uuid: id,
content,
allowed_tools: ["fs_read_file"],
});
Result
The second test also returned:
{
"submode": "auto",
"inherit_host_tools": true,
"granted_tools": ["*"]
}
I then asked the Agent to modify a file. The Agent invoked:
fs_write_file
The tool call completed successfully:
{
"success": true,
"data": {
"path": "/Users/leyouming/anna-workspace/.docs/tmp.txt",
"size": 52
}
}
The run-level allowed_tools: ["fs_read_file"] setting therefore did not prevent fs_write_file from executing.
Expected vs. Actual Behavior
| Item | Expected | Actual |
|---|---|---|
Create-level inherit_host_tools |
false |
true |
Create-level allowed_tools |
Only fs_read_file is available |
granted_tools: ["*"] is returned |
Run-level allowed_tools |
Only fs_read_file is available for the run |
fs_write_file executes successfully |
| Host tool set | File-writing tools should not be available | The complete Host tool set remains available |
Possible Causes
I cannot determine which layer is responsible for the behavior. Could you please confirm whether one of the following explanations applies?
-
The server-side session minting logic does not process the tool-scope fields
The server may not read
quotaCaps.inherit_host_tools, or the requestedfalsevalue may be overwritten by a default value oftruewhen the request is intersected with the user’s grant. -
quotaCaps.allowed_toolsmay be documented but not yet implemented by the current APIThe returned
granted_tools: ["*"]indicates that the session did not receive a Sandbox tool surface. -
Run-level
allowed_toolsis intentionally ignored for sessions that inherit Host toolsThe official Platform tools page states that a session inheriting the Host tool set cannot be narrowed through per-run
allowed_tools. The observed result is consistent with that statement. -
The development grant may enable the complete Host tool set by default
The grant used by
anna-app devmay forceinherit_host_tools: true, preventing an App from creating a genuine Sandbox session in the development environment. -
Manifest-level
agent.tools: []does not restrict inherited Host toolsThe manifest declares an empty
agent.toolsarray, but the session still receivesgranted_tools: ["*"]. It would be helpful to confirm whether this is the expected inheritance behavior or whether the manifest ACL is not being applied on this path.
Questions
- Are
quotaCaps.inherit_host_toolsandquotaCaps.allowed_toolsonagent.session.createcurrently supported in the staging environment? - If the user’s grant permits Host tool inheritance, can an App still create a Sandbox session by explicitly passing
inherit_host_tools: false? - Is
agent.session.run.allowed_toolssupported only for Sandbox sessions? - Can
fs_read_fileandfs_write_filebe controlled independently through the Sandbox registry? - What is the recommended way for an App to create an Agent session that can read files but is explicitly prohibited from writing them?
Conclusion
In the current local anna-app dev environment, neither of the following configurations achieved the intended policy of allowing fs_read_file while preventing fs_write_file:
- Create-level restriction:
quotaCaps.inherit_host_tools: falsetogether withquotaCaps.allowed_tools: ["fs_read_file"] - Run-level restriction:
allowed_tools: ["fs_read_file"]
In both tests, the session received the complete Host tool set and successfully executed fs_write_file. I would appreciate clarification on whether this behavior is caused by an implementation issue, development-specific grant behavior, or documentation that does not yet match the currently deployed API version.
