Give background sub-agents the same tool permissions as foreground#150
Merged
Conversation
Background sub-agents (the Agent tool with run_in_background) had their nested Write/Edit/Bash denied: a detached, non-blocking task can't surface an approval prompt, so the CLI denies tools needing one and can_use_tool is never invoked for them. Add a catch-all PreToolUse hook that pre-approves all non-interactive tools (a hook fires for nested background-subagent calls where can_use_tool can't reach). Interactive tools and Read still defer to can_use_tool / the image validator, so web pause-for-input and image validation are unchanged. Gated by agent.background_agent_permissions (default true).
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.
Problem
Sub-agents spawned via the
Agenttool withrun_in_background: trueget permission-denied for their nestedWrite/Edit/Bashcalls, so background build/write agents silently fail and must be run in the foreground.Root cause (empirically verified)
A background sub-agent is detached and non-blocking, so the CLI has no way to surface an approval prompt for its nested tool calls. Nerve grants permissions entirely through the
can_use_toolcallback (nopermission_mode, no staticallowed_tools), and that callback is never invoked for a background sub-agent's nested calls — the CLI denies upstream.Tested against
claude_agent_sdk0.2.104:can_use_toolreached?agent_id)Key finding: a
PreToolUsehook does fire for those nested background-subagent calls (it's a programmatic callback, not a user-facing prompt), wherecan_use_toolcannot reach. ReturningpermissionDecision: "allow"from a hook grants the permission.Fix
A catch-all
PreToolUsehook inAgentEngine._build_hooksthat pre-approves all non-interactive tools, giving background sub-agents the same auto-approval foreground agents already get:AskUserQuestion,ExitPlanMode,EnterPlanMode) → left untouched, so they still defer tocan_use_tooland the web pause-for-input flow is unchanged.Read→ left untouched, so the existing image-validator's deny still wins.allowed_toolsallowlist because the hook also covers dynamically-discovered MCP tools (the original reason the engine avoided an allowlist).Gated by a new config flag
agent.background_agent_permissions(defaulttrue; setfalseto restore the previous CLI-default behavior).Verification
_build_hooks()into a live background sub-agent: flag on → nested write succeeds, flag off → denied (prior behavior preserved).TestBuildHooksBackgroundPermissions); full suite green (123 passed).Security note
This extends Nerve's existing "auto-approve all non-interactive tools" posture (already true for foreground via
can_use_tool) to background sub-agents — no new risk class relative to foreground. A future ALLOW/CONFIRM/DENY tool-policy classifier would need wiring into bothcan_use_tooland this hook.