- The agent handoff. Owners and admins can decide whether coding agents, such as Claude Code or Cursor, may use Iris Code’s agent tools on the team’s code.
- Pre-push records. The team’s record can note each time the pre-push check passed, and show when a pushed commit has no such record, so a person can look into it.
The agent handoff
The agent handoff is the Iris Code MCP server. MCP is a connection that lets a coding agent call tools; through it, Iris Code gives the agent findings, file paths and short excerpts of code. What the agent then does with those results is governed by its own provider’s data policies. Turning the handoff off refuses every tool that reads the repository, including configuration and safe fixes. The agent receives the errorHANDOFF_FORBIDDEN, with an explanation of who set the restriction.
A few things keep working, because they do not hand over repository content:
iris_check_package, which checks a package name- package guard agent hooks
iris rules
Policy levels
A restriction can be set at three levels. The table shows each setting and what it covers.
To change the organisation or project setting, open Team settings > Agent handoff. Members can see the setting; only an owner or admin can change it. Making it stricter or looser both ask for confirmation, and the workspace history records who changed it and what it was before and after.
Restrictions only add up, never cancel out:
- A project can follow the organisation setting or turn the handoff off. It cannot be more permissive than the organisation.
- In a repository,
"agentHandoff": trueor leaving the key out adds no restriction. Neither one can override a Team restriction.
When changes take effect
The VS Code extension fetches the latest organisation and project settings when it starts, when its window regains focus, and every ten minutes while you are signed in and online. Each agent tool call reads the most recently saved setting. A change therefore applies inside a running agent session once the editor has fetched it. A tool call that has already started finishes under the setting it started with. The repository setting in.irisconfig.json is read on every tool call, so adding false takes effect on the next call. A restriction in a config file higher up the folder tree, or in the folder being checked, also applies.
The CLI can be used while signed out. Editors that are offline or signed out keep any restrictions they remember, under the seven-day rule described below.
Every active membership counts. Policy applies whether or not the member has Pro or an active seat, and if any of a person’s teams restricts the handoff, the restriction wins. Invited people are not covered until they join.
Offline and signed-out behaviour
Each time Iris Code successfully checks your licence, it saves the current policy in~/.iris/governance.json. VS Code, the CLI and JetBrains all share this file. A development build of the editor uses governance.development.json instead.
When the connection fails, the saved policy keeps applying:
- Signing out keeps the saved policy.
- Network failures, server errors and rate limiting keep the last confirmed policy.
- After seven days without a successful check, a machine that remembers any restriction refuses the handoff until it reconnects and checks again.
- Signing in successfully after leaving all organisations clears an old restriction.
Pre-push hook records
The pre-push hook is a check that runs on a developer’s machine when they push. After the whole local check passes, the hook recordshook_passed for each commit and branch that Git handed to it. A failed scan or a failed package guard check records nothing.
Each record holds the commit identifier, branch and time. It contains no code, file paths or member identity. It is only sent when there is a licence, a teamProjectId, and project evidence is switched on.
Some further details:
- Records are kept under the normal Team evidence retention, currently 365 days. Once a record is removed it can no longer be found.
- The hook records up to ten pushed refs (branches or tags) each time it runs, and reports when more were pushed.
- If the record cannot be sent, an otherwise passing push still goes ahead.
iris hook git status tells you when that is needed.
Verify in CI
You can check in CI whether a pushed commit has a pass record:iris hook verify needs Pro and a repository linked to a Team project. It looks for hook_passed against the full 40 or 64 character commit identifier.
If no record is found, it prints a warning and tries to add hook_missing to the Team audit log, shown as Push with no hook record. It always exits 0, including when there is no licence or no network, so it never fails your build.
- GitHub pull requests use
pull_request.head.shafrom the event file, not the merge SHA inGITHUB_SHA. - GitHub pushes use
GITHUB_SHA. - GitLab uses
CI_COMMIT_SHA. - Bitbucket uses
BITBUCKET_COMMIT.
--sha. An explicit SHA always takes precedence.
The command explains why it did not check when:
- the run has no licence, including fork pull requests without secrets;
- Pro entitlement cannot be established;
- the repository has no Team project binding or has invalid config;
- Team evidence is off or the run cannot access the project;
- the GitHub push deletes a branch, is made by a bot, or uses the
web-flowcommitter; - the event is unsupported, cannot be read, or contains no valid full commit identifier;
- another CI system did not supply
--sha; - Iris Code cannot be reached or the lookup response cannot be read.
Read the evidence carefully
A missing record has several possible causes:- the push used
--no-verifyto skip the hook - the hook was not installed, or is an older version
- evidence is switched off
- the record failed to upload