Permissions

What permissions control

Permissions determine how often Happier asks for approval when an agent wants to run tools (like editing files or running commands), and how restrictive the session environment should be.

You can set permissions in two places:

• CLI: when starting a session
• App UI: per-session (and as defaults for new sessions)

Happier stores your choice in the session so it stays consistent when you open the same session on another device.

Permission modes

These are the modes you may see in the CLI and/or the app:

• Default: uses the provider’s normal behavior (ask when needed).
• Read-only: the agent can read and inspect, but write-like actions are denied.
• Safe YOLO: automatically allows read-like actions; asks for approval before write-like actions.
• YOLO: skips approvals as much as the provider allows (full speed, least safe).

Not every provider supports every mode. When a mode isn’t supported, Happier will fall back to the closest supported behavior and show you the Effective policy in the UI.

Legacy note:

• some older sessions and compatibility paths may still carry plan in permission metadata
• in current Happier builds, Plan is treated as a session mode, not a normal permission choice
• when Happier sees legacy permissionMode=plan, it maps that to Mode = Plan for compatible providers

Session modes

Some providers expose session modes (for example, plan vs build or default vs plan).

Session modes are separate from permissions:

• Permissions control approvals and safety boundaries.
• Session modes control the agent’s operating mode (provider-defined).

Important distinction:

• changing Mode changes the current session
• starting a Plan subagent launches parallel work in the Agents surface

Those are intentionally different features.

For the full user-facing guide, see Session modes.

CLI usage

Start a session with a session mode:

happier claude --agent-mode plan
happier codex --agent-mode plan
happier opencode --agent-mode plan
happier kilo --agent-mode plan

App UI usage

In a session, open the input settings and pick a value from the Mode section when it’s available for the current provider.

If the provider does not support session modes, the Mode control is not shown.

When session modes are available, Happier also supports returning to the provider default mode. In the app this appears as the default/no-override option.

Important: Plan mode does not bypass permissions

Plan mode changes how the provider behaves. It does not mean “auto-approve everything”.

In current Happier builds:

• you can be in Mode = Plan and still receive permission prompts
• your selected permission mode still matters when the provider/runtime asks for approval
• when you exit plan mode, Happier returns the session to the normal working mode for that provider

Exiting plan mode

When a provider asks to exit plan mode, Happier surfaces that as a user-action request, not as a generic permission prompt.

Typical actions are:

• Approve Plan: exit plan mode and continue
• Request changes: stay in plan mode and ask the provider to revise the plan
• provider-specific approval variants such as Accept Edits or Bypass All Permissions

Claude is the clearest example:

• Approve Plan returns the session to Mode: Build
• Approve Plan (Accept Edits) returns to build mode with a safer edit-friendly permission mode
• Approve Plan (Bypass All Permissions) returns to build mode with a YOLO-style permission mode

Those approval variants affect what happens after plan mode ends. They do not mean that plan mode itself bypasses approval prompts.

Resume support

Resume is now a session-level eligibility decision in Happier, not a normal runtime-probing flow.

In practice, Happier decides resumability from:

• the session’s agent/provider
• whether the session has a valid stored provider resume id
• your account/backend settings

For Codex specifically:

• resume depends on the session metadata and the selected backend path
• App Server is the default resumable path in Happier
• if Codex is set to plain mcp, fresh sessions can still run there, but vendor resume is not available on that path
• explicit resume remains fail-closed: Happier errors instead of silently starting a fresh session

For the user-facing workflow, see Resume inactive sessions.

Model selection

Some providers let you choose which model runs your session.

If model selection is available, you can set it from:

• CLI: when starting the session
• App UI: from the input settings inside a session

CLI usage

happier gemini --model gemini-2.5-pro

App UI usage

In a session, open the input settings and pick a model from the Model section.

For ACP providers that advertise supported models, Happier will show the provider’s live list. For providers without a live list (like Claude Code), Happier may allow entering a custom model id.

Model apply behavior (what happens after you change it)

Model changes are capability-driven and provider-specific:

• Claude: applies on the next prompt (no session restart required).
• Codex (MCP): model is decided when the MCP session starts; changing model means starting a new MCP session.
• Codex/OpenCode/Kilo/Auggie (ACP): Happier applies model changes live when session/set_model is supported; otherwise it falls back to provider config options when available.
• Gemini (ACP): model changes may require recreating the underlying ACP process; Happier preserves context using replay/history so the session still continues.

CLI usage

Start a session with a permission mode:

happier codex --permission-mode read-only
happier codex --permission-mode safe-yolo
happier claude --permission-mode yolo

For new sessions, prefer:

• --permission-mode ... for approval behavior
• --agent-mode plan when you want to start the session itself in plan mode

Aliases (you can use the words you already know)

The CLI accepts common aliases and normalizes them automatically:

• readonly, read only, ro → read-only
• full, full-access, danger-full-access, bypass → yolo
• ask, prompt, auto → default
• accept-edits (Claude wording) → safe-yolo
• bypass-permissions (legacy) → yolo

If you pass an unknown value, Happier prints the supported list and examples.

