Control file access

File governance answers two separate questions: which paths a user can reach and what operations the user can perform there. Governance is always active. Maia always denies unmatched paths, so adding a user and role does not expose files; you add only narrow grants for real work.

Understand policy evaluation

Maia can evaluate access from role, team, and individual user policies. A path policy normally distinguishes read access from write access and can require a human confirmation before a permitted write is applied.

Create a folder policy

1. Open Governance → File access.
2. Review the existing policy list first, then select Add policy.
3. Enter the narrowest absolute folder path that contains the required work.
4. Select the roles, registered teams, or individual users that may read or write.
5. Enable write confirmation when changes require an authorized person to approve the final operation.
6. Save and test with an identity in that scope.

Example configuration

governance:
  users:
    "slack:U_MANAGER":
      roles: [manager]
  folder_policies:
    - path: /srv/company/finance/reports
      read_roles: [viewer, operator]
    - path: /srv/company/finance/drafts
      read_roles: [operator]
      write_roles: [operator]
      write_approval_users: ["slack:U_MANAGER"]

For every non-admin identity, there is no configurable global allow policy: when no folder policy or direct person/team grant matches a path, Maia denies the operation. An authenticated administrator has global file authority.

Grant access from People or Teams

For focused exceptions, open Governance → People or Governance → Teams and add an exact file or folder grant. Choose read access, whether files and subfolders are included, and one of three write modes: No write, Direct write, or Write after approval. Keep Include files and subfolders enabled for a folder; disabling it grants only the exact path and does not cover files inside. Approval mode shows governed managers and administrators by name, not roles, and Maia refuses to save a new approval-mode grant until at least one person is selected. A selected manager receives the path access needed to inspect and execute the reviewed edit. Existing role-based YAML remains compatible.

Enter the server path manually or select Browse to navigate the filesystem visible to the Maia process. The browser inserts the exact server-side path; it does not upload, copy, or expose file contents. When Maia runs in WSL, use the path shown by this browser rather than translating it into a Windows path.

Gateway conversations receive only the current requester's readable path grants as agent context. This means a person with an exact grant for /srv/company/finance/financas.xlsx can ask for “the finance spreadsheet” without knowing the full server path. When a broad search root is not granted, Maia searches only that person's readable grants and authorizes every result again; denied sibling files and more-specific denied child paths stay invisible.

Saving a grant, revocation, read/write change, or approval-mode change replaces the user's existing sandbox when their next gateway request starts. The user does not need to open a new thread and the administrator does not need to restart the gateway.

An authenticated administrator has global file access, including paths without a matching grant and paths with user/team deny entries. Maia still fails closed if Governance cannot authenticate that role. A team manager may change only paths below a delegated team root and cannot create role-wide grants or grant access to another team's users; governed administrators remain available as named reviewers.

Handle write confirmation

When a permitted operation requires confirmation, Maia blocks the employee's file-tool call without changing or staging the file. The agent can finish planning the exact edit and tag the selected reviewer returned by Governance. For Slack and Discord reviewers on the same platform, Maia returns native <@USER_ID> markup so the response creates a real mention; the employee may also tag the reviewer.

Conversation remains natural: Maia does not match approval keywords or intercept the reviewer's text. The selected manager's or an administrator's later message is a normal agent turn under that person's authenticated identity, so it can agree, reject, ask a question, or revise the edit. If they ask Maia to proceed, the model calls the file tool and Governance rechecks that current sender before writing. The natural-language reply never grants access or changes the file policy.

Check the gateway review prerequisites

• Admit both people to the gateway and map each stable platform identity in Governance → People.
• Give the employee Write after approval and select at least one named governed manager or administrator. You do not need a second direct-write grant for that selected manager.
• Keep the employee, reviewer, and Maia in one shared platform thread with gateway.thread_sessions_per_user: false.
• Do not move the review between separate direct messages. They are isolated and do not transfer conversation context.
• Let the reviewer respond in natural language. The authenticated sender of each turn, not an approval keyword, determines whether Governance allows the requested file operation.

Follow the platform-specific setup for Slack governed edit review or Discord governed edit review.

Use individual exceptions sparingly

Prefer role and team policies because they are easier to audit. Use an individual policy for a temporary responsibility or a genuinely unique access requirement, and document why the exception exists.

Test both directions

• Read an allowed file and verify the content is available.
• Attempt a sibling path that is not covered and verify denial.
• Propose a write as a conditional writer and verify the planning-only block names eligible writers without creating a staged change.
• Reply naturally as an ineligible user and verify that the target file remains unchanged.
• Continue in the shared thread as an eligible writer, request the final edit, and verify both the file and audit event.