Deep Dive into Open Agent SDK (Part 5): Session Persistence and Security

An Agent is more than a one-shot Q&A tool. A truly useful Agent must do three things: remember context (where we left off), control permissions (which operations are allowed), and audit behavior (who did what and when). Open Agent SDK uses four subsystems to cover these needs — SessionStore, PermissionPolicy, SandboxSettings, and HookRegistry.

This article analyzes the implementation details of these four subsystems, how each works individually, and how they combine to build a secure Agent.

1. Session Persistence: SessionStore

Each Agent Loop run produces a messages array. Without persistence, it's lost when the process exits. SessionStore persists this conversation history to disk for restoration on next startup.

What Is SessionStore

SessionStore is an actor — all methods require await. By default, sessions are stored in ~/.open-agent-sdk/sessions/, with one subdirectory per session containing a transcript.json file.

let sessionStore = SessionStore()  // Default path
let sessionStore = SessionStore(sessionsDir: "/custom/path")  // Custom path

Five Core Operations

SessionStore provides five core methods covering the full session lifecycle.

save — Save a session. Serializes the messages array and metadata to JSON and writes to disk:

try await sessionStore.save(
    sessionId: "my-session",
    messages: messages,
    metadata: PartialSessionMetadata(
        cwd: "/project",
        model: "claude-sonnet-4-6",
        summary: "Code analysis session",
        tag: "analysis",
        firstPrompt: "Analyze project structure"
    )
)

Storage structure:

~/.open-agent-sdk/sessions/
  my-session/
    transcript.json    // { "metadata": {...}, "messages": [...] }

File permissions are 0600, directory permissions 0700 — only the current user can read/write. Each save preserves the original createdAt timestamp, updating only updatedAt.

load — Load a session. Reads transcript.json from disk and deserializes into SessionData:

if let data = try await sessionStore.load(sessionId: "my-session") {
    print("Messages: \(data.metadata.messageCount)")
    print("Model: \(data.metadata.model)")
    // data.messages is [[String: Any]] array
}

load supports pagination parameters limit and offset for loading only the tail when full history isn't needed:

// Load only the last 50 messages
let recent = try await sessionStore.load(sessionId: "my-session", limit: 50, offset: nil)

list — List all sessions, sorted by updatedAt descending (most recent first):

let sessions = try await sessionStore.list(limit: 10)
for session in sessions {
    print("\(session.id) — \(session.summary ?? "(untitled)") [\(session.messageCount) messages]")
}

SessionMetadata includes id, cwd, model, createdAt, updatedAt, messageCount, and optional summary, tag, firstPrompt, gitBranch, fileSize.

fork — Fork a session. Copies messages from an existing session to a new one, optionally specifying a truncation point:

// Full copy
let newId = try await sessionStore.fork(sourceSessionId: "my-session")

// Copy only the first 10 messages
let truncatedId = try await sessionStore.fork(
    sourceSessionId: "my-session",
    upToMessageIndex: 10
)

// Specify new session ID
let customId = try await sessionStore.fork(
    sourceSessionId: "my-session",
    newSessionId: "forked-session"
)

delete — Delete an entire session directory:

let deleted = try await sessionStore.delete(sessionId: "my-session")

Additional helper methods include rename (change title) and tag (add tags).

Three Session Recovery Modes

When SessionStore is injected into an Agent, the SDK provides three recovery strategies:

1. Specified sessionId Recovery

The most direct approach: given a session ID, the Agent loads historical messages at startup, prepending them to the messages array:

let agent = createAgent(options: AgentOptions(
    apiKey: apiKey,
    model: "claude-sonnet-4-6",
    sessionStore: sessionStore,
    sessionId: "my-session"      // Specify which session to restore
))

2. continueRecentSession — Auto-Continue Most Recent

When you don't know the session ID, let the SDK automatically find the most recent one:

let agent = createAgent(options: AgentOptions(
    apiKey: apiKey,
    model: "claude-sonnet-4-6",
    sessionStore: sessionStore,
    continueRecentSession: true   // Auto-load most recent session
))

Internally calls sessionStore.list() and takes the first result (already sorted by updatedAt descending).

3. forkSession + resumeSessionAt — Fork and Truncate

Fork a new branch from an existing session, optionally truncating at a specific message:

let agent = createAgent(options: AgentOptions(
    apiKey: apiKey,
    model: "claude-sonnet-4-6",
    sessionStore: sessionStore,
    sessionId: "my-session",
    forkSession: true,                     // Copy to new session
    resumeSessionAt: "msg-uuid-123"        // Truncate at this message
))

