{"record":{"id":"09750fd53c74c48f","repo":"langchain-ai/deepagents","slug":"path-unsafe-subagent-name-name-r","errorCode":null,"errorMessage":"{path}: unsafe subagent name {name!r}","messagePattern":"(.+?): unsafe subagent name (.+?)","errorType":"error_code","errorClass":"FleetImportError","httpStatus":null,"severity":"error","filePath":"libs/talon/deepagents_talon/fleet_import.py","lineNumber":306,"sourceCode":"\n\ndef _copy_zip_file(archive: zipfile.ZipFile, info: zipfile.ZipInfo, target: Path) -> None:\n    target.parent.mkdir(mode=0o700, parents=True, exist_ok=True)\n    copied = 0\n    with archive.open(info) as src, target.open(\"wb\") as dst:\n        while chunk := src.read(_COPY_CHUNK_SIZE):\n            copied += len(chunk)\n            if copied > info.file_size or copied > _MAX_ZIP_UNCOMPRESSED_BYTES:\n                msg = f\"{info.filename}: zip entry expanded beyond declared size\"\n                raise FleetImportError(msg)\n            dst.write(chunk)\n    target.chmod(0o600)\n\n\ndef _validate_agent_name(name: str, path: str) -> None:\n    if not _AGENT_ID_PATTERN.fullmatch(name) or name in {\".\", \"..\"}:\n        msg = f\"{path}: unsafe subagent name {name!r}\"\n        raise FleetImportError(msg)\n\n\ndef _is_subagent_prompt_path(name: str) -> bool:\n    parts = PurePosixPath(name).parts\n    return (\n        len(parts) == _SUBAGENT_FILE_PARTS and parts[0] == \"subagents\" and parts[2] == \"AGENTS.md\"\n    )\n\n\ndef _is_subagent_tools_path(name: str) -> bool:\n    parts = PurePosixPath(name).parts\n    return (\n        len(parts) == _SUBAGENT_FILE_PARTS and parts[0] == \"subagents\" and parts[2] == \"tools.json\"\n    )\n\n\ndef _mcp_summaries(staging: Path, source: Path) -> list[_ServerSummary]:\n    grouped: dict[tuple[str, str], _ServerSummary] = {}","sourceCodeStart":288,"sourceCodeEnd":324,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/talon/deepagents_talon/fleet_import.py#L288-L324","documentation":"A subagent directory name taken from `subagents/<name>/AGENTS.md` or `subagents/<name>/tools.json` fails validation: it must fully match `[A-Za-z0-9_.-]{1,128}` and not be `.` or `..`. Names outside this set could escape the `agents/` directory or produce unusable paths, so import aborts with the offending path in the message.","triggerScenarios":"`import_fleet_zip` materializes a subagent file whose second path component contains characters like spaces, slashes, unicode, `~`, `!`, `@`, `#`, or is longer than 128 chars, or equals `.`/`..`.","commonSituations":"Fleet exports where subagent folders were named with human-friendly labels (`My Assistant!`), localization characters (`Assistanté`), or copy-paste artifacts (trailing spaces).","solutions":["Rename the subagent directory in the export to only `[A-Za-z0-9_.-]`, max 128 chars (e.g. `my-assistant`)","Pre-check names before zipping: regex-fullmatch every `subagents/*/` folder name","Check the path in the error message to identify which folder to rename; update any cross-references to the old name"],"exampleFix":"// before\nsubagents/My Assistant!/AGENTS.md\n// after\nsubagents/my-assistant/AGENTS.md","handlingStrategy":"validation","validationCode":"import re\nimport zipfile\n\nPATTERN = re.compile(r\"[A-Za-z0-9_.-]{1,128}\")\n\ndef has_unsafe_agent_names(path):\n    with zipfile.ZipFile(path) as z:\n        for name in z.namelist():\n            parts = name.replace(\"\\\\\", \"/\").split(\"/\")\n            if len(parts) == 3 and parts[0] == \"subagents\":\n                if not PATTERN.fullmatch(parts[1]) or parts[1] in {\".\", \"..\"}:\n                    return True\n    return False","typeGuard":"def is_safe_agent_name(name: str) -> bool:\n    return bool(re.fullmatch(r\"[A-Za-z0-9_.-]{1,128}\", name)) and name not in {\".\", \"..\"}","tryCatchPattern":"try:\n    import_fleet_zip(zip_path, target_dir=target)\nexcept FleetImportError as exc:\n    if \"unsafe subagent name\" in str(exc):\n        print(f\"Rename subagent dir to [A-Za-z0-9_.-] only: {exc}\")\n    raise","preventionTips":["Name subagent folders with kebab-case ASCII identifiers","Validate folder names in your export pipeline before zipping","Avoid spaces, unicode, and punctuation in agent directory names"],"tags":["validation","zip","naming","path-safety"],"backgroundTag":"invalid-identifier-name","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}