< Back to README

This document details Agent!'s security model and entitlements.

Agent! requires the following entitlements in Agent.entitlements:

Protected macOS APIs require user approval. Agent handles TCC correctly:

Rule: Use run_agent_script or applescript_tool for Accessibility/Automation tasks, not shell commands.

• applescript_tool blocks destructive operations (delete, close, move, quit) by default
• The AI must explicitly set allow_writes: true to permit them
• This prevents accidental data loss from misinterpreted commands

All privileged operations go through XPC (Inter-Process Communication):

Agent.app (SwiftUI)
    |
    |-- UserService (XPC) → Agent.app.toddbruss.user    (LaunchAgent, runs as user)
    |-- HelperService (XPC) → Agent.app.toddbruss.helper  (LaunchDaemon, runs as root)

The XPC boundary ensures:

• The main app runs with minimal privileges
• Root operations are isolated to the daemon
• Each XPC call is a discrete, auditable transaction
• File permissions are restored to the user after root operations

Agent! prevents false-action claims — where an AI reports performing an action it never executed — with three independent layers:

The system prompt instructs the LLM to say "action not performed" if it did not call a tool. It may never claim to have searched, opened, clicked, ran, or found something without a matching tool_result.

If the LLM returns text claiming "I searched", "I opened", "I clicked", etc. but made zero tool calls in that turn, the app injects a correction tool_result telling the LLM to use the actual tool or admit it cannot perform the action. This is logged in the activity view as ⚠️ action not performed.

Apple Intelligence tool calls (accessibility, applescript, shell) are logged to the activity view with the 🍎 prefix showing exactly what was called and what it returned. If Apple AI's tools produce no substantive output (empty, just an exit code, or error), the request is automatically forwarded to the cloud LLM. Apple AI can only claim task completion when its tools return real evidence of work.

All tool execution flows through the app's dispatchTool() layer — the LLM never self-reports tool results. The flow is:

1. LLM returns a tool_use JSON block
2. Agent!'s dispatch layer executes the tool via XPC, shell, or in-process
3. The real output goes back as tool_result
4. The LLM summarizes the real result

The LLM cannot fabricate tool outputs because it never controls what tool_result contains — the app does.