SDK parsing order: continueRecentSession determines session ID first, then forkSession creates a fork, then resumeSessionAt truncates history. These three options work independently or in combination.

SessionStore Security Details

SessionStore includes path traversal prevention in session ID validation:

private func validateSessionId(_ sessionId: String) throws {
    guard !sessionId.isEmpty else {
        throw SDKError.sessionError(message: "Session ID must not be empty")
    }
    let forbidden = ["/", "\\", ".."]
    for component in forbidden {
        if sessionId.contains(component) {
            throw SDKError.sessionError(message: "Session ID contains invalid character: '\(component)'")
        }
    }
}

Session IDs cannot contain /, \, or .. — preventing attackers from crafting IDs to read/write unexpected paths.

2. Permission Control: PermissionPolicy

Session persistence solves "remembering." Permission control solves "what's allowed."

Six PermissionModes

The SDK defines 6 permission modes:

Mode	Behavior
`default`	Ask user before each tool execution
`plan`	Read-only tools execute directly; write operations require confirmation
`auto`	Automatically execute all tools except dangerous operations
`acceptEdits`	File edits auto-execute; other operations require confirmation
`dontAsk`	Don't ask user; auto-judge based on context
`bypassPermissions`	Skip all permission checks

let agent = createAgent(options: AgentOptions(
    apiKey: apiKey,
    model: "claude-sonnet-4-6",
    permissionMode: .plan  // Read-only tools run directly; writes need confirmation
))

canUseTool Callback: More Granular Than PermissionMode

permissionMode is a global switch with coarse granularity. For fine-grained control by tool name or properties, use the canUseTool callback:

let agent = createAgent(options: AgentOptions(
    apiKey: apiKey,
    model: "claude-sonnet-4-6",
    permissionMode: .bypassPermissions,
    canUseTool: { tool, input, context in
        if tool.name == "Bash" {
            return CanUseToolResult.deny("Bash is not allowed")
        }
        return nil  // nil means "no opinion, defer to permissionMode"
    }
))

canUseTool returns CanUseToolResult?. Returning nil means the callback has no opinion, passing to the next check. Non-nil results use the callback's decision, ignoring permissionMode.

CanUseToolResult has three factory methods:

CanUseToolResult.allow()                              // Allow
CanUseToolResult.deny("reason")                          // Deny
CanUseToolResult.allowWithInput(modifiedInput)         // Allow but modify input parameters

allowWithInput is rare but practical — you can modify tool input parameters during permission checks, such as redirecting file write paths to a safe directory.

Policy Pattern: Composable Permission Rules

Writing closures is flexible but not reusable. The SDK provides a PermissionPolicy protocol, encapsulating permission judgments as composable policies:

public protocol PermissionPolicy: Sendable {
    func evaluate(
        tool: ToolProtocol,
        input: Any,
        context: ToolContext
    ) async -> CanUseToolResult?
}

Four built-in policies:

ToolNameAllowlistPolicy — Allowlist, only permits specified tools:

let policy = ToolNameAllowlistPolicy(allowedToolNames: ["Read", "Glob", "Grep"])
// Write, Edit, Bash etc. all denied

ToolNameDenylistPolicy — Denylist, rejects specified tools:

let policy = ToolNameDenylistPolicy(deniedToolNames: ["Bash", "Write"])
// Other tools execute normally

ReadOnlyPolicy — Only allows read-only tools (isReadOnly == true):

let policy = ReadOnlyPolicy()
// Read, Glob, Grep, WebSearch etc. allowed
// Write, Edit, Bash etc. denied

CompositePolicy — Combines multiple policies, evaluated in order:

let policy = CompositePolicy(policies: [
    ToolNameDenylistPolicy(deniedToolNames: ["Bash"]),
    ReadOnlyPolicy()
])
// Denylist checked first (Bash denied), then read-only policy

CompositePolicy evaluation rules:

Any sub-policy returning deny causes overall deny (short-circuit)
Sub-policy returning nil (no opinion) is skipped
All sub-policies allow or no opinion results in overall allow

Bridge policies to callbacks with canUseTool(policy:):

let policy = CompositePolicy(policies: [
    ToolNameDenylistPolicy(deniedToolNames: ["Bash"]),
    ReadOnlyPolicy()
])

let agent = createAgent(options: AgentOptions(
    apiKey: apiKey,
    model: "claude-sonnet-4-6",
    permissionMode: .bypassPermissions,
    canUseTool: canUseTool(policy: policy)
))

