agent execution context requires MULTICA_TOKEN to be a task-

Error message

agent execution context requires MULTICA_TOKEN to be a task-scoped mat_ token%s

What it means

newAPIClient refuses to build a client in a daemon-managed execution context unless the token is a task-scoped mat_ token. When the only daemon signal is a leftover workdir marker (no MULTICA_AGENT_ID/MULTICA_TASK_ID/MULTICA_DAEMON_PORT), the message appends the exact marker file path so the user can recover instead of hitting an opaque refusal.

Source

Thrown at server/cmd/multica/cmd_agent.go:265

// resolveProfile returns the --profile flag value (empty string means default profile).
func resolveProfile(cmd *cobra.Command) string {
	val, _ := cmd.Flags().GetString("profile")
	return val
}

func newAPIClient(cmd *cobra.Command) (*cli.APIClient, error) {
	taskContext := inDaemonManagedExecutionContext()
	token := resolveToken(cmd)
	if taskContext && !strings.HasPrefix(token, "mat_") {
		// When the ONLY daemon signal is a workdir marker (no MULTICA_AGENT_ID /
		// MULTICA_TASK_ID / MULTICA_DAEMON_PORT), the likeliest cause outside a
		// real task is a leftover marker from a crashed daemon task in a
		// local_directory. Name the exact file so a normal user can recover
		// instead of hitting an opaque "requires mat_ token" error. Shares its
		// wording with requireHumanLocalCommand: same cause, same remedy.
		if markerPath := leftoverDaemonTaskMarkerPath(); markerPath != "" {
			return nil, fmt.Errorf("agent execution context requires MULTICA_TOKEN to be a task-scoped mat_ token%s", leftoverMarkerSuffix(markerPath))
		}
		return nil, fmt.Errorf("agent execution context requires MULTICA_TOKEN to be a task-scoped mat_ token%s", daemonPortOnlyContextHint())
	}

	serverURL := resolveServerURL(cmd)
	workspaceID := resolveWorkspaceID(cmd)
	if serverURL == "" {
		return nil, fmt.Errorf("server URL not set: use --server-url flag, MULTICA_SERVER_URL env, or 'multica config set server_url <url>'")
	}

	client := cli.NewAPIClient(serverURL, workspaceID, token)
	// When running inside a daemon task, attribute actions to the agent.
	if agentID := os.Getenv("MULTICA_AGENT_ID"); agentID != "" {
		client.AgentID = agentID
	}
	if taskID := os.Getenv("MULTICA_TASK_ID"); taskID != "" {
		client.TaskID = taskID
	}

View on GitHub (pinned to 2c0912b6ec)

Solutions

Delete the marker file named in the error's appended suffix (the message gives the exact path).
Re-run the command from a directory outside the stale marker's tree, or from the repository root above it, to confirm it was directory-scoped.
If this recurs, check why daemon tasks in local_directory workdirs are not cleaning up their markers on failure, and report/fix the cleanup path.

Example fix

# before: error in a repo where a daemon task crashed
multica agent list
# -> agent execution context requires MULTICA_TOKEN to be a task-scoped mat_ token ...

# after: remove the stale marker named in the message
rm /path/to/repo/.multica/daemon-task-marker.json
multica agent list

Defensive patterns

Strategy: validation

Validate before calling

# Before running multica in a repo, check for a stale daemon marker and remove it.
find . -name daemon-task-marker.json -path '*/.multica/*' \
  -exec sh -c 'echo "removing stale marker: $1"; rm "$1"' _ {} \;

Try / catch

// In Go code shelling out to multica:
out, err := cmd.CombinedOutput()
if err != nil && strings.Contains(string(out), "task-scoped mat_ token") {
    if i := strings.Index(string(out), "marker"); i >= 0 {
        return fmt.Errorf("stale daemon marker detected; delete the file named in: %s", string(out))
    }
}

Prevention

Add stale-marker cleanup (or at least detection) to post-task teardown for local_directory runs.
When a daemon task crashes, check its workdir for the marker before reuse.
Keep human shells out of directories used as daemon task workdirs.

When it happens

Trigger: inDaemonManagedExecutionContext() is true (marker file found walking up from cwd, or daemon env vars present), resolveToken returned a non-mat_ token (e.g. the human user's token), and leftoverDaemonTaskMarkerPath() found a stale marker file.

Common situations: A daemon task ran in a local_directory, crashed without cleanup, and left its marker file in the user's repository (MUL-6132); every later multica command in that directory tree is then treated as agent-context while the user authenticates as a human.

Related errors

AI-assisted analysis of multica-ai/multica@2c0912b6ec (2026-08-15). Data as JSON: /api/errors/ff16f5524707f062. Report an issue: GitHub.