share

# Share

Use these Code Mode tools from a Python snippet executed with `run_sdk_snippet`. Import `tool` from `sdk.tool` and call tools with `tool.call(...)`.

## Choose the Target

- For workspace files, continue with this document. This is the most common workflow.
- When a file may reference local assets, first read [references/file-dependencies.md](references/file-dependencies.md).
- For the entire current project, first read [references/project-share.md](references/project-share.md).
- For the current topic or conversation, first read [references/topic-share.md](references/topic-share.md).
- To inspect or change an existing share, first read [references/edit-share.md](references/edit-share.md).
- Never infer an entire-project share from a request to share one or more files.

## File Share Workflow

1. Confirm which files the user wants to share. Do not add additional files without the user’s approval.
2. Call `list_file_shares` with the original exact `file_paths` before creating anything.
3. Read the entry and understand its actual local references first. Decide yourself whether `inspect_file_share` would reduce uncertainty; it is optional assistance, not a mandatory step. Treat its output as static candidates only, then verify candidates against the entry and relevant files. If confirmed local dependencies are omitted, explain that images, styles, fonts, video, or interactions may be missing. When the user has not already requested the related files, ask whether to include them, preferably with an interactive question when available. Do not add unrequested files.
4. Read the entry and the files that will actually be shared when content review is needed. Stop for clearly prohibited content. For possible personal data, credentials, internal material, or an apparently wrong file, explain the concrete risk and ask the user whether to exclude it or cancel.
5. Handle the result:
   - One active share and no requested setting change: return its existing URL and password. Do not call `create_file_share`.
   - Multiple active shares: show the candidates and ask which share to reuse, update, or delete.
   - No active share: continue to entry-file and access selection. If dependencies changed the final file set, call `list_file_shares` again with that final set before creating.
6. Select the required entry file:
   - One file: use that file as `entry_file_path`.
   - Multiple files: use the file explicitly named by the user. Ask which file should open first when it is not uniquely clear.
7. If the user did not choose an access method, explain the three choices and ask before creating:
   - Team access is safest because only organization members can open it, but it is less convenient for external recipients.
   - Password access is the recommended balance of safety and convenience. Anyone with both the link and password can open it. Password-protected file and project shares require VIP.
   - Public access is highest risk because anyone with the link can open it. Use it only after the user explicitly chooses public access.
8. Never change a failed password share to public automatically. Explain the VIP restriction and ask the user to choose team access or explicitly approve public access.

When the original file set already has an active share and the user approves adding dependencies, read that share and call `update_file_share` with the complete final `file_paths` and the existing `entry_file_path`. Do not call `create_file_share` for this repair; preserve the original resource ID and settings. The file list is a complete replacement, so retain every existing file that should remain shared.

Use the user's language when asking about access. A concise question is:

```
How should this be shared?

1. Team access: safest; only team members can open it, but it is less convenient for external recipients.
2. Password access: recommended balance of safety and convenience; file and project password shares require VIP.
3. Public access: highest risk; anyone with the link can open it. Use only for intentional public distribution.
```

## File Tools

Use the literal string values shown for fields with alternatives.

```python
list_file_shares(
    file_paths: list[str] = [],
    status: "active" | "expired" | "deleted" | "all" = "active",
    keyword: str | None = None,
    current_project_only: bool = True,
    page: int = 1,
    page_size: int = 20,
)
```

Pass `file_paths` for exact active-share lookup. Omit it only when browsing file shares. Browsing is limited to the current project unless the user explicitly requests a cross-project search. Exact lookup returns the password when one exists; browsing results do not expose passwords.

For list tools, `status="expired"` includes shares that passed their expiry time and shares that were manually disabled. `status="deleted"` means the share record was deleted and the link is unavailable.

```python
create_file_share(
    file_paths: list[str],
    entry_file_path: str,
    access_type: "password" | "team" | "public" = "password",
    password: str | None = None,
    team_scope: "all" | "designated" = "all",
    team_user_ids: list[str] = [],
    team_department_ids: list[str] = [],
    expire_days: int | None = None,
    show_original_info: bool = True,
    allow_download: bool = True,
    allow_copy: bool = True,
    show_file_list: bool = True,
    hide_super_magic_watermark: bool = False,
    immersive: bool = False,
)
```

`file_paths` and `entry_file_path` are required. The entry file must also appear in `file_paths`. Paths must remain inside the current workspace and already have MagicFS file IDs.

## Access and Page Settings

- Password access: use `access_type="password"`. Omit `password` to generate a secure password.
- Team access for everyone: use `access_type="team"` and keep `team_scope="all"`.
- Team access for selected recipients: use `access_type="team"`, `team_scope="designated"`, and provide at least one user or department ID.
- Pub