How to Persist Tool Permissions in Amazon Q Developer CLI

Background

When using Amazon Q Developer CLI, permission requests appear every time tools are called, interrupting the workflow. Even after granting permission multiple times in the same project, the requests reappear when the session changes, making it tedious to repeat the same actions repeatedly.

This article explains the types of tool permission settings in Q Developer CLI and how to persist them across sessions.
Please note that this information is as of August 2025, as this tool evolves very rapidly.

Types of Permission Settings

While I wanted to configure tool permissions across sessions, I also investigated within-session settings.

Permission Settings Within Sessions

1. Setting with Slash Commands

After starting a session with the q command, you can set permissions using slash commands:

# Allow specific tools
/tools trust @mcp_name/tool_name

# Allow all tools
/tools trust-all

2. Setting with Command Arguments

You can specify permissions with arguments when starting a session:

# Allow specific tools
q chat --trust-tools @mcp_name/tool_name

# Allow all tools
q chat --trust-all-tools

Issues with Within-Session Settings

• Settings must be configured every time a new session starts
• Individual specification is cumbersome when there are many MCP tools
• trust-all is dangerous

Persistence Across Sessions

Solution with Custom Agents

While persisting tool permissions across sessions was previously impossible, it became possible with the Custom Agents feature released on July 31, 2025.
Custom Agents are originally designed as agents for specific tasks or as Sub Agents called from the Main Agent, but they can also be used as a means to persist permissions.

https://aws.amazon.com/about-aws/whats-new/2025/07/amazon-q-developer-cli-custom-agents/
https://aws.amazon.com/jp/blogs/news/overcome-development-disarray-with-amazon-q-developer-cli-custom-agents/

Creating Configuration Files

Create a configuration file in the .amazonq/cli-agents/ directory:

{
  "$schema": "https://raw.githubusercontent.com/aws/amazon-q-developer-cli/refs/heads/main/schemas/agent-v1.json",
  "name": "your-custom-agent",
  "description": "your-agent-description",
  "prompt": "your-custom-agent-prompt",
  "tools": ["*"],
  "allowedTools": [
    "@filesystem/read_file",
    "@filesystem/write_file"
  ],
  "resources": [
    "file://README.md",
    "file://.amazonq/rules/**/*.md"
  ],
  "useLegacyMcpJson": true
}

Starting the Agent

Start the agent by specifying the created agent:

q chat --agent your-custom-agent

The permissions for the specified tools are then available in the ready state.

Thoughts

With Claude Code, you can adjust permissions in various ways, such as persisting them as project-specific settings in settings.json. For Q CLI, it’s not currently that flexible, and the design philosophy seems to prioritize security and simplicity.

Also, the fact that Custom Agents can persist permissions might be because they are entities used by the Main Agent, and constantly asking users for permissions would significantly impair autonomy.

Summary

• Within sessions: Temporarily set with --trust-tools or /tools trust
• Across sessions: Persist permissions with Custom Agents

This approach allows for more efficient workflows while maintaining the security-focused design of Amazon Q Developer CLI.

Original Article

This is the English translation of my Japanese article:
https://zenn.dev/arvehisa/articles/amazon-q-dev-cli-permission-session-persistence