Happier tools & actions

Happier exposes one unified Happier tools surface.

That surface includes:

• Built-in Happier actions such as review, plan, delegate, session mode changes, session targeting, and request responses
• Custom tools from your configured MCP servers

You do not need to think about those as two different systems. Happier delivers them through the best transport the current provider supports.

Happier also separates three related ideas:

• Action availability: whether an action is allowed on a surface at all.
• Action discovery: whether an agent or client can find the action through action_spec_search / action_spec_get and execute it through action_execute.
• Direct tool exposure: whether the action is registered as its own named tool, such as session_title_set.

An action can be available and discoverable without being exposed as a direct tool. That mode is called discoverable-only.

What “Happier tools” means

Happier tools are the actions and external tools that an agent can use through Happier itself.

Examples:

• start a review run
• start a plan or delegate subagent
• switch a session into a provider-supported mode like plan
• answer an AskUserQuestion or Exit Plan Mode request
• call a custom MCP tool such as Playwright, GitHub, or Context7

From the user point of view, this is one product surface:

• configure tools in Settings → MCP servers
• preview what a session will get
• see the resulting tool activity in the normal session transcript

Native MCP vs shell bridge

Different providers accept tools in different ways.

Happier supports two delivery modes:

Native MCP

For providers that can consume MCP directly, Happier injects tools as native MCP tools.

Current native-MCP providers include:

• Claude
• Codex
• OpenCode
• Gemini
• Kiro
• Custom ACP providers that expose native MCP support

Shell bridge

For providers that can execute shell commands but do not use native MCP directly, Happier exposes the same tool surface through the happier tools CLI bridge.

Current shell-bridge providers include:

• Auggie
• Qwen
• Kimi
• Kilo
• Pi
• Copilot

The important user-facing result is the same:

• the provider can still use Happier-managed tools
• the transcript still shows normal Happier tool activity
• MCP server configuration still happens in one place

Built-in actions vs custom MCP tools

Happier tools intentionally mix:

• built-in actions backed by Happier ActionSpec
• custom MCP tools from configured MCP servers

Built-in actions

Built-in actions are the safest way to expose structured Happier workflows to agents.

Examples include:

• review.start
• subagents.plan.start
• subagents.delegate.start
• session.mode.set
• session.permission.respond
• session.user_action.answer
• session.target.primary.set
• session.target.tracked.set

These actions have canonical:

• ids
• input hints
• examples
• option sources

That means Happier can reuse the same source of truth across:

• app launchers and forms
• voice tools
• MCP delivery
• CLI bridge delivery

For session agents, most first-party action-backed tools default to discoverable-only. The session still gets a small direct bootstrap set for action discovery and generic execution, and the larger action catalog stays available through that bootstrap path. This keeps provider-native tool inventories focused while preserving access to Happier workflows.

Custom MCP tools

Custom MCP tools are still configured the same way as before:

• add them in Settings → MCP servers
• scope them by machine and workspace
• preview what a session will see

Once configured, they join the same Happier tools surface as built-in actions.

The direct/discoverable-only exposure setting applies to built-in action-backed tools. Configured custom MCP tools keep their normal direct MCP delivery behavior and are controlled from Settings → MCP servers unless a separate custom-tool discovery path is added later.

Surfaces and approvals

Each built-in action can be configured per surface (where it is available), such as:

• session agents
• the CLI (happier session ... and happier tools ...)
• the external MCP server (happier mcp serve)
• voice tools

Those are all powered by the same action catalog, so one surface can be documented, approved, or disabled without creating a separate action system for each client.

For sensitive actions, you can also configure the surface as approval-gated.

In the app, this lives under Settings → Actions.

When an action is approval-gated, callers do not execute it immediately. Instead, Happier creates an approval request and surfaces it in Inbox for review and execution.

Eligible tool-backed action surfaces also have a tool exposure setting:

