Claude Code Reference

Invoke the Claude Code agent for sub-tasks using structured JSON output and explicit session management.

When to Use Claude Code

Use Claude Code when you need:

• Complex reasoning and planning - Uses opusplan model for sophisticated analysis

• Multi-file refactoring - Excellent at understanding and modifying across large codebases

• Tool-rich operations - File operations, Bash execution, Web search, MCP servers

• Persistent sessions - Continue complex tasks across multiple interactions

Capabilities

• Core Tools: File operations (Read, Write, Edit, Glob, Grep), Bash execution (safe subset).

• Web: WebSearch , WebFetch .

• MCP Servers:

• context7 : Documentation queries.

• brave-search : Web search (Brave).

• Specialty: Excellent at planning, reasoning, and complex refactoring. Uses opusplan model.

Calling from Another Agent

Use claude -p "prompt" to spawn Claude as a sub-agent for delegated tasks:

Delegate a complex analysis task

result=$(claude -p "Analyze the authentication flow in @src/auth/ and identify security issues"
--output-format json --allowedTools "Read,Glob,Grep")

Extract the response and session_id for follow-up

response=$(echo "$result" | jq -r '.response') session_id=$(echo "$result" | jq -r '.session_id')

Output Formats

Format Description

text (default) Plain text output

json

Single JSON result with response , session_id , usage , permission_denials

stream-json

Real-time streaming JSON events

JSON Response Fields:

• response : (string) The agent's final answer

• session_id : (string) UUID for continuing the session

• usage : (object) Token usage and cost information

• permission_denials : (array) Tools that were blocked and need approval

Handling Permission Denials

When Claude needs tools you didn't pre-approve, the command completes but includes permission_denials . Continue the session with expanded permissions:

Step 1: Initial attempt with limited permissions

result=$(claude -p "Fix the build errors" --output-format json --allowedTools "Read,Glob")

Step 2: Check if permissions were denied

denials=$(echo "$result" | jq -r '.permission_denials')

if [[ $(echo "$denials" | jq 'length') -gt 0 ]]; then echo "Additional permissions needed: $denials" session_id=$(echo "$result" | jq -r '.session_id')

Step 3: Continue session with expanded permissions

result=$(echo "Continue fixing build errors, you now have permission to run commands"
> /tmp/continue.md claude -p "Read /tmp/continue.md"
--session-id "$session_id"
--output-format json
--allowedTools "Read,Glob,Grep,Bash(npm *),Bash(node *),Edit") fi

Extract final response

final_response=$(echo "$result" | jq -r '.response')

Session Management for Agent Delegation

Starting a Task

mkdir -p .claude/sessions echo "*" > .claude/.gitignore

Write the task with full context

cat > .claude/sessions/task.md << 'EOF' Analyze the database schema in @src/models/ and:

1. Identify missing indexes
2. Check for N+1 query patterns
3. Suggest optimizations EOF

Spawn Claude with scoped permissions

result=$(claude -p "Read .claude/sessions/task.md"
--output-format json
--allowedTools "Read,Glob,Grep")

Capture session info

session_id=$(echo "$result" | jq -r '.session_id') rm .claude/sessions/task.md

Resuming a Session

Continue a specific session when you have the session_id :

echo "Based on your analysis, implement the top 3 optimizations" > .claude/sessions/continue.md

result=$(claude -p "Read .claude/sessions/continue.md"
--session-id "$session_id"
--output-format json
--allowedTools "Read,Edit,Bash(git *)")

rm .claude/sessions/continue.md

Important: Always use explicit --session-id instead of --continue when calling from another agent.

Permission Handling

By default, Claude Code requests permission for actions that modify your system. When calling from another agent, pre-approve specific tools:

--allowedTools

Specify which tools Claude can use without prompting:

Read-only analysis

claude -p "Analyze codebase" --allowedTools "Read,Glob,Grep"

Code editing with git

claude -p "Fix lint errors" --allowedTools "Edit,Bash(git status),Bash(git diff *),Bash(git add *),Bash(git commit *)"

Nix operations

claude -p "Update package hashes" --allowedTools "Read,Edit,Bash(nix-prefetch-*),Bash(nix build *)"

Permission rule syntax:

- "Read" - allows all Read operations

- "Bash(git *)" - allows Bash commands starting with "git "

- Separate multiple with commas

Permission Modes

Use --permission-mode for high-level permission behavior:

Mode Description

default

Prompt for permission on sensitive actions

acceptEdits

Automatically accept file edits

plan

Start in Plan Mode (read-only exploration)

dontAsk