3. Sandbox Mechanism: SandboxSettings + SandboxChecker

Permission control manages "can this tool execute." Sandbox manages "is this operation within allowed bounds." For example, the Bash tool passes permission checks, but you still need to ensure it won't run rm -rf /.

SandboxSettings Configuration

let sandbox = SandboxSettings(
    // Path control
    allowedReadPaths: ["/project/"],
    allowedWritePaths: ["/project/build/"],
    deniedPaths: ["/etc/", "/var/"],

    // Command control
    deniedCommands: ["rm", "sudo"],           // Denylist
    // allowedCommands: ["git", "swift"],     // Allowlist (choose one with denylist)

    // Behavior control
    allowNestedSandbox: false,
    autoAllowBashIfSandboxed: false,          // Auto-approve Bash when sandbox is active
    allowUnsandboxedCommands: false,
    enableWeakerNestedSandbox: false,

    // Network control
    network: SandboxNetworkConfig(
        allowedDomains: ["api.example.com"],
        allowLocalBinding: false
    )
)

Paths and commands each have two modes:

Paths: allowedReadPaths/allowedWritePaths are allowlists (empty = allow all); deniedPaths is a denylist (higher priority)
Commands: allowedCommands is an allowlist (non-nil restricts to listed commands); deniedCommands is a denylist. allowedCommands takes priority over deniedCommands

SandboxChecker Execution Logic

SandboxChecker is a stateless enum providing isPathAllowed, checkPath, isCommandAllowed, checkCommand static methods. isXxx returns Bool; checkXxx throws SDKError.permissionDenied on failure.

Path checking uses prefix matching with segment boundary guarantees:

// /project/ matches /project/src/file.swift
// /project/ does NOT match /project-backup/file.swift
SandboxChecker.isPathAllowed("/project/src/main.swift", for: .read, settings: sandbox)
// -> true

SandboxChecker.isPathAllowed("/project-backup/old.swift", for: .read, settings: sandbox)
// -> false (segment boundary mismatch)

The key is SandboxPathNormalizer — normalizes paths first (resolving .., ., symlinks), then ensures trailing / for segment boundaries during prefix comparison:

// Path traversal attacks get normalized away
let normalized = SandboxPathNormalizer.normalize("/project/src/../../etc/passwd")
// -> "/etc/passwd", then caught by deniedPaths

Command checking has three phases:

Shell metacharacter detection — identifying bypass patterns like bash -c "cmd", $(cmd), `cmd`
Basename extraction — extracting rm from /usr/bin/rm -rf /tmp
Allowlist/denylist matching

// Denylist has "rm"
SandboxChecker.isCommandAllowed("rm -rf /tmp", settings: blocklist)
// -> false

// Path-form commands are recognized
SandboxChecker.isCommandAllowed("/usr/bin/rm -rf /tmp", settings: blocklist)
// -> false (basename extracted as "rm")

// Backslash bypass
SandboxChecker.isCommandAllowed("\\rm -rf /tmp", settings: blocklist)
// -> false (leading \ removed, gets "rm")

// Quote bypass
SandboxChecker.isCommandAllowed("\"rm\" -rf /tmp", settings: blocklist)
// -> false (quotes removed, gets "rm")

// Subshell bypass
SandboxChecker.isCommandAllowed("bash -c \"rm -rf /tmp\"", settings: blocklist)
// -> false (recursive check of inner command)

Commands that can't be reliably parsed default to denied.

File paths in command arguments are also extracted and checked — if a command references a path in deniedPaths, the command is rejected.

autoAllowBashIfSandboxed

This option bridges sandbox and permission systems. When autoAllowBashIfSandboxed = true, the Bash tool skips canUseTool permission callback checks but still undergoes SandboxChecker.checkCommand() filtering.

The design rationale: if you've configured comprehensive sandbox rules, what Bash can do is already constrained. No need for an additional permission confirmation.

4. Hook System: 20+ Lifecycle Events

The first three systems solve "can it be done." The Hook system solves "know when it's done" and "intervene before it happens."

20+ HookEvents

The SDK defines 24 lifecycle events:

