AgentDefinition and subagent frontmatter should support cwd and additionalDirectories for per-subagent directory scoping

[ckblockit]

Summary

There is currently no way to set a different cwd or additional allowed directories for a subagent. Both AgentDefinition (SDK) and file-based subagent frontmatter lack any directory-scoping fields. This makes per-subagent filesystem isolation impossible at the configuration level.

Current behavior

AgentDefinition (TypeScript SDK) supports:

description, tools, disallowedTools, prompt, model,
mcpServers, skills, maxTurns

File-based subagent frontmatter supports:

name, description, tools, disallowedTools, model,
permissionMode, maxTurns, skills, mcpServers, hooks,
memory, background, isolation

Neither supports cwd or additionalDirectories. Subagents always inherit the parent session's cwd, and additionalDirectories is only available on the top-level query() options — applying to the entire session, not per-agent.

Expected behavior

AgentDefinition and file-based frontmatter should support:

// SDK
const agents = {
  "user-reader-user1": {
    description: "Reads user1's private data",
    prompt: "...",
    tools: ["Read"],
    cwd: "/workspace",                          // override cwd
    additionalDirectories: ["users/user1"],     // allow this dir only
  }
}

# .claude/agents/user-reader-user1.md
---
name: user-reader-user1
description: Reads user1's private data
tools: Read
additionalDirectories:
  - users/user1
---

Why this matters

Concrete use case: A scheduling agent where the orchestrator spawns per-user subagents to read private calendar and contact data from users/{userId}/. The orchestrator should have no access to user data; each user-subagent should be scoped to its own user's directory.

Without directory scoping per subagent:

• The only workaround is PreToolUse hooks with union-based enforcement (see related issue PreToolUse hook input should include agent_id to identify subagent origin #31939), which breaks down when multiple user-subagents run in parallel
• isolation: worktree goes the wrong direction — it isolates the subagent into a fresh git worktree that lacks runtime-generated user data entirely
• additionalDirectories on the parent query() grants the directories to all agents in the session, not just the intended subagent

With additionalDirectories on AgentDefinition / frontmatter:

• Each subagent is declaratively scoped to exactly the directories it needs
• No hook gymnastics required
• Works correctly for parallel subagents of the same type operating on different users

Related

• PreToolUse hook input should include agent_id to identify subagent origin #31939 — PreToolUse hook input missing agent_id (the other half of this problem — without either fix, per-subagent isolation requires fragile workarounds)

Verified SDK version

@anthropic-ai/claude-agent-sdk v0.2.52

[yurukusa]

Until per-subagent directory scoping is supported:

Agent(subagent_type: "general-purpose", isolation: "worktree", prompt: "Work in src/backend/...")

isolation: "worktree" creates a separate git worktree for the subagent, providing filesystem isolation. The subagent works in its own copy and changes are merged back.

INPUT=$(cat)
if [ -n "$CLAUDE_AGENT_NAME" ]; then
  FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
  ALLOWED_DIR="src/$CLAUDE_AGENT_NAME"
  if [ -n "$FILE" ] && ! echo "$FILE" | grep -q "^$ALLOWED_DIR"; then
    echo '{"decision":"deny","message":"Subagent restricted to '$ALLOWED_DIR'"}'
  fi
fi
exit 0