GrantTap field guide · · 15 min read
Bring a colleague into an agent project with clear access
A collaboration lifecycle across person, device, project and computer: scoped roles, repository grants, useful context, secrets, verified handoff and honest offboarding.
Sharing an agent project with a colleague is more than forwarding a conversation. The colleague needs to understand the objective, see the relevant material, reach an allowed computer, and know which decisions they may make. At the same time, the original owner may need to keep unrelated repositories, credentials, and personal history separate. A useful collaboration setup makes those boundaries understandable before the first shared task, rather than discovering them through a failed command or an unexpectedly broad view of somebody else's work.
GrantTap organizes collaboration through distinct account, device, project, and execution scopes. A stable Task can continue across supported providers and computers, but it does not merge every permission attached to those endpoints. This article proposes an onboarding and offboarding method based on that separation. It is a practical guide, not a claim that access can erase material somebody already copied. The editorial date is October 29; the article and its product references were prepared and checked on November 5, 2026.
Define the collaboration before granting access
Begin with the work the colleague should help complete. Name the project, the repositories involved, the intended duration, and the actions the person needs. Reading a progress report, answering a product question, creating a Task, choosing a computer, and changing Governance are different responsibilities. A role label is useful only when its effective permissions fit those responsibilities. Avoid starting with the broadest access and planning to narrow it later. A small initial scope is easier to explain, verify, and expand when a real need appears during the collaboration.
Also state what successful onboarding looks like. The colleague should be able to find the intended project, understand one task, and perform one permitted action through the expected route. They should not need an accidental view of another repository to make the demonstration work. Include a harmless denied action in your review where appropriate, so you can see that the boundary is real rather than merely absent from the navigation. This is a proposed acceptance method, not a test GrantTap runs automatically for every invitation. The owner should be able to recognize both the allowed path and its intended limit.
Distinguish the person, the device, and the project
An account identifies a person in the relevant account space. A paired device is a controller with its own connection and key material. A Project Mesh defines a collaboration scope for tasks, repositories, people, computers, and rules. These layers relate to one another without becoming interchangeable. Signing in on a phone does not automatically authorize it to operate every computer. Pairing a controller does not make its owner an administrator of every project. Joining a project does not give the recipient unrestricted access to the original person's provider account or file system.
Keep a simple access map for the collaboration. It should identify the person, their intended controller, the project, the allowed repositories, and any computer they can use for execution. You do not need to publish private identifiers in that map, but the owner needs a way to distinguish similar names. If something is missing, repair the relevant layer instead of recreating the whole account or granting universal access. This separation is especially helpful when one person uses several devices or the same computer participates in multiple projects. The relationship you need to change may be much narrower than the visible symptom suggests.
Review repository grants and Mesh membership separately
GrantTap's repository-related access and project membership have their own roles. A repository grant is not an edit to the Git provider's access-control list. An invitation to a Mesh does not, by itself, supply a clone of every repository or the credentials needed to fetch it. Confirm how the colleague will obtain the authorized code through the team's existing Git or file workflow. Then check the GrantTap scope that lets the controller see and act on the relevant project information. Neither layer should be treated as a substitute for the other merely because both use the same repository name.
When the collaboration spans several repositories, list which relationships are needed. A linked project can expose relevant shared evidence without merging all access decisions. A colleague working on one library may need its public interface and selected integration facts rather than unrestricted access to every consumer. Keep the actual grants aligned with that need. If a dependency report is incomplete, do not widen access just to make its diagram look complete. The practical objective is enough information to finish the authorized work while preserving the separation that made the collaboration acceptable to the participating owners.
Choose a role by the actions it permits
Viewer, Member, and Admin are recognizable starting points, but inspect the permissions beneath the role. Reading project events, posting a message, creating a Task, changing Governance, selecting an allowed computer, and choosing a model can require distinct authority. Use the controls available in the current client and the computer's reported support. Do not infer an operation from a role name if the interface or policy explicitly restricts it. A member may be able to contribute to a task without being allowed to choose any machine or modify the project's execution boundary.
Explain the important restrictions in ordinary terms during onboarding. The colleague should know where a refusal is expected and how to ask for a legitimate extension. A useful denial names the missing permission or unavailable route; it should not be disguised as an endless spinner. If the owner already authorized a particular action, preserve that authorization rather than forcing the person to request it again on every turn. Collaboration should make ordinary permitted work easier while keeping new sensitive decisions explicit. Excessive broad grants and excessive repeated confirmation are both signs that the practical scope has not been described clearly enough.
Treat the execution computer as a real boundary
A Task needs an actual computer route when the chosen integration executes locally. Check which machine owns the execution, which workspace is available there, and whether the provider is installed and authenticated. A display name is not a reliable replacement for that identity. Renaming a machine or joining another network should not be interpreted as permission to run the task on a different computer with a similar label. GrantTap's route information helps preserve this distinction, but the collaborator should still inspect the intended destination before starting consequential work.
If a project pins execution to an allowed computer, an unavailable machine should remain an unavailable route or enter the supported queue with its stated conditions. It should not silently fall back to somebody else's workstation. This matters for data access, tool versions, and responsibility for the result. During onboarding, test a small safe task on the intended machine and inspect its receipt and provider activity separately. A connected account or online relay does not prove that the selected computer is awake, that its MCP is current, or that the provider can begin the requested work.
Give the colleague enough context to continue
Prepare a compact starting packet: the objective, current revision, relevant files or interfaces, accepted decisions, meaningful checks, and unresolved questions. Avoid exporting the entire conversation merely because it is available. A well-scoped summary helps the colleague understand why the current approach exists and what evidence supports it. Preserve links to source material where the recipient is allowed to read it. Distinguish facts from hypotheses and product decisions from suggestions found in external documents. The new participant should not have to guess which sentence in a long transcript actually defines the task they are expected to complete.
GrantTap's Knowledge and project instructions can support this organization, within their implemented scope. They are not proof that every agent has already read or adopted the material. Prepared context and observed agent behavior remain different states. Check that the selected execution receives the relevant information through its supported path. If the packet refers to an unavailable repository, replace the assumption with an allowed interface description or resolve the grant explicitly. Do not silently copy private material across a boundary just because it would make the summary more complete. Useful context has both content and a legitimate route to its reader.
Keep secrets out of ordinary onboarding material
An environment variable's name and purpose may be useful to a new contributor without exposing its value. Explain which service provides a credential, which task needs it, and how the team normally grants the required access. Prefer a restricted account or a supported secret-management path over a shared personal token. Do not place production credentials into a general Knowledge entry or an invitation note. The fact that project participants can read instructions does not mean they should receive every secret used by the owner's local machine. Documentation and authorization serve different purposes.
Provider sign-in is also separate from project membership. If the colleague runs a provider on their own computer, that installation needs its own supported authentication and tool readiness. GrantTap's Devices controls can start supported sign-in and update actions for the selected computer; they do not automatically transfer the original owner's provider account. When the person is intended only to review or answer questions, avoid granting unnecessary execution authority just to make a setup checklist look symmetrical. A useful onboarding record explains the permitted path and the credentials it actually requires, while leaving unrelated personal access untouched.
Coordinate work without confusing ownership
When several people or agents contribute, make the current owner of each task or file concern visible. Resource claims and project events can help communicate overlap, but a claim is not an operating-system lock and not a substitute for Git integration. A stale claim needs a supported release or a deliberate owner decision; it should not be treated as permanent proof that somebody is still working. Conversely, an empty claim list does not establish that no person has local edits. Use the available evidence together with the team's actual development workflow.
Define how changes will be integrated. Separate worktrees or branches can reduce accidental interference, but they still require review and a chosen merge path. A colleague's successful test does not automatically validate a later combined tree. Keep the relevant revision and check result with the work it describes. GrantTap can preserve task continuity and route supported actions, while the repository remains responsible for its actual state. This division avoids a common misunderstanding: a shared timeline of progress is useful coordination, but it does not make independently edited working copies instantly synchronized or resolve their conflicts without an explicit integration step.
Transfer a Task with a verifiable starting point
Before a supported handoff, inspect the source state and any local changes. A commit-based transfer does not carry uncommitted work automatically. The source may offer a checkpoint on a separate branch; read its effect and wait for confirmation. If work remains on the original machine, state that clearly in the handoff record. The destination should know which facts and files it can rely on. A transfer note saying that everything is ready is less useful than a specific revision, a short explanation of the change, and the next unresolved acceptance condition.
On the receiving side, distinguish Request queued, Source confirmed, and Destination ready. The colleague can close a waiting interface without assuming the transfer is complete. Once the destination is ready, open its Execution and verify the provider, computer, workspace, and relevant files. A new conversation may belong to the same Task while keeping a different native session identifier. That is not necessarily a failure of continuity. The important question is whether the receiving execution has an authorized, understood starting point and can continue the intended objective without inventing missing state from an old source-machine transcript.
Test both the allowed path and a meaningful limit
Use a sample task to check onboarding. Ask the colleague to find the project, read the intended context, and perform one low-impact action their role allows. Observe the actual result on the relevant computer or source. Then inspect a boundary that should remain restricted, using a harmless route that cannot damage real data. For example, the interface may refuse a role-limited configuration change before sending it to the computer. The exercise should be proportionate and explicit; do not probe unrelated systems or create a destructive operation just to demonstrate that it would be denied.
Record what the test established. A visible denial can confirm one permission path without proving that every operation is constrained. A successful read can confirm access to the selected project without confirming access to all linked repositories. A sample provider turn can establish readiness for that route without demonstrating every tool integration. Keep these limitations in the onboarding note so future participants do not inherit an exaggerated assurance. The proposed exercise is useful precisely because another owner can repeat or challenge it. It is not a generic security certification and should not be presented as one in a report or marketing screenshot.
Plan how the collaboration will end
Decide how long the access should last and who is responsible for removing it. A short review engagement may need a different lifecycle from an ongoing maintainer role. Identify the account membership, project permissions, repository grants, direct device connections, and external credentials that were actually added. You do not need to revoke unrelated personal access or dismantle every project when one collaboration ends. The removal plan should mirror the granted scope. Preparing it at onboarding makes offboarding a known operation instead of a hurried search through settings after the person is already unavailable.
Keep a distinction between preventing future access and removing material already obtained. Revoking a grant cannot make a person forget code they read or delete an independent copy on their machine by assertion. Provider credentials and Git permissions also have their own owners and revocation paths. If a shared credential was used, the appropriate service may require rotation rather than merely removing a Mesh invitation. The plan should identify those separate actions honestly. A clean-looking project member list is useful evidence about that list; it is not proof that every related external system has revoked the same person's access.
Verify offboarding and preserve useful work
After removing the intended access, confirm the resulting state from an appropriate source. The former participant should no longer be able to perform the restricted future action through the revoked path. Keep the verification harmless and within the owner's authority. Preserve accepted commits, task history, and legitimate project evidence according to the team's retention policy. Removing a contributor does not mean their reviewed code should disappear or that unfinished work must be destroyed. Ownership of the artifact and access to the collaboration surface are related but separate decisions.
If the outcome is uncertain, record the specific unresolved layer. Perhaps Mesh membership is removed while a Git provider grant still needs attention. Perhaps a controller is unlinked while the person's provider account remains their own. This is more useful than declaring complete revocation without checking its components. A good offboarding record also identifies who can finish any remaining task and where its last verified state lives. The project should remain understandable after the participant leaves, with enough evidence to continue safely and without retaining unnecessary active credentials or unexplained execution routes.
Make the collaboration record useful to the next person
The most durable onboarding artifact is a short map of responsibility and evidence. It names the purpose, access scope, intended computer route, context sources, integration workflow, verification point, and removal owner. Keep it current when the project changes materially. If the provider or workspace changes, update the route rather than leaving the old machine as an implicit assumption. If a role gains a new responsibility, record why the extra permission is needed. This makes future troubleshooting more precise and prevents an obsolete setup instruction from becoming a permanent reason for excessive access.
The conceptual illustrations here show separate keys, project boundaries, and independent work folders. They are not product screenshots or evidence that a real person's access was granted or revoked. For current controls, use the GrantTap guide on members, account recovery, workspaces, handoff, provider readiness, and project configuration. The practical aim is a collaboration that somebody can explain from beginning to end: who may do what, on which computer, with which data, and how the result is verified. That clarity helps the agents continue useful work while keeping the human owners in control of the decisions that actually belong to them.
