> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/phases/phase_19/session_05_attention_and_permissions.md).

# Session 05: Attention And Permissions

**Session ID**: `phase19-session05-attention-and-permissions` **Packages**: apps/server, apps/web, apps/hooks **Status**: Complete **Completed**: 2026-06-26 **Estimated Tasks**: \~12-25 **Estimated Duration**: 2-4 hours

***

## Objective

Merge plans, permissions, guarded actions, blocked tasks, and review gates into one operator attention queue.

***

## Scope

### In Scope (MVP)

* Attention manager snapshot and decision routes
* Blocking permission request and response-file round trips for supported hook providers
* Plan approvals, local proposals, async notices, stale queue decisions, failed verification, and review gates as attention items
* Timeout, requester, family/kind, risk, preview, target, revision, expected result, reason, actor, and result state fields
* Web approval/rejection controls with reason capture and audited result state

### Out of Scope

* Running executor families after approval
* Push or mobile notification delivery

***

## Prerequisites

* [x] Sessions 01 through 04 complete
* [x] Current permission, plan approval, guarded action, and hook response paths inspected

***

## Deliverables

1. Unified attention manager and snapshot route
2. Permission and plan approval response adapters
3. Attention queue UI with filters, counts, and reason capture
4. Tests for timeout, stale decision, blocking response, and visible counts

***

## Source Coverage And Evidence

Source coverage:

* Session Split Plan Session 05: Attention And Permissions
* Implementation Target 3: Unify Plans, Permissions, And Guarded Actions
* Balls-To-The-Wall Track B `attentionManager` and `permissionRequestManager` routes
* Balls-To-The-Wall Track D permission hook mapping

Key EXAMPLES links:

* [Side panel plan and permission guide](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-guide/SKILL.md#L101-L112)
* [Permission modes](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/skills/factionos-guide/SKILL.md#L137-L145)
* [Permission hook](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/1st-pass-artifacts/hooks-bundle/factionos-permission-request.sh#L1-L154)
* [Permission routes](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/api-routes.txt#L118-L122)
* [Claude hook contract response flow](https://github.com/AI-with-Apex-VIP/factionos/tree/main/.spec_system/EXAMPLES/findings/claude-hook-contract.md#L61-L99)

***

## Success Criteria

* [x] Guarded actions, permission requests, plan approvals, blocked tasks, and review gates appear in one queue
* [x] Approve/reject decisions record actor, reason, revision, time, and result
* [x] Blocking permission requests unblock or time out through tested paths
* [x] Unsupported providers surface capability errors instead of dropped items


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/phases/phase_19/session_05_attention_and_permissions.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.