Skip to content

Understanding Tool Permissions

Sidekick uses an AI agent that can take actions on your behalf — reading decompiled code, renaming functions, running Python scripts, issuing debugger commands. Before you hand the agent broad authority, it helps to understand exactly how those actions are controlled and what you can do to keep the agent inside boundaries you are comfortable with.

This tutorial walks you through the current permissions model, from the moment the agent asks to run a tool, through tag-based rules and per-tool overrides, to the scopes where you can save your preferences.

What happens when a tool needs approval

Sidekick is fail-closed: a tool call requires approval unless a policy allows it. Sidekick ships with default application-wide rules that already allow most tool families (see Recommended starting configurations); anything not covered by a rule still asks. For your own chats, rules can come from the current chat, the current workspace, or the application-wide settings. Agents that Sidekick runs in the background on its own do not inherit your workspace or application-wide settings; each has its own rules, which you can change.

When the agent tries to use a tool that is not already allowed, the chat thread pauses and a tool call card appears in the conversation.

The card shows:

  • The tool name, its purpose, and its arguments
  • An Allow button with a dropdown arrow, and a Reject button with a dropdown arrow

Library-backed chat execution appears here as its own tool call. For example, running a Library script from chat shows up as library_python_run, which is categorized under library.run (and python.binja.run) and executes Python inside Binary Ninja.

The five actions

Clicking the main button performs the default action. Opening the dropdown reveals additional choices.

Allow menu:

Action What it does
Allow / Allow Once (default) Approves this single tool call. The next call from the same tool will ask again. The main button is labelled Allow; the first menu item is labelled Allow Once.
Allow all [tags] tools for this chat Approves the tool now and adds every tag shown in the brackets (comma-separated, used for the category-based rules explained below) to the allow list for the current chat only. Matching tools in that chat run without asking; the rule is stored with the chat and does not affect other chats.
Allow 'tool_name' for this chat Approves the tool now and adds this specific tool to the allow list for the current chat only.

In a background agent's chat (such as Notebook Validation), these two entries read "for Notebook Validation" instead of "for this chat". They add the rule to that agent's own permissions, so it applies to every run of that agent in all workspaces.

Reject menu:

Action What it does
Reject (default) Cancels the tool call and returns a rejection message to the agent.
Reject with Reason... Opens a text field so you can explain why you rejected the call. The agent receives your explanation and can adjust its approach.

Tip

"Allow for this chat" options are a good way to build momentum when you trust the current chat but are not ready to make a workspace-wide or application-wide change.

When approvals are pending only in sub-agent threads, the chat shows a notice with bulk actions as well: approve all pending calls once, reject them all, or allow the currently pending tool types for the rest of that chat.

Edit before approving

Next to the Allow and Reject buttons is an Edit button. Clicking it opens the tool call arguments as editable JSON, so you can modify parameters before the tool runs. Click Save to replace the call's arguments with your edits (the arguments must be a valid JSON object). The call stays pending, so click Allow afterwards to run the edited call, or Reject to refuse it. Cancel discards your edits and returns to the original approval prompt.

Opening the Tool Permissions Settings dialog

To configure standing rules that apply across sessions, open the dialog from the Binary Ninja menu:

Plugins > Sidekick > Configure Tool Permissions...

Note

This menu item is disabled (greyed out) until the current window has an active Sidekick workspace session (for example, after you open a binary or a project workspace).

The menu item opens the dialog with the This Workspace and All Workspaces scopes. To edit the This Chat scope, open the chat's menu (hamburger button) and choose Tool Permissions...; the dialog opened from there also offers This Chat.

The dialog (titled Tool Permissions Settings) has a Scope selector at the top that controls which level of settings you are editing, followed by a one-line description of the selected scope. Below that are two panes side by side:

  • Tags — a tree of tool categories with columns Tag, Tools (how many tools match the tag), Explicit, and Effective
  • Tools — the tools matched by the tag selected in the Tags pane (the pane is titled Tools Matching followed by the tag once you select one), with columns Tool, Explicit, and Effective

Each row has an Explicit selector with three radio buttons — Allow, Ask, and Inherit — that edits the rule stored at the selected scope. Effective is a badge showing the final permission for the current context after all scopes are combined.

Tag-based permissions

Every Sidekick tool belongs to one or more tags. Tags follow a dot-separated hierarchy. A parent tag can cover an entire family of tools, without you needing to name each tool individually.

The tag hierarchy

The dialog lists the tags of the tools available in your environment. The table below shows common examples.

