ccpocket

The system uses a conservative approach to determine if a pending action conflicts with the current Bridge state.

PendingInputAction is a CONFLICT if the delta since baseSeq contains:

• user_input from another device or client.
• A result that completes the current turn.
• System events that change the conversation context (e.g., session switch, rewind, sandbox restart, or stop_session).

PendingInputAction is NOT a conflict if the delta contains:

• status updates.
• stream_delta or thinking_delta.
• assistant messages.
• tool_result.
• permission_request or permission_resolved.
• conversation_queue updates.

Other Action Conflict Rules:

• PendingStartSessionAction: Not a conflict if projectPath, provider, and startOptions are valid (since the session doesn't exist on the Bridge yet).
• PendingResumeSessionAction: Conflict if the provider session's metadata/timestamp has changed.
• PendingRenameSessionAction: Failed if the session cannot be resolved; otherwise, follows 'latest-wins'.
• PendingCodexQueueAction: Failed if the target itemId no longer exists in the Bridge's conversation_queue.

CC Pocket uses an adaptive layout system that switches between 1, 2, and 3 panes based on available screen width rather than device type. This allows the app to provide an optimized experience on tablets, foldables, and macOS.

Pane Roles

• Left Pane: Contains the session list, new session triggers, and navigation to settings/gallery.
• Center Pane: The primary workspace area, hosting ClaudeSessionScreen or CodexSessionScreen.
• Right Pane: An auxiliary area for tools like GitScreen, ExploreScreen, or GalleryScreen.

Layout Modes

• 1 Pane (< 600dp): Standard full-screen mode. Navigation uses route pushes (e.g., moving from list to detail).
• 2 Pane (600 - 1099dp): Typically shows Left + Center. If a right pane tool (like Git) is requested, the layout switches to Center + Right, automatically collapsing the left pane to prioritize the center content.
• 3 Pane (1100dp+): Shows Left + Center + Right simultaneously. Both side panes can be manually collapsed.

Permissions can be granularly defined using the pattern ToolName(ruleContent). Rules can be set to allow, deny, or ask behaviors.

Rule Syntax Examples

• Read: Matches any use of the Read tool.
• Bash(npm:*): Prefix match; matches any Bash command starting with npm.
• Bash(git status): Exact match; matches only the specific command git status.
• Edit(.claude): Matches the Edit tool when targeting .claude files.
• Write(/etc/*): Matches the Write tool for paths under /etc/.

Rule Scopes (Destinations)

Rules are stored in different locations depending on their intended lifecycle:

• session: Volatile, in-memory approvals for the current session.
• cliArg: Passed via --allowed-tools or --disallowed-tools.
• command: Provided via slash commands.
• localSettings: Stored in .claude/settings.local.json.
• projectSettings: Stored in .claude/settings.json (typically checked into version control).
• userSettings: Stored in ~/.claude/settings.json.
• policySettings: Organization-level read-only policies.
• flagSettings: Runtime feature flags (read-only).

{
  "permissions": {
    "allow": ["Bash(npm:*)", "Edit(.claude)", "Read"],
    "deny": ["Bash(rm -rf:*)"],
    "ask": ["Write(/etc/*)"],
    "defaultMode": "acceptEdits"
  }
}

The SDK communicates via a stream of ThreadEvent objects. You should listen for these events to track the lifecycle of a thread and the progress of individual items (like reasoning or tool calls).

Event Lifecycle Patterns

Standard Text Response: thread.started $\rightarrow$ turn.started $\rightarrow$ item.completed(reasoning) $\rightarrow$ item.completed(agent_message) $\rightarrow$ turn.completed

Response with Command Execution: thread.started $\rightarrow$ turn.started $\rightarrow$ item.completed(reasoning) $\rightarrow$ item.completed(agent_message) $\rightarrow$ item.started(command_execution) $\rightarrow$ item.completed(command_execution) $\rightarrow$ item.completed(agent_message) $\rightarrow$ turn.completed

ThreadItem Types

Items represent the specific content generated during a turn:

• AgentMessageItem: The actual text response from the agent.
• ReasoningItem: A summary of the agent's internal reasoning (e.g., "**Planning file read execution**").
• CommandExecutionItem: Details about shell commands being run (includes command, aggregated_output, exit_code, and status).
• FileChangeItem: Patches or file modifications.
• McpToolCallItem: Calls to MCP tools.
• WebSearchItem: Web search results.
• TodoListItem: Task lists generated by the agent.
• ErrorItem: Error details.

type ThreadEvent =
  | ThreadStartedEvent
  | TurnStartedEvent
  | TurnCompletedEvent
  | TurnFailedEvent
  | ItemStartedEvent
  | ItemUpdatedEvent
  | ItemCompletedEvent
  | ThreadErrorEvent;

type ThreadItem =
  | AgentMessageItem
  | ReasoningItem
  | CommandExecutionItem
  | FileChangeItem
  | McpToolCallItem
  | WebSearchItem
  | TodoListItem
  | ErrorItem;