# Sharing & tags

Work belongs to its owner. A share opens one file or conversation to a member, a tagged group, or the whole project.

A **share** grants one file or conversation to an audience. A **tag** is an
opaque label such as `team:acme`; a member who holds it is admitted by tag
shares. Default visibility is in [Who can see what](/identity#who-can-see-what).

**You need:** to own the resource, or an owner, admin, or
[Admin Agent key](/identity/agents#create-an-admin-agent-key).

## Share a file or conversation

1. Create the share:
   ```bash
   introspection shares create --resource-type conversation --resource-id <task-id> --member <member-id>
   ```
2. Check it is listed: `introspection shares list`.

| Audience flag | Admits |
| --- | --- |
| `--member` | That member |
| `--tag` | Every member holding the tag, now or later |
| Both | That member, only while they hold the tag |
| Neither | Everyone in the project |

A share has no read or write mode: the grantee's own token scopes decide. A
file share covers every version of the file.

To change the audience, delete the share (`introspection shares delete <share-id>`)
and create a new one. Revoking takes effect on the next request.

## Give a group access with tags

1. An owner or admin tags each member. Write `{"tags": ["team:acme"]}` to `member.json`, then run:
   ```bash
   introspection members update <member-id> @member.json
   ```
2. Share each resource with `--tag team:acme`.

A task created with `--tag team:acme` needs no share: every member holding
that tag can read and write it. A tag list replaces the old one; `[]` clears
it. Removing a tag takes effect at the member's next token refresh.

## Share from your app

An end user shares their own conversation from the browser or a runner:

```ts
await client.shares.create({ resource_type: "conversation", resource_id: taskId, granted_member_id });
```

Pass `granted_member_id` for one member, `granted_tag` for a tag, or neither
for the whole project. To let an advisor see assigned people's work, tag the
advisor (`advisor:dana`) and have your backend share each assigned
conversation with that tag, using an Admin Agent key.

## Verify

`introspection shares list --filter granted_to_me=true`, run as the grantee,
shows the share, and `introspection conversations get <task-id>` returns the
conversation.

Give a shared file to an agent

A shared file is not mounted into the grantee's tasks. Attach it by ID on a
run; it lands in `/workspace/files`:

```bash
introspection tasks prompt <task-id> --prompt "Use the shared brief" --file <file-id>
```

Hide earlier history, or fork a shared conversation

Add `--visible-from <RFC3339>` to `shares create` to share a conversation from
that moment on. Such a share cannot be forked.

To continue someone's shared conversation as your own task:

```bash
introspection tasks create --runtime support-agent --environment production \
  --fork-share <share-id> --prompt "Continue from here."
```

Tag end users as they arrive

With `INTROSPECTION_TOKEN` set to an API key, pass tags the first time you
name an end user, so tag shares admit them at once:

```bash
introspection tasks create --runtime-id <version-id> --environment production \
  --subject user_123 --identity-tag team:acme --prompt "Summarize my open tickets."
```

Only tags the key's agent member holds are applied, and only when the member
is first created. A returning end user is never re-tagged.

## Limits

| Not supported | Do this instead |
| --- | --- |
| A share that expires | Delete it yourself on a schedule. `--visible-from` hides history; it doesn't end access. |
| Sharing with someone outside your organization | Invite them as a `member`, then share with `--member`. |
| Sharing with someone who is not a member | Show the content through your own app. |

## Next

- [Serve many customers](/patterns/multi-tenant)
- [Files and memory](/observe/files)
- [Projects & members](/identity/projects)

Sharing & tags

Work belongs to its owner. A share opens one file or conversation to a member, a tagged group, or the whole project.

A share grants one file or conversation to an audience. A tag is an opaque label such as team:acme; a member who holds it is admitted by tag shares. Default visibility is in Who can see what.

You need: to own the resource, or an owner, admin, or Admin Agent key.

Create the share:


introspection shares create --resource-type conversation --resource-id <task-id> --member <member-id>

Check it is listed: introspection shares list.

Audience flag	Admits
`--member`	That member
`--tag`	Every member holding the tag, now or later
Both	That member, only while they hold the tag
Neither	Everyone in the project

A share has no read or write mode: the grantee’s own token scopes decide. A file share covers every version of the file.

To change the audience, delete the share (introspection shares delete <share-id>) and create a new one. Revoking takes effect on the next request.

Give a group access with tags

An owner or admin tags each member. Write {"tags": ["team:acme"]} to member.json, then run:
```
introspection members update <member-id> @member.json
```
Share each resource with --tag team:acme.

A task created with --tag team:acme needs no share: every member holding that tag can read and write it. A tag list replaces the old one; [] clears it. Removing a tag takes effect at the member’s next token refresh.

An end user shares their own conversation from the browser or a runner:


await client.shares.create({ resource_type: "conversation", resource_id: taskId, granted_member_id });

Pass granted_member_id for one member, granted_tag for a tag, or neither for the whole project. To let an advisor see assigned people’s work, tag the advisor (advisor:dana) and have your backend share each assigned conversation with that tag, using an Admin Agent key.

Verify

introspection shares list --filter granted_to_me=true, run as the grantee, shows the share, and introspection conversations get <task-id> returns the conversation.

Give a shared file to an agent

A shared file is not mounted into the grantee’s tasks. Attach it by ID on a run; it lands in /workspace/files:


introspection tasks prompt <task-id> --prompt "Use the shared brief" --file <file-id>

Hide earlier history, or fork a shared conversation

Add --visible-from <RFC3339> to shares create to share a conversation from that moment on. Such a share cannot be forked.

To continue someone’s shared conversation as your own task:


introspection tasks create --runtime support-agent --environment production \
  --fork-share <share-id> --prompt "Continue from here."

Tag end users as they arrive

With INTROSPECTION_TOKEN set to an API key, pass tags the first time you name an end user, so tag shares admit them at once:


introspection tasks create --runtime-id <version-id> --environment production \
  --subject user_123 --identity-tag team:acme --prompt "Summarize my open tickets."

Only tags the key’s agent member holds are applied, and only when the member is first created. A returning end user is never re-tagged.

Limits

Not supported	Do this instead
A share that expires	Delete it yourself on a schedule. `--visible-from` hides history; it doesn’t end access.
Sharing with someone outside your organization	Invite them as a `member`, then share with `--member`.
Sharing with someone who is not a member	Show the content through your own app.