Tag Description Example tools
repo All repository operations —
repo.read Read files read_repo_file, list_repo_files
repo.write Write or create files write_repo_file, delete_repo_file
repo.manage Repository management (create, commit) create_repo, commit_repo
ui All Binary Ninja UI operations —
ui.visible Read visible content get_visible_content
ui.selection Read the current selection get_selection
ui.navigation Open or navigate Binary Ninja UI views open_project_file
project Binary Ninja project —
project.read List files in the current project list_project_files
notebook All Notebook operations —
notebook.query Query notebook entries query_notebook
notebook.update Modify notebook entries and analysis context update_notebook, update_notebook_context
briefing All session briefing operations —
briefing.query Read the session briefing get_session_briefing
briefing.update Modify the session briefing update_session_briefing
database All decompilation database operations —
database.query Query the binary database query_database, inspect_type_usage, read_update_report, list_transactions, get_transaction
database.state Analysis status and mapping options get_analysis_status, get_mapping_options
database.update Modify the binary database update_database
index All index operations —
index.query Query indexes query_indexes
index.update Update indexes update_index
library All Library item tools —
library.search, library.manage Search Library items / create Library items search_library, ensure_library_item
library.run Run Library items and retrieve script outcomes/output library_python_run, library_agent_run, wait_script, read_script_output
codemap All code map operations —
codemap.query Query code maps query_code_maps
codemap.update Update code maps update_code_map
python All Python tools —
python.binja Python interpreter running inside Binary Ninja —
python.binja.run Run Python scripts inside Binary Ninja library_python_run
python.binja.eval Evaluate Python expressions python_eval
python.binja.typecheck Static type-check Python (Pyright) pyright_check
docs Bundled documentation tools search_docs, read_doc_page
debugger All debugger operations —
debugger.control Control execution debug_launch, debug_continue, debug_step
debugger.inspection Inspect state debug_inspect, debug_modules
debugger.mutation Modify registers or memory debug_write_register, debug_write_memory
debugger.backend Direct backend commands debug_backend_command
debugger.breakpoints Manage breakpoints debug_breakpoint
source.read Read source files read_source
terminal Run shell commands (asks by default) run_terminal_command
mcp Tools from configured MCP servers (asks by default) —
agent Tools for handing work from one agent to another —
system Sidekick's own housekeeping tools, such as starting and coordinating sub-agents and searching for tools —

How tag state works

Each scope stores an explicit tri-state for tags and tools:

  • Allow: tools matching that rule run without asking
  • Ask: tools matching that rule always require approval
  • Inherit: no explicit rule at this scope; Sidekick falls through to the next lower-precedence scope

Setting database to Allow stores an explicit Allow for the database tag. Any tool tagged database.query, database.update, or any other sub-tag under database matches that rule unless a more specific tag or tool override says otherwise.

Unlike older versions of the dialog, Sidekick does not expand a parent rule into explicit sibling rules behind the scenes. The UI shows inherited and effective state directly instead.

Note

Tags use prefix matching under the hood. A rule that allows database automatically covers any tool tagged database.query, database.update, or any other sub-tag under database.

Tool-specific overrides

The Tools pane lets you pin a single tool to Allow (never ask) or Ask (always ask, even if its tag would otherwise allow it), regardless of what the tag rules say.

Adding an override

  1. In the Tags pane, select a tag that covers the tool. Selecting a parent such as database lists all of its tools in the Tools pane.
  2. In the Tools pane, find the tool and set its Explicit radio button to Allow or Ask.

Changes apply immediately. The tool's Effective badge shows the resulting permission.

Removing an override

Set the tool's Explicit radio button back to Inherit. The tool reverts to whatever the tag rules say.

When overrides and tags conflict

An explicit tool Ask override always beats a tag allow. If database is allowed but you have added update_database as Ask, the agent will still ask before modifying your binary.

An explicit tool Allow override beats a tag set to Ask. If python.binja is set to Ask but you add python_eval as Allow, python_eval runs without asking while library_python_run still does.

The resolution order within any scope is:

  1. Explicit tool state
  2. The most specific matching tag state
  3. No rule at this scope — inherit to the next scope

If no scope allows the tool, the final result is Ask.

A tool can carry several tags. For example, library_python_run is tagged both library.run and python.binja.run. Across all of a tool's tags, the matching rule with the longest tag wins, and if two rules are equally specific, Ask wins. Because python.binja is Allow by default, setting only library.run to Ask at All Workspaces does not stop library_python_run. Also set python.binja (or python.binja.run), or the tool itself, to Ask. Use the Effective column to confirm the result.

Permission scoping

The Scope selector at the top of the dialog determines which layer you are reading and writing. Changes in one scope do not affect the others.

Scope Label in UI What it covers When to use
This Chat "Applies only to this chat." The current chat Grants for one chat only; they are saved with that chat and do not affect other chats. Appears only when the dialog is opened from a chat's Tool Permissions... menu item
This Workspace "Applies only to this workspace." The current Binary Ninja workspace Per-binary or per-project rules for your chats
All Workspaces "Applies across all workspaces and updates open user-owned workspaces immediately." The live application-wide policy for your chats Global preferences that should apply everywhere immediately

Note

