# AiMe Capability and Permission Model

Status: Draft policy model  
Last updated: 2026-08-15

## Purpose

This document defines how AiMe converts a broad product goal into explicit,
revocable local authority. It is a product-policy contract, not a statement that
every listed capability is implemented today.

## Core rules

1. **Deny by default.** A tool is unavailable unless the active profile grants
   its capability and all risk modifiers pass policy.
2. **No implicit escalation.** A lower level cannot reach a higher level through
   interpreter scripts, helper configuration, plugins, aliases, child processes,
   UI automation, or argument side effects.
3. **Local authority wins.** Remote prompt text, tool output, websites, files,
   and model reasoning cannot create a root, grant, approval, or profile.
4. **One session, one target.** A session is bound to one device and one profile.
   Switching either requires a new explicit user action.
5. **Structured tools first.** Prefer narrow operations whose effects can be
   previewed and enforced. Raw shell is a separately granted fallback.
6. **Risk may only move upward.** Path, target, authentication state, data
   sensitivity, network effect, or destructiveness may require a higher level
   than the tool's nominal level.
7. **Revocation is immediate.** Downgrade, disconnect, emergency stop, profile
   revoke, or device revoke must fail the next action closed.
8. **Remote policy only narrows.** Account, organization, role, share, and lease
   policy is an additional ceiling; it never grants above the local profile or
   satisfies local confirmation.
9. **Managed authority expires.** Missing, stale, replayed, conflicting, or
   unauthenticated managed policy fails tool execution closed after the bounded
   lease window. Local stop and revoke remain available.

## Terms

| Term | Meaning |
| --- | --- |
| Device | One AiMe installation with an independent identity and revocation boundary. |
| Profile | Local policy containing root aliases, capabilities, limits, confirmation rules, and tunnel binding. |
| Session | A time-bounded connection to exactly one device/profile pair. |
| Capability | A named local authority, such as reading a file or controlling a window. |
| Grant | A local decision that permits capabilities for a profile or time-bounded session. |
| Confirmation | User-presence approval for one clearly described action or bounded batch. |
| Risk modifier | Context that raises the required level or requires per-action confirmation. |
| Organization role | Web control-plane authority to administer tenant metadata and requested policy; not a local Windows capability. |
| Profile share | Expiring delegation to use explicit tools/capabilities on one profile, subject to local activation and ceiling. |
| Policy lease | Short-lived authenticated server authorization for one user, connection, device, profile, policy version, and scope. |

## Remote authorization and local capability intersection

For Managed mode, effective authority is calculated for every call:

```text
effective capability
  = authenticated user/organization membership
  AND active profile share
  AND connection/session lease scope
  AND local profile capability ceiling
  AND local confirmation state
  AND current local risk evaluation
```

Any missing or mismatched term denies the call. Owner, Organization Admin, and
Platform Admin roles are control-plane roles; none automatically grants Read,
Modify, Control, Full, or Admin on a computer. A locally accepted share may be
narrower than the web request. Web-side downgrade/revoke takes effect on the
next call; web-side widening remains pending until the intended device accepts
the new policy version locally.

Platform Admin can operate, suspend, or revoke service identity and releases
but cannot retrieve a local credential/content, create a local confirmation, or
send an arbitrary device command. The full role and sharing matrix is defined
in [the web control-plane and RBAC plan](WEB_CONTROL_PLANE_AND_RBAC_PLAN.md).

## Permission levels

The product uses five user-facing levels. **Modify** is the structured
workspace-change and development level. It is intentionally not named `Work`
because ChatGPT Work is a different product surface and is not AiMe's required
surface.

| Level | Intended authority | Default confirmation | Examples |
| --- | --- | --- | --- |
| Read | Bounded observation inside pre-approved roots. | Profile/session activation; extra confirmation for sensitive surfaces. | Status, one-level listing, text read, metadata, bounded search. |
| Modify | Structured workspace changes and constrained development processes. | Preview or bounded session grant; destructive/external effects remain per action. | Apply patch, preview patch, create/move file, build/test, Git status/diff. |
| Control | Interact with a visible browser or Windows UI and sensitive user surfaces. | Foreground local session indicator plus per-risk action confirmation. | Screenshot, accessibility tree, clipboard, click, type, window/browser control. |
| Full | General-purpose execution that can escape structured-operation guarantees. | Explicit short-lived local grant and exact command/action preview. | Raw shell, interpreters, arbitrary executable, unrestricted network-capable CLI. |
| Admin | Narrow operating-system changes requiring elevation. | Per-action local approval and Windows elevation through a separate broker. | Approved service/firewall/install operation implemented by a signed broker verb. |

