Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/app-kit/manifest-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -821,7 +821,7 @@ packages at all.
| `permissions.cron` | boolean | Can create cron jobs |
| `permissions.memory` | string | Memory access: `""` (none), `"app-scoped"`, or `"shared"` |
| `permissions.network` | boolean | Can make external network requests |
| `permissions.sessionApproval` | boolean | Controls existing local user sessions: send messages (including generated response-option choices), approve or deny pending tool requests, and change approval modes within the limits below |
| `permissions.sessionApproval` | boolean | Controls existing local user sessions: send messages (including generated response-option choices, but not a change to the session's agent binding, persona settings, or a harness slash command), approve or deny pending tool requests, and change approval modes within the limits below |
| `permissions.spawn` | boolean | May start a background agent through the host's subagent manager (`ctx.spawn`) |
| `permissions.jobs` | boolean | May run durable background work through `ctx.jobs` and the app-owned `_jobs/*` routes |
| `permissions.exposeToApps` | string[] | App names (or `"*"`) allowed to request cross-app visibility into this app's slots/subagents |
Expand Down
15 changes: 11 additions & 4 deletions docs/architecture/app-platform-trust-model.md
Original file line number Diff line number Diff line change
Expand Up @@ -118,10 +118,17 @@ an existing local user-owned session, choose a generated response option,
approve or deny a pending tool request, or change that session's approval mode.
The app still needs the matching route in `permissions.api`. Cron, system,
remote, member-mode, and other apps' sessions are denied; an app's existing
access to its own slots is unchanged. Mode changes must name a live allowed
slot, which prevents one app call from silently widening every session, and are
limited to Normal, Reads and Trust. YOLO is a process-global override: an app
token can neither arm it nor revoke it, so it stays a dashboard-only decision.
access to its own slots is unchanged. A message the app sends runs as a turn: a
send carrying a change to the session's agent binding, persona settings, or a
harness slash command is refused before anything is written or queued
(`chat_handlers._deny_app_session_settings`, pinned by
`test_chat_mode_security`). The send cannot steer, its row is echoed to the
user's open tabs, it neither starts nor names the session's auto-title (a
queued send restored after a gateway restart has lost that attribution), and
its SSE stream ends with the app's own turn. Mode changes must name a live allowed slot, which
prevents one app call from silently widening every session, and are limited to
Normal, Reads and Trust. YOLO is a process-global override: an app token can
neither arm it nor revoke it, so it stays a dashboard-only decision.

The guard reads the live manifest so that removing the flag revokes the grant at
once. Live-read is not a grant path for this flag: `update_app` compares the old
Expand Down
39 changes: 34 additions & 5 deletions docs/system-specs/modules/app-kit-platform.md
Original file line number Diff line number Diff line change
Expand Up @@ -1492,11 +1492,40 @@ or deny tool requests, or change approval modes require an enabled app whose
live manifest declares `permissions.sessionApproval: true`. The route must also
be allowed by `permissions.api`. Cron, system, remote, member-mode, and other
apps' sessions are denied. An app's existing access to its own slots is
unchanged. Mode changes require an explicit live allowed slot and are limited
to Normal, Reads and Trust; YOLO is global rather than slot-scoped, so app
tokens are refused (``app_yolo_forbidden``) for both arming and revoking it.
Consent is
captured when the user enables the app, so `update_app` disables an enabled app
unchanged. On a user-owned session a `POST /api/chat` from the app sends a
turn: a send carrying a change to the session's agent binding, persona settings,
or a harness slash command (the body's `agent` onto an agent-less slot, its
`color_theme` with `theme_consent` and `theme_consent_sha`, or a first word
`is_harness_slash_command` forwards) is refused with 403
`app_session_settings_forbidden` and an SEL denial before anything is written or
queued (`chat_handlers._deny_app_session_settings`), the same policy as the
agent route. Naming the agent the slot already runs is a
plain send. On that send the `steer` flag is ignored, so it waits behind running
sub-agents like any queued message; the gateway mints the row id; the row is
echoed to the user's open tabs; it starts no auto-title, does not count as a
user turn for titling or the refresh cadence, and the app's turn, its row and
the reply to it, is left out of the automatic title prompts and their truncated
fallback (`chat_title._titling_messages`; the user's own Regenerate title reads
every row); with `dashboard.merge_queued_messages` on, a queued app send never
merges with the user's queued words (`chat_utils._dequeue_next_message` stops a
run where the stamped actor changes); and an SSE send streams the app's own turn
only, including a recovery that same turn queues to retry it (matched by a
per-turn id the recovery carries, not by actor): the `turn_end` frame
lands before the drain or the cycle's end writes a held note, a drop notice or
the next turn's first row, the stream also stops at any user row that is not
its own gateway-minted row, and it skips `queued` placeholder rows (a
cron notification or MCP-App message queued meanwhile), while the user's tabs
keep receiving the session's rows. A queued
send that a gateway restart restores has lost its attribution, because the
restore drops the actor stamp: it drains alone, never merged with fresh words,
as a user row marked `turnProvenanceRestored`, which titling skips on a slot no
app owns, and never as a cron or sub-agent event. `test_chat_mode_security`
pins this, and `test_every_api_chat_body_key_is_classified` fails on a body
field nobody has classified as turn-only or settings-bearing. Mode changes
require an explicit live allowed slot and are limited to Normal, Reads and
Trust; YOLO is global rather than slot-scoped, so app tokens are refused
(``app_yolo_forbidden``) for both arming and revoking it. Consent is captured
when the user enables the app, so `update_app` disables an enabled app
whose new version adds the flag (SEL operation `session_approval_widened`) and
returns `notice: "session_approval_reconsent"`; the detail page shows that notice
and the user re-enables the app after seeing the grant. `register_external_app`
Expand Down
9 changes: 6 additions & 3 deletions docs/system-specs/modules/history.md
Original file line number Diff line number Diff line change
Expand Up @@ -976,9 +976,12 @@ no longer destroy older turns.
- **Client-supplied row `meta` survives the whole path (the client-meta
survival contract).** The `meta` a dashboard send carries (`POST /api/chat`
body) rides onto the user row it becomes and reaches every
reader unchanged: ingress drops only `RESERVED_ROW_META_KEYS` (today
`decisions_strip`, the gateway's own receipt carrier -- `chat_handlers.py`),
`_redact_meta` (`chat_utils.py`) redacts credential- and exfiltration-shaped
reader unchanged: ingress drops only `RESERVED_ROW_META_KEYS`
(`chat_handlers.py`: the keys the gateway mints itself -- `decisions_strip`,
its receipt carrier, the human-turn marker and the turn-actor stamp), plus
`mid` on an app's send to a user session through `permissions.sessionApproval`,
where the gateway mints the row id (see
[app-kit-platform](app-kit-platform.md)); `_redact_meta` (`chat_utils.py`) redacts credential- and exfiltration-shaped
STRING values recursively and is not a key allowlist, `slot.append` broadcasts
the row's `meta` on the WebSocket `chat_message` echo
(`include_metadata=True`), `_save_slot_to_history` writes it verbatim on the
Expand Down
Loading
Loading