For your chats, scopes are consulted in order from most specific to least: This Chat, then This Workspace, then All Workspaces. If a tool is set to Ask in "This Chat" but Allow in "This Workspace", the chat-level Ask wins for that session.

Settings saved to This Chat, This Workspace, and All Workspaces are all persisted between sessions. A This Chat rule is stored with that chat, so it lasts as long as the chat does.

Note

Sidekick's built-in background helpers (Notebook Validation and Analysis Briefings) start on their own, so they have their own permissions instead of yours. They do not inherit This Workspace or All Workspaces. Each comes with built-in rules that let it do its job without asking. Anything those rules don't allow asks for approval in that helper's chat. To change a helper's permissions, open Tool Permissions... from its chat menu. The only scope is the helper itself, for example Notebook Validation (All Workspaces). Your changes apply to that helper in every workspace. Set a rule back to Inherit to return to the built-in rule. Specialist agents that a helper or chat delegates to follow the same rules as whatever started them.

The Suggest commands are not background helpers. Each one opens a regular chat that uses your permissions.

Sidekick ships with default application-wide rules, which apply unless you override them in All Workspaces, This Workspace, or This Chat. By default these tag families are Allow: agent, briefing, codemap, database, docs, index, library, notebook, project, python.binja, repo, system, and ui, plus debugger.breakpoints and debugger.inspection. These tags are Ask: debugger (so debugger control, mutation, and backend commands), mcp, and terminal. Any tag with no rule, and any tool with no matching rule at any scope, still asks. The Effective column in the dialog shows the result.

Because most families already allow reads and writes, tightening means explicitly setting tags to Ask. The configurations below are suggested starting points, not presets — you configure them manually in the dialog.

There is no single correct configuration — it depends on what you are doing and how much you trust the current task. Three starting points are described below.

Conservative: approve everything

At All Workspaces (or This Workspace), set the tags the defaults allow to Ask: agent, briefing, codemap, database, docs, index, library, notebook, project, python.binja, repo, system, ui, debugger.breakpoints, and debugger.inspection. Every action the agent takes will require your explicit approval unless a more specific rule allows it.

This is appropriate when: - You are working with a sensitive or production binary - You are exploring what the agent does on a new binary for the first time - You want a complete audit trail of every agent action

The tradeoff is friction: multi-step analysis tasks will pause frequently waiting for your input.

Moderate: allow reads, ask before changes

Keep the default read tags allowed, and set the write and mutation tags to Ask in This Workspace scope so the rule applies to your chats on this binary:

  • database.update — renaming functions, adding types, writing comments
  • notebook.update — modifying notebook entries and analysis context
  • index.update and codemap.update — updating indexes and code maps
  • briefing.update — modifying the session briefing
  • library.run — launching Library items
  • python.binja — direct Python execution inside Binary Ninja
  • repo.write and repo.manage — file and repository changes

The agent can read freely (database.query, ui.visible, ui.selection, notebook.query, docs, index.query, codemap.query) but must ask before making any change.

This configuration suits most day-to-day reverse engineering sessions. The agent can investigate the binary, reason about it, and propose actions, while you review each proposed change.

Liberal: allow most tools

The defaults already allow reads and writes. To go further, set these tags to Allow:

  • debugger.control — lets the agent launch, continue, and step the debugger
  • source.read — lets the agent read source files

Leave the following requiring approval: - debugger.mutation and debugger.backend — modifying registers or memory and issuing raw backend commands carry significant risk - terminal — shell commands can do anything your user account can - mcp — tools from external MCP servers

If you want direct Python execution (python.binja.run, python.binja.eval) or repository changes (repo.write, repo.manage) to ask, set those tags to Ask, because they are allowed by default.

This configuration suits experienced users working on CTF challenges or personal research where convenience outweighs the risk of unreviewed database edits.

Warning

database.update is allowed by default, so your chats can rename functions and add annotations in every binary you open without asking. To opt in per binary instead, set database.update to Ask at the All Workspaces scope and set it to Allow only in the This Workspace scope of binaries you trust.

Putting it together: a practical example

Suppose you are analyzing a malware sample and want the agent to survey the binary, create a Notebook summary, and propose a list of interesting functions — but you do not want it modifying anything yet.

  1. Open Plugins > Sidekick > Configure Tool Permissions...
  2. Set scope to This Workspace.
  3. Set these tags to Ask: database.update, notebook.update, python.binja, repo.write, repo.manage.
  4. Leave everything else on Inherit.
  5. Click Close.

Now start a chat and ask Sidekick to survey the binary. The agent can read freely. When it eventually wants to write a Notebook entry summarizing its findings, it will pause and ask you — giving you a chance to review before anything is recorded.

After reviewing its summary and approving the notebook write, you can re-open the dialog and set notebook.update back to Allow (or Inherit) to let future writes go through automatically.

Next steps

Denying library.run also blocks later wait_script and read_script_output calls, not just new Library launches (unless an explicit tool override allows the call).