• Use default follows Happier’s default for that action and surface.
• Discoverable only keeps the action available through discovery and action_execute, but does not register a named direct tool on that surface.
• Direct tool registers the action as its own named tool when the action is otherwise enabled on that surface.

The exposure setting is independent from approval mode. A direct tool can still require approval, and a discoverable-only action can still require approval when it is executed through action_execute.

User guide: Inbox and approvals

Discovery-first behavior

Happier no longer needs to stuff a huge fixed action catalog into every prompt.

Instead, agents can discover actions on demand.

The built-in discovery flow is:

1. Search action specs when the agent knows the goal but not the exact action id
2. Get action spec when it needs the exact fields, examples, and hints
3. Resolve action options when it needs valid dynamic values such as backends or session modes
4. Execute the action with validated input

This reduces prompt overload and keeps the available tool surface aligned with the real current runtime.

This is the default posture for in-session agents. Happier-managed review, plan, delegate, and execution-run launch actions stay discoverable, but they are not promoted into the session agent’s direct tool list unless the default or your settings make them direct. External MCP clients and CLI workflows keep direct named tools by default where those tools are configured, so existing automations can continue to use them.

Hot-path actions

Happier still keeps a small dynamic hot path for common actions.

This hot path is not a hard-coded documentation list. It is derived from the canonical ActionSpec metadata and the current exposure policy, so when an action’s voice/tool metadata or direct/discoverable setting changes, the hot path changes with it.

In practice, that means common actions like review, plan, delegate, request responses, and session targeting stay easy to reach without maintaining a second parallel registry.

Plan run vs plan mode

These are two different user-facing concepts.

Plan subagent

Use Start plan run when you want Happier to launch a separate planning run or planner-style subagent.

This creates parallel work in the Agents surface.

Session mode

Use Set session mode when you want the current session itself to switch into a provider-supported mode such as plan.

This changes the mode of the current session. It does not start a new subagent.

If the provider does not support session modes, Happier simply does not offer that control.

Responding to user actions

Happier uses one generalized response path for user-action-style requests.

That includes cases such as:

• AskUserQuestion
• ExitPlanMode
• other structured user-action requests exposed by the provider/runtime

The response action can:

• approve
• reject
• request changes
• return structured question/answer pairs

This keeps request handling consistent across UI, voice, and agent-driven flows.

Where you see these tools in the product

App

In the app, Happier tools show up through:

• Settings → MCP servers
• the session MCP chip
• the transcript tool timeline
• the Agents surface for subagent-related actions
• voice surfaces when voice is enabled

CLI

In the CLI, Happier exposes:

happier tools list

and:

happier tools call --session-id <session-id> --source happier --tool <tool-name> --args-json '<json>'

Use list when you want to inspect the current built-in and custom tool surface.

Use call when you want to invoke one built-in Happier tool or one configured custom MCP tool directly.

Common workflows

I want an agent to find the right action instead of guessing

Use the discovery flow:

1. search the action catalog
2. inspect the matching action spec
3. resolve dynamic options if needed
4. execute the action

I want plan behavior in the current session

Switch the session into a supported mode such as plan.

Use a plan subagent only when you want parallel planning work rather than changing the current session’s mode.

I want the same tool configuration to work across providers

Configure the tool once in Happier.

If the provider supports native MCP, Happier uses that. If not, Happier uses the shell bridge automatically when supported.

If you are asking an agent for provider-native parallel subagents, use the provider-native subagent/delegation tools when that provider exposes them. Happier review, plan, and delegate actions are Happier-managed execution runs; they are available through the action catalog and can be surfaced directly when that is the intended product workflow.

I want voice to do structured work reliably

Voice can use the same built-in actions as the rest of Happier, including:

• action discovery
• subagent launch
• session mode changes
• permission responses
• user-action answers

That keeps voice aligned with the normal app and CLI surfaces instead of inventing separate voice-only commands.

Related pages

• MCP servers
• Agents & subagents
• Permissions
• Inbox and approvals
• Voice
• CLI