Fixes #10707.

What

beforeAddTeamMember is typed Promise<void | { data: Record<string, any> }>, the same as beforeCreateTeam and beforeUpdateTeam. It does not honour that return value. At routes/crud-team.ts the call site read the hook's result, tested it, and then did nothing with it:

if (response && typeof response === "object" && "data" in response) {
    // Allow the hook to modify the data
}

The plugin has ten "data" in response sites and this was the only one with an empty body. git log -L puts its origin in bba0a42 ("feat(organization): organization life cycle hooks"), the same PR that added the working siblings — so it shipped empty rather than having been broken later. The comment describes the opposite of what the block does.

Fixing that alone is not enough to make the reporter's case work. teamMember was also the only one of the plugin's six org-owned models whose schema option omitted additionalFields — the other five all carry it. Since transformInput iterates the declared fields (packages/core/src/db/adapter/factory.ts:210) and never Object.keys(data), an undeclared key is dropped silently before it reaches any adapter. So the hook had nothing it could legally write, and the two defects are only observable together.

That gap looks like scope drift rather than a decision: additionalFields landed in 93698af, whose title names exactly the four models that existed then; teamMember arrived later with only modelName + fields, and the next model added after it (organizationRole) did ship with additionalFields.

How

• types.ts / organization.ts — give teamMember the additionalFields option and spread it into the model's fields, matching the five siblings.
• routes/crud-team.ts — capture response.data and pass it to both insert paths. There are two: addTeamMemberWithLimit when teams.maximumMembersPerTeam is set, and findOrCreateTeamMember otherwise. Threading only the second would have left the seat-limited path silently dropping hook data, so both are covered and both are tested.
• adapter.ts — thread the fields through to createTeamMemberWithKey, the single adapter.create({ model: "teamMember" }) in non-test source. They are spread first, so teamId / userId / membershipKey / createdAt are re-applied after and stay authoritative. That ordering is load-bearing, not tidiness:
  • the route validates the team, the target user's org membership and the user record before the hook runs, so a merged { data: { teamId: "…" } } would insert into a team that was never checked;
  • membershipKey is declared input: false, but nothing in packages/core/src/db/adapter/ enforces input: false — transformInput has no such check. The ordering is the only thing protecting the unique membership key.
• adapter.ts — stripTeamMembershipKey now runs through filterOutputFields. Every teamMember-returning path used that hand-rolled helper instead of filterOutputFields, which is what enforces returned: false for the siblings; enabling additionalFields without this would have leaked any field declared returned: false.
• client.ts — OrganizationClientOptions["schema"] listed five models and omitted teamMember too. Without this, declaring teamMember fields on the client fails to compile, and the documented inferOrgAdditionalFields pattern fails with TS2559: has no properties in common when teamMember is the only model with additional fields — which is exactly the reported use case.

computeTeamMembershipKey still hashes only [teamId, userId], so no additional field can perturb the dedup key or the unique index. Nothing under packages/core is touched.

Direction — worth a maintainer's call

I implemented the reading that the type signature promises. The honest counter-argument is that this hook's JSDoc never advertised the mutation: "You can return a data object to override the default data." appears seven times in types.ts and never for beforeAddTeamMember, and the docs example only validates and throws.

The alternative is narrowing the return type to Promise<void> and admitting the hook is validate-only. I did not take it because the TypeScript contract is unambiguous and identical to two hooks that do honour it, and because narrowing is a breaking type change for anyone returning data today — currently a silent no-op, afterwards a compile error — with no runtime benefit. If you would rather have the narrowing, say so and I will swap it; the failing test is already here either way.

Two smaller semantics I picked and would happily change:

• Re-add applies nothing. Both adapter methods are find-or-create, so when the membership already exists the existing row is returned untouched. I think not silently rewriting an established membership is right, but it does differ from beforeUpdateTeam.
• createdAt stays authoritative, unlike beforeCreateTeam, which lets the hook override it. One rule seemed easier to explain than two: the hook adds fields, it does not rewrite the row's identity or timestamp.

Scope

Section 3 of the issue — that only the dedicated endpoint fires teamMember hooks — is deliberately not here. The other three insert paths (crud-org.ts, crud-members.ts, crud-invites.ts) create rows without running this hook, so hook-supplied fields are absent there. Changing that changes when hooks fire, which is an API decision rather than a bug fix. It is now stated in the docs example so nobody adopts the pattern expecting full coverage, and I am glad to follow up if you want it.

Verification

Baseline captured on main @ 64da15b before any edit; pnpm test avoided per AGENTS.md, so this is the organization plugin suite.

Zero pre-existing failures, and no test that passed in the baseline fails now. All four new tests were watched failing before the fix:

• should declare teamMember additional fields on the table — the schema spread, via getAuthTables
• should apply data returned from beforeAddTeamMember — end to end on the find-or-create path, including returned: false filtering
• applies the hook data on the seat-limited insert path — the maximumMembersPerTeam path the report never reaches
• lets the client schema declare teamMember additional fields — the client-side gap

The compile-time half of the bug reproduces as TS2353 on the satisfies form and TS2769 on the organization({ … }) call form.

Changeset included (better-auth: patch).

Parts of this were written with AI assistance; I have reviewed the change and can discuss any of it.

Summary by cubic

Applies beforeAddTeamMember returned data and adds schema.teamMember.additionalFields, so member-level fields persist and round-trip like other org models. Previously the hook’s data was ignored and undeclared fields were dropped.

• Threads additionalFields from the route through the adapter into both insert paths (find-or-create and seat-limited). teamId, userId, membershipKey, and createdAt remain authoritative and override hook data.
• Filters teamMember responses via filterOutputFields to honor returned: false; membershipKey remains server-only.
• Extends server types and client OrganizationClientOptions["schema"] to include teamMember.additionalFields, unblocking inferOrgAdditionalFields.
• Docs clarify limits (hook runs only on addTeamMember, applies on insert only), require optional or defaultValue fields for other creation paths, and the example now declares the teamMember field it returns.

Migration

• Declare schema.teamMember.additionalFields on both server and client if you want to store extra member-level data.
• Make those fields optional or give them a defaultValue if you also add members via createOrganization, addMember, or acceptInvitation (these do not invoke the hook).
• Do not rely on overriding teamId, userId, membershipKey, or createdAt in the hook; they are ignored.

Written for commit 50f9c94. Summary will update on new commits.