Event	Trigger Timing
`preToolUse`	Before tool execution
`postToolUse`	After successful tool execution
`postToolUseFailure`	After failed tool execution
`sessionStart`	Agent session starts
`sessionEnd`	Agent session ends
`stop`	Agent Loop stops
`subagentStart`	Sub-agent launches
`subagentStop`	Sub-agent completes
`userPromptSubmit`	User submits prompt
`permissionRequest`	Permission check occurs
`permissionDenied`	Permission denied
`taskCreated`	Task created
`taskCompleted`	Task completed
`configChange`	Configuration change
`cwdChanged`	Working directory change
`fileChanged`	File change
`notification`	Notification event
`preCompact`	Before conversation compaction
`postCompact`	After conversation compaction
`teammateIdle`	Team member idle
`setup`	Agent initialization
`worktreeCreate`	Worktree created
`worktreeRemove`	Worktree removed

Function Hooks vs Shell Hooks

Hooks have two implementation approaches: function callbacks and shell commands.

Function Hook — Swift closure, suitable for in-process logic:

await registry.register(.preToolUse, definition: HookDefinition(
    handler: { input in
        // input is HookInput with event, toolName, toolInput, sessionId, etc.
        return HookOutput(message: "Intercepted", block: true)
    }
))

Shell Hook — External command, suitable for integrating non-Swift scripts:

await registry.register(.preToolUse, definition: HookDefinition(
    command: "python3 /path/to/check.py"  // HookInput passed via stdin JSON
))

Shell Hooks execute via ShellHookExecutor: using /bin/bash -c to launch a process, serializing HookInput as JSON to stdin, reading HookOutput JSON from stdout. If stdout isn't valid JSON, it's wrapped as HookOutput(message: stdout).

Shell Hook environment variables include HOOK_EVENT, HOOK_TOOL_NAME, HOOK_SESSION_ID, HOOK_CWD for easy context detection in scripts.

HookRegistry Registration and Execution

HookRegistry is an actor, internally maintaining [HookEvent: [HookDefinition]] mappings:

let registry = HookRegistry()

// Register function Hook
await registry.register(.preToolUse, definition: HookDefinition(
    handler: { input in
        return HookOutput(message: "Bash blocked", block: true)
    },
    matcher: "Bash"  // Only match Bash tool
))

// Register Shell Hook
await registry.register(.postToolUse, definition: HookDefinition(
    command: "/usr/bin/logger 'Tool executed'",
    timeout: 5000  // 5 second timeout
))

// Execute all Hooks registered on an event
let results = await registry.execute(.preToolUse, input: hookInput)
// results: [HookOutput], containing return values from all matching Hooks

matcher filtering: Each HookDefinition can have a matcher (regex). During execution, input.toolName is checked against the matcher; non-matching Hooks are skipped. nil matcher matches all tools.

Timeout handling: Function Hooks use withThrowingTaskGroup for timeout — placing actual execution and Task.sleep in the same TaskGroup, using whichever completes first. Timed-out Hooks don't affect other Hooks. Shell Hooks use DispatchQueue.asyncAfter for timeout, terminating the process when time's up.

Execution order: Hooks on the same event execute serially in registration order.

HookOutput Capabilities

HookOutput can do all of this:

HookOutput(
    message: "Log message",                          // Attached info
    block: true,                                      // Intercept operation
    notification: HookNotification(               // Send notification
        title: "Warning",
        body: "Dangerous operation detected",
        level: .warning
    ),
    permissionUpdate: PermissionUpdate(           // Dynamically modify permissions
        tool: "Bash",
        behavior: .deny
    ),
    systemMessage: "Please operate within sandbox",  // Inject system message
    reason: "Security policy",                         // Interception reason
    updatedInput: ["command": "echo safe"],            // Modify tool input
    decision: .block                                   // Explicit approve/block
)

block: true prevents tool execution, returning an error result to the LLM. permissionUpdate dynamically modifies tool permissions during Hook execution. updatedInput replaces tool input parameters.

5. Practical Combination: Building a Secure Agent

Four subsystems, each with its own role:

SessionStore — Remember conversation history
PermissionPolicy — Control whether tools can execute
SandboxSettings — Limit operational scope
HookRegistry — Audit and intercept

Here's a complete example showing how to combine them:

import Foundation
import OpenAgentSDK

// 1. Create SessionStore
let sessionStore = SessionStore()

// 2. Create HookRegistry, register audit and security interception
let hookRegistry = HookRegistry()

// Log all tool executions
await hookRegistry.register(.postToolUse, definition: HookDefinition(
    handler: { input in
        if let toolName = input.toolName {
            print("[Audit] Tool \(toolName) completed")
        }
        return nil
    }
))

// Intercept dangerous Bash commands
await hookRegistry.register(.preToolUse, definition: HookDefinition(
    handler: { input in
        return HookOutput(
            message: "Bash blocked by security policy",
            block: true,
            decision: .block
        )
    },
    matcher: "Bash"
))