App UI usage

Change permissions for the current session

In a session, open the permission chip (shield) and pick a mode.

The picker shows:

• a short description of each mode, and
• an Effective line that explains what the selected mode means for the current provider/session.

Action approvals are separate

Action approvals are configured independently from permission modes.

Use Settings → Actions when you want to choose, per action and per surface, whether Happier should:

• make the action available at all
• route the action through an approval request before it executes

That same approval model applies across the main action surfaces, including:

• the session agent surface
• the CLI surface
• the external MCP surface
• voice surfaces

For the broader model, see Happier tools & actions and Inbox and approvals.

Set defaults for new sessions

Go to Settings → Session → Permissions and set your default permission mode per backend choice.

The defaults screen is designed around two separate concerns:

• Default permissions for each enabled backend choice
• Apply permission changes for running sessions

That split matters because those settings solve different problems.

Dedicated Permissions screen

In the app, the Permissions screen is the central place for session-permission defaults.

Open:

1. Settings
2. Session
3. Permissions

Default permissions

The Default permissions section shows one row per enabled backend choice.

Important details:

• the list is dynamic
• it is generated from the resolved backend catalog
• it is not hardcoded to specific providers in the UI

This means:

• if you enable a new backend, it can appear automatically
• if a backend is unavailable in your current account/build, it should not appear
• configured Custom ACP backends can appear here alongside built-in providers

Apply permission changes

The Apply permission changes section is a separate dropdown.

It controls when a permission change should take effect:

• Immediate: publish the new permission mode to the session right away
• Next prompt: arm the change locally and publish it when you send the next message

This is useful because some users want a running agent to react immediately, while others want the next turn to be the first one that uses the new permission mode.

Prompt surface

The same screen also lets you choose where permission requests should appear:

• in the composer, or
• in the transcript

That setting changes the UI surface for approvals. It does not change the underlying permission decision.

Remembering approvals for the current session

When Happier shows a permission prompt, some providers can also offer scoped “don’t ask again” choices.

Examples:

• don’t ask again for this tool
• don’t ask again for this command

These choices update the current session’s allowlist so later matching requests do not prompt again in that same session.

Important details:

• this is session-scoped, not a permanent global policy
• command-scoped approvals are narrower than tool-scoped approvals
• if the provider/runtime does not support a matching allowlist update, Happier falls back to normal prompting

Push notifications for permission and user-action requests

When push notifications are enabled for the account, Happier can also notify you when a session is blocked on either:

• a permission request, or
• a user-action request such as AskUserQuestion or Exit Plan Mode

Current mobile behavior:

• the notification can show the requested tool or request type
• it may include a short detail hint, such as a file hint or command name
• it can expose:
  • Allow / Deny for permission requests
  • Answer for user-action requests

Pressing Allow or Deny opens the app, sends the response when the target server is already active or already saved on the device, and then returns you to the session.

Pressing Answer opens the app on the exact session so you can answer in context.

If the notification targets a server that is not already trusted on the device, Happier routes you through the safer add/switch flow instead of auto-approving on an unknown server.

Transcript-storage defaults

When your current server/build supports transcript-storage choices, the Permissions screen can also show the default storage mode for new sessions per backend choice.

That lives here because it affects the default safety / persistence posture of new sessions.

When does a change apply?

In Settings → Session, you can control when a permission change takes effect:

• Immediate: publish the new permission mode to the session right away (best when you want the running agent to react without sending a new message).
• Next prompt: apply the new mode to the next message you send, and publish it after that message is committed (best when you want the change to “arm” for the next request without touching the current running turn).

If you select Next prompt and then don’t send a message, the change stays local to your device until you send one.

What the dropdown rows show

In current app builds, permission dropdown rows show the current selection directly in the row itself.

That means you can usually see:

• the selected mode label on the right, and
• the explanation for the selected option as the row subtitle

without reopening the dropdown.

Provider notes (what to expect)

Codex (App Server default, ACP optional, MCP for fresh sessions)

Codex can run via different backends:

• App Server: the default backend in Happier and the normal resume path when the session has valid Codex resume metadata
• ACP: still available when you explicitly switch Codex to ACP mode; resume can also work there
• MCP: still usable for normal fresh sessions, but plain MCP is not a vendor-resume path in current Happier builds

In Happier, permissions remain the primary control for Codex. Happier maps your selected permission intent to the closest backend-native policy for the active Codex backend.

Model IDs can also vary by Codex build and account. If model selection isn’t shown in the app for your Codex session, you can still set it via the CLI (when supported by your installed Codex backend).

The UI’s Effective line is the source of truth for what your current session will do.

Related guides

• ACP backends
• Profiles
• Session modes
• Session settings

Claude

Claude supports both:

• normal Happier permission modes, and
• a provider-specific Mode = Plan

While Claude is in plan mode:

• Claude can still ask for permissions
• Happier still surfaces permission prompts normally
• Exit Plan Mode is surfaced as a user-action request with plan-specific approval choices

If the Effective line is different from what you expected, treat the Effective line as source of truth for that session.