langchain-ai/deepagents · error · PermissionError

Project hooks cannot execute before workspace trust is grant

Error message

Project hooks cannot execute before workspace trust is granted

What it means

HooksRuntime.invoke refuses to run any hooks that come from project-level configuration when the workspace has not yet been marked trusted. The library treats project-supplied hook handlers as untrusted code, so executing them before an explicit trust grant would let a cloned repo run arbitrary code. It raises PermissionError defensively at the top of invoke.

Source

Thrown at libs/code/deepagents_code/hooks/runtime.py:197

            agent_id: Optional subagent scope.
        """
        self.transcripts.append_messages(thread_id, messages, agent_id=agent_id)

    async def invoke(self, invocation: HookInvocation) -> HookDecision:
        """Materialize transcripts, execute matching handlers, and return a decision.

        Args:
            invocation: Domain lifecycle invocation.

        Returns:
            Event-specific decision with notices, sequences, and diagnostics.

        Raises:
            PermissionError: If project handlers were loaded without workspace trust.
        """
        if self.project_hooks_loaded and not self.workspace_trusted:
            msg = "Project hooks cannot execute before workspace trust is granted"
            raise PermissionError(msg)
        prepared = self.prepare_invocation(invocation)
        return await self.engine.run(
            prepared.invocation,
            transcript_path=prepared.transcript_path,
            agent_transcript_path=prepared.agent_transcript_path,
            on_progress=self.presenter.update_progress,
        )

    def prepare_invocation(
        self,
        invocation: HookInvocation,
    ) -> PreparedHookInvocation:
        """Materialize client-only transcript paths and revision identity.

        Args:
            invocation: Domain lifecycle invocation.

        Returns:

View on GitHub (pinned to a1af029e6e)

Solutions

1. Mark the workspace trusted before invoking: set runtime.workspace_trusted = True (or call the trust-approval API / trust_project_hooks flow for the project path).
2. If project hooks are not needed, load only user-level hooks so project_hooks_loaded stays False.
3. In automated environments, pre-seed the hooks trust store (hooks trust store JSON with the project path and current version) so trust is already granted.
4. Catch PermissionError and surface a trust prompt to the user instead of retrying.

Example fix

// before
runtime = HooksRuntime.from_config(project_config)
await runtime.invoke(invocation)  # PermissionError

// after
if not runtime.workspace_trusted:
    trust_project_hooks(project_root)  # or prompt the user
await runtime.invoke(invocation)

if runtime.project_hooks_loaded and not runtime.workspace_trusted:
    raise PermissionError("Trust this workspace before running project hooks")
await runtime.invoke(invocation)

def can_invoke(runtime) -> bool:
    return not runtime.project_hooks_loaded or bool(runtime.workspace_trusted)

try:
    await runtime.invoke(invocation)
except PermissionError:
    prompt_workspace_trust(runtime)  # then retry once

When it happens

Trigger: Calling runtime.invoke (public) while runtime.project_hooks_loaded is True and runtime.workspace_trusted is False — i.e. project hook handlers were loaded from the workspace but the user never approved trust for that workspace.

Common situations: Opening a cloned repository that ships .deepagents/hooks config and immediately invoking hooks programmatically; CI running in a fresh checkout where no trust prompt was answered; tests constructing a runtime with project hooks but skipping the trust step.

Related errors

• debug log directory is not a real directory: {path}
• debug log directory is not owned by the current user: {path}
• Cannot determine whether {str(left)!r} is {str(right)!r}: {e
• Repository root must be an absolute contained path: {root!r}
• allow_fs_tools must be None or a non-empty list

AI-assisted analysis of langchain-ai/deepagents@a1af029e6e (2026-08-29). Data as JSON: /api/errors/3b3ab8201186fadf. Report an issue: GitHub.