Tools

Add native iOS remote tool suites, artifact providers, or custom app tools, gate them with the iOS build opt-in and ToolGuard, and keep them limited to local development workflows.

Remote tools let the local host player and CLI clients inspect or operate on a paired iOS app. Keep them scoped to local development and QA builds.

Important Security Rule

Do not ship native tool suites in TestFlight, App Store, CI release, or other distributable builds unless the capability is explicitly approved.

Do this:

add the aggregate Ansight product or individual tool products only to local development builds
set ANSIGHT_ALLOW_REMOTE_TOOLS=true only for those local builds
use the narrowest runtime guard that works for the workflow

Do not do this:

ship tool products in distribution builds
leave ANSIGHT_ALLOW_REMOTE_TOOLS=true in shared release configuration
expose write or critical tools when read-only inspection is enough

Build-Time Opt-In

export ANSIGHT_ALLOW_REMOTE_TOOLS=true

Without this local-development opt-in, the SwiftPM build tool and CocoaPods build phase fail when they detect concrete AnsightTool implementations.

Runtime Registration

The aggregate Ansight product registers the standard native tool suites for you:

import Ansight

let options = try AnsightOptions.createBuilder(.ansightDeveloperDefaults)
    .withReadOnlyToolAccess()
    .build()

try AnsightRuntime.shared.initializeAndActivateAnsightSdk(options: options)

Core-only apps can register suites directly:

import AnsightCore
import AnsightToolsDatabase
import AnsightToolsFileDescriptorDiagnostics
import AnsightToolsFileSystem
import AnsightToolsPreferences
import AnsightToolsReflection
import AnsightToolsSecureStorage
import AnsightToolsVisualTree

try AnsightRuntime.shared.registerVisualTreeTools()
try AnsightRuntime.shared.registerDatabaseTools()
try AnsightRuntime.shared.registerFileDescriptorDiagnosticsTools()
try AnsightRuntime.shared.registerFileSystemTools()
try AnsightRuntime.shared.registerPreferencesTools()
try AnsightRuntime.shared.registerReflectionTools()
try AnsightRuntime.shared.registerSecureStorageTools()

Registered tools stay hidden and unusable until toolGuard allows their policy.

Runtime Availability

tool.query evaluates each visible tool against current app state. Catalog entries include runtime.available, reasonCode, reason, requiredState, remediation, retryable, and evaluatedAtUtc, plus a top-level executable flag. Availability is evaluated again immediately before tool.call; an unavailable call returns a structured error instead of running the tool. Tools without prerequisites return .availableNow.

Suite Registration API

Suite	Product	Common registration API
VisualTree	`AnsightToolsVisualTree`	`registerVisualTreeTools()`
Database	`AnsightToolsDatabase`	`registerDatabaseTools(options:)`, `AnsightDatabaseToolsOptions.createBuilder()`, `addRoot(alias:path:)`, `includePlatformRoots(...)`
FileSystem	`AnsightToolsFileSystem`	`registerFileSystemTools(options:)`, `AnsightFileSystemToolsOptions.createBuilder()`, `addRoot(alias:path:)`
File Descriptor Diagnostics	`AnsightToolsFileDescriptorDiagnostics`	`registerFileDescriptorDiagnosticsTools(options:)`, `AnsightFileDescriptorDiagnosticsOptions(...)`
Preferences	`AnsightToolsPreferences`	`registerPreferencesTools(options:)`, `AnsightPreferencesToolOptions(defaultStore:allowedStores:allowedKeys:allowedKeyPrefixes:)`
SecureStorage	`AnsightToolsSecureStorage`	`registerSecureStorageTools(options:)`, `AnsightSecureStorageToolsOptions.createBuilder()`, `withStorageIdentifier(...)`, `withAppleService(...)`, `allowKey(...)`, `allowKeyPrefix(...)`
Reflection	`AnsightToolsReflection`	`AnsightReflectionRootRegistry.register(...)`, `registerGetter(...)`, `deregister(...)`, `clear()`, `registerReflectionTools(options:)`, `AnsightReflectionToolsOptions.createBuilder()`, `allowRoot(...)`, `allowTypePrefix(...)`
Custom Tools	app code	`registerTool(_:)`, `registerTool(_:replaceExisting:)`, `isToolRegistered(...)`
Artifacts	`AnsightCore` / `Ansight`	`registerArtifactProvider(...)`, `registerArtifactProviders(...)`, `unregisterArtifactProvider(...)`, `clearArtifactProviders()`

Guard Levels

Guard	What it allows
`withToolsDisabled()` / `.disabled`	No discovery, no execution.
`withReadOnlyToolAccess()` / `.readOnly`	Maximum policy `.read`.
`withReadWriteToolAccess()` / `.readWrite`	Maximum policy `.write`.
`withAllToolAccess()` / `.fullAccess`	Maximum policy `.critical`.

Tool Suites

Artifacts are a core provider model rather than a separate native tool package. Registering an artifact provider adds the .read policy artifacts.query and artifacts.request tools. See Artifacts.

Suite	Product	Typical use
VisualTree	`AnsightToolsVisualTree`	Inspect the foreground UIKit hierarchy, capture screenshots, and manage diagnostic overlays.
Database	`AnsightToolsDatabase`	Discover SQLite databases, inspect schema, and run read-only queries.
FileSystem	`AnsightToolsFileSystem`	List directories, read files, download files, push, copy, move, and delete files inside approved roots.
File Descriptor Diagnostics	`AnsightToolsFileDescriptorDiagnostics`	Count and inspect open process descriptors, limits, and utilization.
Preferences	`AnsightToolsPreferences`	Read and mutate `UserDefaults` values under store/key allow-lists.
SecureStorage	`AnsightToolsSecureStorage`	Read and mutate Keychain values under explicit key allow-lists.
Reflection	`AnsightToolsReflection`	Inspect explicitly registered live object roots and optionally call root-owned mutation/invocation adapters.
Custom Tools	app code	Expose narrow app-specific development operations.

Recommended Defaults

For most teams:

Start with VisualTree and Database.
Use .readOnly by default.
Use File Descriptor Diagnostics for resource-leak investigations, with targets disabled unless paths are needed.
Add FileSystem, Preferences, or SecureStorage only for a specific debugging workflow.
Add Reflection only after registering narrow roots and type/root filters.
Add Artifacts when app-specific output should become a streamed file or durable session artifact.
Add Custom Tools only for narrow operations that packaged suites cannot cover.
Keep write and delete operations off unless the workflow genuinely depends on them.