No profile may receive Admin as a blanket token. Admin is a collection of
separately implemented broker operations.

## Capability matrix

The following matrix defines the minimum level. Risk modifiers can raise it.

| Capability family | Minimum level | Important boundaries |
| --- | --- | --- |
| `status`, capability discovery | Read | Return aliases and health only; no host, user, token, IP, or absolute path. |
| Directory list, file metadata, text read/search | Read | Approved root alias, bounded output, handle-verified object, no reparse traversal. Profile-gated `search_text_files` is available on the supported default Read stdio/tunnel route with exact literal case-sensitive UTF-8 recursive search, a query capped at 256 UTF-8 bytes with no NUL/CR/LF, and redacted audit counters/fingerprints only. |
| Screen, window image, accessibility tree | Control | User-visible indicator; target preview; secret/redaction policy. |
| Clipboard read | Control | Per-use or short-lived grant; never silently included with generic Read. |
| Create/write/apply patch | Modify | Handle-relative publication, expected-state conflict detection, size limit, and bounded rollback/recovery; no hostile same-user compare-and-swap guarantee. |
| Preview patch | Modify | Metadata-only prediction of a bounded patch against the current approved UTF-8 file; returns hashes, counts, and bytes only, never content or diff, and does not mutate or reserve the file. |
| Move/delete | Modify | Exact target preview; recycle/rollback where practical; stronger confirmation for bulk actions. |
| Git status/diff/log | Read | Repository must be inside an approved workspace. |
| Git add/restore/commit | Modify | Exact repository and diff preview; commit is an explicit user intent. |
| Git push, release, remote mutation | Modify plus external-effect confirmation | Show remote and branch; never infer publish authorization from permission to edit. |
| Dedicated structured build/test wrapper | Modify | Purpose-specific wrapper that constrains every executable input, config, and plugin; approved cwd; Job Object; bounded output/time/network policy; local confirmation; no raw shell or stdin. |
| Raw shell, interpreter, arbitrary executable, or generic process preset | Full | Short expiry, exact argv/cwd/env preview, no hidden shell, supervised tree. |
| Browser navigation/read-only DOM | Control | Isolated or explicitly selected browser profile; authenticated state is sensitive. |
| Browser form submit/purchase/post/message | Control plus external-effect confirmation | Show destination and effect; login/MFA remains user action. |
| Mouse, keyboard, hotkey, application/window control | Control | Foreground target binding, visible session, emergency stop, input rate limits. |
| Install, service, registry-machine, firewall, protected-path mutation | Admin | Only a specific signed broker verb; never arbitrary elevated shell. |

## Risk modifiers

Any of the following requires stronger policy, confirmation, or denial:

- target is outside the profile's approved root, application, window, or browser;
- operation is recursive, bulk, destructive, irreversible, or difficult to
  preview;
- command can load plugins, interpreters, helpers, config files, aliases, or
  executable content;
- operation can access the network, credentials, authenticated sessions,
  clipboard, screen, camera, microphone, or personal data;
- target is a repository remote, package registry, production environment,
  payment flow, email/message destination, or public publishing surface;
- path contains or resolves through reparse, hard-link ambiguity, device
  namespace, alternate stream, UNC, mapped-drive, or mutable executable state;
- action requires elevation or would weaken security policy, logging, update
  trust, credential protection, or process containment;
- user is not visibly present for a Control, Full, or Admin action.

## Confirmation model

Confirmation is a local policy artifact, not text sent by the model.

| Confirmation type | Permitted use | Required display |
| --- | --- | --- |
| Profile activation | Start a bounded Read or Modify session. | Device alias, profile name, roots by alias, capabilities, duration. |
| Action confirmation | One high-risk or externally visible operation. | Exact target/effect, risk reason, initiating session, allow once/deny. |
| Bounded batch | A homogeneous, previewable set of actions. | Complete or safely summarized target set, count/limits, rollback behavior. |
| Full-session grant | Short-lived raw execution authority. | Expiry, workspace, executable/network boundaries, persistent warning/stop control. |
| Admin broker confirmation | One predefined elevated verb. | Exact broker operation, parameters, expected OS change, UAC transition. |

Prohibited confirmation patterns include opaque "allow everything" prompts,
approval embedded in ChatGPT, approval derived from a filename or document, and
consent/pairing/invitation links that perform an action merely by being opened.
Managed shares remain unusable until the intended device records local
activation, except for a future explicitly configured bounded Read delegation
rule whose ceiling and expiry were approved in advance.

## Enforcement layers

Every Managed-mode tool call passes all applicable layers in order:

