[TASK TOOLS] Adds a list of tasks to the project backlog.

[TASK TOOLS] Atomically closes one or more tasks and auto-unblocks dependents.

[ARTIFACT TOOLS] Deletes a single artifact file by moving it to the recycle bin. The file is preserved in the recycle bin and can be restored using restore_project_artifact if needed.

Do NOT use to move or rename a file — call move_project_artifact instead.

Returns: confirmation string with the deleted file path. Raises: 404 error if the path does not exist in artifact storage.

[SESSION TOOLS] Assembles and returns the full context bundle (core guidelines + role-specific phase guidelines + filtered foundational ADRs) for a named agent role, without reading or modifying session.md.

Use this for deliberate mid-session role switches when you already know the target role and do not want to disturb pipeline state. Do NOT use at session start — call get_session_context instead, which also injects the SESSION STATE block and the correct NEXT STEP directive.

Allowed role values: any role registered in the project's role_profiles.yaml (e.g. 'discovery', 'architecture', 'planning', 'execution'). Returns an error string listing valid roles if the value is unrecognised.

Returns: assembled markdown string (core guidelines + role guidelines + ADRs). Raises: error string if role is not registered in role_profiles.yaml.

[ARTIFACT TOOLS] Extracts table of contents.

[SESSION TOOLS] Reads session.md, detects the active pipeline phase, and returns core guidelines + phase-appropriate role guidelines + filtered foundational ADRs

• role-linked skill stubs (=== PLAYBOOKS === section, when the role has skills registered) as a single assembled string.

If start_role is provided, session.md is bypassed entirely: the named role is resolved directly and SESSION STATE is omitted from the response.

[TASK TOOLS] Returns full task details.

[PROJECT TOOLS] Creates a new Marrow project workspace by copying the built-in default template into TASKS_DIR/projects/{project}. Produces a ready-to-use artifact tree (session.md, spec.md, guidelines, role_profiles.yaml).

Primary use case: first-run initialization on Glama or any single-container deployment where shell access is unavailable. For docker-compose deployments, use the marrow-init service instead.

Do NOT use to list existing projects — call list_projects instead. Do NOT use to read session state — call get_session_context(project) after init.

Parameters: project : str — unique project name (must not already exist) template : str — scaffold template; only "default" is supported in this release

Returns: { project, files_created, starting_role } where files_created lists every file path copied into the new workspace (relative to workspace root) and starting_role is Discovery Agent or Init Agent.

Raises: ValidationError if project already exists or template is unsupported.

[HISTORY TOOLS] Returns the version history for a single artifact file — a list of backup snapshots automatically created by save_project_artifacts on each write. Each entry represents a point-in-time copy that can be restored.

Use this to inspect available versions before calling restore_project_artifact. The most recent backup is listed first. Do NOT use this to read current file content — call read_project_artifacts instead.

Returns: list of version objects — each with backup_name, created_at timestamp, and size in bytes. Empty list if no history exists for the path. Raises: 404 if the artifact path does not exist in the project.

[ARTIFACT TOOLS] Lists artifact files in a project's artifact storage, optionally scoped to a subfolder and optionally traversing subdirectories.

path narrows the listing to a specific folder (e.g. 'docs/features/active'); omit or pass '' to list from the project root. recursive=True traverses all subdirectories; default is False (top-level only).

Do NOT use to read file content — call read_project_artifacts instead. Do NOT use to browse source code — call get_project_map for the src/ tree.

Returns: list of objects — each with path (relative to project root) and size in bytes. Raises: 404 if the project or path does not exist.

[PROJECT TOOLS] Returns a list of all available projects.

[ARTIFACT TOOLS] Moves or renames an artifact.

[ARTIFACT TOOLS] Reads one or more artifact files in a single batch call. Each item in reads targets one file and specifies an independent read mode.

Read modes per item: full — returns the entire file content. paged — windowed read of the entire file. max_chars (default 10000), skip_chars, and direction (default). section — returns only the content under a named ## header (requires section_name). lines — returns a specific line range (requires start_line and end_line).

Optional per-item fields: max_chars : int — truncate response at N characters (default 10000). skip_chars : int — skip N characters from the start of the selection. direction : 'begin' | 'end' — read from start or end of file (default 'begin'). line_numbers : bool — prefix each line with its 1-based line number.

Do NOT loop this tool per file — batch all reads into a single call to minimise round-trips. For source code files in src/, use view_file_source instead.