// Log permission denial events
await hookRegistry.register(.permissionDenied, definition: HookDefinition(
    handler: { input in
        print("[Security Alert] Permission denied: \(input.error ?? "unknown")")
        return nil
    }
))

// Session lifecycle tracking
await hookRegistry.register(.sessionStart, definition: HookDefinition(
    handler: { _ in print("[Session] Started"); return nil }
))
await hookRegistry.register(.sessionEnd, definition: HookDefinition(
    handler: { _ in print("[Session] Ended"); return nil }
))

// 3. Configure sandbox: restrict paths and commands
let sandbox = SandboxSettings(
    allowedReadPaths: ["/project/"],
    allowedWritePaths: ["/project/src/", "/project/tests/"],
    deniedPaths: ["/etc/", "/var/", "/tmp/"],
    deniedCommands: ["rm", "sudo", "chmod", "chown"],
    autoAllowBashIfSandboxed: false,
    allowNestedSandbox: false
)

// 4. Configure permission policy: read-only + exclude Bash
let policy = CompositePolicy(policies: [
    ToolNameDenylistPolicy(deniedToolNames: ["Bash"]),
    ReadOnlyPolicy()
])

// 5. Create Agent, inject all components
let agent = createAgent(options: AgentOptions(
    apiKey: "sk-...",
    model: "claude-sonnet-4-6",
    systemPrompt: "You are a code analysis assistant. Read-only, no modifications.",
    maxTurns: 10,
    permissionMode: .bypassPermissions,
    canUseTool: canUseTool(policy: policy),
    sessionStore: sessionStore,
    sessionId: "analysis-session",
    hookRegistry: hookRegistry,
    sandbox: sandbox
))

// 6. Execute query
let result = await agent.prompt("Analyze the Swift source file structure in the project")
print(result.text)

// 7. Resume session later
let resumedAgent = createAgent(options: AgentOptions(
    apiKey: "sk-...",
    model: "claude-sonnet-4-6",
    permissionMode: .bypassPermissions,
    canUseTool: canUseTool(policy: policy),
    sessionStore: sessionStore,
    sessionId: "analysis-session",  // Same session ID, auto-restores history
    hookRegistry: hookRegistry,
    sandbox: sandbox
))

let continued = await resumedAgent.prompt("Continue analyzing test files")
print(continued.text)

This Agent's security features:

Permission layer: CompositePolicy ensures only read-only tools execute, with Bash denied by denylist
Sandbox layer: Even if tools pass permission checks, they're restricted by path — only reading files under /project/, unable to touch /etc/ or /var/
Hook layer: All tool executions are logged (audit), and Bash calls are secondarily intercepted by the preToolUse Hook
Session layer: Conversations auto-saved and restored, continuing previous work after restart

Multi-layer defense benefit: even if one layer has a configuration gap, others provide backup. For example, if you accidentally add Bash to the allowlist, the Hook's matcher still intercepts it. Even if the Hook misses it, the sandbox's command filtering still blocks it.

Summary

SessionStore, PermissionPolicy, SandboxSettings, and HookRegistry — four systems each managing one concern, but combined they form a complete security framework:

SessionStore's actor isolation and session ID validation ensure storage security
PermissionPolicy's composable policies provide flexible permission management
SandboxChecker's path normalization and segment boundary matching prevent directory traversal
HookRegistry's matcher filtering and timeout mechanisms ensure Hook system reliability

The next article covers the SDK's multi-LLM providers: how to simultaneously support Anthropic, OpenAI, and other LLMs, the Provider protocol design, and runtime model switching mechanisms.

Deep Dive into Open Agent SDK (Swift) Series:

Part 0: Open Agent SDK (Swift): Build AI Agent Applications with Native Swift Concurrency
Part 1: Deep Dive into Open Agent SDK (Part 1): Agent Loop Internals
Part 2: Deep Dive into Open Agent SDK (Part 2): Behind the 34 Built-in Tools
Part 3: Deep Dive into Open Agent SDK (Part 3): MCP Integration in Practice
Part 4: Deep Dive into Open Agent SDK (Part 4): Multi-Agent Collaboration
Part 5: Deep Dive into Open Agent SDK (Part 5): Session Persistence and Security
Part 6: Deep Dive into Open Agent SDK (Part 6): Multi-LLM Providers and Runtime Controls

GitHub: terryso/open-agent-sdk-swift