1. human/connection identity and tenant membership validity;
2. active share, short-lived lease, policy version, and server revoke state;
3. transport, device/profile/session binding, and local revoke state;
4. exact tool and strict input schema;
5. local capability and risk-modifier policy;
6. local confirmation state when required;
7. native resource containment and executable identity;
8. bounded execution under process/resource supervision;
9. bounded, redacted result construction; and
10. fail-closed local and control-plane audit persistence where required.

Personal local mode omits the account/tenant/share layers but preserves every
local enforcement layer.

Within the current local Modify boundary, `repair_required` denies create,
apply-patch, replace, and rollback before native dispatch. Only a future
authorized local operator-repair workflow may clear that state; remote MCP
content cannot do so.

A failure in any layer prevents later resource access. Internal helper,
protocol, audit, or policy failure is not converted into an allow decision.
The internal offline search helper isolates ordinary reads through a dedicated
cancellable worker and returns only bounded redacted audit data.

## Prompt-injection boundary

AiMe assumes ChatGPT may read malicious instructions from files, pages, screen
content, clipboard data, command output, logs, and application UI. Therefore:

- content never carries authority or approval;
- tool results label provenance and untrusted content where the protocol allows;
- a read operation cannot activate a write, shell, control, or network grant;
- confirmations describe the actual local effect rather than repeating the
  model's rationale;
- secrets are minimized and redacted before returning results when possible;
- cross-capability chains are re-evaluated at each call; and
- externally visible side effects require explicit policy even if earlier
  steps in the task were approved.

## Process and command containment

- Launch absolute, verified executables without a command shell unless Full is
  explicitly granted.
- Use an allowlisted environment rather than inheriting the desktop process
  environment.
- Bind cwd to an approved workspace and retain the verified identity needed to
  prevent path swapping.
- Assign the process tree to a kill-on-close Job Object before its first
  instruction can run.
- Bound wall time, output, concurrency, children, and cancellation grace.
- Treat interpreters, script files, plugin-capable tools, helper options, and
  executable downloads as Full unless a dedicated structured wrapper proves a
  narrower boundary.

The current lower-level `run_process_preset` proof is Full-risk even though the
profile, rather than Chat input, fixes the executable identity, argv, cwd, root,
and limits. A pinned interpreter or package manager can still load mutable
scripts, imports, lifecycle hooks, config, plugins, helpers, and network code.
Its direct test MCP surface is limited to start, task status/output, and
cancellation and accepts no raw executable, argv, environment, or stdin, but
those constraints are not isolation. The production local Modify runtime and
stdio host reject the capability before acquiring owners. It remains internal
mechanism evidence for a future Full-session gate or dedicated structured
wrapper, is not exposed by Managed or ordinary Read, and is not a public release
claim.

The current production exposure, verification checkpoint, explicit non-claims,
and dependency-ordered work remaining are summarized in
[Implementation Status and Next Steps](IMPLEMENTATION_STATUS.md).

## Audit contract

Each request records allowlisted metadata such as UTC time, correlation ID,
device/profile/session aliases, tool, allow/deny, reason code, duration, and
bounded byte/entry/process counts. Audit output must not contain raw prompts,
headers, tokens, environment variables, absolute roots, file content, screen
content, clipboard content, command output, or stack traces.

Audit unavailable means the action is unavailable unless a future offline
policy explicitly defines a safe, bounded exception. No such exception exists
for Modify, Control, Full, or Admin.

The control plane separately audits authentication, membership, role, pairing,
share, connection, lease, revoke, release, and Platform Admin events using
allowlisted metadata. Those records do not contain local tool content.

## Revocation and emergency stop

- Profile downgrade affects the next call.
- Session stop cancels active operations and closes the supervised tree.
- Device revoke invalidates its remote binding without affecting other devices.
- Account session revoke, membership removal, profile-share revoke/expiry, and
  organization suspension invalidate derived managed leases.
- A locally initiated downgrade or revoke is enforced immediately even if the
  control plane is unreachable.
- Emergency stop is always visible in the local app during Control or Full.
- Admin broker operations do not create a reusable elevated interactive
  session.

## Level release gate

A level may ship only when:

1. every included capability has an explicit schema and risk classification;
2. negative and prompt-injection tests demonstrate no path to a higher level;
3. confirmation, audit, cancellation, revocation, and crash cleanup pass on real
   Windows;
4. privacy and retention behavior is documented;
5. no Critical or High finding remains for the included capabilities; and
6. Managed capabilities additionally pass role-matrix, tenant-isolation,
   share-activation, lease-expiry, replay, outage, and revoke tests; and
7. all lower-level guarantees continue to pass.

The delivery order is defined in the [delivery roadmap](ROADMAP.md).