Returns: list of result objects — each with path and content (or error if not found). Raises: per-item error entry if a path does not exist; does not abort the batch.

[HISTORY TOOLS] Restores a named backup snapshot of an artifact, replacing the current live file with the backup content. The current live version is NOT automatically backed up before the restore — it will be overwritten.

Use list_artifact_history first to retrieve valid backup_name values for the target path. The backup_name is the exact string returned in the history list. Do NOT guess or construct backup names — always read them from list_artifact_history.

Returns: confirmation string with the restored path and backup_name applied. Raises: 404 if the path or backup_name does not exist.

[ARTIFACT TOOLS] Creates or updates one or more artifact files in a single atomic batch. Each item in updates targets one file and specifies an independent write mode — modes in the same batch do not interact.

Write modes per update item: replace_file — overwrites the entire file (creates it if absent). replace_section — replaces the content under a named ## header; raises if the header appears more than once (ADR-0011). append_section — appends a new ## section at the end of the file. replace_chunk — replaces lines start_line..end_line with new content. patch — finds old_str (must be unique in the file) and replaces it with new content. Preferred for surgical single-line edits. delete_section — removes a named ## section and its content.

Do NOT use replace_file when only a section needs updating — use patch or replace_section to avoid clobbering concurrent edits. Do NOT use this tool for source code in src/ — the source directory is read-only from the agent's perspective.

Returns: list of result objects, one per update — each with path and status. Raises: duplicate-header error (with line numbers) if replace_section finds multiple matching headers in the same file.

[ARTIFACT TOOLS] Full-text search across all artifact files in a project, matching against file content and returning files and sections that contain the query string.

Query is plain text — no special syntax required. Case-insensitive. For semantic / meaning-based search, use semantic_search instead. Do NOT use this to list files — call list_project_artifacts instead. Do NOT use this for source code — call search_code_skeletons instead.

Returns: list of match objects — each with path, matched section name, and a short excerpt of the matched content with surrounding context. Raises: 404 if the project does not exist.

[TASK TOOLS] Queries the task backlog in LanceDB with optional filters and returns matching task summaries ranked by creation order.

All parameters are optional filters — omit to retrieve all tasks with default status. Default status filter is 'open'; pass status=None to retrieve tasks of all statuses. Do NOT call get_task_details on every result — use this tool for status checks and task selection, then call get_task_details on the single selected task for full content.

Allowed status values: open | in_progress | blocked | done | None (no filter) Allowed priority values: low | medium | high | critical | None (no filter) Allowed type values: feature | bug | task | td | None (no filter)

Returns: list of task summary objects — each with task_id, title, status, priority, type, and blocked_by. Full problem/solution content is excluded; call get_task_details for that. Raises: 404 if project is not found.

[ARTIFACT TOOLS] Semantic search over artifact chunks, optionally scoped to one or more directories; returns each hit's location plus file content. Read-only.

Parameters: project : project name. query : natural-language search text. limit : max hits. With scopes, applies to the combined OR result, not per scope. scopes : project-relative directory paths, max 20, OR semantics. Omit (or None/[]) for unscoped -- unchanged from before this param existed. Directories only; a file path simply matches nothing.

Returns: on a normal or unscoped call, a list of hits (path, section, start_line, end_line, distance, content, warning -- as before). If scopes matched zero chunks, returns a single object instead of a list: {"message": str} explaining why -- check for a "message" key, not list length, to tell the two shapes apart. Raises: 404 unknown project. Validation error for a bad scope (absolute, '..', outside project root) or >20 scopes -- names the scope, never a host path. Per-hit read failures set warning (partial success), not an exception.

Do NOT use to read a known file -- call read_project_artifacts instead. Do NOT pass a file path as a scope -- scopes are directories.

[TASK TOOLS] Partially updates mutable fields on an existing task (status, priority, title, solution, etc.) using a merge strategy — only keys present in updates are changed; all other fields remain intact. Use this for in-progress changes (e.g. updating priority or editing the solution).

Do NOT use to close a task — call complete_tasks instead, which atomically closes and auto-unblocks dependents. Do NOT use to create tasks — call add_tasks instead.

Allowed updates keys: status : open | in_progress | blocked | done priority : low | medium | high | critical title : str problem : str solution : str blocked_by : list[task_id]

Returns: updated task object with all current field values. Raises: 404 if task_id not found in project.