Don't ask for permissions (still checks)

bypassPermissions

Skip all permission checks (use with caution)

Agent Delegation Patterns

Pattern 1: Initial Exploration → Implementation

Phase 1: Exploration (read-only)

explore_result=$(claude -p "Explore @src/ to understand the codebase structure"
--output-format json --allowedTools "Read,Glob")

session_id=$(echo "$explore_result" | jq -r '.session_id')

Phase 2: Implementation (with edit permissions)

impl_result=$(echo "Implement a logging middleware following the patterns you found"
| claude -p "$(cat)" --session-id "$session_id" --output-format json
--allowedTools "Read,Write,Edit")

Pattern 2: Permission Escalation

Start conservative

result=$(claude -p "Fix the bug" --output-format json --allowedTools "Read")

Check what was denied

denied=$(echo "$result" | jq -r '.permission_denials[] | select(.tool_name == "Bash")')

if [[ -n "$denied" ]]; then session_id=$(echo "$result" | jq -r '.session_id')

Re-run with broader permissions

result=$(claude -p "Continue fixing with command execution allowed"
--session-id "$session_id" --output-format json
--allowedTools "Read,Bash(*),Edit") fi

Pattern 3: Parallel Sub-Agents

Spawn multiple Claude sessions for different tasks

result1=$(claude -p "Analyze security" --output-format json &) result2=$(claude -p "Analyze performance" --output-format json &) result3=$(claude -p "Check test coverage" --output-format json &)

wait

Combine results...

Code Review Delegation

To delegate code review to Claude:

mkdir -p .claude/sessions echo "Run 'jj diff -s -r @-' and 'jj diff -r @-' and review the output." > .claude/sessions/review.md

result=$(claude -p "Read .claude/sessions/review.md"
--output-format json
--allowedTools "Bash(jj *)")

rm .claude/sessions/review.md

Important: Do not allow Edit/Write tools during reviews - keep it read-only.

Additional Useful Flags

Flag Description

--model

Set model (sonnet/opus/haiku)

--max-turns

Limit agentic turns before stopping

--max-budget-usd

Max spend before stopping

--tools

Restrict available tools (vs allow them)

--verbose

Full turn-by-turn output

--no-session-persistence

Don't save to disk (one-off tasks)

--system-prompt

Replace system prompt

--append-system-prompt

Append to system prompt

Best Practices for Agent Delegation

Prompting

• Be Specific: Provide clear goals, file paths, and constraints.

• Include Context: The spawned agent can't see your context - include relevant files with @path .

• Provide Verification: Include success criteria so Claude can verify its work.

Permission Safety

• Start Conservative: Use minimal --allowedTools initially.

• Escalate as Needed: Check permission_denials and continue with broader permissions.

• Never use --dangerously-skip-permissions : Always use scoped --allowedTools .

Session Management

• Always Extract session_id: Capture it from JSON output even if you don't plan to continue.

• Session per Task: Use separate sessions for unrelated tasks.

• Check permission_denials: Always inspect this array in the JSON response.

Cost Control

• Use --max-budget-usd : Prevent runaway costs in automation.

• Use --max-turns : Limit how long the agent runs.

• Monitor usage: Check the usage field in JSON output.

Example: Complete Agent Delegation Workflow

#!/bin/bash

1. Create temp directory

mkdir -p tmp/.claude && echo "*" > tmp/.gitignore

2. Write task with full context

cat > tmp/task.md << 'EOF' Analyze the codebase and provide:

1. Architecture overview
2. Potential security issues
3. Performance bottlenecks

Focus on @src/ and @config/ directories. EOF

3. Spawn Claude with initial permissions

result=$(claude -p "Read tmp/task.md"
--output-format json
--allowedTools "Read,Glob,Grep"
--max-budget-usd 2.00)

4. Check for permission issues

denials=$(echo "$result" | jq '.permission_denials') if [[ $(echo "$denials" | jq 'length') -gt 0 ]]; then echo "Note: Some tools were denied: $(echo "$denials" | jq -r '.[].tool_name')" fi

5. Extract results

response=$(echo "$result" | jq -r '.response') session_id=$(echo "$result" | jq -r '.session_id') usage=$(echo "$result" | jq -r '.usage')

6. Report findings to parent agent

echo "=== Analysis Complete ===" echo "Session ID: $session_id" echo "Usage: $usage" echo "" echo "$response"

7. Optional: Continue for implementation

echo "Now implement the security fixes" > tmp/implement.md

claude -p "Read tmp/implement.md" --session-id "$session_id" ...

8. Clean up

rm -rf tmp