docs(ai-sessions): document tool permissions and profile configuration#193
Merged
docs(ai-sessions): document tool permissions and profile configuration#193
Conversation
Add a dedicated reference page covering how allowed_tools, denied_tools, and permission_mode work in both user Profiles and ai_agent Hive records. Explains the Claude Code tool-name grammar (built-ins, Bash(prefix:*) pipeline-stage semantics, MCP mcp__server__tool names, the lc_call_tool meta-tool scoping), allow/deny precedence, permission modes, session-scoped approvals, and the defaults shipped to new users. Cross-link from the index, user-sessions, dr-sessions, and CLI pages, and add it to the AI Sessions nav section. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Use a popular security MCP server (VirusTotal) in the MCP pattern examples instead of the LimaCharlie MCP server, since the recommended path for agents talking to LimaCharlie is now the CLI rather than the MCP server. Also drop the lc_call_tool meta-tool scoping section for the same reason, and trim the unattended-D&R example to not wire in an LC MCP server. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Drop the "Task / Agent" dual-naming — the Claude Agent SDK surfaces
the subagent tool as Task.
- Fix the AskUserQuestion row: the tool routes questions to the
attached chat client (browser UI or `ai session attach`), not to
the ext-feedback extension's UI as I'd erroneously implied.
- Add MultiEdit to the list of tools acceptEdits auto-approves.
- Replace the invented `ai_agent.capture-profile` name with the real
`POST /v1/sessions/{sessionId}/capture-profile` API, and link it.
- Remove the "suffix matching for server name drift" paragraph. That
behaviour only lives in the bridge's session-scoped pattern matcher
and does not extend to Profile-level allowed_tools/denied_tools, so
stating it as a general Profile rule was wrong. Replace with a
simple pointer that the server_name in the pattern must match the
key in the mcp_servers map.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…e routing Tracks ai-sessions PR route-allowed-tools-through-matcher: profile `allowed_tools` now seed into the bridge's session-approved pattern set and are evaluated by the hardened matcher (pipeline-stage coverage, wrapper stripping, fail-close on $() / backticks / subshell grouping / newlines). `denied_tools` still goes to the Claude Agent SDK as `disallowed_tools` and uses the SDK's simpler literal-prefix matcher. - Label the "Matching semantics" section as allow-list behaviour and add an explicit denied_tools section documenting the SDK-level literal-prefix matcher (no stage coverage, no fail-close). - Rewrite the allowed_tools vs denied_tools section around the two enforcement layers (SDK deny → bridge allow → permission_mode fall- through). - Unify session-scoped approvals with profile allowed_tools — same pattern store, same matcher. - Fix the destructive-Bash-verbs example: a denied `Bash(rm:*)` does NOT block `ls && rm -rf /`; the correct containment comes from the allow-list matcher refusing to cover the `rm -rf /` stage. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Tracks ai-sessions commit 81b9969 "route denied_tools through the matcher; fix bare Bash allow regression": - denied_tools is now seeded into session_denied_patterns and evaluated by the bridge, not handed to the SDK's opts.disallowed_tools anymore. Both lists share the same pipeline splitting, wrapper stripping, env-assignment skip, and newline handling so an allow+deny pair can no longer be played against each other. - Restructure the Bash-pattern section into Common pre-processing + Allow semantics (all stages covered) + Deny semantics (any stage matching) + fail-closed-into-prompt on dangerous constructs. - Call out the bare-tool-name short-circuit (e.g. bare `Bash` means "every Bash invocation"; applies on both sides of the split). - Rewrite the allowed_tools vs denied_tools section around the deny-first / allow-second / permission_mode-fallback order, since both lists now live at the bridge layer. - Update the destructive-Bash-verbs example: a denied `Bash(rm:*)` now DOES block `ls && rm -rf /`, and `timeout 30 rm ...` is caught via the same wrapper-stripping as allow. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
maximelb
added
the
to-code-review
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
9-ai-sessions/tool-permissions.mdreference page explaining howallowed_tools,denied_tools, andpermission_modework in both user Profiles andai_agentHive records — the two surfaces that configure the Claude Agent SDK inside AI Sessions.Bash(prefix:*)pipeline-stage semantics and fail-closed rules,mcp__server__toolpatterns, and thelc_call_toolmeta-tool scoping), the allow/deny precedence,permission_modevalues (acceptEdits/plan/bypassPermissions) and when to pick which, session-scoped approvals, and the two default Profiles the session manager provisions for new users.index.md,user-sessions.md,dr-sessions.md, andcli.md; add the new page to the AI Sessions nav inmkdocs.yml.refractionPOINT/ai-sessions(scripts/sdk_bridge.py,internal/sessionmanager/profiles.go,internal/runner/config.go) andrefractionPOINT/legion_config_hive/hives/def_ai_agent.go, so every pattern/precedence claim is grounded in the code that evaluates it at tool-call time.Test plan
mkdocs build --strict— builds cleanly; no new warnings introduced by this change.🤖 Generated with Claude Code